> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/solana-foundation/anchor/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
anchor test [OPTIONS] [-- <ARGS>...]
```

## Alias

```bash theme={null}
anchor t
```

## Options

### Test Configuration

<ParamField path="--program-name" type="string">
  Build and test only this program
</ParamField>

<ParamField path="--skip-deploy" type="flag" default="false">
  Skip deploying programs (test against previously deployed programs)
</ParamField>

<ParamField path="--skip-build" type="flag" default="false">
  Skip building the program in the workspace
</ParamField>

<ParamField path="--skip-lint" type="flag" default="false">
  Skip checking for safety comments ("CHECK") in the code
</ParamField>

<ParamField path="--no-idl" type="flag" default="false">
  Do not build the IDL
</ParamField>

### Validator Options

<ParamField path="--skip-local-validator" type="flag" default="false">
  Skip starting a local validator (if configured cluster is localnet)
</ParamField>

<ParamField path="--validator" type="enum" default="surfpool">
  Validator type to use for local testing

  **Options:**

  * `surfpool`: Use Surfpool validator (default, faster)
  * `legacy`: Use Solana test validator
</ParamField>

<ParamField path="--detach" type="flag" default="false">
  Keep the local validator running after tests complete
</ParamField>

### Build Options

<ParamField path="--arch" type="enum" default="sbf">
  Architecture to use when building the program

  **Options:** `sbf`, `bpf`
</ParamField>

<ParamField path="--env" type="array">
  Environment variables to pass into the Docker container
</ParamField>

<ParamField path="cargo_args" type="string">
  Arguments to pass to the underlying `cargo build-sbf` command (use `--` to separate)
</ParamField>

### Test Suite Options

<ParamField path="--run" type="array">
  Run test suites under the specified path(s)
</ParamField>

<ParamField path="args" type="string">
  Additional arguments to pass to the test runner
</ParamField>

## Examples

### Basic Test

Run all tests with automatic build and deployment:

```bash theme={null}
anchor test
```

**Output:**

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

  my_program
    ✓ Is initialized! (523ms)

  1 passing (524ms)
```

### Test Specific Program

```bash theme={null}
anchor test --program-name my_program
```

### Skip Build (Faster Testing)

Skip building when the program code hasn't changed:

```bash theme={null}
anchor test --skip-build
```

### Test Against Deployed Programs

Test without redeploying programs:

```bash theme={null}
anchor test --skip-deploy
```

### Keep Validator Running

Useful for inspecting transactions after tests:

```bash theme={null}
anchor test --detach
```

### Run Specific Test Files

```bash theme={null}
anchor test --run tests/my_test.ts
```

### Use Legacy Validator

```bash theme={null}
anchor test --validator legacy
```

### Pass Arguments to Test Runner

```bash theme={null}
anchor test -- --grep "my specific test"
```

### Complete Skip (No Build, No Deploy)

```bash theme={null}
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`:

```toml theme={null}
[scripts]
test = "yarn run ts-mocha -p ./tsconfig.json -t 1000000 tests/**/*.ts"
```

For Jest:

```toml theme={null}
[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)

```typescript theme={null}
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

<Tip>
  Use `--skip-build` when iterating on tests without changing program code to save time.
</Tip>

<Tip>
  Use `--skip-deploy` when testing client-side logic against already deployed programs.
</Tip>

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

## Notes

<Warning>
  The `--detach` flag keeps the validator running. Remember to stop it manually when done.
</Warning>

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

<Note>
  The default timeout for Mocha tests is 1000000ms (1000 seconds) to accommodate Solana's transaction confirmation times.
</Note>