Skip to main content

Fork Testing with Cadence

This tutorial teaches you how to run your Cadence tests against a snapshot of Flow mainnet or testnet using flow test --fork. You'll learn how to test your contracts against real deployed contracts and production data without needing to deploy anything to a live network or bootstrap test accounts.

Fork testing bridges the gap between fast local unit tests and expensive testnet deployments. It enables you to validate your contracts work correctly with real on-chain state, test integrations with deployed contracts, and debug issues using historical blockchain data—all in a safe, local environment.

What You'll Learn​

After completing this tutorial, you'll be able to:

  • Run Cadence tests against forked networks using flow test --fork
  • Test contracts that depend on real mainnet contracts without manual setup
  • Use account impersonation to execute transactions as any mainnet account
  • Read from production blockchain state in your test suite
  • Pin tests to specific block heights for historical debugging
  • Integrate fork testing into your development workflow

What You'll Build​

You'll create a complete fork testing setup that demonstrates:

  • Reading from the live FlowToken contract on mainnet
  • Deploying your own contract that interacts with mainnet contracts
  • Testing custom logic against real account balances and state
  • Executing transactions using impersonated mainnet accounts
  • A reusable pattern for integration testing your Flow applications

Time Commitment: Approximately 30 minutes

Prerequisites​

Flow CLI​

This tutorial requires Flow CLI v1.8.0 or later installed. If you haven't installed it yet and have homebrew installed, run:


_10
brew install flow-cli

For other operating systems, refer to the installation guide.

Basic Cadence Testing Knowledge​

You should be familiar with writing basic Cadence tests. If you're new to Cadence testing, start with Testing Smart Contracts first.

Network Access​

You'll need network access to Flow's public access nodes. The tutorial uses these endpoints, which are freely available:

  • Mainnet: access.mainnet.nodes.onflow.org:9000
  • Testnet: access.devnet.nodes.onflow.org:9000
info

This tutorial covers flow test --fork (running tests against forked network state), which is different from flow emulator --fork (starting the emulator in fork mode for manual interaction).

Create Your Project​

Navigate to your development directory and create a new Flow project:


_10
mkdir fork-testing-demo
_10
cd fork-testing-demo
_10
flow init --yes

The --yes flag accepts defaults non-interactively. flow init is interactive by default and can scaffold various templates.

Alternatively, create the directory and initialize in one command:


_10
flow init fork-testing-demo --yes
_10
cd fork-testing-demo

Install Dependencies​

Use the Dependency Manager to install the FlowToken and FungibleToken contracts:


_10
flow dependencies install FlowToken FungibleToken

This downloads the contracts and their dependencies into the imports/ folder and updates your flow.json with the correct addresses and aliases across all networks (mainnet, testnet, emulator).

Your flow.json will now include an entry like:


_12
{
_12
"dependencies": {
_12
"FlowToken": {
_12
"source": "mainnet://1654653399040a61.FlowToken",
_12
"aliases": {
_12
"emulator": "0ae53cb6e3f42a79",
_12
"mainnet": "1654653399040a61",
_12
"testnet": "7e60df042a9c0868"
_12
}
_12
}
_12
}
_12
}

Your flow.json should now have the mainnet and testnet networks configured from flow init. In fork mode, contract imports automatically resolve to the correct network addresses.

Test Reading Live State​

Create the test directories:


_10
mkdir -p tests cadence/scripts

First, create a script to read FlowToken supply. Create cadence/scripts/GetFlowTokenSupply.cdc:

cadence/scripts/GetFlowTokenSupply.cdc

_10
import "FlowToken"
_10
_10
access(all) fun main(): UFix64 {
_10
return FlowToken.totalSupply
_10
}

Now create the test file tests/flow_token_test.cdc:

tests/flow_token_test.cdc

_13
import Test
_13
_13
access(all) fun testFlowTokenSupplyIsPositive() {
_13
let scriptResult = Test.executeScript(
_13
Test.readFile("cadence/scripts/GetFlowTokenSupply.cdc"),
_13
[]
_13
)
_13
_13
Test.expect(scriptResult, Test.beSucceeded())
_13
_13
let supply = scriptResult.returnValue! as! UFix64
_13
Test.assert(supply > 0.0, message: "FlowToken supply should be positive")
_13
}

Notes:

  • Use Test.executeScript() to read contract state
  • The script imports FlowToken by name - the dependency manager handles address resolution
  • In fork mode, this automatically uses the mainnet FlowToken contract
  • Extract the return value with proper type casting and assert on it

Quick verify​

Run just this test file against a fork to confirm your setup works:


_10
flow test tests/flow_token_test.cdc --fork

Target testnet instead:


_10
flow test tests/flow_token_test.cdc --fork testnet

You should see the test PASS. If not, verify your network host in flow.json and that dependencies are installed.

Deploy and Test Your Contract​

Now you'll create a contract that depends on FlowToken and test it against the forked mainnet state—no need to bootstrap tokens or set up test accounts.

Create a Test Account​

Create a mainnet account for testing:


_10
flow accounts create

When prompted, select mainnet as the network. This will generate a new account and save the private key to a .pkey file. Note the account address (e.g., 0xf8d6e0586b0a20c7).

Create a Contract that Uses FlowToken​

Generate a new contract:


_10
flow generate contract TokenChecker

This creates cadence/contracts/TokenChecker.cdc and adds it to flow.json. Now update the contract with your logic:

cadence/contracts/TokenChecker.cdc

_18
import "FlowToken"
_18
_18
access(all) contract TokenChecker {
_18
_18
access(all) fun checkBalance(address: Address): UFix64 {
_18
let account = getAccount(address)
_18
_18
let vaultRef = account.capabilities
_18
.borrow<&FlowToken.Vault>(/public/flowTokenBalance)
_18
?? panic("Could not borrow FlowToken Vault reference")
_18
_18
return vaultRef.balance
_18
}
_18
_18
access(all) fun hasMinimumBalance(address: Address, minimum: UFix64): Bool {
_18
return self.checkBalance(address: address) >= minimum
_18
}
_18
}

Configure Contract Deployment​

Add the deployment configuration to flow.json. Replace YOUR_ACCOUNT_ADDRESS with the address from the previous step:


_18
{
_18
"contracts": {
_18
"TokenChecker": {
_18
"source": "cadence/contracts/TokenChecker.cdc"
_18
}
_18
},
_18
"deployments": {
_18
"mainnet": {
_18
"mainnet-account": ["TokenChecker"]
_18
}
_18
},
_18
"accounts": {
_18
"mainnet-account": {
_18
"address": "YOUR_ACCOUNT_ADDRESS",
_18
"key": "$PRIVATE_KEY"
_18
}
_18
}
_18
}

This configuration tells the test framework to deploy TokenChecker to your mainnet account when running fork tests.

Create Scripts for Testing​

Create cadence/scripts/CheckBalance.cdc:

cadence/scripts/CheckBalance.cdc

_10
import "TokenChecker"
_10
_10
access(all) fun main(addr: Address): UFix64 {
_10
return TokenChecker.checkBalance(address: addr)
_10
}

Create cadence/scripts/HasMinimumBalance.cdc:

cadence/scripts/HasMinimumBalance.cdc

_10
import "TokenChecker"
_10
_10
access(all) fun main(addr: Address, min: UFix64): Bool {
_10
return TokenChecker.hasMinimumBalance(address: addr, minimum: min)
_10
}

Test Your Contract with Forked State​

Create tests/token_checker_test.cdc:

tests/token_checker_test.cdc

_37
import Test
_37
_37
access(all) fun setup() {
_37
// Deploy TokenChecker to the test account
_37
let err = Test.deployContract(
_37
name: "TokenChecker",
_37
path: "cadence/contracts/TokenChecker.cdc",
_37
arguments: []
_37
)
_37
Test.expect(err, Test.beNil())
_37
}
_37
_37
access(all) fun testCheckBalanceOnRealAccount() {
_37
// Test against a real mainnet account (Flow service account)
_37
let scriptResult = Test.executeScript(
_37
Test.readFile("cadence/scripts/CheckBalance.cdc"),
_37
[0x1654653399040a61] // Flow service account on mainnet
_37
)
_37
_37
Test.expect(scriptResult, Test.beSucceeded())
_37
_37
let balance = scriptResult.returnValue! as! UFix64
_37
// The Flow service account should have a balance
_37
Test.assert(balance > 0.0, message: "Service account should have FLOW tokens")
_37
}
_37
_37
access(all) fun testHasMinimumBalance() {
_37
let scriptResult = Test.executeScript(
_37
Test.readFile("cadence/scripts/HasMinimumBalance.cdc"),
_37
[0x1654653399040a61, 1000.0]
_37
)
_37
_37
Test.expect(scriptResult, Test.beSucceeded())
_37
_37
let hasMinimum = scriptResult.returnValue! as! Bool
_37
Test.assert(hasMinimum == true, message: "Service account should have at least 1000 FLOW")
_37
}

What's Happening Here​

  1. Your contract uses FlowToken: TokenChecker imports and interacts with the real FlowToken contract
  2. No bootstrapping needed: When you run with --fork, real mainnet accounts (like 0x1654653399040a61, the Flow service account) already have balances
  3. Test against real state: You can query actual accounts and verify your contract logic works with production data
  4. Local deployment: Your TokenChecker contract is deployed locally to the test environment, but it reads from forked mainnet state

Execute Transactions with Account Impersonation​

Fork testing includes built-in account impersonation—you can execute transactions as any mainnet account without needing private keys. This lets you test interactions with real accounts and their existing state.

Create Transactions​

Create the transactions directory:


_10
mkdir -p cadence/transactions

First, create a transaction to set up a FlowToken vault. Create cadence/transactions/SetupFlowTokenVault.cdc:

cadence/transactions/SetupFlowTokenVault.cdc

_13
import "FungibleToken"
_13
import "FlowToken"
_13
_13
transaction {
_13
prepare(signer: &Account) {
_13
if signer.storage.borrow<&FlowToken.Vault>(from: /storage/flowTokenVault) == nil {
_13
signer.storage.save(<-FlowToken.createEmptyVault(vaultType: Type<@FlowToken.Vault>()), to: /storage/flowTokenVault)
_13
let cap = signer.capabilities.storage.issue<&FlowToken.Vault>(/storage/flowTokenVault)
_13
signer.capabilities.publish(cap, at: /public/flowTokenReceiver)
_13
signer.capabilities.publish(cap, at: /public/flowTokenBalance)
_13
}
_13
}
_13
}

Now create the transfer transaction. Create cadence/transactions/TransferTokens.cdc:

cadence/transactions/TransferTokens.cdc

_23
import "FungibleToken"
_23
import "FlowToken"
_23
_23
transaction(amount: UFix64, to: Address) {
_23
let sentVault: @{FungibleToken.Vault}
_23
_23
prepare(signer: &Account) {
_23
let vaultRef = signer.storage.borrow<auth(FungibleToken.Withdraw) &FlowToken.Vault>(
_23
from: /storage/flowTokenVault
_23
) ?? panic("Could not borrow reference to the owner's Vault")
_23
_23
self.sentVault <- vaultRef.withdraw(amount: amount)
_23
}
_23
_23
execute {
_23
let recipient = getAccount(to)
_23
let receiverRef = recipient.capabilities
_23
.borrow<&{FungibleToken.Receiver}>(/public/flowTokenReceiver)
_23
?? panic("Could not borrow receiver reference")
_23
_23
receiverRef.deposit(from: <-self.sentVault)
_23
}
_23
}

Test Transaction Execution with Impersonation​

Add this test function to the existing tests/token_checker_test.cdc file:


_60
access(all) fun testTransactionAsMainnetAccount() {
_60
// Impersonate the Flow service account (or any mainnet account)
_60
// No private keys needed - fork testing has built-in impersonation
_60
let serviceAccount = Test.getAccount(0x1654653399040a61)
_60
_60
// Check initial balance
_60
let initialBalanceScript = Test.executeScript(
_60
Test.readFile("cadence/scripts/CheckBalance.cdc"),
_60
[serviceAccount.address]
_60
)
_60
Test.expect(initialBalanceScript, Test.beSucceeded())
_60
let initialBalance = initialBalanceScript.returnValue! as! UFix64
_60
_60
// Create a test recipient account and set up FlowToken vault
_60
let recipient = Test.createAccount()
_60
_60
// Set up the recipient's FlowToken vault
_60
let setupResult = Test.executeTransaction(
_60
Test.Transaction(
_60
code: Test.readFile("cadence/transactions/SetupFlowTokenVault.cdc"),
_60
authorizers: [recipient.address],
_60
signers: [recipient],
_60
arguments: []
_60
)
_60
)
_60
Test.expect(setupResult, Test.beSucceeded())
_60
_60
// Execute transaction AS the mainnet service account
_60
// This works because fork testing allows impersonating any account
_60
let txResult = Test.executeTransaction(
_60
Test.Transaction(
_60
code: Test.readFile("cadence/transactions/TransferTokens.cdc"),
_60
authorizers: [serviceAccount.address],
_60
signers: [serviceAccount],
_60
arguments: [10.0, recipient.address]
_60
)
_60
)
_60
_60
Test.expect(txResult, Test.beSucceeded())
_60
_60
// Verify the sender's balance decreased
_60
let newBalanceScript = Test.executeScript(
_60
Test.readFile("cadence/scripts/CheckBalance.cdc"),
_60
[serviceAccount.address]
_60
)
_60
Test.expect(newBalanceScript, Test.beSucceeded())
_60
let newBalance = newBalanceScript.returnValue! as! UFix64
_60
_60
// Balance should have decreased by exactly the transfer amount
_60
Test.assertEqual(initialBalance - 10.0, newBalance)
_60
_60
// Verify the recipient received the tokens
_60
let recipientBalanceScript = Test.executeScript(
_60
Test.readFile("cadence/scripts/CheckBalance.cdc"),
_60
[recipient.address]
_60
)
_60
Test.expect(recipientBalanceScript, Test.beSucceeded())
_60
let recipientBalance = recipientBalanceScript.returnValue! as! UFix64
_60
Test.assertEqual(10.0, recipientBalance)
_60
}

Key Points About Account Impersonation​

  1. Any account can be used: Call Test.getAccount(address) with any mainnet address
  2. No private keys needed: Fork testing has built-in impersonation—you can sign transactions as any account
  3. Real account state: The account has its actual mainnet balance, storage, and capabilities
  4. Mutations are local: Changes only affect your test environment, not the real network
  5. Test complex scenarios: Impersonate whale accounts, protocol accounts, or any user to test edge cases

Run All Tests Together​

Now that you have multiple test files, run them all against the forked network:


_10
flow test --fork

This runs all *_test.cdc files in your project against mainnet by default. You should see:


_10
Test results: "tests/flow_token_test.cdc"
_10
- PASS: testFlowTokenSupplyIsPositive
_10
_10
Test results: "tests/token_checker_test.cdc"
_10
- PASS: testCheckBalanceOnRealAccount
_10
- PASS: testHasMinimumBalance
_10
- PASS: testTransactionAsMainnetAccount

Additional Options​

You can also fork from testnet (flow test --fork testnet) or pin to a specific block height (--fork-height). See the Fork Testing Flags reference for all available options.

When to Use Fork Testing​

Fork testing is most valuable for:

  • Integration testing with real onchain contracts and data
  • Pre-deployment validation before mainnet releases
  • Upgrade testing against production state
  • Reproducing issues at a specific block height
  • Testing interactions with high-value or protocol accounts
  • Validating contract behavior with real-world data patterns

For strategy, limitations, and best practices, see the guide: Testing Smart Contracts.

Conclusion​

In this tutorial, you learned how to use fork testing to validate your Cadence contracts against live Flow network state. You created tests that read from real mainnet contracts, deployed custom contracts that interact with production data, and executed transactions using account impersonation—all without deploying to a live network or bootstrapping test accounts.

Now that you have completed this tutorial, you should be able to:

  • Run Cadence tests against forked networks using flow test --fork
  • Test contracts that depend on real mainnet contracts without manual setup
  • Use account impersonation to execute transactions as any mainnet account
  • Read from production blockchain state in your test suite
  • Pin tests to specific block heights for historical debugging
  • Integrate fork testing into your development workflow

Fork testing bridges the gap between local unit tests and testnet deployments, enabling you to catch integration issues early and test against real-world conditions. Use it as part of your pre-deployment validation process, alongside unit tests for speed and testnet deployments for final verification.

Next Steps​

  • Explore additional assertions and helpers in the Cadence Testing Framework
  • Add more real-world tests that read from standard contracts like Flow NFT
  • Keep unit tests on the emulator for speed and run forked integration tests selectively in CI
  • Review the Fork Testing Flags reference for advanced options
  • Learn about Flow Networks and public access nodes
Rate this page