anchor test

Run integration tests with automatic program deployment and validator management

Overview

The anchor test command builds programs, starts a local validator, deploys programs, and runs your test suite.

Command Syntax

anchor test [OPTIONS] [-- <ARGS>...]

Alias

anchor t

Options

Test Configuration

--program-name · string

Build and test only this program

--skip-deploy · flag · default: "false"

Skip deploying programs (test against previously deployed programs)

--skip-build · flag · default: "false"

Skip building the program in the workspace

--skip-lint · flag · default: "false"

Skip checking for safety comments (“CHECK”) in the code

--no-idl · flag · default: "false"

Do not build the IDL

Validator Options

--skip-local-validator · flag · default: "false"

Skip starting a local validator (if configured cluster is localnet)

--validator · enum · default: "surfpool"

Validator type to use for local testing

Options:

• surfpool: Use Surfpool validator (default, faster)
• legacy: Use Solana test validator

--detach · flag · default: "false"

Keep the local validator running after tests complete

Build Options

--arch · enum · default: "sbf"

Architecture to use when building the program

Options: sbf, bpf

--env · array

Environment variables to pass into the Docker container

cargo_args · string

Arguments to pass to the underlying cargo build-sbf command (use -- to separate)

Test Suite Options

--run · array

Run test suites under the specified path(s)

args · string

Additional arguments to pass to the test runner

Examples

Basic Test

Run all tests with automatic build and deployment:

anchor test

Output:

Build success
Deploying programs...
Running tests...

  my_program
    ✓ Is initialized! (523ms)

  1 passing (524ms)

Test Specific Program

anchor test --program-name my_program

Skip Build (Faster Testing)

Skip building when the program code hasn’t changed:

anchor test --skip-build

Test Against Deployed Programs

Test without redeploying programs:

anchor test --skip-deploy

Keep Validator Running

Useful for inspecting transactions after tests:

anchor test --detach

Run Specific Test Files

anchor test --run tests/my_test.ts

Use Legacy Validator

anchor test --validator legacy

Pass Arguments to Test Runner

anchor test -- --grep "my specific test"

Complete Skip (No Build, No Deploy)

anchor test --skip-build --skip-deploy --skip-local-validator

Test Workflow

The test command executes the following steps:

1. Build Phase (unless --skip-build):

   • Compiles Rust programs
   • Generates IDL files
   • Runs build hooks

2. Validator Phase (unless --skip-local-validator):

   • Starts local validator (Surfpool or legacy)
   • Waits for validator to be ready

3. Deploy Phase (unless --skip-deploy):

   • Deploys all programs to the local validator
   • Uploads IDL for each program

4. Test Phase:

   • Runs the test script defined in Anchor.toml
   • Executes test suites (Mocha, Jest, etc.)

5. Cleanup Phase:

   • Stops the validator (unless --detach)

Validator Types

Surfpool (Default)

• Faster startup time
• Optimized for Anchor development
• Managed automatically by Anchor

Legacy

• Standard solana-test-validator
• Compatible with all Solana CLI features
• Useful for advanced testing scenarios

Test Configuration

The test script is defined in Anchor.toml:

[scripts]
test = "yarn run ts-mocha -p ./tsconfig.json -t 1000000 tests/**/*.ts"

For Jest:

[scripts]
test = "yarn run jest --preset ts-jest"

Environment Setup

Tests have access to:

• anchor.workspace.<ProgramName>: Program clients
• anchor.AnchorProvider.env(): Provider connected to local validator
• anchor.web3: Solana web3.js library

Example Test (TypeScript)

import * as anchor from "@anchor-lang/core";
import { Program } from "@anchor-lang/core";
import { MyProgram } from "../target/types/my_program";

describe("my_program", () => {
  anchor.setProvider(anchor.AnchorProvider.env());

  const program = anchor.workspace.MyProgram as Program<MyProgram>;

  it("Is initialized!", async () => {
    const tx = await program.methods.initialize().rpc();
    console.log("Transaction signature:", tx);
  });
});

Performance Tips

Use --skip-build when iterating on tests without changing program code to save time.

Use --skip-deploy when testing client-side logic against already deployed programs.

The Surfpool validator (default) is significantly faster than the legacy validator for most use cases.

Notes

The --detach flag keeps the validator running. Remember to stop it manually when done.

When testing on devnet or mainnet (not localnet), the validator is not started automatically.

The default timeout for Mocha tests is 1000000ms (1000 seconds) to accommodate Solana’s transaction confirmation times.