cadence-testing

name

cadence-testing

description

Guide for writing, running, and debugging unit tests for Cadence smart contracts using the built-in Cadence Testing Framework and `flow test`. Covers test file structure (_test.cdc, setup/beforeEach/tearDown), assertions and matchers, blockchain emulation (accounts, deployments, events, time manipulation), coverage reports, CI integration, and testing patterns. TRIGGER when: writing Cadence unit tests, debugging failing tests, using Test.assert / Test.expect / Test.assertEqual / Test.expectFailure, matchers (Test.equal, Test.beGreaterThan, etc.), Test.createAccount / Test.deployContract / Test.executeTransaction / Test.executeScript in tests, Test.moveTime, Test.eventsOfType in tests, Test.reset, `flow test`, `flow test --cover`, coverage reports, `_test.cdc`, "how do I test this contract", "test is flaky", "mock a capability in a test". DO NOT TRIGGER when: writing contract or transaction code itself (use cadence-lang), generating new contracts/transactions from scratch (use cadence-scaffold), auditing non-test code for security (use cadence-audit), running flow CLI commands other than `flow test` (use flow-cli), setting up flow.json contract aliases outside a testing context (use flow-project-setup).

Cadence Testing Guide

Write and run unit tests for Cadence smart contracts using the built-in Test contract and the Flow CLI's flow test command. Tests are Cadence files named *_test.cdc that run against an implicit in-process emulator. They deploy contracts, execute scripts and transactions, and assert expected behavior — all through calls on the Test contract.

Key Principles

1. Lifecycle is fixed — setup() runs once, beforeEach() / afterEach() wrap every test, testXxx() functions are the test cases, and tearDown() runs once at the end. All are optional except the test functions.
2. Start each test from a clean state — deploy contracts in setup(), capture the height, and call Test.reset(to: setupHeight) in beforeEach() to rewind to that snapshot.
3. Use the right assertion — Test.assert(cond, msg?) for boolean checks, Test.assertEqual(expected, actual) for equality, Test.expect(value, matcher) for matcher-based checks, and Test.expectFailure(closure, errorSubstring) for expected failures.
4. Cover failure paths — access-control denials, pre/post-condition violations, and resource-ownership errors are the parts of the contract that bugs hide in. Every test file should include at least one expectFailure case.

Navigation

Task	Reference
Project layout, flow.json test aliases, lifecycle, first test	setup-and-basics.md
Assertions, matchers, combinators, custom matchers, expectFailure	assertions-and-matchers.md
Accounts, deployments, scripts, transactions, reset, moveTime, mocking	blockchain-emulation.md
Events and logs — reading, filtering, asserting	events-and-logs.md
Running tests, coverage, determinism, fork mode, CI	coverage-and-ci.md
Testing patterns, isolation, flakiness prevention, anti-patterns	patterns.md

Running Tests — Quick Reference

flow test                                 # run every *_test.cdc it can find
flow test cadence/tests/Counter_test.cdc  # run a specific file
flow test --cover                         # with coverage report
flow test --name testMintWorks            # only tests whose name matches
flow test --seed 42                       # deterministic random order

Full flag reference and CI integration live in coverage-and-ci.md.

Companion Skills

• cadence-lang — Essential. Tests are Cadence too; all access control, resource, and capability rules apply.
• cadence-scaffold — Generate the contracts and transactions you're about to test.
• cadence-audit — After writing tests, audit the contracts they cover. Audit findings often point back at missing tests.
• flow-cli — Background on non-test CLI commands. This skill covers flow test in depth.
• flow-project-setup — Configuring flow.json outside a testing context.