TestFile
TestFile[symbol]
gives a test file associated with symbol.
TestFile["symbol"]
gives a test file associated with the symbol named symbol.
TestFile["symbol/name"]
gives a test file associated with symbol and categorized according to name.
TestFile[{PacletObject[…],…,"name"}]
gives a test file in a paclet that has been categorized according to name.
Details and Options
- TestFile returns a File[…] representation of a test file.
- TestFile[symbol] resolves to a file of the form File["root/symbol/core.wlt"] or File["root/symbol/core.nb"].
- TestFile["symbol/name"] resolves to a file of the form File["root/symbol/name.wlt"] or File["root/symbol/name.nb"] .
- TestFile[PacletObject[…], …, "name"] resolves to a file of the form File["root/ … /name.wlt"] or File["root/ … /name.nb"] .
- Whether a test file with extension .wlt or .nb is returned depends on the "TestFileExtension" option.
- When TestFile["spec"] returns a file of the form File["root/ …"], the root directory resolves to the "TestFiles" directory in the paclet extracted from spec.
- In TestFile["spec"] , the relevant "TestFiles" directory of the paclet extracted from "spec" appears in its PacletInfo.wl file with Extensions key, {"TestFiles","Root""TestFiles"}.
- TestFile["…/name.wlt"] is equivalent to TestFile["…/name","TestFileExtension"".wlt"].
- TestFile["…/name.nb"] is equivalent to TestFile["…/name","TestFileExtension"".nb"].
- If TestFile[".../dir"] has dir as a directory, it returns a file of the form File["…/dir/core.wlt"] or File["…/dir/core.nb"] depending on the "TestFileExtension" option.
- TestSummary and TestReport can be applied to the file returned by TestFile.
- TestSummary[TestFile["spec"]] can be abbreviated to TestSummary["spec"] when spec resolves to a test file location.
- In TestFile["symbol/dir/ …/name"] more finely granulated test file categorizations are supported.
- TestFile["symbol/dir1/dir2/…"] is equivalent to TestFile[{symbol, dir1,dir2, …}].
- TestFile[{paclet,"dir1/dir2/ …"}] is equivalent to TestFile[{paclet,dir1,dir2, …}].
- TestFile[File["…/name.ext"]] returns File["…/name.ext"] if ext is either .nb or .wlt.
- The list of all implicit TestFiles directories defined by all paclets is returned by PacletManager`PacletResources["TestFiles"].
- TestFile returns $Failed if it cannot find a file with the specified name and location.
- The following options can be given:
-
"TestFileExtension" Automatic specifies the test file extension to search for - Possible settings for "TestFileExtension" include:
-
".wlt" search only for a test file with extension .wlt ".nb" search only for a test file with extension .nb {".wlt",".nb"} search first for a test file with extension .wlt and failing this search for one with extension .nb {".nb",".wlt"} search first for a test file with extension .nb and failing this search for one with extension .wlt Automatic equivalent to the setting {".wlt", ".nb"} - TestFile["name.ext"] is equivalent to TestFile["name","TestFileExtension"ext].
Examples
Basic Examples (1)
Show TestFile's core tests.
Run and generate a test summary of core tests
Show TestFile's exception-handling tests
Run and generate a test summary of exception-handling tests
Access a test file with a more finely-granulated categorization here involving core tests that use the HandlerFunctions option of TestSummary.
Run and generate a test summary of handler function tests.
A convenient syntax when applying TestSummary to the output of TestFile can be obtained by feeding its file-specification directly to TestSummary
Test files in .wlt form are generally efficient to run: time a running of the previous test suite:
In contrast, although convenient for storing and managing tests, running corresponding.nb test files is generally less efficient. For this reason, corresponding .nb test file are not installed in CodeAssurance although here, the original core.nb file corresponding to "TestSummary/Handler" has been included as an asset for illustrative purposes.
Running the corresponding .nb test file produces the same output but is less efficient as it needs to first extract the tests from the notebook.
The .nb test file also has a considerably larger memory footprint than its .wlt counterpart.
Consequently, best practice workflows suggests organizing and managing test files as .nb test files during development but when it comes to running and shipping test files, using their .wlt counterparts.