Testing Anchor Programs with TypeScript Clients

Hello! In our last lesson, we focused on creating new accounts using Anchor's init constraint. We even got a sneak peek at how to write a TypeScript test for that specific initialize instruction.

This lesson will build directly on that foundation. Our goal is to formalize your understanding of testing and empower you to write and run comprehensive integration tests for any Anchor program using its TypeScript client. We'll cover the full testing workflow, from setting up the environment to writing assertions that verify your on-chain logic.

Given your extensive experience with frontend development and testing frameworks, you'll find the tools and patterns used in Anchor testing—namely TypeScript, Mocha, and Chai—very familiar. This lesson will focus on applying those skills in the unique context of the Solana blockchain.

Unit Tests vs. Integration Tests

In software development, we often distinguish between different types of tests. In Solana, the two most common are unit tests and integration tests.

• Unit Tests are written in Rust and live alongside your program code. They are designed to test small, isolated pieces of logic (e.g., a single helper function) without involving the Solana runtime. They are fast and great for testing pure logic.
• Integration Tests are written in TypeScript/JavaScript and live in the tests/ directory of your Anchor project. Their purpose is to test how your program behaves as a whole when deployed on a live (or simulated) Solana cluster. They test the interaction between instructions, accounts, and the Solana runtime itself.

When you run the anchor test command, you are executing these integration tests.

The Anchor Testing Workflow

Anchor provides a powerful, streamlined workflow for integration testing. The central command is anchor test. When you run it, Anchor performs several steps automatically:

1. Starts a local Solana test validator: It creates a fresh, local blockchain instance for your tests.
2. Builds your program: It compiles your Rust code into a Solana-compatible BPF (Berkeley Packet Filter) binary.
3. Generates the IDL: It creates or updates the Interface Definition Language (IDL) file in target/idl/. This JSON file describes your program's instructions, accounts, and custom types.
4. Deploys the program: It deploys your BPF binary to the local test validator.
5. Runs your tests: It executes the TypeScript test files located in your project's tests/ directory using the Mocha test runner.

Setting Up the Test Environment

Your test environment is primarily configured in two places: Anchor.toml and your TypeScript test file.

1. Anchor.toml Configuration

This file tells Anchor how to run your tests. The [scripts] section is key:

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

This line specifies the command to execute your tests. By default, it uses ts-mocha to find and run all files ending in .ts inside the tests/ directory.

You can also configure the behavior of the local validator under the [test.validator] section, for example, to airdrop SOL to a specific address at genesis or to clone accounts from a public cluster.

2. The TypeScript Test File

Anchor test files use a standard structure that will be familiar from modern JavaScript/TypeScript testing.

• Mocha: The test framework that provides the describe() and it() blocks to structure your tests. describe groups related tests, and it defines an individual test case.
• Chai: The assertion library used to verify outcomes. While Anchor examples often use assert, you can also use expect or should styles.
• @coral-xyz/anchor: The library that provides the tools to connect to the cluster and interact with your program.

Writing a Test Suite: The Core Pattern

Let's break down how to write a typical test file, following the Arrange-Act-Assert pattern.

Arrange: Setting the Stage

Before you can call an instruction, you need to set up all the necessary context.

1. Get the Provider and Program:

   • anchor.AnchorProvider.env() creates a connection to the Solana cluster based on your Anchor.toml configuration.
   • anchor.workspace.YourProgramName provides a typed client object for interacting with your specific program. This object is automatically generated by Anchor using the IDL, giving you type-safe access to your program's methods.

2. Create Keypairs:

   • You'll often need to generate new keypairs to represent users or new accounts. You do this with anchor.web3.Keypair.generate().

3. Fund Wallets:

   • Transactions on Solana cost SOL for fees, and creating accounts requires SOL for rent. You must ensure your payer accounts have sufficient funds. A common pattern is to create a helper function to airdrop SOL.

Here's a typical setup block using Mocha's before hook, which runs once before all tests in the describe block.

import * as anchor from "@coral-xyz/anchor";
import { Program } from "@coral-xyz/anchor";
import { assert } from "chai";
import { MyProgram } from "../target/types/my_program";

describe("my_program", () => {
  // --- ARRANGE ---
  const provider = anchor.AnchorProvider.env();
  anchor.setProvider(provider);

  const program = anchor.workspace.MyProgram as Program<MyProgram>;
  
  // A keypair for the account we'll create in our tests
  const counterAccount = anchor.web3.Keypair.generate();

  // The main user/payer for the tests
  const payer = provider.wallet;

  // This runs once before all tests
  before(async () => {
    // Airdrop SOL to our payer, just in case
    await provider.connection.confirmTransaction(
      await provider.connection.requestAirdrop(payer.publicKey, 2 * anchor.web3.LAMPORTS_PER_SOL),
      "confirmed"
    );
  });

  // ... your 'it' blocks go here
});

Act: Calling the Instruction

To call a program instruction, you use the program.methods object. The syntax is a chain of method calls:

program.methods.instructionName(...args).accounts({...}).signers([...]).rpc()

• .methods.instructionName(...args): This corresponds to your Rust instruction handler. Any arguments the Rust function takes (besides Context) are passed here. Note that numbers like u64 must be wrapped in new anchor.BN().
• .accounts({...}): You provide the public keys of all the accounts required by the instruction's Accounts struct.
• .signers([...]): An array of the full Keypair objects that need to sign the transaction. This includes the payer and, as we saw in the last lesson, any new accounts being created with init.
• .rpc(): This sends the transaction to the network and waits for confirmation.

Assert: Verifying the Result

After the transaction is confirmed, you need to check that the program's state changed as expected.

1. Fetch the Account Data: You can retrieve the latest state of an account using program.account.accountStructName.fetch(publicKey).
2. Make Assertions: Use Chai's assert (or expect) to compare the fetched data with your expected values.

Here's a complete it block for an initialize instruction:

it("Is initialized!", async () => {
  // --- ACT ---
  await program.methods
    .initialize()
    .accounts({
      counter: counterAccount.publicKey,
      user: payer.publicKey,
      systemProgram: anchor.web3.SystemProgram.programId,
    })
    .signers([counterAccount]) // The new account must sign for `init`
    .rpc();

  // --- ASSERT ---
  const account = await program.account.counter.fetch(counterAccount.publicKey);
  assert.ok(account.count.toNumber() === 0);
});

And for a subsequent increment instruction:

it("Increments the count", async () => {
  // --- ACT ---
  await program.methods
    .increment()
    .accounts({
      counter: counterAccount.publicKey,
    })
    .rpc();

  // --- ASSERT ---
  const account = await program.account.counter.fetch(counterAccount.publicKey);
  assert.ok(account.count.toNumber() === 1);
});

Test your understanding!

In the increment test above, why don't we need to pass anything to .signers()?

Show answer

The increment instruction modifies the counter account, but the transaction is paid for by the default wallet/payer configured in the provider (provider.wallet). Anchor automatically includes this default wallet as a signer.

The Rust Accounts struct for increment would not require any additional signers (unlike initialize, which needs the new account's signature). Therefore, no extra signers are needed in the .signers([]) array.

Walkthrough: Building a Test Suite

Now, let's see all these pieces come together. The following video is a fantastic, detailed walkthrough of creating a test suite for a simple counter program. It covers everything from setting up the describe block to testing initialize, update, increment, and decrement instructions.

This video clearly illustrates the "Arrange, Act, Assert" pattern for each instruction and highlights common pitfalls, like forgetting to use anchor.BN for u64 types.

Conclusion

You now have a solid framework for testing your Anchor programs. Because of your background, this TypeScript-based workflow should feel natural, allowing you to focus on the unique aspects of on-chain testing.

Here are your key takeaways:

• anchor test is the primary command for running integration tests, which validate your program's on-chain behavior.
• Tests are written in TypeScript using Mocha (describe, it) for structure and Chai (assert) for verification.
• The Arrange-Act-Assert pattern provides a clean structure for test cases.
  • Arrange: Set up the provider, program client, and create/fund necessary keypairs.
  • Act: Call program methods using the program.methods.name(...).accounts(...).signers(...).rpc() chain.
  • Assert: Fetch the updated account state with program.account.name.fetch(...) and verify its properties.
• Anchor's workspace and typed program client, powered by the IDL, provide a safe and efficient way to interact with your program from your tests.

In our next lesson, we will dive into a concept we've already used implicitly: Cross-Program Invocations (CPIs). You've seen Anchor use a CPI to the System Program via the init constraint. Next, we'll learn how to perform these program-to-program calls manually and explicitly, unlocking a vast new range of capabilities for your Solana programs.