Testing Scarb projects
scarb test command executes all unit and integration tests of a local package. It is not a test runner by itself, but rather delegates work to a testing solution of choice. Scarb comes with preinstalled
scarb cairo-test extension, which bundles Cairo's native test runner. It is the default test runner used by
scarb cairo-test extension calls
scarb build --test to build actual executable test files, using the test targets mechanism. The extension itself only relies on produced artifacts to actually run the tests.
As for how to write Cairo tests, we recommend reading the "Testing Cairo Programs" chapter in the Cairo Programming Language book.
Testing Starknet contracts
scarb cairo-test automatically enables Starknet-related testing features if the package depends on the
Scarb supports two types of tests: unit and integration. Unit tests are defined in the main package file, while integration tests are defined in separate files in directory called
tests besides the manifest file. From integration tests, you can only reference the main package by package name (as if you would add it as dependency). The integration tests can be either a single module with a
lib.cairo file in
tests directory, or multiple files with
cairo extension, each defining a separate test module.
Note: For now, the compilation of integration tests with
lib.cairo file in the
tests directory will be faster than compilation of integration tests defined in separate files.
Using third-party test runners
The behaviour of the
scarb test command can be changed by developers. To do so, provide a script named explicitly
test in the current workspace
Scarb.toml. If such script is found, Scarb will execute it instead of running the default test runner.
Scarb can be configured to use any tool in place of the default
cairo-test, simply by providing a custom script named
[scripts] test = "command-to-run-tests"
Using Starknet Foundry
Starknet Foundry, like Scarb, is a project developed by Software Mansion team. It enables advanced testing of Starknet contracts, including fuzz testing, forking the network state, setting-up a specific contract state in your tests, and many more.
In order to tell
scarb test to use Starknet Foundry as the test runner testing in your project, define the following:
[scripts] test = "snforge test"
Do not forget to properly set up Starknet Foundry in your project beforehand.
Using multiple test runners
The default test runner is regular Scarb extension, and thus it is always available directly, as
scarb cairo-test command. With script-based override for the
scarb test command, it is possible to perform arbitrary actions before and after the test runner itself. This trick also allows running multiple test runners in the project. For example, to run a custom end-to-end test suite using a popular pytest, Starknet Devnet and Starknet.py combination, type the following:
[scripts] test = "scarb cairo-test && pytest"