solana-test-validator
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.soQuando 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çãoO que isso demonstra:
--resetlimpa o ledger para execuções determinísticas.--bpf-programregistra 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--ledgersobrescreva.
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 18899Armadilhas
- --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-validatorou altere--rpc-port. - Clone sem URL da mainnet - conta vazia na inicialização. Correção: passe
--url mainnet-betacom--clone. - ID de programa incompatível - o ID de
--bpf-programdeve corresponder adeclare_id!do cliente. Correção: use pubkey do keypair detarget/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.