Test

Summary

Defines the execution of an executable as a test.

Test( alias ) // (optional) Alias { // Options .TestExecutable // The executable file to run that will execute the tests .TestOutput // Output file for captured test output // Additional inputs .TestInput // (optional) Input file(s) to pass to executable .TestInputPath // (optional) Path to find files in .TestInputPattern // (optional) Pattern(s) to use when finding files (default *.*) .TestInputPathRecurse // (optional) Recurse into dirs when finding files (default true) .TestInputExcludePath // (optional) Path(s) to exclude .TestInputExcludedFiles // (optional) File(s) to exclude from compilation (partial, root-relative of full path) .TestInputExcludePattern // (optional) Pattern(s) to exclude // Other .TestArguments // (optional) Arguments to pass to test executable .TestWorkingDir // (optional) Working dir for test execution .TestTimeOut // (optional) TimeOut (in seconds) for test (default: 0, no timeout) .TestAlwaysShowOutput // (optional) Show output of tests even when they don't fail (default: false) // Additional options .PreBuildDependencies // (optional) Force targets to be built before this Test (Rarely needed, // but useful when Test relies on externally generated files). .Environment // (optional) Environment variables to use for local build // If set, linker uses this environment // If not set, linker uses .Environment from your Settings node }

Details

The Test function is used to create a target that is used to execute tests. It may depend on other FASTBuild targets via the .TestExecutable option.

When a test is run, its output (standard output and error channel) is captured and will be written to the file specified in .TestOutput. The captured output will not be shown directly (printed to FASTBuild's output) unless the test process has a non-zero return value. This is done in order to keep FASTBuild's output clean and reduce noise.

Options

.TestExecutable - String - (Required)

The executable file to run that will execute the tests.

Can either be a file path or the name of a target specified with the Executable function.

.TestOutput - String - (Required)

Output file for captured test output.

When executing tests, FASTBuild will capture standard output channels of the executable and write them to this file when done.

.TestArguments - String - (Optional)

Arguments to pass to test executable.

.TestWorkingDir - String - (Optional)

Working dir for test execution.

.TestTimeOut - Integer - (Optional)

The amount of time (in seconds) to wait for a test to finish execution.

The default is 0, which means there is no timeout and FASTBuild will wait until the executable terminates on its own.

.TestAlwaysShowOutput - Boolean - (Optional)

The output of a test is normally shown only when the test fails. This option specifies that the output should always be shown.

Additional Options

.PreBuildDependencies - String/ArrayOfStrings - (Optional)

One or more nodes which must be built before this test is executed.

The .PreBuildDependencies option ensures the specified targets are up-to-date before the Test() is executed.

.Environment - String or ArrayOfStrings - (Optional)

When set, overrides the environment for running a Test.

This allows you to have a different environment per Test if needed.

Simple Example

The following will produce a target MyCoreTests-Run that will excute the FASTBuild target called MyCoreTests-Exe. The usual FASTBuild rules apply; Whenever MyCoreTests-Exe is considered out-of-date, invoking MyCoreTests-Run will automatically build MyCoreTests-Exe. After MyCoreTests-Run was executed, the file "Tests/MyCoreTests_Output.txt" will contain the output, regardless of success or failure.

Test( 'MyCoreTests-Run' ) { .TestExecutable = 'MyCoreTests-Exe' // Must be previously defined, usually with Executable() .TestOutput = 'Tests/MyCoreTests_Output.txt' }