Foundry Book

forge snapshot

NAME

forge-snapshot - Create a snapshot of each test’s gas usage.

DESCRIPTION

Create a snapshot of each test’s gas usage.

The results are written to a file named .gas-snapshot. You can change the name of the file by passing --snap <PATH>.

Fuzz tests are included by default in the snapshot. They use a static seed to achieve deterministic results.

Snapshots can be compared with --diff and --check. The first flag will output a diff, and the second will output a diff and exit with code 1 if the snapshots do not match.

OPTIONS

Snapshot Options

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

--tolerance threshold
Tolerates gas deviations up to the specified percentage (0-100).

--diff path
Output a diff against a pre-existing snapshot.

By default the comparison is done with .gas-snapshot.

--check path
Compare against a pre-existing snapshot, exiting with code 1 if they do not match.

Outputs a diff if the snapshots do not match.

By default the comparison is done with .gas-snapshot.

--snap path
Output file for the snapshot. Default: .gas-snapshot.

Test Options

-m regex
--match regex
Only run test functions matching the specified regex pattern.
Deprecated: See --match-test.

--match-test regex
Only run test functions matching the specified regex pattern.

--no-match-test regex
Only run test functions that do not match the specified regex pattern.

--match-contract regex
Only run tests in contracts matching the specified regex pattern.

--no-match-contract regex
Only run tests in contracts that do not match the specified regex pattern.

--match-path glob
Only run tests in source files matching the specified glob pattern.

--no-match-path glob
Only run tests in source files that do not match the specified glob pattern.

--debug regex
Run a test in the debugger.

The argument passed to this flag is the name of the test function you want to run, and it works the same as --match-test.

If more than one test matches your specified criteria, you must add additional filters until only one test is found (see --match-contract and --match-path).

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.

--gas-report
Print a gas report.

--allow-failure
Exit with code 0 even if a test fails.

--fail-fast
Stop running tests after the first failure.

--etherscan-api-key key
Etherscan API key. If set, traces are decoded using Etherscan if --fork-url is also set.
Environment: ETHERSCAN_API_KEY

EVM Options

-f url
--rpc-url url
--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.

--fork-block-number block
Fetch state from a specific block number over a remote endpoint. See --fork-url.

--fork-retry-backoff <BACKOFF>
Initial retry backoff on encountering errors.

--no-storage-caching
Explicitly disables the use of RPC caching.

All storage slots are read entirely from the endpoint. See --fork-url.

-v
--verbosity
Verbosity of the EVM.

Pass multiple times to increase the verbosity (e.g. -v, -vv, -vvv).

    Verbosity levels:
    - 2: Print logs for all tests
    - 3: Print execution traces for failing tests
    - 4: Print execution traces for all tests, and setup traces for failing tests
    - 5: Print execution and setup traces for all tests

--sender address
The address which will be executing tests

--initial-balance balance
The initial balance of deployed contracts

--ffi
Enables the FFI cheatcode

Executor Options

--base-fee <FEE>
--block-base-fee-per-gas <FEE>
The base fee in a block (in wei).

--block-coinbase address
The coinbase of the block.

--block-difficulty difficulty
The block difficulty.

--block-gas-limit gas_limit
The block gas limit.

--block-number block
The block number.

--block-timestamp timestamp
The timestamp of the block (in seconds).

--chain-id chain_id
The chain ID.

--gas-limit gas_limit
The block gas limit.

--gas-price gas_price
The gas price (in wei).

--tx-origin address
The transaction origin.

Cache Options

--force
Clear the cache and artifacts folder and recompile.

Linker Options

--libraries libraries
Set pre-linked libraries.

The parameter must be in the format <remapped path to lib>:<library name>:<address>, e.g. src/Contract.sol:Library:0x....

Can also be set in your configuration file as libraries = ["<path>:<lib name>:<address>"].

Compiler Options

--optimize
Activate the Solidity optimizer.

--optimizer-runs runs
The number of optimizer runs.

--via-ir
Use the Yul intermediate representation compilation pipeline.

--revert-strings
How to treat revert and require reason strings.

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

--no-auto-detect
Do not auto-detect solc.

--ignored-error-codes error_codes
Ignore solc warnings by error code. The parameter is a comma-separated list of error codes.

--extra-output selector
Extra output to include in the contract's artifact.

Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

For a full description, see the Solidity docs.

--extra-output-files selector
Extra output to write to separate files.

Example keys: abi, storageLayout, evm.assembly, ewasm, ir, ir-optimized, metadata.

For a full description, see the Solidity docs.

--evm-version version
The target EVM version.

Project Options

--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, this is the root directory of the current git repository, or the current working directory.

-C path
--contracts path
The contracts source directory.
Environment: DAPP_SRC

--lib-paths path
The path to the library folder.

-R remappings
--remappings remappings
The project's remappings.

The parameter is a comma-separated list of remappings in the format <source>=<dest>.

--cache-path path
The path to the compiler cache.

--config-path file
Path to the config file.

--hh
--hardhat
This is a convenience flag, and is the same as passing --contracts contracts --lib-paths node-modules.

-o path
--out path
The project's artifacts directory.

--silent
Suppress all output.

Create a snapshot:
```
forge snapshot
```
Generate a diff:
```
forge snapshot --diff
```
Check that the snapshots match:
```
forge snapshot --check
```