Skip to main content

​
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 testingOptions:
  • 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 programOptions: 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us