bash-doxygen
Reference documentation for bash-doxygen
Loading...
Searching...
No Matches
run-tests.sh
Go to the documentation of this file.
1#!/bin/sh
2## @file tests/run-tests.sh
3## @brief Runs the bash-doxygen behavior-focused regression suite.
4## @details
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.
10##
11## @par Examples
12## @code
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
15## @endcode
16set -u
17
18ROOT_DIR=$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd)
19TMP_DIR=$(mktemp -d) || exit 1
20trap 'rm -rf "$TMP_DIR"' EXIT HUP INT TERM
21
22AWK_BIN=${AWK_BIN:-awk}
23TEST_NUMBER=0
24FAILURE_COUNT=0
25
26## @fn tap_ok()
27## @brief Emits one successful TAP assertion.
28## @param description Human-readable assertion description.
29## @par STDIN
30## Nothing is read from STDIN.
31## @par STDOUT
32## One numbered TAP success record is written to STDOUT.
33## @par STDERR
34## Nothing is written to STDERR.
35## @returns One TAP assertion line.
36## @retval 0 The TAP record was emitted.
37tap_ok() {
38 TEST_NUMBER=$((TEST_NUMBER + 1))
39 printf 'ok %s - %s\n' "$TEST_NUMBER" "$1"
40}
42## @fn tap_not_ok()
43## @brief Emits one failed TAP assertion and records the failure.
44## @param description Human-readable assertion description.
45## @par STDIN
46## Nothing is read from STDIN.
47## @par STDOUT
48## One numbered TAP failure record is written to STDOUT.
49## @par STDERR
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.
53tap_not_ok() {
54 TEST_NUMBER=$((TEST_NUMBER + 1))
55 FAILURE_COUNT=$((FAILURE_COUNT + 1))
56 printf 'not ok %s - %s\n' "$TEST_NUMBER" "$1"
57}
59## @fn tap_diag()
60## @brief Emits diagnostic text that remains valid inside a TAP stream.
61## @param message Diagnostic text to annotate.
62## @par STDIN
63## Nothing is read from STDIN.
64## @par STDOUT
65## One TAP diagnostic line prefixed with a hash is written to STDOUT.
66## @par STDERR
67## Nothing is written to STDERR.
68## @returns One TAP diagnostic line.
69## @retval 0 The diagnostic line was emitted.
70tap_diag() {
71 printf '# %s\n' "$1"
72}
73
74## @fn tap_file_diag()
75## @brief Emits a text file as TAP diagnostic lines.
76## @param path File whose contents should be annotated.
77## @par STDIN
78## Nothing is read from STDIN.
79## @par STDOUT
80## The file contents are written to STDOUT with TAP diagnostic prefixes.
81## @par STDERR
82## Nothing is written to STDERR.
83## @returns The annotated file contents.
84## @retval 0 The file was emitted successfully.
86 sed 's/^/# /' "$1"
87}
88
89## @fn bail_out()
90## @brief Terminates the harness when the test environment is unusable.
91## @param message Human-readable reason the harness cannot continue.
92## @par STDIN
93## Nothing is read from STDIN.
94## @par STDOUT
95## One TAP bail-out record is written to STDOUT.
96## @par STDERR
97## Nothing is written to STDERR.
98## @returns A TAP bail-out record.
99## @retval 1 The harness terminates because testing cannot continue.
100bail_out() {
101 printf 'Bail out! %s\n' "$1"
102 exit 1
103}
104
105## @fn normalize_warnings()
106## @brief Removes source-location prefixes from filter diagnostics.
107## @param path File containing raw filter diagnostics.
108## @par STDIN
109## Nothing is read from STDIN.
110## @par STDOUT
111## Normalized diagnostic text is written to STDOUT.
112## @par STDERR
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"
118}
119
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.
123## @par STDIN
124## Nothing is read from STDIN.
125## @par STDOUT
126## The resolved absolute filter path is written to STDOUT.
127## @par STDERR
128## Nothing is written to STDERR.
129## @returns One absolute filter path.
130## @retval 0 The path was rendered.
132 case "$1" in
133 /*) printf '%s\n' "$1" ;;
134 *) printf '%s/%s\n' "$ROOT_DIR" "$1" ;;
135 esac
136}
137
138## @fn verify_checksum()
139## @brief Verifies the checksum adjacent to one generated AWK artifact.
140## @param path Absolute path to the generated AWK artifact.
141## @par STDIN
142## Nothing is read from STDIN.
143## @par STDOUT
144## Nothing is written to STDOUT.
145## @par STDERR
146## Verification-tool diagnostics are suppressed by this helper.
147## @returns Nothing is written to STDOUT.
148## @retval 0 The checksum exists and verifies successfully.
149## @retval 1 The checksum is missing, no supported verifier exists, or verification fails.
150verify_checksum() {
151 artifact=$1
152 checksum=$artifact.sha256
153 directory=${artifact%/*}
154 filename=${artifact##*/}
155
156 [ -f "$checksum" ] || return 1
157
158 if command -v sha256sum >/dev/null 2>&1; then
159 (cd "$directory" && sha256sum -c "$filename.sha256" >/dev/null 2>&1)
160 return $?
161 fi
162 if command -v shasum >/dev/null 2>&1; then
163 (cd "$directory" && shasum -a 256 -c "$filename.sha256" >/dev/null 2>&1)
164 return $?
165 fi
166 return 1
167}
168
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.
173## @par STDIN
174## Nothing is read from STDIN.
175## @par STDOUT
176## TAP assertions and diagnostics are written to STDOUT.
177## @par STDERR
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.
182 label=$1
183 path=$2
184
185 [ "$label" != source ] || return 0
186
187 contract_ok=1
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
194
195 case "$label" in
196 development)
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
199 ;;
200 ordinary)
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
203 contract_ok=0
204 fi
205 ;;
206 minified)
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
209 ;;
210 *)
211 contract_ok=0
212 ;;
213 esac
214
215 if [ "$contract_ok" -eq 1 ]; then
216 tap_ok "$label artifact contract"
217 else
218 tap_not_ok "$label artifact contract"
219 tap_diag "generated artifact metadata or representation is invalid: ${path#$ROOT_DIR/}"
220 fi
221
222 if verify_checksum "$path"; then
223 tap_ok "$label artifact checksum"
224 else
225 tap_not_ok "$label artifact checksum"
226 tap_diag "checksum verification failed: ${path#$ROOT_DIR/}.sha256"
227 fi
228}
229
230## @fn run_output_cases()
231## @brief Runs successful translation fixtures against the selected filter.
232## @par STDIN
233## Nothing is read from STDIN.
234## @par STDOUT
235## TAP assertions and diagnostics are written to STDOUT.
236## @par STDERR
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/*.cpp; do
242 name=${expected##*/}
243 name=${name%.cpp}
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"
248
249 if [ ! -f "$input" ]; then
250 tap_not_ok "$description"
251 tap_diag "missing input fixture: ${input#$ROOT_DIR/}"
252 continue
253 fi
254
255 if ! "$AWK_BIN" -f "$FILTER" -- --compact "$input" >"$actual" 2>"$errors"; then
256 tap_not_ok "$description"
257 tap_diag 'filter execution failed'
258 [ ! -s "$errors" ] || tap_file_diag "$errors"
259 continue
260 fi
261 if [ -s "$errors" ]; then
262 tap_not_ok "$description"
263 tap_diag 'successful fixture emitted a diagnostic'
264 tap_file_diag "$errors"
265 continue
266 fi
267 if ! diff -u "$expected" "$actual" >"$TMP_DIR/$FILTER_KEY.$name.diff" 2>&1; then
268 tap_not_ok "$description"
269 tap_diag 'filtered output differs from expected pseudo-C++'
270 tap_file_diag "$TMP_DIR/$FILTER_KEY.$name.diff"
271 continue
272 fi
273
274 tap_ok "$description"
275 done
276}
277
278## @fn run_diagnostic_cases()
279## @brief Runs warning and strict-mode diagnostic fixtures.
280## @par STDIN
281## Nothing is read from STDIN.
282## @par STDOUT
283## TAP assertions and diagnostics are written to STDOUT.
284## @par STDERR
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/*.err; do
290 name=${expected##*/}
291 name=${name%.err}
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"
297 case_ok=1
298
299 if [ ! -f "$input" ]; then
300 tap_not_ok "$description"
301 tap_diag "missing diagnostic fixture: ${input#$ROOT_DIR/}"
302 continue
303 fi
304
305 if ! "$AWK_BIN" -f "$FILTER" -- --compact "$input" \
306 >"$TMP_DIR/$FILTER_KEY.$name.warning.cpp" 2>"$warning_err"; then
307 case_ok=0
308 tap_diag 'non-strict diagnostic case exited non-zero'
309 fi
310 normalize_warnings "$warning_err" >"$normalized"
311 if ! diff -u "$expected" "$normalized" >"$TMP_DIR/$FILTER_KEY.$name.warning.diff" 2>&1; then
312 case_ok=0
313 tap_diag 'non-strict diagnostic differs from expected output'
314 tap_file_diag "$TMP_DIR/$FILTER_KEY.$name.warning.diff"
315 fi
316
317 if "$AWK_BIN" -f "$FILTER" -- --strict --compact "$input" \
318 >"$TMP_DIR/$FILTER_KEY.$name.strict.cpp" 2>"$strict_err"; then
319 case_ok=0
320 tap_diag 'strict diagnostic case exited zero'
321 fi
322 normalize_warnings "$strict_err" >"$normalized"
323 if ! diff -u "$expected" "$normalized" >"$TMP_DIR/$FILTER_KEY.$name.strict.diff" 2>&1; then
324 case_ok=0
325 tap_diag 'strict diagnostic differs from expected output'
326 tap_file_diag "$TMP_DIR/$FILTER_KEY.$name.strict.diff"
327 fi
328
329 if [ "$case_ok" -eq 1 ]; then
330 tap_ok "$description"
331 else
332 tap_not_ok "$description"
333 fi
334 done
335}
336
337## @fn run_default_mode_case()
338## @brief Verifies default blank-placeholder line preservation.
339## @par STDIN
340## Nothing is read from STDIN.
341## @par STDOUT
342## One TAP assertion and any diagnostics are written to STDOUT.
343## @par STDERR
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"
352 case_ok=1
353
354 if ! "$AWK_BIN" -f "$FILTER" "$input" >"$actual" 2>"$errors"; then
355 case_ok=0
356 tap_diag 'default-mode filter execution failed'
357 fi
358 if [ -s "$errors" ]; then
359 case_ok=0
360 tap_diag 'default mode emitted a diagnostic for ignored lines'
361 tap_file_diag "$errors"
362 fi
363
364 expected_lines=$(wc -l <"$input" | tr -d ' ')
365 actual_lines=$(wc -l <"$actual" | tr -d ' ')
366 if [ "$actual_lines" -ne "$expected_lines" ]; then
367 case_ok=0
368 tap_diag "expected $expected_lines placeholder lines, found $actual_lines"
369 fi
370 if grep -q '[^[:space:]]' "$actual"; then
371 case_ok=0
372 tap_diag 'default mode emitted non-blank content for undocumented input'
373 fi
374
375 if [ "$case_ok" -eq 1 ]; then
376 tap_ok "$description"
377 else
378 tap_not_ok "$description"
379 fi
380}
381
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.
386## @par STDIN
387## Nothing is read from STDIN.
388## @par STDOUT
389## TAP assertions and diagnostics are written to STDOUT.
390## @par STDERR
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.
395 FILTER_LABEL=$1
396 FILTER=$(resolve_filter_path "$2")
397 FILTER_KEY=$(printf '%s' "$FILTER_LABEL" | tr -c 'A-Za-z0-9_.-' '_')
398
399 if [ ! -f "$FILTER" ]; then
400 tap_not_ok "$FILTER_LABEL filter availability"
401 tap_diag "missing filter: ${FILTER#$ROOT_DIR/}"
402 return 0
403 fi
404
405 check_artifact_contract "$FILTER_LABEL" "$FILTER"
409}
411printf 'TAP version 13\n'
412printf '# AWK_BIN: %s\n' "$AWK_BIN"
413
414[ "$#" -gt 0 ] || set -- "source=doxygen-bash.awk"
415
416for filter_spec do
417 case "$filter_spec" in
418 *=*) ;;
419 *) bail_out "invalid filter specification: $filter_spec" ;;
420 esac
421
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"
426 run_filter_suite "$filter_label" "$filter_path"
427done
428
429printf '1..%s\n' "$TEST_NUMBER"
430
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.