Skip to content

Tests Functions

🛠️ Tools · ⬅ Top

validateFileExtensionContents

Check files for the existence of a string

Usage

validateFileExtensionContents extension0 [ extension1 ... ] -- text0 [ text1 ... ] [ -- findArgs ]

Search for item extensions and ensure that text is found in each item.

This can be run on any directory tree to test files in any application.

By default, any directory which begins with a dot . will be ignored.

Side-effect: Errors written to stderr, status written to stdout Return Code: 0 - All found files contain all text strings Return Code: 1 - One or more files does not contain all text strings Return Code: 2 - Arguments error (missing extension or text)

Arguments

  • extension0 - Required - the extension to search for (*.extension)
  • -- - Required. Separates extensions from text
  • text0 - Required. Text which must exist in each item with the extension given.
  • -- - Optional. Final delimiter to specify find arguments.
  • findArgs - Optional. Limit find to additional conditions.

Examples

validateFileContents sh php js -- 'Widgets LLC' 'Copyright © 2026'

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

  • This operates in the current working directory

validateFileContents

Check files for the existence of a string or strings

Usage

validateFileContents file0 [ file1 ... ] -- text0 [ text1 ... ]

Search for item extensions and ensure that text is found in each item.

This can be run on any directory tree to test files in any application.

By default, any directory which begins with a dot . will be ignored.

Side-effect: Errors written to stderr, status written to stdout Return Code: 0 - All found files contain all text string or strings Return Code: 1 - One or more files does not contain all text string or strings Return Code: 2 - Arguments error (missing extension or text)

Arguments

  • file0 - Required - a item to look for matches in. Use - to read file list from stdin.
  • -- - Required. Separates files from text
  • text0 - Required. Text which must exist in each item

Examples

validateFileContents foo.sh my.sh -- "Copyright 2024" "Company, LLC"

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

evalCheck

Check files to ensure evals in code have been checked

Usage

evalCheck

Check files to ensure evals in code have been checked

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

findUncaughtAssertions

Search bash files for assertions which do not terminate a

Usage

findUncaughtAssertions [ --help ] [ --handler handler ] [ --exec binary ] [ directory ] [ --list ]

Search bash files for assertions which do not terminate a function and are likely an error

Arguments

  • --help - Optional. Flag. Display this help.
  • --handler handler - Optional. Function. Use this error handler instead of the default error handler.
  • --exec binary - Executable. Optional. For each failed file run this command.
  • directory - Directory. Optional. Where to search for files to check.
  • --list - Flag. Optional. List files which fail. (Default is simply to exit silently.)

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Test Subsystem

testTools

Load test tools and make testSuite function available

Usage

testTools [ --help ] [ binary ] [ ... ]

Load test tools and make testSuite function available

Arguments

  • --help - Optional. Flag. Display this help.
  • binary - Optional. Callable. Run this program after loading test tools.
  • ... - Optional. Arguments for binary.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Tag filters

Prefix a tag with + for --tag or --skip-tag queries to add the meaning "previous AND".

  • --tag foo --tag bar means tests must have foo tag OR must have bar tag
  • --tag foo --tag +bar means tests must have foo tag AND must have bar tag (must have both)
  • --skip-tag foo --skip-tag bar means skip any test with foo tag OR with any test with bar tag (either)
  • --skip-tag foo --skip-tag +bar means skip any test with foo tag AND with the bar tag (must have both)
  • --tag a --tag +b --tag c --tag +d --tag +e is (a and b) or (c and d and e)

Filters (--tag and --skip-tag) are applied in order after the function pattern or suite filter.

Arguments

  • --help - Optional. This help.
  • --clean - Optional. Delete test artifact files and exit. (No tests run)
  • --list - Optional. Flag. List all test names (which match if applicable).
  • --env-file environmentFile - Optional. EnvironmentFile. Load one ore more environment files prior to running tests
  • --continue - Optional. Flag. Continue from last successful test.
  • -c - Optional. Flag. Continue from last successful test.
  • --delete directoryOrFile - Optional. FileDirectory. A file or directory to delete when the test suite terminates.
  • --delete-common - Flag. Delete ./vendor and ./node_modules (and other temporary build directories) by default.
  • --verbose - Optional. Flag. Be verbose.
  • --coverage - Optional. Flag. Feature in progress - generate a coverage file for tests.
  • --no-stats - Optional. Flag. Do not generate a test.stats file showing test timings when completed.
  • --messy - Optional. Do not delete test artifact files afterwards.
  • --fail executor - Optional. Callable. One or more programs to run on the failed test files. Takes arguments: testName testFile testLine
  • --cd-away - Optional. Flag. Change directories to a temporary directory before each test.
  • --tap tapFile - Optional. FileDirectory. Output test results in TAP format to tapFile.
  • --show - Optional. Flag. List all test suites.
  • -l - Optional. Flag. List all test suites.
  • --one testSuite - Optional. Add one test suite to run. (Synonym for --suite)
  • --suite testSuite - Optional. Add one test suite to run.
  • -1 testSuite - Optional. Add one test suite to run. (Synonym for --suite)
  • --tag tagName - Optional. String. Include tests (only) tagged with this name.
  • --show-tags - Optional. Flag. Of the matched tests, display the tags that they have, if any. Unique list.
  • --skip-tag tagName - Optional. String. Skip tests tagged with this name.
  • testFunctionPattern - Optional. String. Test function (or substring of function name) to run.

Debugging settings

Append to the value of BUILD_DEBUG (a comma-delimited (,) list) and add these tokens to enable debugging:

  • test-dump-environment - When set tests will dump the environment at the end.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

Environment

    • BUILD_TEST_FLAGS - Modify default flags and test behavior.
    • BUILD_DEBUG - Many settings to debug different systems, comma-delimited.

Requires

head tee printf trap decorate loadAverage consoleConfigureColorMode buildEnvironmentLoad usageArgumentString catchEnvironment bashCoverage

Mocking help

mockEnvironmentStart

Fake a value for testing

Usage

mockEnvironmentStart globalName [ value ] [ ... ]

Fake a value for testing

Arguments

  • globalName - EnvironmentVariable. Required. Global to change temporarily to a value.
  • value - EmptyString. Optional. Force the value of globalName to this value temporarily. Saves the original value.
  • ... - Continue passing pairs of globalName value to mock additional values.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

mockEnvironmentStop

Restore a mocked value. Works solely with the default saveGlobalName

Arguments

  • --help - Optional. Flag. Display this help.
  • globalName ... - EnvironmentVariable. Required. Global to restore from the mocked saved value.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

mockConsoleAnimationStart

Fake hasConsoleAnimation for testing

Usage

mockConsoleAnimationStart [ true | false ]

Fake hasConsoleAnimation for testing Developer Note: Keep this here to keep it close to the definition it modifies

Arguments

  • true |- false - Boolean. Force the value of hasConsoleAnimation to this value temporarily. Saves the original value.

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error

mockConsoleAnimationStop

Stop faking hasConsoleAnimation for testing

Usage

mockConsoleAnimationStop

Stop faking hasConsoleAnimation for testing

Arguments

  • none

Return codes

  • 0 - Success
  • 1 - Environment error
  • 2 - Argument error