Running Tests

To run tests with snforge, simply run the snforge test command from the package directory.

$ snforge test
Output:
Collected 3 test(s) from hello_snforge package Running 0 test(s) from src/ Running 3 test(s) from tests/ [PASS] hello_snforge_integrationtest::test_contract::test_calling (l1_gas: ~0, l1_data_gas: ~0, l2_gas: ~40000) [PASS] hello_snforge_integrationtest::test_contract::test_executing (l1_gas: ~0, l1_data_gas: ~0, l2_gas: ~40000) [PASS] hello_snforge_integrationtest::test_contract::test_calling_another (l1_gas: ~0, l1_data_gas: ~0, l2_gas: ~40000) Tests: 3 passed, 0 failed, 0 ignored, 0 filtered out

Filtering Tests

You can pass a filter string after the snforge test command to filter tests. By default, any test with an absolute module tree path matching the filter will be run.

$ snforge test calling
Output:
Collected 2 test(s) from hello_snforge package Running 0 test(s) from src/ Running 2 test(s) from tests/ [PASS] hello_snforge_integrationtest::test_contract::test_calling_another (l1_gas: ~0, l1_data_gas: ~0, l2_gas: ~40000) [PASS] hello_snforge_integrationtest::test_contract::test_calling (l1_gas: ~0, l1_data_gas: ~0, l2_gas: ~40000) Tests: 2 passed, 0 failed, 0 ignored, 1 filtered out

Running a Specific Test

To run a specific test, you can pass a filter string along with an --exact flag. Note, you have to use a fully qualified test name, including a module name.

📝 Note

Running a specific test results in optimized compilation. snforge will try to compile only the desired test, unlike the case of running all tests where all of them are compiled.

$ snforge test hello_snforge_integrationtest::test_contract::test_calling --exact
Output:
Collected 1 test(s) from hello_snforge package Running 1 test(s) from tests/ [PASS] hello_snforge_integrationtest::test_contract::test_calling (l1_gas: ~0, l1_data_gas: ~0, l2_gas: ~40000) Running 0 test(s) from src/ Tests: 1 passed, 0 failed, 0 ignored, other filtered out

Skipping tests

You can use the --skip flag to exclude tests matching a specified filter pattern. This is useful for temporarily disabling problematic tests or focusing on a subset of tests by excluding others.

You can skip tests by function name, module name or full path:

  • Skip a specific test: --skip test_feature_a
  • Skip tests in a module: --skip nested_module
  • Skip by full path: --skip my_tests::nested_module::test_feature_b
$ snforge test --skip test_failing --skip failing_example_tests::test_xyz
Output:
Collected 1 test(s) from failing_example package Running 0 test(s) from src/ Running 1 test(s) from tests/ [PASS] failing_example_tests::test_abc (l1_gas: ~0, l1_data_gas: ~0, l2_gas: ~40000) Tests: 1 passed, 0 failed, 0 ignored, 2 filtered out

Stopping Test Execution After First Failed Test

To stop the test execution after first failed test, you can pass an --exit-first flag along with snforge test command.

$ snforge test --exit-first
Output:
Collected 3 test(s) from failing_example package Running 3 test(s) from tests/ [FAIL] failing_example_tests::test_failing Failure data: 0x6661696c696e6720636865636b ('failing check') Failures: failing_example_tests::test_failing Tests: 0 passed, 1 failed, 0 ignored, 0 filtered out Interrupted execution of 2 test(s).

Displaying Resources Used During Tests

To track resources like builtins / syscalls that are used when running tests, use snforge test --detailed-resources.

$ snforge test --detailed-resources
Output:
Collected 2 test(s) from hello_starknet package Running 2 test(s) from tests/ [PASS] hello_starknet_integrationtest::test_contract::test_cannot_increase_balance_with_zero_value (l1_gas: ~0, l1_data_gas: ~96, l2_gas: ~360000) steps: 3405 memory holes: 22 builtins: (range_check: 77, pedersen: 7) syscalls: (CallContract: 2, StorageRead: 1, Deploy: 1) [PASS] hello_starknet_integrationtest::test_contract::test_increase_balance (l1_gas: ~0, l1_data_gas: ~192, l2_gas: ~480000) steps: 4535 memory holes: 15 builtins: (range_check: 95, pedersen: 7) syscalls: (CallContract: 3, StorageRead: 3, Deploy: 1, StorageWrite: 1) Running 0 test(s) from src/ Tests: 2 passed, 0 failed, 0 ignored, 0 filtered out

For more information about how starknet-foundry calculates those, see gas and resource estimation section.