Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Important: If you're upgrading snforge to version 0.48.0 or later, please read the 0.48.0 Migration Guide.

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: ~406680)
        sierra gas: 406680
        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: ~511980)
        sierra gas: 511980
        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.