2## @file tests/run-tests.sh
3## @brief Runs the bash-doxygen behavior-focused regression suite.
5## Exercises one or more Bash Doxygen filters supplied as LABEL=PATH arguments.
6## Successful fixtures, diagnostic fixtures, generated-artifact contracts, and
7## default line-preserving behavior are reported as one TAP stream. The harness
8## accumulates ordinary assertion failures so callers receive the complete set of
9## regressions from a run while reserving TAP bail-outs for unusable test state.
13## sh ./tests/run-tests.sh source=doxygen-bash.awk
14## sh ./tests/run-tests.sh source=doxygen-bash.awk ordinary=dist/doxygen-bash.awk
18ROOT_DIR=$(CDPATH=
'' cd --
"$(dirname -- "$0
")/.." && pwd)
19TMP_DIR=$(mktemp -d) || exit 1
20trap
'rm -rf "$TMP_DIR"' EXIT HUP INT TERM
22AWK_BIN=${AWK_BIN:-awk}
27## @brief Emits one successful TAP assertion.
28## @param description Human-readable assertion description.
30## Nothing is read from STDIN.
32## One numbered TAP success record is written to STDOUT.
34## Nothing is written to STDERR.
35## @returns One TAP assertion line.
36## @retval 0 The TAP record was emitted.
38 TEST_NUMBER=$((TEST_NUMBER + 1))
39 printf 'ok %s - %s\n' "$TEST_NUMBER" "$1"
43## @brief Emits one failed TAP assertion and records the failure.
44## @param description Human-readable assertion description.
46## Nothing is read from STDIN.
48## One numbered TAP failure record is written to STDOUT.
50## Nothing is written to STDERR.
51## @returns One TAP failure assertion line.
52## @retval 0 The TAP record was emitted and the failure counter was updated.
54 TEST_NUMBER=$((TEST_NUMBER + 1))
55 FAILURE_COUNT=$((FAILURE_COUNT + 1))
56 printf
'not ok %s - %s\n' "$TEST_NUMBER" "$1"
60## @brief Emits diagnostic text that remains valid inside a TAP stream.
61## @param message Diagnostic text to annotate.
63## Nothing is read from STDIN.
65## One TAP diagnostic line prefixed with a hash is written to STDOUT.
67## Nothing is written to STDERR.
68## @returns One TAP diagnostic line.
69## @retval 0 The diagnostic line was emitted.
75## @brief Emits a text file as TAP diagnostic lines.
76## @param path File whose contents should be annotated.
78## Nothing is read from STDIN.
80## The file contents are written to STDOUT with TAP diagnostic prefixes.
82## Nothing is written to STDERR.
83## @returns The annotated file contents.
84## @retval 0 The file was emitted successfully.
90## @brief Terminates the harness when the test environment is unusable.
91## @param message Human-readable reason the harness cannot continue.
93## Nothing is read from STDIN.
95## One TAP bail-out record is written to STDOUT.
97## Nothing is written to STDERR.
98## @returns A TAP bail-out record.
99## @retval 1 The harness terminates because testing cannot continue.
101 printf
'Bail out! %s\n' "$1"
105## @fn normalize_warnings()
106## @brief Removes source-location prefixes from filter diagnostics.
107## @param path File containing raw filter diagnostics.
109## Nothing is read from STDIN.
111## Normalized diagnostic text is written to STDOUT.
113## sed diagnostics may be written to STDERR if normalization fails.
114## @returns Normalized warning text without generated source locations.
115## @retval 0 The sed transformation completed successfully.
117 sed
's/^.*: warning: //' "$1"
120## @fn resolve_filter_path()
121## @brief Resolves a filter path against the repository root when needed.
122## @param path Absolute or repository-relative filter path.
124## Nothing is read from STDIN.
126## The resolved absolute filter path is written to STDOUT.
128## Nothing is written to STDERR.
129## @returns One absolute filter path.
130## @retval 0 The path was rendered.
156 [ -f
"$checksum" ] ||
return 1
158 if command -v sha256sum >/dev/null 2>&1; then
159 (cd
"$directory" && sha256sum -c
"$filename.sha256" >/dev/null 2>&1)
162 if command -v shasum >/dev/null 2>&1; then
163 (cd "$directory" && shasum -a 256 -c "$filename.sha256" >/dev/null 2>&1)
169## @fn check_artifact_contract()
170## @brief Validates generated-artifact metadata and checksum expectations.
171## @param label Logical filter label supplied by the Makefile.
172## @param path Absolute path to the filter under test.
174## Nothing is read from STDIN.
176## TAP assertions and diagnostics are written to STDOUT.
178## Nothing is intentionally written to STDERR.
179## @returns TAP records describing the generated artifact contract.
180## @retval 0 Contract assertions were emitted; failures are tracked globally.
185 [
"$label" != source ] ||
return 0
188 first_line=$(sed -n
'1p' "$path" 2>/dev/null || printf
'')
189 [
"$first_line" =
'#!/usr/bin/awk -f' ] || contract_ok=0
190 grep -Fq
'# Generated by make build. Do not edit directly.' "$path" 2>/dev/null || contract_ok=0
191 grep -Fq
'# DOXYGEN_BASH_VERSION=' "$path" 2>/dev/null || contract_ok=0
192 grep -Fq
'# DOXYGEN_BASH_BUILD_DATE=' "$path" 2>/dev/null || contract_ok=0
193 grep -Fq
'# DOXYGEN_BASH_BUILD_COMMIT=' "$path" 2>/dev/null || contract_ok=0
197 grep -Fq
'# Artifact: development' "$path" 2>/dev/null || contract_ok=0
198 grep -Fq
'# Documentation-led Doxygen preprocessor for Bash' "$path" 2>/dev/null || contract_ok=0
201 grep -Fq
'# Artifact: ordinary' "$path" 2>/dev/null || contract_ok=0
202 if sed
'1,/^# End generated header\.$/d' "$path" | grep -q
'^[[:space:]]*#'; then
207 grep -Fq
'# Artifact: minified' "$path" 2>/dev/null || contract_ok=0
208 grep -Fq
'# Minifier: AWK Minifier v0.2.4' "$path" 2>/dev/null || contract_ok=0
215 if [
"$contract_ok" -eq 1 ]; then
216 tap_ok "$label artifact contract"
219 tap_diag "generated artifact metadata or representation is invalid: ${path#$ROOT_DIR/}"
223 tap_ok "$label artifact checksum"
226 tap_diag "checksum verification failed: ${path#$ROOT_DIR/}.sha256"
230## @fn run_output_cases()
231## @brief Runs successful translation fixtures against the selected filter.
233## Nothing is read from STDIN.
235## TAP assertions and diagnostics are written to STDOUT.
237## Nothing is intentionally written to STDERR.
238## @returns TAP records for every successful translation fixture.
239## @retval 0 All fixture assertions were emitted; failures are tracked globally.
241 for expected in
"$ROOT_DIR"/tests/expected
244 input=
"$ROOT_DIR/tests/fixtures/$name.bash"
245 actual=
"$TMP_DIR/$FILTER_KEY.$name.cpp"
246 errors=
"$TMP_DIR/$FILTER_KEY.$name.err"
247 description=
"$FILTER_LABEL output: $name"
249 if [ ! -f
"$input" ]; then
251 tap_diag "missing input fixture: ${input#$ROOT_DIR/}"
255 if !
"$AWK_BIN" -f
"$FILTER" -- --compact
"$input" >
"$actual" 2>
"$errors"; then
261 if [ -s
"$errors" ]; then
263 tap_diag 'successful fixture emitted a diagnostic'
267 if ! diff -u
"$expected" "$actual" >
"$TMP_DIR/$FILTER_KEY.$name.diff" 2>&1; then
269 tap_diag 'filtered output differs from expected pseudo-C++'
278## @fn run_diagnostic_cases()
279## @brief Runs warning and strict-mode diagnostic fixtures.
281## Nothing is read from STDIN.
283## TAP assertions and diagnostics are written to STDOUT.
285## Nothing is intentionally written to STDERR.
286## @returns TAP records for every diagnostic fixture.
287## @retval 0 All diagnostic assertions were emitted; failures are tracked globally.
289 for expected in
"$ROOT_DIR"/tests/diagnostics
292 input=
"$ROOT_DIR/tests/diagnostics/$name.bash"
293 warning_err=
"$TMP_DIR/$FILTER_KEY.$name.warning.err"
294 strict_err=
"$TMP_DIR/$FILTER_KEY.$name.strict.err"
295 normalized=
"$TMP_DIR/$FILTER_KEY.$name.normalized.err"
296 description=
"$FILTER_LABEL diagnostic: $name"
299 if [ ! -f
"$input" ]; then
301 tap_diag "missing diagnostic fixture: ${input#$ROOT_DIR/}"
305 if !
"$AWK_BIN" -f
"$FILTER" -- --compact
"$input" \
306 >
"$TMP_DIR/$FILTER_KEY.$name.warning.cpp" 2>
"$warning_err"; then
308 tap_diag 'non-strict diagnostic case exited non-zero'
311 if ! diff -u
"$expected" "$normalized" >
"$TMP_DIR/$FILTER_KEY.$name.warning.diff" 2>&1; then
313 tap_diag 'non-strict diagnostic differs from expected output'
317 if "$AWK_BIN" -f
"$FILTER" -- --strict --compact
"$input" \
318 >
"$TMP_DIR/$FILTER_KEY.$name.strict.cpp" 2>
"$strict_err"; then
320 tap_diag 'strict diagnostic case exited zero'
323 if ! diff -u
"$expected" "$normalized" >
"$TMP_DIR/$FILTER_KEY.$name.strict.diff" 2>&1; then
325 tap_diag 'strict diagnostic differs from expected output'
329 if [
"$case_ok" -eq 1 ]; then
337## @fn run_default_mode_case()
338## @brief Verifies default blank-placeholder line preservation.
340## Nothing is read from STDIN.
342## One TAP assertion and any diagnostics are written to STDOUT.
344## Nothing is intentionally written to STDERR.
345## @returns One TAP record for the default output mode.
346## @retval 0 The assertion was emitted; failure is tracked globally.
348 input=
"$ROOT_DIR/tests/fixtures/undocumented-ignored.bash"
349 actual=
"$TMP_DIR/$FILTER_KEY.default-blanks.cpp"
350 errors=
"$TMP_DIR/$FILTER_KEY.default-blanks.err"
351 description=
"$FILTER_LABEL mode: default blank placeholders"
354 if !
"$AWK_BIN" -f
"$FILTER" "$input" >
"$actual" 2>
"$errors"; then
356 tap_diag 'default-mode filter execution failed'
358 if [ -s
"$errors" ]; then
360 tap_diag 'default mode emitted a diagnostic for ignored lines'
364 expected_lines=$(wc -l <
"$input" | tr -d
' ')
365 actual_lines=$(wc -l <
"$actual" | tr -d
' ')
366 if [
"$actual_lines" -ne
"$expected_lines" ]; then
368 tap_diag "expected $expected_lines placeholder lines, found $actual_lines"
370 if grep -q
'[^[:space:]]' "$actual"; then
372 tap_diag 'default mode emitted non-blank content for undocumented input'
375 if [
"$case_ok" -eq 1 ]; then
382## @fn run_filter_suite()
383## @brief Runs the complete regression contract against one filter.
384## @param label Logical name used in TAP assertion descriptions.
385## @param path Absolute or repository-relative filter path.
387## Nothing is read from STDIN.
389## TAP assertions and diagnostics are written to STDOUT.
391## Nothing is intentionally written to STDERR.
392## @returns TAP records for the selected filter.
393## @retval 0 The suite assertions were emitted; failures are tracked globally.
397 FILTER_KEY=$(printf
'%s' "$FILTER_LABEL" | tr -c
'A-Za-z0-9_.-' '_')
399 if [ ! -f
"$FILTER" ]; then
400 tap_not_ok "$FILTER_LABEL filter availability"
401 tap_diag "missing filter: ${FILTER#$ROOT_DIR/}"
411printf
'TAP version 13\n'
412printf
'# AWK_BIN: %s\n' "$AWK_BIN"
414[
"$#" -gt 0 ] || set --
"source=doxygen-bash.awk"
417 case "$filter_spec" in
419 *)
bail_out "invalid filter specification: $filter_spec" ;;
422 filter_label=${filter_spec%%=*}
423 filter_path=${filter_spec#*=}
424 [ -n
"$filter_label" ] ||
bail_out 'filter label must not be empty'
425 [ -n
"$filter_path" ] ||
bail_out "filter path must not be empty: $filter_label"
429printf
'1..%s\n' "$TEST_NUMBER"
431[
"$FAILURE_COUNT" -eq 0 ]
int tap_file_diag(String path)
Emits a text file as TAP diagnostic lines.
int tap_diag(String message)
Emits diagnostic text that remains valid inside a TAP stream.
int resolve_filter_path(String path)
Resolves a filter path against the repository root when needed.
int verify_checksum(String path)
Verifies the checksum adjacent to one generated AWK artifact.
int run_diagnostic_cases()
Runs warning and strict-mode diagnostic fixtures.
int run_default_mode_case()
Verifies default blank-placeholder line preservation.
int tap_not_ok(String description)
Emits one failed TAP assertion and records the failure.
int tap_ok(String description)
Emits one successful TAP assertion.
int run_output_cases()
Runs successful translation fixtures against the selected filter.
int normalize_warnings(String path)
Removes source-location prefixes from filter diagnostics.
int check_artifact_contract(String label, String path)
Validates generated-artifact metadata and checksum expectations.
int run_filter_suite(String label, String path)
Runs the complete regression contract against one filter.
int bail_out(String message)
Terminates the harness when the test environment is unusable.