## Testing

Configuration related to the behavior of `forge test`.

**Sections**

* [General](#general)
* [Fuzz](#fuzz)
* [Invariant](#invariant)

### General

##### `verbosity`

* Type: integer
* Default: 0
* Environment: `FOUNDRY_VERBOSITY` or `DAPP_VERBOSITY`

The verbosity level to use during tests.

* **Level 2 (`-vv`)**: Logs emitted during tests are also displayed.
* **Level 3 (`-vvv`)**: Stack traces for failing tests are also displayed.
* **Level 4 (`-vvvv`)**: Stack traces for all tests are displayed, and setup traces for failing tests are displayed.
* **Level 5 (`-vvvvv`)**: Stack traces and setup traces are always displayed.

##### `ffi`

* Type: boolean
* Default: false
* Environment: `FOUNDRY_FFI` or `DAPP_FFI`

Whether or not to enable the `ffi` cheatcode.

**Warning:** Enabling this cheatcode has security implications for your project, as it allows tests to execute arbitrary programs on your computer.

##### `sender`

* Type: string (address)
* Default: 0x1804c8AB1F12E6bbf3894d4083f33e07309d1f38
* Environment: `FOUNDRY_SENDER` or `DAPP_SENDER`

The value of `msg.sender` in tests.

##### `tx_origin`

* Type: string (address)
* Default: 0x1804c8AB1F12E6bbf3894d4083f33e07309d1f38
* Environment: `FOUNDRY_TX_ORIGIN` or `DAPP_TX_ORIGIN`

The value of `tx.origin` in tests.

##### `initial_balance`

* Type: string (hexadecimal)
* Default: 0xffffffffffffffffffffffff
* Environment: `FOUNDRY_INITIAL_BALANCE` or `DAPP_INITIAL_BALANCE`

The initial balance of the test contracts in wei, written in hexadecimal.

##### `block_number`

* Type: integer
* Default: 1
* Environment: `FOUNDRY_BLOCK_NUMBER` or `DAPP_BLOCK_NUMBER`

The value of `block.number` in tests.

##### `chain_id`

* Type: integer
* Default: 31337
* Environment: `FOUNDRY_CHAIN_ID` or `DAPP_CHAIN_ID`

The value of the `chainid` opcode in tests.

##### `network`

* Type: string
* Default: none
* Environment: `FOUNDRY_NETWORK`

Selects the active non-Ethereum network family for tests, scripts, and local execution.

Valid values include:

* `optimism`
* `tempo`

Use this when Foundry is not forking a live RPC endpoint and therefore cannot infer the network from chain ID. Foundry still accepts the legacy boolean forms such as `optimism = true` and `tempo = true`.

```toml
[profile.default]
network = "tempo"
```

##### `hardfork`

* Type: string
* Default: none
* Environment: `FOUNDRY_HARDFORK`

Sets the runtime hardfork for tests and scripts.

This can be either:

* A plain Ethereum hardfork such as `osaka` or `cancun`
* A namespaced hardfork such as `optimism:holocene` or `tempo:T3`

When you use a namespaced hardfork, Foundry also infers the matching network automatically.

```toml
[profile.default]
hardfork = "tempo:T3"
```

##### `gas_limit`

* Type: integer or string
* Default: 1073741824
* Environment: `FOUNDRY_GAS_LIMIT` or `DAPP_GAS_LIMIT`

The gas limit for each test case.

> ℹ️ **Note**
>
> Due to a limitation in a dependency of Forge, you **cannot raise the gas limit** beyond the default without changing the value to a string.
>
> In order to use higher gas limits use a string:

```toml
gas_limit = "9223372036854775807" # limited to 64-bit integers
```

##### `gas_price`

* Type: integer
* Default: 0
* Environment: `FOUNDRY_GAS_PRICE` or `DAPP_GAS_PRICE`

The price of gas (in wei) in tests.

##### `block_base_fee_per_gas`

* Type: integer
* Default: 0
* Environment: `FOUNDRY_BLOCK_BASE_FEE_PER_GAS` or `DAPP_BLOCK_BASE_FEE_PER_GAS`

The base fee per gas (in wei) in tests.

##### `block_coinbase`

* Type: string (address)
* Default: 0x0000000000000000000000000000000000000000
* Environment: `FOUNDRY_BLOCK_COINBASE` or `DAPP_BLOCK_COINBASE`

The value of `block.coinbase` in tests.

##### `block_timestamp`

* Type: integer
* Default: 1
* Environment: `FOUNDRY_BLOCK_TIMESTAMP` or `DAPP_BLOCK_TIMESTAMP`

The value of `block.timestamp` in tests.

##### `block_difficulty`

* Type: integer
* Default: 0
* Environment: `FOUNDRY_BLOCK_DIFFICULTY` or `DAPP_BLOCK_DIFFICULTY`

The value of `block.difficulty` in tests.

##### `gas_reports`

* Type: array of strings (contract names)
* Default: \["\*"]
* Environment: `FOUNDRY_GAS_REPORTS` or `DAPP_GAS_REPORTS`

The contracts to print gas reports for.

##### `no_storage_caching`

* Type: boolean
* Default: false
* Environment: `FOUNDRY_NO_STORAGE_CACHING` or `DAPP_NO_STORAGE_CACHING`

If set to `true`, then block data from RPC endpoints in tests will not be cached. Otherwise, the data is cached to `$HOME/.foundry/cache/<chain id>/<block number>`.

##### `[rpc_storage_caching]`

The `[rpc_storage_caching]` block determines what RPC endpoints are cached.

###### `rpc_storage_caching.chains`

* Type: string or array of strings (chain names)
* Default: all
* Environment: N/A

Determines what chains are cached. By default, all chains are cached.

Valid values are:

* "all"
* A list of chain names, e.g. `["optimism", "mainnet"]`

###### `rpc_storage_caching.endpoints`

* Type: string or array of regex patterns (to match URLs)
* Default: remote
* Environment: N/A

Determines what RPC endpoints are cached. By default, only remote endpoints are cached.

Valid values are:

* all
* remote (default)
* A list of regex patterns, e.g. `["localhost"]`

##### `eth_rpc_url`

* Type: string
* Default: none
* Environment: `FOUNDRY_ETH_RPC_URL` or `DAPP_ETH_RPC_URL`

The url of the rpc server that should be used for any rpc calls.

##### `etherscan_api_key`

* Type: string
* Default: none
* Environment: `FOUNDRY_ETHERSCAN_API_KEY` or `DAPP_ETHERSCAN_API_KEY`

The etherscan API key for RPC calls.

##### `match-test`

* Type: regex
* Default: none
* Environment: `FOUNDRY_MATCH_TEST` or `DAPP_MATCH_TEST`

Only run test methods matching regex.
Equivalent to `forge test --match-test <TEST_PATTERN>`

##### `no-match-test`

* Type: regex
* Default: none
* Environment: `FOUNDRY_NO_MATCH_TEST` or `DAPP_NO_MATCH_TEST`

Only run test methods not matching regex.
Equivalent to `forge test --no-match-test <TEST_PATTERN_INVERSE>`

##### `match-contract`

* Type: regex
* Default: none
* Environment: `FOUNDRY_MATCH_CONTRACT` or `DAPP_MATCH_CONTRACT`

Only run test methods in contracts matching regex.
Equivalent to `forge test --match-contract <CONTRACT_PATTERN>`

##### `no-match-contract`

* Type: regex
* Default: none
* Environment: `FOUNDRY_NO_MATCH_CONTRACT` or `DAPP_NO_MATCH_CONTRACT`

Only run test methods in contracts not matching regex.
Equivalent to `forge test --no-match-contract <CONTRACT_PATTERN_INVERSE>`

##### `match-path`

* Type: regex
* Default: none
* Environment: `FOUNDRY_MATCH_PATH` or `DAPP_MATCH_PATH`

Only runs test methods on files matching the path.
Equivalent to `forge test --match-path <PATH_PATTERN>`

##### `no-match-path`

* Type: regex
* Default: none
* Environment: `FOUNDRY_NO_MATCH_PATH` or `DAPP_NO_MATCH_PATH`

Only runs test methods on files not matching the path.
Equivalent to `forge test --no-match-path <PATH_PATTERN_INVERSE>`

##### `threads`

* Type: integer
* Default: none
* Environment: `FOUNDRY_THREADS`

Number of threads to use.
Not set or zero specifies the number of logical cores.

##### `show_progress`

* Type: boolean
* Default: false
* Environment: `FOUNDRY_SHOW_PROGRESS`

Whether to show test execution progress.

##### `block_gas_limit`

* Type: integer
* Default: none
* Environment: `FOUNDRY_BLOCK_GAS_LIMIT` or `DAPP_BLOCK_GAS_LIMIT`

The block.gaslimit value during EVM execution.

##### `memory_limit`

* Type: integer
* Default: 33554432
* Environment: `FOUNDRY_MEMORY_LIMIT` or `DAPP_MEMORY_LIMIT`

The memory limit of the EVM in bytes.

##### `names`

* Type: boolean
* Default: false
* Environment: `FOUNDRY_NAMES` or `DAPP_NAMES`

Print compiled contract names.

##### `sizes`

* Type: boolean
* Default: false
* Environment: `FOUNDRY_SIZES` or `DAPP_SIZES`

Print compiled contract sizes.

##### `rpc_endpoints`

* Type: table of RPC endpoints
* Default: none
* Environment: none

This section lives outside of profiles and defines a table of RPC endpoints, where the key specifies the RPC endpoints's name and the value is the RPC endpoint itself.

The value can either be a valid RPC endpoint or a reference to an environment variable (wrapped with in `${}`).

These RPC endpoints can be used in tests and Solidity scripts (see [`vm.rpc`](/reference/cheatcodes/rpc)).

The following example defines an endpoint named `optimism` and an endpoint named `mainnet` that references an environment variable `RPC_MAINNET`:

```toml
[rpc_endpoints]
optimism = "https://optimism.alchemyapi.io/v2/..."
mainnet = "${RPC_MAINNET}"
```

##### `prompt_timeout`

* Type: integer
* Default: 120
* Environment: `FOUNDRY_PROMPT_TIMEOUT`

The number of seconds to wait before `vm.prompt` reverts with a timeout.

### Fuzz

Configuration values for `[fuzz]` section.

##### `runs`

* Type: integer
* Default: 256
* Environment: `FOUNDRY_FUZZ_RUNS` or `DAPP_FUZZ_RUNS`

The amount of fuzz runs to perform for each fuzz test case. Higher values gives more confidence in results at the cost of testing speed.

##### `timeout`

* Type: integer
* Default: None
* Environment: `FOUNDRY_FUZZ_TIMEOUT`

Optional timeout (in seconds) for fuzz test.

##### `fail_on_revert`

* Type: boolean
* Default: true
* Environment: `FOUNDRY_FUZZ_FAIL_ON_REVERT`

Fails the fuzzed test if a revert occurs in a call to a contract other than the test contract.

##### `max_test_rejects`

* Type: integer
* Default: 65536
* Environment: `FOUNDRY_FUZZ_MAX_TEST_REJECTS`

The maximum number of combined inputs that may be rejected before the test as a whole aborts.
"Global" filters apply to the whole test case. If the test case is rejected, the whole thing is regenerated.

##### `seed`

* Type: string (hexadecimal)
* Default: none
* Environment: `FOUNDRY_FUZZ_SEED`

Optional seed for the fuzzing RNG algorithm.

##### `dictionary_weight`

* Type: integer (between 0 and 100)
* Default: 40
* Environment: `FOUNDRY_FUZZ_DICTIONARY_WEIGHT`

The weight of the dictionary. A higher dictionary weight will bias the fuzz inputs towards "interesting" values, e.g. boundary values like `type(uint256).max` or contract addresses from your environment.

##### `include_storage`

* Type: boolean
* Default: true
* Environment: `FOUNDRY_FUZZ_INCLUDE_STORAGE`

The flag indicating whether to include values from storage.

##### `include_push_bytes`

* Type: boolean
* Default: true
* Environment: `FOUNDRY_FUZZ_INCLUDE_PUSH_BYTES`

The flag indicating whether to include push bytes values.

##### `gas_report_samples`

* Type: integer
* Default: 256
* Environment: `FOUNDRY_FUZZ_GAS_REPORT_SAMPLES`

Number of runs to use for generating gas report.

##### `failure_persist_dir`

* Type: string (path)
* Default: `./cache/fuzz`
* Environment: `FOUNDRY_FUZZ_FAILURE_PERSIST_DIR`

Path where fuzz failures are recorded and replayed.

##### `failure_persist_file`

* Type: string
* Default: `failures`
* Environment: `FOUNDRY_FUZZ_FAILURE_PERSIST_FILE`

Name of the file to record fuzz failures.

##### `show_logs`

* Type: boolean
* Default: false
* Environment: `FOUNDRY_FUZZ_SHOW_LOGS`

The flag indicates whether to display console logs in fuzz tests or not. Note that in order to enable displaying console logs, you'll need to set `show_logs = true` and then use `forge test -vv` or set `verbosity >= 2`.

##### `max_fuzz_dictionary_addresses`

* Type: integer
* Default: 15728640
* Environment: `FOUNDRY_FUZZ_MAX_FUZZ_DICTIONARY_ADDRESSES`

Maximum addresses to record for the fuzz dictionary. Once this limit is exceeded, the fuzzer starts evicting random entries.

##### `max_fuzz_dictionary_values`

* Type: integer
* Default: 9830400
* Environment: `FOUNDRY_FUZZ_MAX_FUZZ_DICTIONARY_VALUES`

Maximum values to record for the fuzz dictionary. Once this limit is exceeded, the fuzzer starts evicting random entries.

##### `max_fuzz_dictionary_literals`

* Type: integer
* Default: 6553600
* Environment: `FOUNDRY_FUZZ_MAX_FUZZ_DICTIONARY_LITERALS`

Maximum literal values to seed from the AST for the fuzz dictionary.

##### `corpus_dir`

* Type: string (path)
* Default: none
* Environment: `FOUNDRY_FUZZ_CORPUS_DIR`

Path to corpus directory. When set, enables coverage-guided fuzzing mode.

##### `corpus_gzip`

* Type: boolean
* Default: true
* Environment: `FOUNDRY_FUZZ_CORPUS_GZIP`

Whether corpus files use gzip compression (relevant only if `corpus_dir` is configured).

##### `corpus_min_mutations`

* Type: integer
* Default: 5
* Environment: `FOUNDRY_FUZZ_CORPUS_MIN_MUTATIONS`

Number of mutations until entry marked as eligible to be flushed from in-memory corpus.

##### `corpus_min_size`

* Type: integer
* Default: 0
* Environment: `FOUNDRY_FUZZ_CORPUS_MIN_SIZE`

Minimum corpus size that won't be evicted from memory.

##### `show_edge_coverage`

* Type: boolean
* Default: false
* Environment: `FOUNDRY_FUZZ_SHOW_EDGE_COVERAGE`

Whether to collect and display edge coverage metrics (automatically enabled if `corpus_dir` is configured).

### Invariant

Configuration values for `[invariant]` section.

> ℹ️ **Note**
>
> Configuration for `[invariant]` section has the fallback logic
> for common config entries (`runs`, `seed`, `dictionary_weight` etc).
>
> * If the entries are not set in either section, then the defaults will be used.
> * If the entries are set in the `[fuzz]` section, but are not set in the `[invariant]`
>   section, these values will automatically be set to the values specified in
>   the `[fuzz]` section.
> * For any profile other than `default`:
>   * If at least one entry is set in the `[invariant]` (same as
>     `[profile.default.invariant]`) section, then the values from
>     `[invariant]` section will be used, including defaults.
>   * If no entry is set in the `[invariant]` section, but there are
>     entries in the `[fuzz]` (same as `[profile.default.fuzz]`) section,
>     then the values from the `[fuzz]` section will be used.
>   * If it's none of the cases described above, then the defaults
>     will be used.

##### `runs`

* Type: integer
* Default: 256
* Environment: `FOUNDRY_INVARIANT_RUNS`

The number of runs that must execute for each invariant test group. See also [fuzz.runs](#runs)

##### `depth`

* Type: integer
* Default: 500
* Environment: `FOUNDRY_INVARIANT_DEPTH`

The number of calls executed to attempt to break invariants in one run.

##### `timeout`

* Type: integer
* Default: None
* Environment: `FOUNDRY_INVARIANT_TIMEOUT`

Optional timeout (in seconds) for invariant time based campaigns.

##### `fail_on_revert`

* Type: boolean
* Default: false
* Environment: `FOUNDRY_INVARIANT_FAIL_ON_REVERT`

Fails the invariant fuzzing if a revert occurs.

##### `call_override`

* Type: boolean
* Default: false
* Environment: `FOUNDRY_INVARIANT_CALL_OVERRIDE`

Overrides unsafe external calls when running invariant tests, useful for e.g. performing reentrancy checks.

##### `dictionary_weight`

* Type: integer (between 0 and 100)
* Default: 80
* Environment: `FOUNDRY_INVARIANT_DICTIONARY_WEIGHT`

The weight of the dictionary. See also [fuzz.dictionary\_weight](#dictionary_weight)

##### `include_storage`

* Type: boolean
* Default: true
* Environment: `FOUNDRY_FUZZ_INCLUDE_STORAGE`

The flag indicating whether to include values from storage. See also [fuzz.include\_storage](#include_storage)

##### `include_push_bytes`

* Type: boolean
* Default: true
* Environment: `FOUNDRY_FUZZ_INCLUDE_PUSH_BYTES`

The flag indicating whether to include push bytes values. See also [fuzz.include\_push\_bytes](#include_push_bytes)

##### `shrink_run_limit`

* Type: integer
* Default: 5000
* Environment: `FOUNDRY_INVARIANT_SHRINK_RUN_LIMIT`

The maximum number of attempts to shrink a failed the sequence. Shrink process is disabled if set to 0.

##### `max_assume_rejects`

* Type: integer
* Default: 65536
* Environment: `FOUNDRY_INVARIANT_MAX_ASSUME_REJECTS`

The maximum number of rejects via `vm.assume` which can be encountered during a single invariant run.

##### `gas_report_samples`

* Type: integer
* Default: 256
* Environment: `FOUNDRY_INVARIANT_GAS_REPORT_SAMPLES`

Number of runs to use for generating gas report.

##### `failure_persist_dir`

* Type: string (path)
* Default: `./cache/invariant`
* Environment: `FOUNDRY_INVARIANT_FAILURE_PERSIST_DIR`

Path where invariant failures are recorded and replayed.

##### `corpus_dir`

* Type: string (path)
* Default: None
* Environment: `FOUNDRY_INVARIANT_CORPUS_DIR`

Optional path where invariant corpus is stored. Enables coverage guided fuzzing and edge coverage metrics.

##### `corpus_gzip`

* Type: boolean
* Default: true
* Environment: `FOUNDRY_INVARIANT_CORPUS_GZIP`

Flag indicating whether corpus should use gzip file compression and decompression (relevant only if `corpus_dir` is configured). If set to `false`, then corpus is persisted as regular json file.

##### `corpus_min_mutations`

* Type: integer
* Default: 5
* Environment: `FOUNDRY_INVARIANT_CORPUS_MIN_MUTATIONS`

Number of corpus mutations until marked as eligible to be flushed from memory (relevant only if `corpus_dir` is configured).

##### `corpus_min_size`

* Type: integer
* Default: 0
* Environment: `FOUNDRY_INVARIANT_CORPUS_MIN_SIZE`

Minimum corpus size to mutate and won't be evicted from memory (relevant only if `corpus_dir` is configured).

##### `show_edge_coverage`

* Type: boolean
* Default: false
* Environment: `FOUNDRY_INVARIANT_SHOW_EDGE_COVERAGE`

Flag indicating whether to collect and display edge coverage metrics (automatically enabled if `corpus_dir` is configured).

##### `show_metrics`

* Type: boolean
* Default: true
* Environment: `FOUNDRY_INVARIANT_SHOW_METRICS`

The flag indicating whether to collect and display fuzzed selectors metrics in test report.

##### `show_solidity`

* Type: boolean
* Default: false
* Environment: `FOUNDRY_INVARIANT_SHOW_SOLIDITY`

Flag indicating whether to display counterexamples as solidity calls.

##### `max_time_delay`

* Type: integer
* Default: none
* Environment: `FOUNDRY_INVARIANT_MAX_TIME_DELAY`

Maximum time (in seconds) between generated transactions. If not set, there is no limit.

##### `max_block_delay`

* Type: integer
* Default: none
* Environment: `FOUNDRY_INVARIANT_MAX_BLOCK_DELAY`

Maximum number of blocks elapsed between generated transactions. If not set, there is no limit.

##### `check_interval`

* Type: integer
* Default: 1
* Environment: `FOUNDRY_INVARIANT_CHECK_INTERVAL`

Number of calls to execute between invariant assertions.

* `0`: Only assert on the last call of each run (fastest, but may miss exact breaking call)
* `1` (default): Assert after every call (most precise)
* `N`: Assert every N calls AND always on the last call