solana-test-validator

Q: Posso persistir o ledger entre reinicializações?

Sim - omita --reset e reutilize o caminho de --ledger; cuidado com deriva de estado nos testes.

Q: Como pré-carrego programas SPL?

Clone IDs do programa Token ou use --bpf-program com pubkeys de programa conhecidos.

Q: O anchor test inicia seu próprio validador?

Por padrão sim - use --skip-local-validator quando você gerencia o validador manualmente.

Q: Posso executar vários validadores?

Sim em valores diferentes de --rpc-port para shards paralelos de CI.

Execute solana-test-validator para obter um cluster Solana de nó único com JSON-RPC, faucet e execução de programas BPF em localhost.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

solana-test-validator
solana-test-validator --reset
solana-test-validator --bpf-program <PROGRAM_ID> target/deploy/my_program.so

Quando usar:

Backend padrão para anchor test.
Teste manual de cliente contra estado fresco.
Carregar programas customizados sem deploy público na devnet.
Clonar contas selecionadas da mainnet para testes realistas de CPI.

Exemplo Funcional

# Terminal 1: validador com seu programa pré-carregado
solana-test-validator --reset \
  --bpf-program "$(solana-keygen pubkey target/deploy/my_program-keypair.json)" \
  target/deploy/my_program.so
 
# Terminal 2: CLI + testes
solana config set --url http://127.0.0.1:8899
solana airdrop 5
anchor test --skip-local-validator  # se o validador já estiver em execução

O que isso demonstra:

--reset limpa o ledger para execuções determinísticas.
--bpf-program registra bytecode em um ID de programa fixo no gênesis.
A porta 8899 serve RPC; 8900 é comum para gossip/WebSocket.

Aprofundamento

Como Funciona

Embute lógica de validador Agave ajustada para velocidade de desenvolvedor (épocas mais curtas, limites relaxados).
Minera blocos localmente com suas transações incluídas imediatamente.
O faucet emite SOL sem limites de taxa.
O ledger fica em test-ledger/ por padrão, a menos que --ledger sobrescreva.

Flags Úteis

Flag	Efeito
`--reset`	Exclui ledger existente
`--ledger <PATH>`	Diretório de estado persistente
`--clone <PUBKEY>`	Copia conta de `--url` na inicialização
`--bpf-program <ID> <SO>`	Pré-carrega binário do programa
`--url <CLUSTER>`	Origem para clones

Notas bash

# Logs silenciosos para CI
solana-test-validator --quiet --reset
 
# Vincular porta RPC customizada
solana-test-validator --rpc-port 18899

Armadilhas

--reset esquecido - estado obsoleto causa testes instáveis. Correção: reset sempre no CI; documente o caminho do ledger para experimentos persistentes.
Porta já em uso - validador anterior ainda em execução. Correção: pkill solana-test-validator ou altere --rpc-port.
Clone sem URL da mainnet - conta vazia na inicialização. Correção: passe --url mainnet-beta com --clone.
ID de programa incompatível - o ID de --bpf-program deve corresponder a declare_id! do cliente. Correção: use pubkey do keypair de target/deploy.
Assumir WebSocket na mesma porta - algumas configurações precisam de URL WS explícita. Correção: verifique erros de conexão em solana logs.

Alternativas

Alternativa	Use quando	Não use quando
Surfpool 0.12.0	Simulação de fork da mainnet	Testes locais mínimos sem dependências
LiteSVM 0.6.x	Testes unitários em subsegundos	Integração completa de cliente RPC
devnet	Ambiente de staging compartilhado	Loop interno de dev rápido
Validador embutido de `anchor test`	Testes em um comando	Sessão manual de longa duração

FAQs

Quais portas o test-validator usa?

RPC padrão 8899, gossip 8900, faucet 9900 - configuráveis via flags.

Posso persistir o ledger entre reinicializações?

Sim - omita --reset e reutilize o caminho de --ledger; cuidado com deriva de estado nos testes.

Como pré-carrego programas SPL?

Clone IDs do programa Token ou use --bpf-program com pubkeys de programa conhecidos.

Suporta transações versionadas?

Sim - corresponde aos recursos do Agave 4.1.1, incluindo transações v0 e ALTs quando habilitados nos recursos do cluster.

Quantos clones são práticos?

Comece com dezenas, não milhares - cada clone adiciona tempo de busca RPC na inicialização.

O Docker pode executar test-validator?

Sim para CI - exponha a porta 8899 aos containers de teste.

Por que o tempo de slot difere da mainnet?

O test validator ajusta o timing de slot para throughput de desenvolvedor, não timing de consenso de produção.

Como parar com segurança?

Ctrl+C no terminal; garanta que nenhum processo órfão segure a porta 8899.

O anchor test inicia seu próprio validador?

Por padrão sim - use --skip-local-validator quando você gerencia o validador manualmente.

Posso executar vários validadores?

Sim em valores diferentes de --rpc-port para shards paralelos de CI.

Relacionado

Local Dev Basics - visão geral do loop de dev
Cloning Mainnet Accounts - estado realista
Loading Programs & Fixtures - padrões de pré-carregamento
Surfpool - alternativa baseada em fork

Versões da stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

solana-test-validator
solana-test-validator --reset
solana-test-validator --bpf-program <PROGRAM_ID> target/deploy/my_program.so

Quando usar:

Backend padrão para anchor test.
Teste manual de cliente contra estado fresco.
Carregar programas customizados sem deploy público na devnet.
Clonar contas selecionadas da mainnet para testes realistas de CPI.

Exemplo Funcional

# Terminal 1: validador com seu programa pré-carregado
solana-test-validator --reset \
  --bpf-program "$(solana-keygen pubkey target/deploy/my_program-keypair.json)" \
  target/deploy/my_program.so
 
# Terminal 2: CLI + testes
solana config set --url http://127.0.0.1:8899
solana airdrop 5
anchor test --skip-local-validator  # se o validador já estiver em execução

O que isso demonstra:

--reset limpa o ledger para execuções determinísticas.
--bpf-program registra bytecode em um ID de programa fixo no gênesis.
A porta 8899 serve RPC; 8900 é comum para gossip/WebSocket.

Aprofundamento

Como Funciona

Embute lógica de validador Agave ajustada para velocidade de desenvolvedor (épocas mais curtas, limites relaxados).
Minera blocos localmente com suas transações incluídas imediatamente.
O faucet emite SOL sem limites de taxa.
O ledger fica em test-ledger/ por padrão, a menos que --ledger sobrescreva.

Flags Úteis

Flag	Efeito
`--reset`	Exclui ledger existente
`--ledger <PATH>`	Diretório de estado persistente
`--clone <PUBKEY>`	Copia conta de `--url` na inicialização
`--bpf-program <ID> <SO>`	Pré-carrega binário do programa
`--url <CLUSTER>`	Origem para clones

Notas bash

# Logs silenciosos para CI
solana-test-validator --quiet --reset
 
# Vincular porta RPC customizada
solana-test-validator --rpc-port 18899

Armadilhas

--reset esquecido - estado obsoleto causa testes instáveis. Correção: reset sempre no CI; documente o caminho do ledger para experimentos persistentes.
Porta já em uso - validador anterior ainda em execução. Correção: pkill solana-test-validator ou altere --rpc-port.
Clone sem URL da mainnet - conta vazia na inicialização. Correção: passe --url mainnet-beta com --clone.
ID de programa incompatível - o ID de --bpf-program deve corresponder a declare_id! do cliente. Correção: use pubkey do keypair de target/deploy.
Assumir WebSocket na mesma porta - algumas configurações precisam de URL WS explícita. Correção: verifique erros de conexão em solana logs.

Alternativas

Alternativa	Use quando	Não use quando
Surfpool 0.12.0	Simulação de fork da mainnet	Testes locais mínimos sem dependências
LiteSVM 0.6.x	Testes unitários em subsegundos	Integração completa de cliente RPC
devnet	Ambiente de staging compartilhado	Loop interno de dev rápido
Validador embutido de `anchor test`	Testes em um comando	Sessão manual de longa duração

FAQs

Quais portas o test-validator usa?

RPC padrão 8899, gossip 8900, faucet 9900 - configuráveis via flags.

Posso persistir o ledger entre reinicializações?

Sim - omita --reset e reutilize o caminho de --ledger; cuidado com deriva de estado nos testes.

Como pré-carrego programas SPL?

Clone IDs do programa Token ou use --bpf-program com pubkeys de programa conhecidos.

Suporta transações versionadas?

Sim - corresponde aos recursos do Agave 4.1.1, incluindo transações v0 e ALTs quando habilitados nos recursos do cluster.

Quantos clones são práticos?

Comece com dezenas, não milhares - cada clone adiciona tempo de busca RPC na inicialização.

O Docker pode executar test-validator?

Sim para CI - exponha a porta 8899 aos containers de teste.

Por que o tempo de slot difere da mainnet?

O test validator ajusta o timing de slot para throughput de desenvolvedor, não timing de consenso de produção.

Como parar com segurança?

Ctrl+C no terminal; garanta que nenhum processo órfão segure a porta 8899.

O anchor test inicia seu próprio validador?

Por padrão sim - use --skip-local-validator quando você gerencia o validador manualmente.

Posso executar vários validadores?

Sim em valores diferentes de --rpc-port para shards paralelos de CI.

Relacionado

Local Dev Basics - visão geral do loop de dev
Cloning Mainnet Accounts - estado realista
Loading Programs & Fixtures - padrões de pré-carregamento
Surfpool - alternativa baseada em fork

Versões da stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.

solana-test-validator

Buscar na documentação

solana-test-validator