Strapi v5 Configuration Troubleshooting Guide

Error: "Cannot destructure property 'client' of 'db.config.connection'"

Este error significa que Strapi no puede cargar la configuración de base de datos para tests.

Estructura de Configuración Requerida

config/
├── database.ts           # Config base (PostgreSQL para desarrollo)
└── env/
    └── test/
        ├── database.ts   # Config para tests (SQLite in-memory)
        └── plugins.ts    # Config de plugins para tests

Solución Paso a Paso

1. Verificar que existe el directorio

ls -la config/env/test/

Debe mostrar:

database.ts
plugins.ts

2. Verificar contenido de config/env/test/database.ts

El archivo DEBE tener exactamente este formato:

/**
 * Test Database Configuration (ADR-009)
 *
 * Uses SQLite in-memory database for fast, isolated testing.
 * Each test run gets a fresh database with no persistent state.
 */

export default () => ({
  connection: {
    client: 'sqlite',
    connection: {
      filename: ':memory:',
    },
    useNullAsDefault: true,
    debug: false,
    pool: {
      min: 1,
      max: 1,
    },
  },
});

IMPORTANTE:

• ✅ Debe tener export default () => ({
• ✅ Debe tener connection: { ... } como primer nivel
• ✅ Dentro va client: 'sqlite'
• ❌ NO debe tener client directamente en el primer nivel

3. Verificar contenido de config/env/test/plugins.ts

/**
 * Test Plugin Configuration (ADR-009)
 *
 * Configures email plugin to use stream transport for testing.
 * Emails are buffered in memory, not sent externally.
 */

export default () => ({
  email: {
    config: {
      provider: 'nodemailer',
      providerOptions: {
        streamTransport: true,
        newline: 'unix',
        buffer: true,
      },
      settings: {
        defaultFrom: '[email protected]',
        defaultReplyTo: '[email protected]',
      },
    },
  },
});

4. Verificar que NODE_ENV se establece correctamente

En package.json, el script de test debe ser:

{
  "scripts": {
    "test": "NODE_ENV=test jest --runInBand --forceExit --detectOpenHandles"
  }
}

5. Limpiar archivos compilados (si existen)

# Eliminar directorios de build que pueden interferir
rm -rf dist/
rm -rf config-dist/
rm -rf .strapi/
rm -rf node_modules/

# Reinstalar dependencias
npm install

6. Verificar que existe la dependencia SQLite

grep "better-sqlite3" package.json

Debe mostrar:

"better-sqlite3": "11.3.0"

Si no existe, instalar:

npm install [email protected]

7. Ejecutar tests

npm test

Cómo Funciona la Configuración por Entorno

Strapi carga configuración en este orden:

1. Archivos base en config/*.ts
2. Overrides por entorno en config/env/{NODE_ENV}/*.ts
3. Variables de entorno desde .env

Ejemplo con NODE_ENV=test:

config/database.ts          ← Base (PostgreSQL)
   ↓
config/env/test/database.ts ← Override (SQLite) ✅ ESTE SE USA
   ↓
.env variables              ← Variables de entorno

Comandos de Diagnóstico

# 1. Verificar estructura
tree config/

# 2. Verificar NODE_ENV en el comando
cat package.json | grep '"test"'

# 3. Verificar que no hay archivos compilados
ls config-dist/ 2>/dev/null || echo "OK - No existe config-dist/"

# 4. Verificar dependencias instaladas
ls node_modules/better-sqlite3/ > /dev/null && echo "✅ SQLite instalado" || echo "❌ Falta SQLite"

# 5. Test de carga de config (debug)
NODE_ENV=test node -e "console.log(require('./config/env/test/database.ts').default())"

Diferencias Clave: Desarrollo vs Testing

Aspecto	Desarrollo (npm run docker:dev)	Testing (npm test)
Entorno	Docker container	Node.js local
NODE_ENV	development	test
Config DB	config/database.ts	config/env/test/database.ts
Base de Datos	PostgreSQL (container)	SQLite in-memory
Persistencia	Sí (named volume)	No (RAM)
Requiere Docker	✅ Sí	❌ No

Errores Comunes

Error: "database is locked"

Causa: Tests corriendo en paralelo con SQLite

Solución: Asegurar que el comando test tiene --runInBand:

"test": "NODE_ENV=test jest --runInBand ..."

Error: "Cannot find module 'better-sqlite3'"

Causa: Dependencia no instalada

Solución:

npm install [email protected]

Error: Config file not found

Causa: Falta el directorio o archivo de configuración

Solución: Crear la estructura completa:

mkdir -p config/env/test
# Luego crear los archivos database.ts y plugins.ts

Checklist de Verificación

Antes de ejecutar tests, verificar:

• Existe config/env/test/database.ts
• Existe config/env/test/plugins.ts
• El formato de archivos es correcto (export default function)
• package.json tiene NODE_ENV=test en script
• Dependencia better-sqlite3 instalada
• No existe config-dist/ (eliminar si existe)
• node_modules/ instalado (npm install)

Comando Completo de "Reset"

Si nada funciona, ejecutar esto:

# 1. Limpiar todo
rm -rf node_modules/ dist/ config-dist/ .strapi/

# 2. Reinstalar
npm install

# 3. Verificar estructura
ls -la config/env/test/

# 4. Correr tests
npm test

Cómo Crear Archivos Si No Existen

Crear directorio

mkdir -p config/env/test

Crear config/env/test/database.ts

cat > config/env/test/database.ts << 'EOF'
/**
 * Test Database Configuration (ADR-009)
 */

export default () => ({
  connection: {
    client: 'sqlite',
    connection: {
      filename: ':memory:',
    },
    useNullAsDefault: true,
    debug: false,
    pool: {
      min: 1,
      max: 1,
    },
  },
});
EOF

Crear config/env/test/plugins.ts

cat > config/env/test/plugins.ts << 'EOF'
/**
 * Test Plugin Configuration (ADR-009)
 */

export default () => ({
  email: {
    config: {
      provider: 'nodemailer',
      providerOptions: {
        streamTransport: true,
        newline: 'unix',
        buffer: true,
      },
      settings: {
        defaultFrom: '[email protected]',
        defaultReplyTo: '[email protected]',
      },
    },
  },
});
EOF

Referencias

• ADR-009: Testing Strategy
• ADR-002: TypeScript Config Compilation
• Strapi v5 Docs: https://docs.strapi.io/dev-docs/configurations