Run the Sway unit tests for the current project.
NOTE: Previously this command was used to support Rust integration testing, however the provided behaviour served no benefit over running cargo test directly. The proposal to change the behaviour to support unit testing can be found at the following link: https://github.com/FuelLabs/sway/issues/1833
Sway unit tests are functions decorated with the #[test] attribute. Each test is compiled as a unique entry point for a single program and has access to the namespace of the module in which it is declared.
Unit tests decorated with the #[test(script)] attribute that are declared within contractprojects may also call directly into their associated contract's ABI.
Upon successful compilation, test scripts are executed to their completion. A test is considered a failure in the case that a revert (rvrt) instruction is encountered during execution. Otherwise, it is considered a success.
forc test [OPTIONS] [--] [FILTER]
<FILTER> When specified, only tests containing the given string will be executed
--asm <ASM>..>
Print the generated ASM (assembler).
Possible values that can be combined: - virtual: initial ASM with virtual registers and abstract control flow. - allocated: ASM with registers allocated, but still with abstract control flow. - abstract: short for both virtual and allocated ASM. - final: final ASM that gets serialized to the target VM bytecode. - all: short for virtual, allocated, and final ASM.
[possible values: virtual, allocated, abstract, final, all]
--ast
Print the generated Sway AST (Abstract Syntax Tree)
--build-profile <BUILD_PROFILE>
The name of the build profile to use
[default: debug]
--build-target <BUILD_TARGET>
Build target to use for code generation
[default: fuel] [possible values: fuel, evm, midenvm]
--bytecode
Print the bytecode. This is the final output of the compiler
--dca-graph <DCA_GRAPH>
Print the computed Sway DCA graph. DCA graph is printed to the specified path. If specified '' graph is printed to stdout
--dca-graph-url-format <DCA_GRAPH_URL_FORMAT>
Specifies the url format to be used in the generated dot file. Variables {path}, {line} {col} can be used in the provided format. An example for vscode would be: "vscode://file/{path}:{line}:{col}"
--error-on-warnings
Treat warnings as errors
--filter-exact
When specified, only the test exactly matching the given string will be executed
-g, --output-debug <DEBUG_FILE>
Create a file containing debug information at the provided path. If the file extension is .json, JSON format is used. Otherwise, an ELF file containing DWARF is emitted
-h, --help
Print help information
--ipfs-node <IPFS_NODE>
The IPFS Node to use for fetching IPFS sources.
Possible values: PUBLIC, LOCAL, <GATEWAY_URL>
--ir
Print the generated Sway IR (Intermediate Representation)
--json-abi
By default the JSON for ABIs is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace
--json-abi-with-callpaths
Outputs json abi with callpaths instead of names for struct and enums
--json-storage-slots
By default the JSON for initial storage slots is formatted for human readability. By using this option JSON output will be "minified", i.e. all on one line without whitespace
-l, --logs
Print Log and LogData receipts for tests
-L, --log-level <LOG_LEVEL>
Set the log level
--locked
Requires that the Forc.lock file is up-to-date. If the lock file is missing, or it needs to be updated, Forc will exit with an error
--metrics-outfile <METRICS_OUTFILE>
Output compilation metrics into file
--no-encoding-v1
Disable the "new encoding" feature
-o, --output-bin <BIN_FILE>
Create a binary file representing the script bytecode at the provided path
--offline
Offline mode, prevents Forc from using the network when managing dependencies. Meaning it will only try to use previously downloaded dependencies
--output-directory <OUTPUT_DIRECTORY>
The directory in which the sway compiler output artifacts are placed.
By default, this is <project-root>/out.
-p, --path <PATH>
Path to the project, if not specified, current working directory will be used
-r, --pretty-print
Pretty-print the logs emitted from tests
--release
Use the release build profile. The release profile can be customized in the manifest file
--reverse-order
Output build errors and warnings in reverse order
-s, --silent
Silence all output
-t, --terse
Terse mode. Limited warning and error output
--test-threads <TEST_THREADS>
Number of threads to utilize when running the tests. By default, this is the number of threads available in your system
--time-phases
Output the time elapsed over each part of the compilation process
-v, --verbose
Use verbose output
-V, --version
Print version information
[33mEXAMPLES:[0m
forc test
forc test $filter
forc test --silent
forc test --locked