Carregando Programas e Fixtures

Pré-carregue programas e fixtures de contas determinísticos para que cada execução de teste comece do mesmo estado on-chain.

Receita

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

solana-test-validator --reset \
  --bpf-program <PROGRAM_ID> target/deploy/my_program.so \
  --account <PUBKEY> fixture.json
 
anchor test

Quando usar:

Pipelines de CI que não devem depender do uptime da devnet.
Testes que exigem saldos de token ou contas de config conhecidos.
Carregar binários .so de terceiros em IDs fixos.
Compartilhar arquivos de fixture entre membros da equipe.

Exemplo Funcional

# 1. Exporte uma conta fixture uma vez da devnet/mainnet
solana account <CONFIG_PUBKEY> --output json-compact > config-fixture.json
 
# 2. Inicie o validador com programa + fixture
PROGRAM_ID=$(solana-keygen pubkey target/deploy/my_program-keypair.json)
 
solana-test-validator --reset \
  --bpf-program "$PROGRAM_ID" target/deploy/my_program.so \
  --account <CONFIG_PUBKEY> config-fixture.json
 
# 3. Execute testes contra estado conhecido
solana config set --url http://127.0.0.1:8899
anchor test --skip-local-validator

O que isso demonstra:

--bpf-program carrega seu bytecode no gênesis.
--account injeta lamports/owner/dados do JSON exportado.
Testes fazem assert contra config estável em vez de estado aleatório da devnet.

Aprofundamento

Como Funciona

JSON de fixture codifica campos de conta que o validador aplica na inicialização.
Programas podem ser builds locais ou .so baixados de solana program dump.
Testes Anchor podem iniciar validador com flags customizadas via seção [test.validator] em Anchor.toml.
LiteSVM 0.6.x oferece fixtures em nível de código para testes unitários Rust sem RPC.

Fontes de Fixture

Fonte	Comando	Caso de uso
Exportação RPC	`solana account --output json`	Configs realistas
JSON escrito à mão	editor	Estado sintético mínimo
Txs de setup de teste	hooks `before`	Dinâmico, porém mais lento
LiteSVM set_account	API Rust	Testes unitários rápidos

Notas bash

# Exemplo Anchor.toml
# [test.validator]
# url = "https://api.mainnet-beta.solana.com"
# clone = ["<MINT>", "<ORACLE>"]

Armadilhas

Hooks before não determinísticos - testes instáveis quando a ordem de setup muda. Correção: prefira fixtures estáticos para gates de CI.
Owner errado no JSON de fixture - conta rejeitada no carregamento. Correção: copie o owner exato da solana account de origem.
Deriva de fixture - conta exportada da devnet muda externamente. Correção: versione arquivos de fixture no git com comentários sobre o slot de origem.
Fixtures oversized - git e boot do validador lentos. Correção: reduza dados ou gere programaticamente nos testes.
ID de programa incompatível em bpf-program - clientes chamam endereço errado. Correção: sincronize declare_id! e pubkey do keypair.

Alternativas

Alternativa	Use quando	Não use quando
`--clone` da mainnet	Layout ao vivo necessário	Testes mínimos só de config
Instruções de setup on-chain	Testar fluxos de init	Custo repetido de CI
LiteSVM	Lógica pura de programa Rust	Clientes RPC end-to-end
Deploy compartilhado devnet	QA manual da equipe	Verificações automatizadas de PR

FAQs

Onde ficam os arquivos JSON de fixture?

Padrão comum: tests/fixtures/ commitado no git com origem documentada.

O Anchor.toml pode configurar clones?

Sim em [test.validator] com array clone e url para o cluster de origem.

Como carrego vários programas?

Repita flags --bpf-program <ID> <SO> em uma linha de comando do validador.

Fixtures incluem saldo isento de aluguel?

JSON exportado inclui lamports - garanta o suficiente para aluguel ao injetar manualmente.

Posso atualizar fixture no meio do teste?

Transações podem mutar estado após o boot - fixtures são apenas condições iniciais.

Como compartilho fixtures com segurança?

Não faça commit de dados privados de usuário - sanitize pubkeys e saldos em fixtures compartilhados.

Isso funciona com Surfpool?

Fork Surfpool reduz a necessidade de fixtures manuais - ainda útil para overlays de config customizados.

Quão grande pode ser o dado de fixture?

Respeite limites de tamanho de conta - contas grandes tornam a inicialização proporcionalmente mais lenta.

Posso carregar programas atualizáveis?

Carregue .so no ID do programa; autoridade de upgrade segue regras do loader na localnet.

Como regenero fixtures?

Execute novamente solana account --output json contra estado bom do cluster e incremente a versão do arquivo na mensagem de commit.

Relacionado

solana-test-validator - flags de inicialização
Cloning Mainnet Accounts - snapshots ao vivo
LiteSVM - fixtures em memória
Testing Against a Validator - testes de integração

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.

Carregando Programas e Fixtures

Pré-carregue programas e fixtures de contas determinísticos para que cada execução de teste comece do mesmo estado on-chain.

Receita

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

solana-test-validator --reset \
  --bpf-program <PROGRAM_ID> target/deploy/my_program.so \
  --account <PUBKEY> fixture.json
 
anchor test

Quando usar:

Pipelines de CI que não devem depender do uptime da devnet.
Testes que exigem saldos de token ou contas de config conhecidos.
Carregar binários .so de terceiros em IDs fixos.
Compartilhar arquivos de fixture entre membros da equipe.

Exemplo Funcional

# 1. Exporte uma conta fixture uma vez da devnet/mainnet
solana account <CONFIG_PUBKEY> --output json-compact > config-fixture.json
 
# 2. Inicie o validador com programa + fixture
PROGRAM_ID=$(solana-keygen pubkey target/deploy/my_program-keypair.json)
 
solana-test-validator --reset \
  --bpf-program "$PROGRAM_ID" target/deploy/my_program.so \
  --account <CONFIG_PUBKEY> config-fixture.json
 
# 3. Execute testes contra estado conhecido
solana config set --url http://127.0.0.1:8899
anchor test --skip-local-validator

O que isso demonstra:

--bpf-program carrega seu bytecode no gênesis.
--account injeta lamports/owner/dados do JSON exportado.
Testes fazem assert contra config estável em vez de estado aleatório da devnet.

Aprofundamento

Como Funciona

JSON de fixture codifica campos de conta que o validador aplica na inicialização.
Programas podem ser builds locais ou .so baixados de solana program dump.
Testes Anchor podem iniciar validador com flags customizadas via seção [test.validator] em Anchor.toml.
LiteSVM 0.6.x oferece fixtures em nível de código para testes unitários Rust sem RPC.

Fontes de Fixture

Fonte	Comando	Caso de uso
Exportação RPC	`solana account --output json`	Configs realistas
JSON escrito à mão	editor	Estado sintético mínimo
Txs de setup de teste	hooks `before`	Dinâmico, porém mais lento
LiteSVM set_account	API Rust	Testes unitários rápidos

Notas bash

# Exemplo Anchor.toml
# [test.validator]
# url = "https://api.mainnet-beta.solana.com"
# clone = ["<MINT>", "<ORACLE>"]

Armadilhas

Hooks before não determinísticos - testes instáveis quando a ordem de setup muda. Correção: prefira fixtures estáticos para gates de CI.
Owner errado no JSON de fixture - conta rejeitada no carregamento. Correção: copie o owner exato da solana account de origem.
Deriva de fixture - conta exportada da devnet muda externamente. Correção: versione arquivos de fixture no git com comentários sobre o slot de origem.
Fixtures oversized - git e boot do validador lentos. Correção: reduza dados ou gere programaticamente nos testes.
ID de programa incompatível em bpf-program - clientes chamam endereço errado. Correção: sincronize declare_id! e pubkey do keypair.

Alternativas

Alternativa	Use quando	Não use quando
`--clone` da mainnet	Layout ao vivo necessário	Testes mínimos só de config
Instruções de setup on-chain	Testar fluxos de init	Custo repetido de CI
LiteSVM	Lógica pura de programa Rust	Clientes RPC end-to-end
Deploy compartilhado devnet	QA manual da equipe	Verificações automatizadas de PR

FAQs

Onde ficam os arquivos JSON de fixture?

Padrão comum: tests/fixtures/ commitado no git com origem documentada.

O Anchor.toml pode configurar clones?

Sim em [test.validator] com array clone e url para o cluster de origem.

Como carrego vários programas?

Repita flags --bpf-program <ID> <SO> em uma linha de comando do validador.

Fixtures incluem saldo isento de aluguel?

JSON exportado inclui lamports - garanta o suficiente para aluguel ao injetar manualmente.

Posso atualizar fixture no meio do teste?

Transações podem mutar estado após o boot - fixtures são apenas condições iniciais.

Como compartilho fixtures com segurança?

Não faça commit de dados privados de usuário - sanitize pubkeys e saldos em fixtures compartilhados.

Isso funciona com Surfpool?

Fork Surfpool reduz a necessidade de fixtures manuais - ainda útil para overlays de config customizados.

Quão grande pode ser o dado de fixture?

Respeite limites de tamanho de conta - contas grandes tornam a inicialização proporcionalmente mais lenta.

Posso carregar programas atualizáveis?

Carregue .so no ID do programa; autoridade de upgrade segue regras do loader na localnet.

Como regenero fixtures?

Execute novamente solana account --output json contra estado bom do cluster e incremente a versão do arquivo na mensagem de commit.

Relacionado

solana-test-validator - flags de inicialização
Cloning Mainnet Accounts - snapshots ao vivo
LiteSVM - fixtures em memória
Testing Against a Validator - testes de integração

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.

Carregando Programas e Fixtures

Buscar na documentação

Carregando Programas e Fixtures