Apidog CLI + Claude Skills: Integración de pruebas automatizadas de API en el flujo de desarrollo

Este artículo presenta cómo combinar Apidog CLI con Claude Skills para construir un flujo de trabajo eficiente para la prueba de automatización de API impulsada por lenguaje natural.

En este flujo de trabajo, solo necesita decir una sola frase a Claude Code en su terminal, por ejemplo:

"Ejecutar la prueba de flujo de pedido de usuario en dev."

Claude Code comprenderá automáticamente su intención, localizará el escenario de prueba o conjunto de pruebas correspondiente, ejecutará las pruebas y luego resumirá e interpretará los resultados para usted.

Apidog CLI + Claude Skills: Integración de pruebas de automatización de API en el flujo de trabajo de desarrollo

Resumen de Herramientas

Este flujo de trabajo se compone de tres herramientas:

1. Apidog CLI

La interfaz de línea de comandos proporcionada por Apidog. Se utiliza para ejecutar pruebas de automatización de API desde la terminal y generar informes de prueba.

2. Claude Code

Un asistente de IA de línea de comandos lanzado por Anthropic. Puede operar en archivos, ejecutar comandos, ejecutar scripts e interactuar con su entorno de desarrollo local.

3. Claude Skills

También conocidas como Habilidades de Agente, un mecanismo de extensión de Claude Code. Una Habilidad define cómo Claude debe completar una tarea específica, actuando esencialmente como un conjunto ejecutable de instrucciones operativas.

En este flujo de trabajo, Claude Code es responsable de comprender las instrucciones en lenguaje natural. Cuando la solicitud de un usuario coincide con una Claude Skill predefinida, Claude ejecuta automáticamente los comandos Apidog CLI correspondientes y analiza los resultados.

Qué Puede Hacer Este Flujo de Trabajo

A continuación se presentan varios escenarios del mundo real para ilustrar cómo se puede utilizar este flujo de trabajo en la práctica.

Ejecutar una Sola Prueba

Si desea ejecutar un escenario de prueba específico, puede nombrarlo explícitamente. Por ejemplo:

"Ejecutar las pruebas de inicio de sesión en dev."

Una vez finalizada la prueba, Claude analiza los resultados y proporciona un resumen.

Listar Todas las Pruebas Disponibles

Para ver qué escenarios de prueba o conjuntos de pruebas están disponibles, puede decir:

"Muéstrame las pruebas disponibles."

Claude ejecutará el script relevante y listará todas las pruebas.

Ejecutar Todas las Pruebas para un Módulo de Negocio

Si desea ejecutar todas las pruebas para un dominio de negocio específico, como las pruebas relacionadas con pagos, puede decir:

"Ejecutar todas las pruebas de pago en el entorno de prueba."

Claude localizará automáticamente todos los archivos de prueba relacionados y los ejecutará secuencialmente o en paralelo.

Comparar Resultados de Prueba entre Entornos

Para comparar resultados entre entornos, puede decir:

"Ejecutar las pruebas de inicio de sesión en dev y test."

Claude ejecutará las pruebas en ambos entornos y analizará las diferencias en los resultados.

Ejecutar Pruebas Basadas en Cambios de Código

Después de los cambios de código, puede pedirle a Claude que ejecute solo las pruebas afectadas:

"Basado en los cambios de código recientes, ejecutar las pruebas de API impactadas en dev."

Claude analizará los cambios de Git, determinará los escenarios o conjuntos de pruebas afectados y ejecutará solo esas pruebas, ahorrando tiempo y recursos.

Más escenarios esperan ser explorados.

A continuación, explicaremos cómo instalar y configurar Apidog CLI, Claude Code y Claude Skills, y cómo combinarlos en un flujo de trabajo completo.

Preparación

Requisitos del Entorno

Asegúrese de que Node.js esté instalado en su máquina. Verifíquelo en su terminal:

node -v
npm -v

Instalación de Apidog CLI (Instalar vía npm):

npm install -g apidog-cli

Verifique la instalación:

apidog --version

Si se muestra un número de versión, la instalación fue exitosa.
Puede copiar un comando CLI para un escenario de prueba o conjunto de pruebas desde Apidog → Pruebas → CI/CD, añadir su Token de Acceso y ejecutarlo en la terminal.

Si aparece la salida de la prueba, Apidog CLI está funcionando correctamente.

💡

Nota: Tanto el cliente de escritorio Apidog como Apidog CLI deben actualizarse a la última versión para usar las funciones más recientes de conjuntos de pruebas.

Instalación de Claude Code

Instalar vía npm:

npm install -g @anthropic-ai/claude-code

Verificar:

claude --version

En la primera ejecución, debe iniciar sesión:

claude

Siga los pasos de autorización. Se requiere una cuenta de Claude. Después de iniciar sesión, ingresará a la interfaz interactiva y podrá hacer preguntas básicas.

En este punto, Claude aún no sabe cómo ejecutar las pruebas de Apidog. A continuación, le enseñaremos usando Claude Skills.

Construyendo Claude Skills

Entendiendo Cómo Funcionan las Habilidades (Skills)

Al usar Claude Code, no selecciona manualmente una Habilidad. Simplemente describe lo que quiere hacer en lenguaje natural.

Si su solicitud coincide con la descripción de una Habilidad, Claude carga automáticamente esa Habilidad y ejecuta el flujo de trabajo definido.

Paso 1: Crear la Carpeta de la Habilidad

Todas las configuraciones de Habilidad residen en la carpeta .claude/skills/. Cada Habilidad tiene su propia subcarpeta.

Cree una carpeta de Habilidad mínima para las pruebas de automatización de Apidog en la raíz del proyecto:

mkdir -p .claude/skills/apidog-tests

Estructura resultante:

.claude/skills/apidog-tests/

Gradualmente agregaremos archivos de entrada y scripts aquí.

Paso 2: Crear `SKILL.md`

Cada Habilidad requiere un archivo SKILL.md que define cómo Claude debe ejecutar la tarea una vez que se activa la Habilidad.

El archivo comienza con metadatos YAML envueltos en ---. Los campos name y description son obligatorios.

La description es especialmente importante: determina cuándo Claude debe activar esta Habilidad.

Debajo del bloque YAML, el contenido Markdown define la lógica de ejecución, las reglas de decisión, los scripts a invocar y las restricciones.

Ejemplo de SKILL.md para pruebas de automatización de Apidog

---
name: apidog-tests
description: Ejecuta e interpreta pruebas API automatizadas de Apidog a través de Apidog CLI. Active esta habilidad siempre que el usuario solicite explícitamente ejecutar pruebas, casos de prueba, escenarios de prueba o suites de prueba, incluyendo solicitudes para ejecutar pruebas en un entorno específico como dev, test o prod, para verificar el comportamiento de la API después de cambios en el código, para realizar pruebas de regresión o pre-lanzamiento, o para ejecutar comprobaciones de API antes de un git commit, push o merge. Incluso si el usuario no menciona explícitamente "Apidog" o "API", asuma que estas solicitudes se refieren a pruebas automatizadas de Apidog cuando la ejecución de pruebas está implícita. La habilidad debe seleccionar el escenario de prueba o suite de prueba apropiada, ejecutar las pruebas y explicar los resultados sin modificar las definiciones de prueba o los comandos.
---

# Pruebas de Apidog

Ejecuta pruebas automatizadas de Apidog e interpreta los resultados.

## Flujo de Trabajo

1. **Seleccionar Prueba**:

- Si el usuario proporciona explícitamente:
  - Ruta del archivo de prueba
  - Nombre del archivo de prueba
  - O un nombre de prueba claro y que coincida de forma única
- Usar esa prueba directamente sin selección automática.
- Si la información no está clara, priorizar la ejecución del script `node ./.claude/skills/apidog-tests/scripts/list-tests.js` para recuperar rápidamente todas las rutas y descripciones de los archivos de prueba.
- Evitar búsquedas globales ciegas en grandes directorios de proyectos; en su lugar, localizar el directorio de archivos de prueba `./.claude/skills/apidog-tests/tests/` dedicado a esta habilidad.

2. **Reglas de Ejecución de Múltiples Pruebas**

- Por defecto, ejecutar solo una prueba, pero ofrecer la opción de ejecución por lotes.
- Si el usuario dice explícitamente:
  - "Ejecuta estos pocos"
  - "Ejecútalos todos"
- Entrar en **Modo de Ejecución por Lotes**.

En Modo de Ejecución por Lotes:
- Listar claramente las pruebas a ejecutar.
- **Pedir método de ejecución**: Dejar que el usuario elija entre "Ejecución Secuencial" (mejor legibilidad) o "Ejecución Paralela" (más rápido).
  - **Ejecución Secuencial**: Ejecutar las pruebas una por una y analizar inmediatamente, adecuado para depuración.
  - **Ejecución Paralela**: Iniciar múltiples pruebas simultáneamente (usando `&` o scripts concurrentes), adecuado para regresión rápida, aunque los registros pueden entrelazarse.
- Solicitar confirmación al usuario para el método de ejecución y la lista de pruebas (Sí / No).
- Ejecutar pruebas según el método elegido.
- Finalmente, resumir o explicar individualmente los resultados de cada prueba.

3. **Confirmar Entorno**:
- Los entornos compatibles incluyen:
  - `dev`
  - `test`
  - `prod`
- Si el usuario no ha especificado un entorno:
  - Listar los nombres de los entornos anteriores.
  - Pedir al usuario que confirme cuál usar.

4. **Ejecutar Prueba**:
- Ejecutar la prueba una vez que la siguiente información esté clara:
  - Ruta del archivo de prueba
  - Nombre del entorno (dev / test / prod)
```bash
node ./.claude/skills/apidog-tests/scripts/run-cli.js <test_file_path> <env_name>
```

5. **Interpretar Resultados**: Analizar la salida de Apidog CLI y explicar las causas de la falla.

## Gestión de Fallos

- No modificar archivos de prueba.
- No modificar comandos de ejecución.
- Explicar las razones de la falla basándose en los nombres de las pruebas, la semántica de la API y la salida de la CLI.

Paso 3: Archivos de Soporte

En los pasos anteriores, hemos creado el archivo SKILL.md, que define las condiciones de activación y el flujo de trabajo de ejecución general para esta Habilidad.

Sobre esta base, todos los archivos restantes sirven solo como componentes de soporte para SKILL.md. Se introducen archivos adicionales bajo demanda, solo cuando el flujo de trabajo requiere información adicional, como entornos de tiempo de ejecución, comandos de ejecución o definiciones de prueba.

Estructura final de la carpeta:

.claude/skills/apidog-tests/
├── SKILL.md
├── env/
│   ├── dev.env
│   ├── test.env
│   └── prod.env
├── scripts/
│   ├── list-tests.js
│   └── run-cli.js
└── tests/
    ├── payment-flow.md
    └── refund-flow.md

A continuación, explicamos cada archivo de soporte, su propósito y ejemplos.

Configuración del Entorno (`env`)

La carpeta env/ se utiliza para almacenar configuraciones de variables de entorno, como el token de acceso de Apidog y el ID de entorno.

Al extraer el ID del entorno en una variable, podemos cambiar rápidamente el entorno de ejecución de la prueba (por ejemplo, desarrollo, pruebas, producción) sin modificar ningún comando o script.

Por ejemplo, cree un archivo dev.env dentro de la carpeta env/:

APIDOG_ACCESS_TOKEN=APS-su-token-de-acceso
APIDOG_ENV_ID=su-id-de-entorno

Si se requieren varios entornos, puede crear archivos adicionales de la misma manera:

test.env
prod.env
…

Cada archivo solo necesita mantener las variables para su entorno correspondiente.

El ID de entorno corresponde al valor numérico pasado al parámetro -e en el comando Apidog CLI. Cada entorno de tiempo de ejecución (como desarrollo, pruebas o producción) tiene un ID de entorno único en Apidog.

💡

Nota: Los archivos .env dentro de la carpeta env/ contienen tokens de acceso, que son información sensible y no deben ser subidos a Git.

Scripts de Ejecución (`scripts`)

La carpeta scripts/ contiene scripts ejecutables responsables de convertir las definiciones de prueba en comandos Apidog CLI ejecutables reales, inyectar variables de entorno y ejecutar las pruebas.

En esta Habilidad, se elige Node.js por dos razones principales:

Apidog CLI en sí depende de Node.js Reutilizar el mismo entorno de ejecución evita la necesidad de instalar entornos de ejecución adicionales como Python.
Reducir la sobrecarga de contexto y el consumo de tokens Al manejar el análisis de comandos, la inyección de variables y la lógica de ejecución dentro de los scripts, Claude no necesita construir repetidamente comandos CLI completos durante la conversación, lo que reduce significativamente el uso de contexto.

Si no está familiarizado con los scripts, puede optar por no usarlos en absoluto. En su lugar, puede dejar que Claude ensamble y ejecute los comandos CLI directamente en SKILL.md.

Sin embargo, este enfoque conlleva mayores costos de contexto y tokens.
Cree run-cli.js dentro de la carpeta scripts/. Sus responsabilidades principales son:

Extraer el comando Apidog CLI de un archivo Markdown de prueba especificado
Cargar el archivo .env correspondiente basado en el entorno seleccionado (por ejemplo, dev / test)
Inyectar variables de entorno y ejecutar la prueba

A continuación se muestra un script de ejemplo listo para usar:

import fs from "fs";
import path from "path";
import { execSync } from "child_process";
import dotenv from "dotenv";
import { fileURLToPath } from "url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// args
const mdPath = process.argv[2];
const envName = process.argv[3] || "local";

if (!mdPath) {
    console.error("❌ Falta la ruta del archivo .md de prueba");
    process.exit(1);
}

// env path: siempre relativo a la carpeta de la habilidad
const envPath = path.join(__dirname, "..", "env", `${envName}.env`);

if (!fs.existsSync(envPath)) {
    console.error(`❌ Configuración de entorno no encontrada: ${envPath}`);
    process.exit(1);
}

dotenv.config({ path: envPath });

// Leer archivo markdown
const content = fs.readFileSync(mdPath, "utf-8");
const match = content.match(/```bash([\s\S]*?)```/);

if (!match) {
    console.error("❌ Bloque de comandos bash no encontrado");
    process.exit(1);
}

let command = match[1].trim();

// Reemplazo de variables
command = command
    .replaceAll("$APIDOG_ACCESS_TOKEN", process.env.APIDOG_ACCESS_TOKEN)
    .replaceAll("$APIDOG_ENV_ID", process.env.APIDOG_ENV_ID);

console.log(`▶ Ejecutando (${envName})`);
console.log(command);

// Ejecutar
try {
    execSync(command, { stdio: "inherit" });
} catch (e) {
    // Apidog CLI devuelve el código de salida 1 cuando las pruebas fallan
    process.exit(1);
}

También cree list-tests.js dentro de la carpeta scripts/. Se utiliza para:

Escanear recursivamente la carpeta tests/
Localizar todos los archivos de prueba Markdown
Extraer la descripción de la primera línea
Generar una lista de todas las pruebas automatizadas de Apidog disponibles

A continuación se muestra un script de ejemplo listo para usar:

import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const testsDir = path.join(__dirname, "..", "tests");

function scan(dir, relativePath = "") {
    const items = fs.readdirSync(dir, { withFileTypes: true });
    
    for (const item of items) {
        const fullPath = path.join(dir, item.name);
        const relPath = path.join(relativePath, item.name);
        
        if (item.isDirectory()) { // Corregido: isfolder() -> isDirectory()
            scan(fullPath, relPath);
        } else if (item.name.endsWith(".md")) {
            try {
                const content = fs.readFileSync(fullPath, "utf-8");
                const firstLine = content.split("\n")[0].trim();
                const description = firstLine.startsWith(">")
                    ? firstLine.replace(/^>\s*/, "").trim()
                    : "Sin descripción";
                const displayPath = path.join(
                    "./.claude/skills/apidog-tests/tests",
                    relPath
                );
                console.log(`[${displayPath}] - ${description}`);
            } catch (err) {
                console.log(`[${relPath}] - (No se puede leer el archivo)`);
            }
        }
    }
}

console.log("🔍 Pruebas automatizadas de Apidog disponibles:");
if (fs.existsSync(testsDir)) {
    scan(testsDir);
} else {
    console.log("❌ Carpeta 'tests' no encontrada");
}

Definiciones de Prueba (`tests`)

La carpeta tests/ almacena definiciones de prueba escritas en Markdown.

Principio de Diseño: Cada archivo Markdown corresponde a un escenario de prueba o un conjunto de pruebas de Apidog. Puede reutilizar directamente las estructuras de carpetas existentes, los nombres de los escenarios de prueba, los nombres de los conjuntos de pruebas y las descripciones de las pruebas de automatización de Apidog.

Cada archivo Markdown solo necesita contener dos partes:

Una breve descripción de la prueba
Un único comando Apidog CLI que se puede ejecutar directamente

En el comando Apidog CLI:

El token de acceso se reemplaza con $APIDOG_ACCESS_TOKEN
El ID del entorno pasado a -e se reemplaza con $APIDOG_ENV_ID

Ambas variables se configuran centralmente en los archivos .env. Este enfoque evita la fuga de tokens y permite una conmutación flexible del entorno.

Ejemplo: login-auth-flow.md

> Verifica las API principales como el inicio de sesión, la actualización de tokens y el cierre de sesión.

```bash
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 5564xxx -e $APIDOG_ENV_ID -n 1 -r html,cli
```

En este punto, la Habilidad está completamente construida. Puede revisar la estructura de la carpeta y compararla con su propia implementación para identificar cualquier diferencia.

Usando el Flujo de Trabajo en Claude Code

Ejecute claude en la carpeta del proyecto. Claude escanea automáticamente .claude/skills/ y carga la Habilidad apidog-tests.

Puede listar las Habilidades cargadas usando /skills.

Luego intente un comando en lenguaje natural:

"Ejecutar las pruebas de inicio de sesión en dev."

Claude localizará la prueba, la ejecutará a través de Apidog CLI, analizará la salida y resumirá los resultados.

Resumen

Este artículo demostró cómo construir un flujo de trabajo de pruebas de API automatizadas utilizando Claude Code, Apidog CLI y Claude Skills.

La idea central es hacer de Claude el puente entre humanos y herramientas:

Usted describe la intención en lenguaje natural
Claude comprende e invoca scripts
Los scripts ejecutan Apidog CLI
Claude analiza y presenta los resultados de manera legible para el ser humano

Para que este flujo de trabajo sea verdaderamente efectivo, debe adaptarlo a su proyecto: la organización de las pruebas, la estrategia de entornos y la lógica de análisis de resultados pueden personalizarse.

Si su equipo ejecuta con frecuencia pruebas de API y desea una experiencia más automatizada e inteligente, este enfoque merece la pena probarlo. Requiere cierta configuración inicial, pero una vez establecido, puede mejorar significativamente la eficiencia, y sigue mejorando a medida que lo refina.