solana-test-validator-js

1.0.2 verified Sat May 09 auth: no javascript

JavaScript library for spinning up a local Solana test validator instance programmatically, intended for use with test frameworks like Mocha. Version 1.0.2 provides a startAndConnect function that spawns a solana-test-validator process, creates a Connection instance, and optionally funds accounts. It also exports getAccounts for generating Keypairs and a Cleanup type. Requires the Solana CLI tool suite to be installed. Differentiators: simplifies test setup compared to manual CLI spawning, supports TypeScript directly, and integrates cleanly with Mocha global fixtures. Release cadence: infrequent (last update 2023).

Common errors

error Error: Cannot find module 'solana-test-validator-js' ↓

cause Library not installed or not in node_modules.

fix

Run: npm install -D solana-test-validator-js

error TypeError: (0 , solana_test_validator_js.startAndConnect) is not a function ↓

cause Using CommonJS require instead of ESM import.

fix

Use import { startAndConnect } from 'solana-test-validator-js' and ensure your project uses ESM (type: module in package.json or .mjs extension).

error Error: spawn solana-test-validator ENOENT ↓

cause Solana CLI not installed or not in PATH.

fix

Install Solana CLI tools and ensure solana-test-validator is accessible in your terminal.

error TypeError: cleanup is not a function ↓

cause Destructured cleanup from startAndConnect incorrectly, or startAndConnect failed.

fix

Ensure startAndConnect returns a tuple: [connection, cleanup]. Check that solana-test-validator process started successfully.

Warnings

missing-dependency solana-test-validator not found. Ensure the Solana CLI is installed ↓

fix Install Solana CLI tools: sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

gotcha Deprecated: Do not use this library in production. It is intended for local testing only. ↓

fix Use a mainnet or devnet connection for production code.

breaking The connection export may be undefined if startAndConnect hasn't been called. ↓

fix Always call startAndConnect before accessing the connection singleton. Alternatively, use the returned connection from startAndConnect.

gotcha Solana ledger data may persist across test runs if test-ledger/ directory is not cleaned. ↓

fix Add test-ledger/ to .gitignore and manually delete the folder between test runs.

deprecated Timeout for entire test suite should be increased (default 2000ms). The test validator takes several seconds to start. ↓

fix Set mocha timeout to at least 60000ms: this.timeout(60000);

Install

npm install solana-test-validator-js

yarn add solana-test-validator-js

pnpm add solana-test-validator-js

Imports

startAndConnect

wrong

const { startAndConnect } = require('solana-test-validator-js')

correct

import { startAndConnect } from 'solana-test-validator-js'

Library is ESM-only; CommonJS require will fail in recent Node versions.

getAccounts

wrong

import getAccounts from 'solana-test-validator-js'

correct

import { getAccounts } from 'solana-test-validator-js'

getAccounts is a named export, not default. Use destructured import.

Cleanup
```
import { Cleanup } from 'solana-test-validator-js'
```
Cleanup is a type alias for a function; only needed for TypeScript type annotations.
connection
wrong
```
import { Connection } from 'solana-test-validator-js'
```
correct
```
import { connection } from 'solana-test-validator-js'
```
connection is a singleton Connection instance exposed after startAndConnect is called. Connection (capital C) is from @solana/web3.js.

Quickstart

Launch a local Solana test validator with one funded account, obtain a Connection, and clean up after tests.

import { Connection, Keypair, LAMPORTS_PER_SOL } from '@solana/web3.js';
import { startAndConnect, getAccounts, Cleanup } from 'solana-test-validator-js';

// Start test validator with 1 funded account of 10000 SOL
const accounts = getAccounts(1);
const [connection, cleanup]: [Connection, Cleanup] = startAndConnect([], {
  number: 1,
  lamports: LAMPORTS_PER_SOL * 10000,
});

// Use connection and accounts in tests
console.log('Validator PID:', (connection as any).rpcEndpoint);

// After tests
cleanup();