forge snapshot
Create a gas snapshot of each test's gas usage
$ forge snapshot --helpUsage: forge snapshot [OPTIONS] [PATH]
Options:
--diff [<SNAPSHOT_FILE>]
Output a diff against a pre-existing gas snapshot.
By default, the comparison is done with .gas-snapshot.
--check [<SNAPSHOT_FILE>]
Compare against a pre-existing gas snapshot, exiting with code 1 if
they do not match.
Outputs a diff if the gas snapshots do not match.
By default, the comparison is done with .gas-snapshot.
--snap <FILE>
Output file for the gas snapshot
[default: .gas-snapshot]
--tolerance <SNAPSHOT_THRESHOLD>
Tolerates gas deviations up to the specified percentage
--diff-sort <ORDER>
How to sort diff results
Possible values:
- percentage: Sort by percentage change (smallest to largest) -
default behavior
- percentage-desc: Sort by percentage change (largest to smallest)
- absolute: Sort by absolute gas change (smallest to largest)
- absolute-desc: Sort by absolute gas change (largest to smallest)
-h, --help
Print help (see a summary with '-h')
Display options:
-v, --verbosity...
Verbosity level of the log messages.
Pass multiple times to increase the verbosity (e.g. -v, -vv, -vvv).
Depending on the context the verbosity levels have different meanings.
For example, the verbosity levels of the EVM are:
- 2 (-vv): Print logs for all tests.
- 3 (-vvv): Print execution traces for failing tests.
- 4 (-vvvv): Print execution traces for all tests, and setup traces
for failing tests.
- 5 (-vvvvv): Print execution and setup traces for all tests,
including storage changes.
-q, --quiet
Do not print log messages
--json
Format log messages as JSON
--md
Format log messages as Markdown
--color <COLOR>
The color of the log messages
Possible values:
- auto: Intelligently guess whether to use color output (default)
- always: Force color output
- never: Force disable color output
-s, --suppress-successful-traces
Suppress successful test traces and show only traces for failures
[env: FORGE_SUPPRESS_SUCCESSFUL_TRACES=]
--junit
Output test results as JUnit XML report
-l, --list
List tests instead of running them
--show-progress
Show test execution progress
--summary
Print test summary table
--detailed
Print detailed test summary table
--disable-labels
Disables the labels in the traces
Test options:
-j, --threads <THREADS>
Number of threads to use. Specifying 0 defaults to the number of
logical cores
[aliases: --jobs]
--debug
Run a single test in the debugger.
The matching test will be opened in the debugger regardless of the
outcome of the test.
If the matching test is a fuzz test, then it will open the debugger on
the first failure case. If the fuzz test does not fail, it will open
the debugger on the last fuzz case.
--flamegraph
Generate a flamegraph for a single test. Implies `--decode-internal`.
A flame graph is used to visualize which functions or operations
within the smart contract are consuming the most gas overall in a
sorted manner.
--flamechart
Generate a flamechart for a single test. Implies `--decode-internal`.
A flame chart shows the gas usage over time, illustrating when each
function is called (execution order) and how much gas it consumes at
each point in the timeline.
--decode-internal
Identify internal functions in traces.
This will trace internal functions and decode stack parameters.
Parameters stored in memory (such as bytes or arrays) are currently
decoded only when a single function is matched, similarly to
`--debug`, for performance reasons.
--dump <PATH>
Dumps all debugger steps to file
--gas-report
Print a gas report
[env: FORGE_GAS_REPORT=]
--gas-snapshot-check <GAS_SNAPSHOT_CHECK>
Check gas snapshots against previous runs
[env: FORGE_SNAPSHOT_CHECK=]
[possible values: true, false]
--gas-snapshot-emit <GAS_SNAPSHOT_EMIT>
Enable/disable recording of gas snapshot results
[env: FORGE_SNAPSHOT_EMIT=]
[possible values: true, false]
--allow-failure
Exit with code 0 even if a test fails
[env: FORGE_ALLOW_FAILURE=]
--fail-fast
Stop running tests after the first failure
--etherscan-api-key <KEY>
The Etherscan (or equivalent) API key
[env: ETHERSCAN_API_KEY=]
--fuzz-seed <FUZZ_SEED>
Set seed used to generate randomness during your fuzz runs
--fuzz-runs <RUNS>
[env: FOUNDRY_FUZZ_RUNS=]
--fuzz-timeout <TIMEOUT>
Timeout for each fuzz run in seconds
[env: FOUNDRY_FUZZ_TIMEOUT=]
--fuzz-input-file <FUZZ_INPUT_FILE>
File to rerun fuzz failures from
--rerun
Re-run recorded test failures from last run. If no failure recorded
then regular test run is performed
[PATH]
The contract file you want to test, it's a shortcut for --match-path
Test filtering:
--match-test <REGEX>
Only run test functions matching the specified regex pattern
[aliases: --mt]
--no-match-test <REGEX>
Only run test functions that do not match the specified regex pattern
[aliases: --nmt]
--match-contract <REGEX>
Only run tests in contracts matching the specified regex pattern
[aliases: --mc]
--no-match-contract <REGEX>
Only run tests in contracts that do not match the specified regex
pattern
[aliases: --nmc]
--match-path <GLOB>
Only run tests in source files matching the specified glob pattern
[aliases: --mp]
--no-match-path <GLOB>
Only run tests in source files that do not match the specified glob
pattern
[aliases: --nmp]
--no-match-coverage <REGEX>
Only show coverage for files that do not match the specified regex
pattern
[aliases: --nmco]
EVM options:
-f, --fork-url <URL>
Fetch state over a remote endpoint instead of starting from an empty
state.
If you want to fetch state from a specific block number, see
--fork-block-number.
[aliases: --rpc-url]
--fork-block-number <BLOCK>
Fetch state from a specific block number over a remote endpoint.
See --fork-url.
--fork-retries <RETRIES>
Number of retries.
See --fork-url.
--fork-retry-backoff <BACKOFF>
Initial retry backoff on encountering errors.
See --fork-url.
--no-storage-caching
Explicitly disables the use of RPC caching.
All storage slots are read entirely from the endpoint.
This flag overrides the project's configuration file.
See --fork-url.
--initial-balance <BALANCE>
The initial balance of deployed test contracts
--sender <ADDRESS>
The address which will be executing tests/scripts
--ffi
Enable the FFI cheatcode
--always-use-create-2-factory
Use the create 2 factory in all cases including tests and
non-broadcasting scripts
--create2-deployer <ADDRESS>
The CREATE2 deployer address to use, this will override the one in the
config
Fork config:
--compute-units-per-second <CUPS>
Sets the number of assumed available compute units per second for this
provider
default value: 330
See also --fork-url and
[https://docs.alchemy.com/reference/compute-units#what-are-cups-compute-units-per-second](https://docs.alchemy.com/reference/compute-units#what-are-cups-compute-units-per-second)
--no-rpc-rate-limit
Disables rate limiting for this node's provider.
See also --fork-url and
[https://docs.alchemy.com/reference/compute-units#what-are-cups-compute-units-per-second](https://docs.alchemy.com/reference/compute-units#what-are-cups-compute-units-per-second)
[aliases: --no-rate-limit]
Executor environment config:
--code-size-limit <CODE_SIZE>
EIP-170: Contract code size limit in bytes. Useful to increase this
because of tests. By default, it is 0x6000 (~25kb)
--chain <CHAIN>
The chain name or EIP-155 chain ID
[aliases: --chain-id]
--gas-price <GAS_PRICE>
The gas price
--block-base-fee-per-gas <FEE>
The base fee in a block
[aliases: --base-fee]
--tx-origin <ADDRESS>
The transaction origin
--block-coinbase <ADDRESS>
The coinbase of the block
--block-timestamp <TIMESTAMP>
The timestamp of the block
--block-number <BLOCK>
The block number
--block-difficulty <DIFFICULTY>
The block difficulty
--block-prevrandao <PREVRANDAO>
The block prevrandao value. NOTE: Before merge this field was mix_hash
--block-gas-limit <BLOCK_GAS_LIMIT>
The block gas limit
[aliases: --block-gas-limit, --gas-limit]
--memory-limit <MEMORY_LIMIT>
The memory limit per EVM execution in bytes. If this limit is
exceeded, a `MemoryLimitOOG` result is thrown.
The default is 128MiB.
--disable-block-gas-limit
Whether to disable the block gas limit checks
[aliases: --no-block-gas-limit, --no-gas-limit]
--enable-tx-gas-limit
Whether to enable tx gas limit checks as imposed by Osaka (EIP-7825)
[aliases: --tx-gas-limit]
--isolate
Whether to enable isolation of calls. In isolation mode all top-level
calls are executed as a separate transaction in a separate EVM
context, enabling more precise gas accounting and transaction state
changes
Cache options:
--force
Clear the cache and artifacts folder and recompile
Build options:
--no-cache
Disable the cache
--dynamic-test-linking
Enable dynamic test linking
--skip <SKIP>...
Skip building files whose names contain the given filter.
`test` and `script` are aliases for `.t.sol` and `.s.sol`.
Linker options:
--libraries <LIBRARIES>
Set pre-linked libraries
[env: DAPP_LIBRARIES=]
Compiler options:
--ignored-error-codes <ERROR_CODES>
Ignore solc warnings by error code
-D, --deny <LEVEL>
A compiler error will be triggered at the specified diagnostic level.
Replaces the deprecated `--deny-warnings` flag.
Possible values: - `never`: Do not treat any diagnostics as errors. -
`warnings`: Treat warnings as errors. - `notes`: Treat both, warnings
and notes, as errors.
Possible values:
- never: Always exit with zero code
- warnings: Exit with a non-zero code if any warnings are found
- notes: Exit with a non-zero code if any notes or warnings are
found
--no-auto-detect
Do not auto-detect the `solc` version
--use <SOLC_VERSION>
Specify the solc version, or a path to a local solc, to build with.
Valid values are in the format `x.y.z`, `solc:x.y.z` or
`path/to/solc`.
--offline
Do not access the network.
Missing solc versions will not be installed.
--via-ir
Use the Yul intermediate representation compilation pipeline
--use-literal-content
Changes compilation to only use literal content and not URLs
--no-metadata
Do not append any metadata to the bytecode.
This is equivalent to setting `bytecode_hash` to `none` and
`cbor_metadata` to `false`.
--ast
Includes the AST as JSON in the compiler output
--evm-version <VERSION>
The target EVM version
--optimize [<OPTIMIZE>]
Activate the Solidity optimizer
[possible values: true, false]
--optimizer-runs <RUNS>
The number of runs specifies roughly how often each opcode of the
deployed code will be executed across the life-time of the contract.
This means it is a trade-off parameter between code size (deploy cost)
and code execution cost (cost after deployment). An `optimizer_runs`
parameter of `1` will produce short but expensive code. In contrast, a
larger `optimizer_runs` parameter will produce longer but more gas
efficient code
--extra-output <SELECTOR>...
Extra output to include in the contract's artifact.
Example keys: evm.assembly, ewasm, ir, irOptimized, metadata
For a full description, see
[https://docs.soliditylang.org/en/v0.8.13/using-the-compiler.html#input-description](https://docs.soliditylang.org/en/v0.8.13/using-the-compiler.html#input-description)
--extra-output-files <SELECTOR>...
Extra output to write to separate files.
Valid values: metadata, ir, irOptimized, ewasm, evm.assembly
Project options:
-o, --out <PATH>
The path to the contract artifacts folder
--revert-strings <REVERT>
Revert string configuration.
Possible values are "default", "strip" (remove), "debug"
(Solidity-generated revert strings) and "verboseDebug"
--build-info
Generate build info files
--build-info-path <PATH>
Output path to directory that build info files will be written to
--root <PATH>
The project's root path.
By default root of the Git repository, if in one, or the current
working directory.
-C, --contracts <PATH>
The contracts source directory
-R, --remappings <REMAPPINGS>
The project's remappings
--remappings-env <ENV>
The project's remappings from the environment
--cache-path <PATH>
The path to the compiler cache
--lib-paths <PATH>
The path to the library folder
--hardhat
Use the Hardhat-style project layout.
This is the same as using: `--contracts contracts --lib-paths
node_modules`.
[aliases: --hh]
--config-path <FILE>
Path to the config file
Watch options:
-w, --watch [<PATH>...]
Watch the given files or directories for changes.
If no paths are provided, the source and test directories of the
project are watched.
--no-restart
Do not restart the command while it's still running
--run-all
Explicitly re-run all tests when a change is made.
By default, only the tests of the last modified test file are
executed.
--rerun-failed
Re-run only previously failed tests first when a change is made.
If all previously failed tests pass, the full test suite will be run
automatically. This is particularly useful for TDD workflows where you
want fast feedback on failures.
--watch-delay <DELAY>
File update debounce delay.
During the delay, incoming change events are accumulated and only once
the delay has passed, is an action taken. Note that this does not mean
a command will be started: if --no-restart is given and a command is
already running, the outcome of the action will be to do nothing.
Defaults to 50ms. Parses as decimal seconds by default, but using an
integer with the `ms` suffix may be more convenient.
When using --poll mode, you'll want a larger duration, or risk
overloading disk I/O.
--asc
Sort results by gas used (ascending)
--desc
Sort results by gas used (descending)
--min <MIN_GAS>
Only include tests that used more gas that the given amount
--max <MAX_GAS>
Only include tests that used less gas that the given amount