How do I install the Cadence Testing skill?

Run npx skillmds@latest add onflow/cadence-testing in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Cadence Testing safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Cadence Testing?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Cadence Testing free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Cadence Testing?

onflow (@onflow) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Cadence Testing by onflow — Agent Skill

Name: Cadence Testing
Author: onflow

Cadence Testing

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-t

onflow 501fcb2 7 files · 116.4 KB Updated Sep 17, 2026

File contents

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

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

---name: cadence-testingdescription: 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-t---# Cadence Testing GuideWrite 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 Principles1. **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](references/setup-and-basics.md) || Assertions, matchers, combinators, custom matchers, `expectFailure` | [assertions-and-matchers.md](references/assertions-and-matchers.md) || Accounts, deployments, scripts, transactions, `reset`, `moveTime`, mocking | [blockchain-emulation.md](references/blockchain-emulation.md) || Events and logs — reading, filtering, asserting | [events-and-logs.md](references/events-and-logs.md) || Running tests, coverage, determinism, fork mode, CI | [coverage-and-ci.md](references/coverage-and-ci.md) || Testing patterns, isolation, flakiness prevention, anti-patterns | [patterns.md](references/patterns.md) |## Running Tests — Quick Reference```bashflow test # run every *_test.cdc it can findflow test cadence/tests/Counter_test.cdc # run a specific fileflow test --cover # with coverage reportflow test --name testMintWorks # only tests whose name matchesflow test --seed 42 # deterministic random order```Full flag reference and CI integration live in [coverage-and-ci.md](references/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.

Frequently asked questions