solana-test-validator
Ejecuta solana-test-validator para obtener un clúster Solana de un solo nodo con ejecución de programas BPF, faucet y JSON-RPC en localhost.
Receta
Tarjeta de receta de referencia rápida - lista para copiar y pegar.
solana-test-validator
solana-test-validator --reset
solana-test-validator --bpf-program <PROGRAM_ID> target/deploy/my_program.soCuándo usar esto:
- Backend predeterminado para
anchor test. - Pruebas manuales del cliente contra un estado nuevo.
- Carga de programas personalizados sin despliegue público en devnet.
- Clonación de cuentas selectas de mainnet para pruebas CPI realistas.
Ejemplo de Trabajo
# Terminal 1: validador con tu programa precargado
solana-test-validator --reset \
--bpf-program "$(solana-keygen pubkey target/deploy/my_program-keypair.json)" \
target/deploy/my_program.so
# Terminal 2: CLI + pruebas
solana config set --url http://127.0.0.1:8899
solana airdrop 5
anchor test --skip-local-validator # si el validador ya se está ejecutandoLo que esto demuestra:
--resetborra el ledger para ejecuciones deterministas.--bpf-programregistra el bytecode en un ID de programa fijo al inicio.- El puerto 8899 sirve RPC; 8900 es común para gossip/WebSocket.
Análisis Profundo
Cómo Funciona
- Incrusta la lógica del validador Agave ajustada para la velocidad del desarrollador (épocas más cortas, límites relajados).
- Mina bloques localmente con tus transacciones incluidas inmediatamente.
- El faucet acuña SOL sin límites de tasa.
- El ledger se almacena por defecto en
test-ledger/a menos que--ledgerlo anule.
Banderas Útiles
| Bandera | Efecto |
|---|---|
--reset | Elimina el ledger existente |
--ledger <RUTA> | Directorio de estado persistente |
--clone <PUBKEY> | Copia la cuenta desde --url al inicio |
--bpf-program <ID> <SO> | Precarga el binario del programa |
--url <CLUSTER> | Fuente para las clonaciones |
Notas de bash
# Silenciar logs para CI
solana-test-validator --quiet --reset
# Vincular puerto RPC personalizado
solana-test-validator --rpc-port 18899Trampas Comunes
- Olvido de
--reset: el estado obsoleto causa pruebas inestables. Solución: restablecer siempre en CI; documentar la ruta del ledger para experimentos persistentes. - Puerto ya en uso: el validador anterior todavía se está ejecutando. Solución:
pkill solana-test-validatoro cambiar--rpc-port. - Clonación sin URL de mainnet: cuenta vacía al inicio. Solución: pasar
--url mainnet-betacon--clone. - Desajuste del ID del programa: el ID de
--bpf-programdebe coincidir condeclare_id!del cliente. Solución: usar la clave pública del keypair detarget/deploy. - Asumir WebSocket en el mismo puerto: algunas configuraciones necesitan URL de WS explícita. Solución: verificar errores de conexión de
solana logs.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Surfpool 0.12.0 | Simulación de fork de Mainnet | Pruebas locales mínimas sin dependencias |
| LiteSVM 0.6.x | Pruebas unitarias sub-segundo | Integración completa del cliente RPC |
| devnet | Entorno de staging compartido | Bucle de desarrollo interno rápido |
anchor test validador incrustado | Pruebas con un solo comando | Sesión manual de larga duración |
Preguntas Frecuentes
¿Qué puertos usa test-validator?
RPC predeterminado 8899, gossip 8900, faucet 9900 - configurable mediante banderas.
¿Puedo persistir el ledger entre reinicios?
Sí - omite --reset y reutiliza la ruta de --ledger; ten cuidado con la deriva del estado en las pruebas.
¿Cómo precargo programas SPL?
Clona los IDs de programa de Token o usa --bpf-program con claves públicas de programas conocidas.
¿Soporta transacciones versionadas?
Sí - coincide con las características de Agave 4.1.1, incluidas las transacciones v0 y ALTs cuando están habilitadas en las características del clúster.
¿Cuántas clonaciones son prácticas?
Empieza con decenas, no miles - cada clonación añade tiempo de recuperación RPC al inicio.
¿Puede Docker ejecutar test-validator?
Sí para CI - expón el puerto 8899 a los contenedores de prueba.
¿Por qué el tiempo de slot es diferente a mainnet?
El validador de prueba ajusta el tiempo de slot para el rendimiento del desarrollador, no para el tiempo de consenso de producción.
¿Cómo me detengo con gracia?
Ctrl+C en la terminal; asegúrate de que no haya procesos huérfanos que retengan el puerto 8899.
¿Anchor test inicia su propio validador?
Por defecto sí - usa --skip-local-validator cuando gestiones el validador manualmente.
¿Puedo ejecutar múltiples validadores?
Sí en diferentes valores de --rpc-port para fragmentos de CI paralelos.
Relacionado
- Conceptos Básicos de Desarrollo Local - resumen del bucle de desarrollo
- Clonación de Cuentas de Mainnet - estado realista
- Carga de Programas y Fixtures - patrones de precarga
- Surfpool - alternativa basada en fork
Versiones de la Pila: Esta página fue 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, y LiteSVM 0.6.x.