bash-doxygen
Reference documentation for bash-doxygen
Loading...
Searching...
No Matches
Functions
run-tests.sh File Reference

Runs the bash-doxygen behavior-focused regression suite. More...

Go to the source code of this file.

Functions

int tap_ok (String description)
 Emits one successful TAP assertion.
 
int tap_not_ok (String description)
 Emits one failed TAP assertion and records the failure.
 
int tap_diag (String message)
 Emits diagnostic text that remains valid inside a TAP stream.
 
int tap_file_diag (String path)
 Emits a text file as TAP diagnostic lines.
 
int bail_out (String message)
 Terminates the harness when the test environment is unusable.
 
int normalize_warnings (String path)
 Removes source-location prefixes from filter diagnostics.
 
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 check_artifact_contract (String label, String path)
 Validates generated-artifact metadata and checksum expectations.
 
int run_output_cases ()
 Runs successful translation fixtures against the selected filter.
 
int run_diagnostic_cases ()
 Runs warning and strict-mode diagnostic fixtures.
 
int run_default_mode_case ()
 Verifies default blank-placeholder line preservation.
 
int run_filter_suite (String label, String path)
 Runs the complete regression contract against one filter.
 

Detailed Description

Runs the bash-doxygen behavior-focused regression suite.

Exercises one or more Bash Doxygen filters supplied as LABEL=PATH arguments. Successful fixtures, diagnostic fixtures, generated-artifact contracts, and default line-preserving behavior are reported as one TAP stream. The harness accumulates ordinary assertion failures so callers receive the complete set of regressions from a run while reserving TAP bail-outs for unusable test state.

Examples
sh ./tests/run-tests.sh source=doxygen-bash.awk
sh ./tests/run-tests.sh source=doxygen-bash.awk ordinary=dist/doxygen-bash.awk

Definition in file run-tests.sh.

Function Documentation

◆ bail_out()

int bail_out ( String  message)

Terminates the harness when the test environment is unusable.

Parameters
messageHuman-readable reason the harness cannot continue.
STDIN
Nothing is read from STDIN.
STDOUT
One TAP bail-out record is written to STDOUT.
STDERR
Nothing is written to STDERR.
Returns
A TAP bail-out record.
Return values
1The harness terminates because testing cannot continue.

◆ check_artifact_contract()

int check_artifact_contract ( String  label,
String  path 
)

Validates generated-artifact metadata and checksum expectations.

Parameters
labelLogical filter label supplied by the Makefile.
pathAbsolute path to the filter under test.
STDIN
Nothing is read from STDIN.
STDOUT
TAP assertions and diagnostics are written to STDOUT.
STDERR
Nothing is intentionally written to STDERR.
Returns
TAP records describing the generated artifact contract.
Return values
0Contract assertions were emitted; failures are tracked globally.

◆ normalize_warnings()

int normalize_warnings ( String  path)

Removes source-location prefixes from filter diagnostics.

Parameters
pathFile containing raw filter diagnostics.
STDIN
Nothing is read from STDIN.
STDOUT
Normalized diagnostic text is written to STDOUT.
STDERR
sed diagnostics may be written to STDERR if normalization fails.
Returns
Normalized warning text without generated source locations.
Return values
0The sed transformation completed successfully.

◆ resolve_filter_path()

int resolve_filter_path ( String  path)

Resolves a filter path against the repository root when needed.

Parameters
pathAbsolute or repository-relative filter path.
STDIN
Nothing is read from STDIN.
STDOUT
The resolved absolute filter path is written to STDOUT.
STDERR
Nothing is written to STDERR.
Returns
One absolute filter path.
Return values
0The path was rendered.

◆ run_default_mode_case()

int run_default_mode_case ( )

Verifies default blank-placeholder line preservation.

STDIN
Nothing is read from STDIN.
STDOUT
One TAP assertion and any diagnostics are written to STDOUT.
STDERR
Nothing is intentionally written to STDERR.
Returns
One TAP record for the default output mode.
Return values
0The assertion was emitted; failure is tracked globally.

◆ run_diagnostic_cases()

int run_diagnostic_cases ( )

Runs warning and strict-mode diagnostic fixtures.

STDIN
Nothing is read from STDIN.
STDOUT
TAP assertions and diagnostics are written to STDOUT.
STDERR
Nothing is intentionally written to STDERR.
Returns
TAP records for every diagnostic fixture.
Return values
0All diagnostic assertions were emitted; failures are tracked globally.

◆ run_filter_suite()

int run_filter_suite ( String  label,
String  path 
)

Runs the complete regression contract against one filter.

Parameters
labelLogical name used in TAP assertion descriptions.
pathAbsolute or repository-relative filter path.
STDIN
Nothing is read from STDIN.
STDOUT
TAP assertions and diagnostics are written to STDOUT.
STDERR
Nothing is intentionally written to STDERR.
Returns
TAP records for the selected filter.
Return values
0The suite assertions were emitted; failures are tracked globally.

◆ run_output_cases()

int run_output_cases ( )

Runs successful translation fixtures against the selected filter.

STDIN
Nothing is read from STDIN.
STDOUT
TAP assertions and diagnostics are written to STDOUT.
STDERR
Nothing is intentionally written to STDERR.
Returns
TAP records for every successful translation fixture.
Return values
0All fixture assertions were emitted; failures are tracked globally.

◆ tap_diag()

int tap_diag ( String  message)

Emits diagnostic text that remains valid inside a TAP stream.

Parameters
messageDiagnostic text to annotate.
STDIN
Nothing is read from STDIN.
STDOUT
One TAP diagnostic line prefixed with a hash is written to STDOUT.
STDERR
Nothing is written to STDERR.
Returns
One TAP diagnostic line.
Return values
0The diagnostic line was emitted.

◆ tap_file_diag()

int tap_file_diag ( String  path)

Emits a text file as TAP diagnostic lines.

Parameters
pathFile whose contents should be annotated.
STDIN
Nothing is read from STDIN.
STDOUT
The file contents are written to STDOUT with TAP diagnostic prefixes.
STDERR
Nothing is written to STDERR.
Returns
The annotated file contents.
Return values
0The file was emitted successfully.

◆ tap_not_ok()

int tap_not_ok ( String  description)

Emits one failed TAP assertion and records the failure.

Parameters
descriptionHuman-readable assertion description.
STDIN
Nothing is read from STDIN.
STDOUT
One numbered TAP failure record is written to STDOUT.
STDERR
Nothing is written to STDERR.
Returns
One TAP failure assertion line.
Return values
0The TAP record was emitted and the failure counter was updated.

◆ tap_ok()

int tap_ok ( String  description)

Emits one successful TAP assertion.

Parameters
descriptionHuman-readable assertion description.
STDIN
Nothing is read from STDIN.
STDOUT
One numbered TAP success record is written to STDOUT.
STDERR
Nothing is written to STDERR.
Returns
One TAP assertion line.
Return values
0The TAP record was emitted.

◆ verify_checksum()

int verify_checksum ( String  path)

Verifies the checksum adjacent to one generated AWK artifact.

Parameters
pathAbsolute path to the generated AWK artifact.
STDIN
Nothing is read from STDIN.
STDOUT
Nothing is written to STDOUT.
STDERR
Verification-tool diagnostics are suppressed by this helper.
Returns
Nothing is written to STDOUT.
Return values
0The checksum exists and verifies successfully.
1The checksum is missing, no supported verifier exists, or verification fails.