Skip to main content

Running Cadence Tests

The Flow CLI provides a straightforward command to execute Cadence tests, enabling developers to validate their scripts and smart contracts effectively.

To run all tests in your project, simply use:


_10
flow test

The flow test command automatically discovers and runs all test scripts in your project that end with _test.cdc.

Note: 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 running your tests, ensure that your contracts are properly configured in your flow.json file, including any necessary testing aliases.

Setting Up Testing Aliases in Contracts​

If your tests involve deploying or interacting with contracts, 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:

  • 0x0000000000000005
  • 0x0000000000000006
  • 0x0000000000000007
  • 0x0000000000000008
  • 0x0000000000000009
  • 0x000000000000000A
  • 0x000000000000000B
  • 0x000000000000000C
  • 0x000000000000000D
  • 0x000000000000000E

Note: For more information on setting up contracts and aliases, refer to the Flow CLI Configuration documentation.

Example Usage​

Assuming 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
_16
import Test
_16
_16
access(all) let blockchain = Test.newEmulatorBlockchain()
_16
_16
access(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 using the CLI:


_10
$ flow test

The Flow CLI will discover all test scripts ending with _test.cdc and execute them. The results will be displayed in the terminal:


_10
Test results:
_10
- PASS: test_script_test.cdc > testSumOfTwo

To learn more about writing tests in Cadence, visit the Cadence Testing Framework documentation.

Running Specific Tests and Files​

Run specific test scripts or directories by providing their paths:


_10
flow 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 for managing test execution and coverage reporting.

Coverage Report​

  • Flag: --cover
  • Default: false

The --cover flag calculates the coverage of the code being tested, helping you identify untested parts of your scripts and contracts.


_10
$ flow test --cover

Sample output:


_10
Test results:
_10
- PASS: test_script_test.cdc > testSumOfTwo
_10
Coverage: 96.5% of statements

Coverage Report Output File​

  • Flag: --coverprofile
  • Valid Inputs: A valid filename with extension .json or .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. Setting the value to "contracts" excludes scripts and transactions from the coverage analysis.


_10
$ flow test --cover --covercode="contracts"

Sample output when no contracts are present:


_10
Test results:
_10
- PASS: test_script_test.cdc > testSumOfTwo
_10
There are no statements to cover

Note: In this example, the coverage report is empty because the --covercode flag 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.


_10
flow 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 by using the same seed value, which is helpful for debugging flaky tests.


_10
flow test --seed=12345

Note: 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.


_10
flow 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.

--fork​

  • Type: string
  • Default: "" (empty). If provided without a value, defaults to mainnet.

Fork tests from a network defined in flow.json. The CLI resolves the GRPC access host and chain ID from the selected network configuration.


_10
flow test --fork # Uses mainnet by default
_10
flow test --fork testnet # Uses testnet
_10
flow 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 host configured

Common errors:

  • network "<name>" not found in flow.json → add the network definition
  • network "<name>" has no host configured → set the host field

--fork-host​

  • Type: string
  • Default: ""

Directly specify a GRPC access node host. This bypasses the flow.json network lookup.


_10
flow 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.


_10
flow test --fork mainnet --fork-height 85432100

Note: Historical data beyond spork boundaries is not available via standard access nodes. See the Network Upgrade (Spork) Process.

Rate this page