El sistema de validación de variables de entorno (app/src/server/envValidation.ts) se ejecuta automáticamente al iniciar el servidor y garantiza que toda la configuración requerida esté presente antes de que la aplicación pueda lanzarse.

Métodos de Prueba

Método 1: Script Automatizado (Recomendado)

El script bash automatizado verifica que la validación detecte variables faltantes:

cd e2e-tests
npm run test:validation

Qué hace el script:

1. ✅ Respalda tu archivo .env.server
2. ✅ Verifica que todas las variables requeridas estén presentes
3. ✅ Muestra cuáles variables faltan (si hay alguna)
4. ✅ Restaura tu configuración original automáticamente

Nota: El script no puede verificar automáticamente que la validación detecta variables faltantes (requeriría iniciar el servidor Wasp). Para eso, usa el Método 2 (Prueba Manual del Servidor).

Salida esperada:

🧪 Testing Environment Variable Validation

Test 1: Server validation with missing STRIPE_API_KEY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Backed up .env.server
✓ Removed STRIPE_API_KEY from .env.server

Note: The validation runs when the server starts.
To see validation errors, manually run: cd app && wasp start

⚠️  Test 1: Automated validation check skipped
   (Requires running Wasp server to trigger validation)

✓ Restored .env.server

Test 2: Server validation with all required variables
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ DATABASE_URL is set
✓ STRIPE_API_KEY is set
✓ STRIPE_WEBHOOK_SECRET is set
✓ PAYMENTS_MONTHLY_SUBSCRIPTION_PLAN_ID is set
✓ PAYMENTS_ANNUAL_SUBSCRIPTION_PLAN_ID is set
✓ ADMIN_EMAILS is set
✓ CLIENT_URL is set

✅ TEST PASSED: All required variables present

Método 2: Prueba Manual del Servidor (Más Confiable)

Prueba iniciando el servidor Wasp real para ver la validación en acción:

Paso 1: Respalda tu configuración

cd app
cp .env.server .env.server.backup

Paso 2: Elimina una variable requerida

# Edita app/.env.server
# Comenta o elimina una variable requerida como:
# STRIPE_API_KEY=sk_test_...

Paso 3: Intenta iniciar el servidor

wasp start

Resultado Esperado: El servidor falla inmediatamente con error de validación:

🚨 ENVIRONMENT VALIDATION FAILED

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 REQUIRED Variables Missing (1)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

❌ STRIPE_API_KEY
   Stripe API key for payment processing
   Get it: https://dashboard.stripe.com/apikeys

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📖 Complete reference: /operaciones/variables-entorno
🔧 Deployment checklist: /operaciones/checklist-produccion

Paso 4: Restaura tu configuración

mv .env.server.backup .env.server

Qué se Valida

Variables REQUIRED (Siempre Obligatorias)

Variable	Descripción	Formato Esperado
DATABASE_URL	Conexión PostgreSQL	postgresql://user:pass@host/db
JWT_SECRET	Autenticación JWT	Base64, mínimo 32 caracteres
STRIPE_API_KEY	Procesamiento de pagos	sk_test_* o sk_live_*
STRIPE_WEBHOOK_SECRET	Verificación webhooks	whsec_*
PAYMENTS_MONTHLY_SUBSCRIPTION_PLAN_ID	Plan mensual	price_*
PAYMENTS_ANNUAL_SUBSCRIPTION_PLAN_ID	Plan anual	price_*
SENDGRID_API_KEY	Email (solo producción)	SG.*
ADMIN_EMAILS	Acceso administrador	Emails separados por coma
CLIENT_URL	URL del frontend	https://dominio.com

Variables CONDITIONAL (Si Feature Habilitado)

AWS S3 + CloudFront (si usas videos en producción):

• AWS_S3_IAM_ACCESS_KEY - Credencial IAM
• AWS_S3_IAM_SECRET_KEY - Secret IAM
• AWS_S3_FILES_BUCKET - Nombre del bucket
• AWS_S3_REGION - Región AWS
• CLOUDFRONT_DOMAIN - Dominio CloudFront
• CLOUDFRONT_KEY_PAIR_ID - ID del key pair
• CLOUDFRONT_PRIVATE_KEY - Clave privada

OAuth Social (si está configurado):

• GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET - Google OAuth
• GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET - GitHub OAuth

Procesadores de Pago Alternativos:

• LEMONSQUEEZY_API_KEY / LEMONSQUEEZY_STORE_ID - Lemon Squeezy
• POLAR_ACCESS_TOKEN / POLAR_ORGANIZATION_ID - Polar

Variables OPTIONAL

Estas generan advertencias pero no detienen el servidor:

• PLAUSIBLE_API_KEY - Analytics Plausible
• REACT_APP_GOOGLE_ANALYTICS_ID - Google Analytics 4
• OPENAI_API_KEY - Funciones de IA
• SENDGRID_FIELD_FROM_NAME - Nombre del remitente email
• SENDGRID_FIELD_FROM_EMAIL - Email del remitente

Validación de Formato

El sistema también valida formatos de valores:

// Ejemplo: STRIPE_API_KEY
{
  name: 'STRIPE_API_KEY',
  format: /^sk_(test|live)_/,  // ✅ sk_test_xxx o sk_live_xxx
  setupUrl: 'https://dashboard.stripe.com/apikeys'
}

Formatos validados:

• STRIPE_API_KEY → Debe empezar con sk_test_ o sk_live_
• STRIPE_WEBHOOK_SECRET → Debe empezar con whsec_
• SENDGRID_API_KEY → Debe empezar con SG.
• DATABASE_URL → Debe ser PostgreSQL válido
• URLs → Deben empezar con http:// o https://

Desarrollo vs Producción

Algunas variables solo son obligatorias en producción:

// Ejemplo: SENDGRID_API_KEY
{
  name: 'SENDGRID_API_KEY',
  category: EnvCategory.REQUIRED,
  productionOnly: true  // ← Solo requerido si NODE_ENV=production
}

En desarrollo:

• Variables productionOnly generan advertencias pero no fallan
• Emails se imprimen en consola en lugar de enviarse
• Puedes usar claves de test de Stripe

En producción:

• Variables productionOnly son obligatorias
• El servidor no inicia sin ellas
• Debe usar claves sk_live_* de Stripe

Integración en CI/CD

Incluye el test de validación en tu pipeline:

GitHub Actions

.github/workflows/test.yml

name: Tests

on: [push, pull_request]

jobs:
  test-validation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "18"

      - name: Install dependencies
        run: |
          cd e2e-tests
          npm install

      - name: Test Environment Validation
        run: |
          cd e2e-tests
          npm run test:validation

GitLab CI

.gitlab-ci.yml

test-validation:
  stage: test
  script:
    - cd e2e-tests
    - npm install
    - npm run test:validation

Troubleshooting

El script muestra “Could not verify validation”

Esto significa que el test automatizado no pudo detectar el error de validación. Usa el Método 2 (Prueba Manual del Servidor) que es más confiable.

Todas las pruebas fallan

Verifica que:

1. Estás ejecutando desde el directorio e2e-tests
2. El archivo app/.env.server existe
3. Tienes todas las dependencias instaladas: npm install

Variables están configuradas pero el test reporta faltantes

Asegúrate que las variables estén en el formato correcto:

# ✅ Correcto
VARIABLE_NAME=value

# ❌ Incorrecto
export VARIABLE_NAME=value  # No se detectará
# VARIABLE_NAME=value       # Comentado, no se detectará

Error: “permission denied”

El script necesita permisos de ejecución:

chmod +x e2e-tests/tests/test-validation.sh

Ejemplos de Errores de Validación

Error: Variable Faltante

🚨 ENVIRONMENT VALIDATION FAILED

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 REQUIRED Variables Missing (3)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

❌ STRIPE_API_KEY
   Stripe API key for payment processing
   Get it: https://dashboard.stripe.com/apikeys

❌ SENDGRID_API_KEY
   SendGrid API key for email delivery
   Get it: https://app.sendgrid.com/settings/api_keys

❌ JWT_SECRET
   Secret for signing JWT tokens
   Get it: Run: openssl rand -base64 32

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📖 Complete reference: /operaciones/variables-entorno
🔧 Deployment checklist: /operaciones/checklist-produccion

Error: Formato Inválido

❌ Invalid format for STRIPE_API_KEY
   Expected pattern: /^sk_(test|live)_/
   Get it: https://dashboard.stripe.com/apikeys

Advertencias (No Detienen el Servidor)

⚠️  ENVIRONMENT VALIDATION WARNINGS

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 CONDITIONAL Variables Missing (5)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️  AWS_S3_IAM_ACCESS_KEY
   AWS IAM access key for S3 video uploads
   Get it: https://console.aws.amazon.com/iam

...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 OPTIONAL Variables Missing (3)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ℹ️  OPENAI_API_KEY
   OpenAI API key for AI features
   Get it: https://platform.openai.com/api-keys

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Implementación Técnica

El sistema de validación está implementado en:

app/src/server/envValidation.ts

Lógica central de validación:

export function validateEnvironment(): ValidationResult {
  const missing = {
    required: [] as EnvVarConfig[],
    conditional: [] as EnvVarConfig[],
    optional: [] as EnvVarConfig[],
  };

  ENV_VARS.forEach(config => {
    const value = process.env[config.name];

    if (!value) {
      // Categorizar variables faltantes
      if (config.category === EnvCategory.REQUIRED) {
        missing.required.push(config);
      }
      // ...
    } else if (config.format && !config.format.test(value)) {
      // Validación de formato
      throw new Error(`Invalid format for ${config.name}`);
    }
  });

  // Lanzar error si faltan variables REQUIRED
  if (missing.required.length > 0) {
    throw new Error(formatValidationError(missing));
  }

  return { success: true, warnings: missing };
}

app/src/server/utils.ts

La validación se ejecuta al importar el módulo:

import { validateEnvironment } from './envValidation';

// Se ejecuta al cargar el módulo (antes de que arranque el servidor)
validateEnvironment();

// Funciones de utilidad...
export function requireEnvVar(name: string, options?: { ... }): string {
  // ...
}

Recursos Relacionados

• Variables de Entorno - Referencia Completa
• Checklist de Producción
• Guía de Despliegue en Fly.io
• Guía de Despliegue en Railway
• Migración de Variables de Entorno