Run

NOTE: Previously this command was used to support Rust integration testing, however the provided behavior served no benefit over running cargo test directly. The proposal to change the behavior 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.

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, unless it is specified as #[test(should_revert)]. Otherwise, it is considered a success.

Usage: forc test [OPTIONS] [FILTER]

Arguments: [FILTER] When specified, only tests containing the given string will be executed

Options:

-p, --path <PATH>

Path to the project.

If not specified, current working directory will be used.

--offline

Offline mode.

Prevents Forc from using the network when managing dependencies. Meaning it will only try to use previously downloaded dependencies.

-t, --terse

Terse mode.

Limited warning and error output.

--output-directory <OUTPUT_DIRECTORY>

The directory in which Forc output artifacts are placed.

By default, this is <project-root>/out.

--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.

--ipfs-node <IPFS_NODE>

The IPFS node to use for fetching IPFS sources.

[possible values: FUEL, PUBLIC, LOCAL, <GATEWAY_URL>]

--ast

Print the generated Sway AST (Abstract Syntax Tree)

--dca-graph <DCA_GRAPH>

Print the computed Sway DCA (Dead Code Analysis) graph.

DCA graph is printed to the specified path. If specified '' graph is printed to the stdout.

--dca-graph-url-format <DCA_GRAPH_URL_FORMAT>

URL format to be used in the generated DCA graph .dot file.

Variables {path}, {line}, and {col} can be used in the provided format. An example for vscode would be: "vscode://file/{path}:{line}:{col}"

--asm <ASM>..>

Print the generated ASM (assembler).

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]

--bytecode

Print the bytecode.

This is the final output of the compiler.

--ir <IR>..>

Print the generated Sway IR (Intermediate Representation).

Values that can be combined:

initial: initial IR prior to any optimization passes.
final: final IR after applying all optimization passes.
: the name of an optimization pass. Prints the IR state after that pass.
all: short for initial, final, and all the optimization passes.
modified: print a requested optimization pass only if it has modified the IR.

[possible values: initial, final, all, modified, inline, simplify-cfg, sroa, dce, globals-dce, fn-dedup-release, fn-dedup-debug, mem2reg, memcpyopt, memcpyprop_reverse, const-folding, arg-demotion, const-demotion, ret-demotion, misc-demotion]

--time-phases

Output the time elapsed over each part of the compilation process

--profile

Profile the compilation process

--reverse-order

Output build errors and warnings in reverse order

--metrics-outfile <METRICS_OUTFILE>

Output compilation metrics into the specified file

-v, --verbose...

Use verbose output

--verify-ir <VERIFY_IR>..>

Verify the generated Sway IR (Intermediate Representation).

Values that can be combined:

initial: initial IR prior to any optimization passes.
final: final IR after applying all optimization passes.
: the name of an optimization pass. Verifies the IR state after that pass.
all: short for initial, final, and all the optimization passes.
modified: verify a requested optimization pass only if it has modified the IR.

--json-abi

Minify JSON ABI files.

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.

-s, --silent

Silence all output

--json-storage-slots

Minify JSON storage slot files.

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, --log-level <LOG_LEVEL>

Set the log level

-o, --output-bin <BIN_FILE>

Create a binary file at the provided path representing the final bytecode

-g, --output-debug <DEBUG_FILE>

Create a file at the provided path containing debug information.

If the file extension is .json, JSON format is used. Otherwise, an .elf file containing DWARF format is emitted.

--output-hexfile <HEX_FILE>

Generates a JSON file containing the hex-encoded script binary

--build-profile <BUILD_PROFILE>

The name of the build profile to use

[default: debug]

--release

Use the release build profile.

The release profile can be customized in the manifest file.

--error-on-warnings

Treat warnings as errors

--build-target <BUILD_TARGET>

Build target to use for code generation

[default: fuel] [possible values: fuel, evm]

--dump-impls <TYPE>

Dump all trait implementations for the given type name

--pretty

Pretty-print the logs emitted from tests

-l, --logs

Print decoded Log and LogData receipts for tests

--raw-logs

Print the raw logs for tests

--reverts

Print the revert information for tests

--dbgs

Print the output of debug ecals for tests

--filter-exact

When specified, only the test exactly matching the given string will be executed

--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

--experimental <EXPERIMENTAL>

Comma separated list of all experimental features that will be enabled

[possible values: new_encoding, references, const_generics, new_hashing]

--no-experimental <NO_EXPERIMENTAL>

Comma separated list of all experimental features that will be disabled

[possible values: new_encoding, references, const_generics, new_hashing]

--gas-costs <GAS_COSTS>

Source of the gas costs values used to calculate gas costs of test executions.

If not provided, a built-in set of gas costs values will be used. These are the gas costs values of the Fuel mainnet as of time of the release of the forc version being used.

The mainnet and testnet options will fetch the current gas costs values from their respective networks.

Alternatively, the gas costs values can be specified as a file path to a local JSON file containing the gas costs values.

[possible values: built-in, mainnet, testnet, <FILE_PATH>]

-h, --help

Print help (see a summary with '-h')

-V, --version

Print version

EXAMPLES: