Running Cadence Tests
The Flow CLI provides a straightforward command to execute Cadence tests, which allows developers to validate their scripts and smart contracts effectively.
To run all tests in your project, simply use:
_10flow test
The flow test command automatically discovers and runs all test scripts in your project that end with _test.cdc.
The test command requires a properly initialized configuration. If you haven’t set up your Flow project yet, refer to the flow init guide for assistance.
Prerequisites
Before you run your tests, ensure that your contracts are properly configured in your flow.json file, particularly any necessary testing aliases.
Set up testing aliases in contracts
If your tests involve contract deployment or contract interaction, you need to add your contracts to the contracts section in the flow.json configuration file. Specifically, include the contract name, source location, and an address alias for the testing environment.
Example flow.json configuration:
_19{_19 "contracts": {_19 "Counter": {_19 "source": "cadence/contracts/Counter.cdc",_19 "aliases": {_19 "testing": "0x0000000000000007"_19 }_19 }_19 },_19 "networks": {_19 // ... your network configurations_19 },_19 "accounts": {_19 // ... your account configurations_19 },_19 "deployments": {_19 // ... your deployment configurations_19 }_19}
For the testing alias, you can use one of the following addresses:
0x00000000000000050x00000000000000060x00000000000000070x00000000000000080x00000000000000090x000000000000000A0x000000000000000B0x000000000000000C0x000000000000000D0x000000000000000E
For more information on how to set up contracts and aliases, refer to the Flow CLI Configuration documentation.
Example use
This example assumes you have a test script named test_script_test.cdc in your project directory, which verifies the functionality of a Cadence script executed in the testing environment:
_16// test_script_test.cdc_16import Test_16_16access(all) let blockchain = Test.newEmulatorBlockchain()_16_16access(all) fun testSumOfTwo() {_16 let scriptResult = blockchain.executeScript(_16 "access(all) fun main(a: Int, b: Int): Int { return a + b }",_16 [2, 3]_16 )_16_16 Test.expect(scriptResult, Test.beSucceeded())_16_16 let sum = scriptResult.returnValue! as! Int_16 Test.assertEqual(5, sum)_16}
This script defines a single test case, testSumOfTwo, which checks if a Cadence script that adds two integers (a + b) works as expected. The test passes if the result matches the expected value of 5.
You can run all tests in your project with the CLI:
_10$ flow test
The Flow CLI will discover all test scripts that end with _test.cdc and execute them. The results will be displayed in the terminal:
_10Test results:_10- PASS: test_script_test.cdc > testSumOfTwo
To learn more about how to write tests in Cadence, visit the Cadence Testing Framework documentation.
Run specific tests and files
To run specific test scripts or directories, by provide their paths:
_10flow test path/to/your/test_script_test.cdc path/to/another_test.cdc tests/subsuite/
This executes only the tests contained in the specified files and directories.
Flags
The flow test command supports several flags that provide additional functionality to manage test execution and coverage reports.
Coverage report
- Flag:
--cover - Default:
false
The --cover flag calculates the coverage of the code being tested, which helps you identify untested parts of your scripts and contracts.
_10$ flow test --cover
Sample output:
_10Test results:_10- PASS: test_script_test.cdc > testSumOfTwo_10Coverage: 96.5% of statements
Coverage report output file
- Flag:
--coverprofile - Valid Inputs: A valid filename with extension
.jsonor.lcov - Default:
"coverage.json"
Use the --coverprofile flag to specify the output file for the coverage report.
Example:
_10$ flow test --cover --coverprofile="coverage.lcov"
The generated coverage file can then be inspected:
_10$ cat coverage.lcov
Coverage code type
- Flag:
--covercode - Valid Inputs:
"all"(default) or"contracts" - Default:
"all"
The --covercode flag lets you limit the coverage report to specific types of code. Set the value to "contracts" to exclude scripts and transactions from the coverage analysis.
_10$ flow test --cover --covercode="contracts"
Sample output when no contracts are present:
_10Test results:_10- PASS: test_script_test.cdc > testSumOfTwo_10There are no statements to cover
Note: In this example, the coverage report is empty because the
--covercodeflag is set to"contracts", and the test script only contains scripts, not contracts.
Random execution of test cases
- Flag:
--random - Default:
false
Use the --random flag to execute test cases in a random order. This can help identify issues that may arise due to test dependencies or the order in which tests are run.
_10flow test --random
Seed for random execution
- Flag:
--seed - Default:
0
Use the --seed flag to specify a seed value for the random execution order of test cases. This allows you to reproduce a specific random order when you use the same seed value, which is helpful to debug flaky tests.
_10flow test --seed=12345
If both --random and --seed are provided, the --random flag will be ignored, and the seed value from --seed will be used for randomization.
Run specific test by name
- Flag:
--name - Default:
""(empty string)
Use the --name flag to run only tests that match the given name. This is useful when you want to execute a specific test function within your test scripts.
_10flow test --name=testSumOfTwo
This command will run only the test function named testSumOfTwo across all test scripts that contain it.
To dive deeper into testing the functionality of your Cadence scripts and contracts, explore the Cadence Testing Framework documentation.
Fork testing flags
Run tests against forked mainnet or testnet state. For a step-by-step tutorial, see: Fork Testing with Cadence. For background and best practices, see the guide: Testing Strategy on Flow.
Configure fork tests
Recommended: Use the #test_fork pragma in your test file:
_10#test_fork(network: "mainnet", height: nil)_10_10import Test_10_10access(all) fun testAgainstMainnet() {_10 // Test runs against mainnet state_10}
Then run with:
_10flow test
The pragma configures fork testing directly in your test files, which makes the tests self-documenting. You can also use CLI flags (documented below) to override or configure fork tests and not modify test files.
--fork
- Type:
string - Default:
""(empty). If provided without a value, defaults tomainnet.
Fork tests from a network defined in flow.json. The CLI resolves the GRPC access host and chain ID from the selected network configuration.
_10flow test --fork # Uses mainnet by default_10flow test --fork testnet # Uses testnet_10flow test --fork mynet # Uses a custom network defined in flow.json
Requirements:
- The network must exist in
flow.json. - The network must have a valid
hostconfigured.
--fork-host
- Type:
string - Default:
""
Directly specify a GRPC access node host. This bypasses the flow.json network lookup.
_10flow test --fork-host access.mainnet.nodes.onflow.org:9000
See public access node URLs in Flow Networks.
--fork-height
- Type:
uint64 - Default:
0
Pin the fork to a specific block height for historical state testing. Only blocks from the current spork (since the most recent network upgrade) are available via public access nodes; earlier blocks are not accessible via public access nodes.
_10flow test --fork mainnet --fork-height 85432100
Historical data beyond spork boundaries is not available via standard access nodes. See the Network Upgrade (Spork) Process.