---

name: test-cli-application description: > Write integration tests for a Node.js CLI application using the built-in node:test module. Covers the exec helper pattern, output assertions, filesystem state verification, cleanup hooks, JSON output parsing, error case testing, and state restoration after destructive tests. Use when adding tests to an existing CLI, testing a new command, verifying adapter behavior across frameworks, or setting up CI for a CLI tool. license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: cli complexity: intermediate language: TypeScript tags: - cli - testing - nodejs - node-test - integration locale: es source_locale: en source_commit: 11edabf5 fence_basis_commit: 11edabf5 translator: "Claude + human review" translation_date: "2026-05-03"

Test a CLI Application

Escribir pruebas de integración para una CLI Node.js usando el módulo built-in node:test con execSync.

Cuándo Usar

• Añadir pruebas a una aplicación CLI existente
• Probar un comando recién creado
• Verificar el comportamiento del adaptador/plugin a través de frameworks objetivo
• Configurar CI que valida la corrección de la CLI
• Captar regresiones después de refactorizar internos de CLI

Entradas

• Requerido: Ruta al punto de entrada de la CLI (p. ej., cli/index.js)
• Requerido: Comandos a probar
• Opcional: Adaptadores de framework a probar (modo dry-run)
• Opcional: Requisitos de limpieza (archivos/symlinks creados por las pruebas)

Procedimiento

Paso 1: Configurar la Infraestructura de Pruebas

import { describe, it, before, after } from 'node:test';
import assert from 'node:assert/strict';
import { execSync } from 'child_process';
import { existsSync, rmSync } from 'fs';
import { resolve } from 'path';

const CLI = 'node cli/index.js';
const ROOT = process.cwd();

function run(args) {
  return execSync(`${CLI} ${args}`, {
    cwd: ROOT,
    encoding: 'utf8',
    timeout: 10000,
  });
}

Decisiones clave de diseño:

• node:test está built-in — no se necesita dependencia de test runner
• execSync ejecuta la CLI como subproceso — prueba el binario real, no funciones internas
• Timeout de 10 segundos previene cuelgues en prompts interactivos
• encoding: 'utf8' da salida string para coincidencia con regex
• Todas las rutas relativas a ROOT para reproducibilidad

Esperado: Un archivo de pruebas que importa de node:test y tiene un helper run() funcional.

En caso de fallo: Si node:test no está disponible, tu versión de Node.js está debajo de 18. Actualizar o usar un polyfill.

Paso 2: Escribir Pruebas Smoke

Las pruebas smoke verifican que la CLI inicia, parsea argumentos y produce las formas de salida esperadas:

describe('meta', () => {
  it('shows version', () => {
    const out = run('--version');
    assert.match(out, /\d+\.\d+\.\d+/);
  });

  it('shows help with all commands', () => {
    const out = run('--help');
    assert.match(out, /install/);
    assert.match(out, /list/);
    assert.match(out, /detect/);
  });
});

describe('registry', () => {
  it('list shows expected counts', () => {
    const out = run('list --domains');
    assert.match(out, /\d+ domains/);
  });

  it('search finds known items', () => {
    const out = run('search "docker"');
    assert.match(out, /result\(s\) for "docker"/);
  });

  it('search returns 0 for nonsense', () => {
    const out = run('search "xyzzy-nonexistent"');
    assert.match(out, /0 result/);
  });
});

Patrones de prueba smoke:

• --version y --help siempre funcionan
• La carga del registry valida la integridad de los datos
• Búsqueda con términos conocidos y desconocidos

Esperado: Las pruebas smoke confirman que la CLI es funcional y los datos están cargados.

En caso de fallo: Si los conteos del registry cambian frecuentemente, usar \d+ en lugar de números hardcoded.

Paso 3: Escribir Pruebas de Lifecycle

Las pruebas de lifecycle verifican secuencias create → verify → delete con limpieza:

describe('install', () => {
  const testPath = resolve(ROOT, '.agents/skills/commit-changes');

  after(() => {
    // Always clean up, even if tests fail
    try { rmSync(testPath); } catch {}
    try { rmSync(resolve(ROOT, '.agents/skills'), { recursive: true }); } catch {}
    try { rmSync(resolve(ROOT, '.agents'), { recursive: true }); } catch {}
  });

  it('dry-run does not create files', () => {
    const out = run('install commit-changes --dry-run');
    assert.match(out, /DRY RUN/);
    assert.ok(!existsSync(testPath));
  });

  it('installs creates the target', () => {
    run('install commit-changes');
    assert.ok(existsSync(testPath));
  });

  it('skips already installed', () => {
    const out = run('install commit-changes');
    assert.match(out, /skipped/);
  });

  it('uninstall removes the target', () => {
    run('uninstall commit-changes');
    assert.ok(!existsSync(testPath));
  });
});

Reglas de limpieza:

• Usar hooks after(), no afterEach() — las pruebas de lifecycle se construyen unas sobre otras
• Envolver la limpieza en try/catch — la limpieza no debe fallar la suite de pruebas
• Limpiar de hoja a raíz (archivo → directorio padre → directorio abuelo)
• Si la prueba modifica estado compartido (symlinks, archivos de config), restaurarlo

Esperado: Las pruebas corren en secuencia dentro del bloque describe, la limpieza corre incluso en caso de fallo.

En caso de fallo: Si las pruebas corren en paralelo (no-predeterminado en node:test), forzar secuencial con { concurrency: 1 }.

Paso 4: Escribir Pruebas Dry-Run para Cada Adaptador

Probar la ruta objetivo de cada adaptador sin hacer cambios:

describe('adapter: cursor (dry-run)', () => {
  it('targets .cursor/skills/ path', () => {
    const out = run('install commit-changes --framework cursor --dry-run');
    assert.match(out, /\.cursor\/skills/i);
  });
});

describe('adapter: copilot (dry-run)', () => {
  it('targets .github/ path', () => {
    const out = run('install commit-changes --framework copilot --dry-run');
    assert.match(out, /\.github/i);
  });
});

Este patrón escala a cualquier número de adaptadores. Cada prueba:

• Usa --framework para sortear la auto-detección
• Usa --dry-run para que no se creen archivos
• Asserta que la ruta objetivo aparece en la salida

Esperado: Un bloque describe por adaptador, cada uno con al menos una assertion de ruta.

En caso de fallo: Si el adaptador no existe en el proyecto, la prueba fallará con "Unknown framework." Esto es correcto — las pruebas de adaptador solo deben existir para adaptadores implementados.

Paso 5: Escribir Pruebas de Casos de Error

describe('errors', () => {
  it('rejects unknown items', () => {
    assert.throws(
      () => run('install nonexistent-skill-xyz'),
      /No matching items|Unknown/,
    );
  });

  it('rejects unknown framework', () => {
    assert.throws(
      () => run('install commit-changes --framework nonexistent'),
      /Unknown framework/,
    );
  });

  it('handles missing state gracefully', () => {
    assert.throws(
      () => run('scatter nonexistent-team'),
      /not burning|Unknown/,
    );
  });
});

Patrones de prueba de errores:

• assert.throws captura códigos de salida no-cero de execSync
• Coincidencia regex en el mensaje de error (capturado de stderr)
• Probar errores tanto de "item no encontrado" como de "opción inválida"
• Verificar que los mensajes de error sugieren acciones correctivas

Esperado: Todos los caminos de error producen códigos de salida no-cero y mensajes útiles.

En caso de fallo: execSync lanza en caso de salida no-cero. El stderr o stdout del error contiene el mensaje. Verificar error.stdout si la regex de assert.throws no coincide.

Paso 6: Escribir Pruebas de Salida JSON

describe('json output', () => {
  it('campfire --json outputs valid JSON', () => {
    const out = run('campfire --json');
    const data = JSON.parse(out);
    assert.ok(typeof data.totalTeams === 'number');
    assert.ok(Array.isArray(data.fires));
  });

  it('gather --dry-run --json outputs structured data', () => {
    const out = run('gather tending --dry-run --json');
    // JSON may follow a DRY RUN header — extract from first '{'
    const jsonStart = out.indexOf('{');
    assert.ok(jsonStart >= 0, 'Should contain JSON');
    const data = JSON.parse(out.slice(jsonStart));
    assert.equal(data.team, 'tending');
  });
});

Trampas de prueba JSON:

• Algunos comandos prefijan JSON con texto legible para humanos (p. ej., header DRY RUN)
• Extraer JSON encontrando el primer carácter {
• Validar la estructura (presencia de claves, tipos), no los valores exactos
• Valores como conteos pueden cambiar conforme se añade contenido

Esperado: La salida JSON es parseable y contiene las claves esperadas.

En caso de fallo: Si JSON.parse falla, el comando puede estar mezclando texto humano con JSON. O arreglar el comando para emitir JSON puro en modo --json, o extraer el substring JSON.

Paso 7: Manejar Limpieza y Restauración de Estado

describe('stateful commands', () => {
  const stateDir = resolve(ROOT, '.agent-almanac');

  after(() => {
    // Remove state file created by tests
    try { rmSync(stateDir, { recursive: true }); } catch {}
  });

  // Tests that create/modify state...
});

// Restore symlinks that destructive tests may remove
describe('destructive tests', () => {
  after(() => {
    // Restore symlinks that scatter/uninstall removed
    const skills = ['heal', 'meditate', 'remote-viewing'];
    for (const skill of skills) {
      const link = resolve(ROOT, `.claude/skills/${skill}`);
      if (!existsSync(link)) {
        try {
          execSync(`ln -s ../../skills/${skill} ${link}`, { cwd: ROOT });
        } catch {}
      }
    }
  });
});

Reglas de restauración de estado:

• Los archivos de estado (.agent-almanac/state.json) deben limpiarse después de las pruebas
• Symlinks eliminados por scatter/uninstall deben ser restaurados
• Los archivos de manifiesto (agent-almanac.yml) creados por init deben eliminarse
• Orden: los hooks after() corren en orden inverso de declaración — declarar hooks de restauración al final

Esperado: La suite de pruebas deja el proyecto en el mismo estado en que lo encontró.

En caso de fallo: Si CI reporta archivos sobrantes después de las ejecuciones de prueba, añadir la limpieza al after(). Usar git status después de las ejecuciones de prueba para detectar estado filtrado.

Validación

• El archivo de prueba corre con node --test cli/test/cli.test.js
• Todas las pruebas pasan (0 fallos)
• Las pruebas smoke cubren --version, --help y carga del registry
• Las pruebas de lifecycle verifican create → verify → delete con limpieza
• Existe al menos una prueba dry-run de adaptador por adaptador implementado
• Los casos de error prueban códigos de salida no-cero con coincidencia de mensaje
• Las pruebas de salida JSON parsean salida real (no mockeada)
• Los hooks after restauran todo el estado modificado por las pruebas

Errores Comunes

• Conteos hardcoded que se rompen: Los totales del registry cambian conforme se añade contenido. Usar regex \d+ o leer el conteo dinámicamente en lugar de assertear 329 skills.
• Pruebas que dependen del orden de ejecución: node:test corre suites en orden de declaración por defecto, pero las pruebas dentro de una suite pueden no. Usar suites de lifecycle (create → verify → delete) dentro de un solo describe para garantizar el orden.
• Limpieza faltante en fallo de prueba: Si una prueba falla a media-lifecycle, after() aún corre. Pero si lanzas en before(), las pruebas subsiguientes y after() pueden no correr. Mantener before() mínimo.
• Prompts interactivos colgando pruebas: Los comandos con prompts de confirmación colgarán execSync. O hacer pipe de echo y | o asegurar que --yes siempre se pase en pruebas.
• Probar con instalaciones reales en CI: Las pruebas que crean archivos en .claude/skills/ o .agents/skills/ modifican el árbol de trabajo. CI puede fallar en verificaciones de "directorio de trabajo sucio". Siempre limpiar.

Habilidades Relacionadas

• scaffold-cli-command — construir los comandos que estas pruebas verifican
• build-cli-plugin — construir los adaptadores probados en el Paso 4
• design-cli-output — patrones de salida contra los que las pruebas assertan