Apidog CLI + Claude: Automatização de Testes API no Desenvolvimento

Este artigo apresenta como combinar o Apidog CLI com as Claude Skills para construir um fluxo de trabalho eficiente para testes de automação de API orientados por linguagem natural.

Neste fluxo de trabalho, você só precisa dizer uma única frase ao Claude Code em seu terminal, por exemplo:

"Execute o teste do fluxo de pedidos do usuário em dev."

O Claude Code entenderá automaticamente sua intenção, localizará o cenário de teste ou pacote de testes correspondente, executará os testes e, em seguida, resumirá e interpretará os resultados para você.

Visão Geral das Ferramentas

Este fluxo de trabalho é composto por três ferramentas:

1. Apidog CLI

A interface de linha de comando fornecida pelo Apidog. É usada para executar testes de automação de API a partir do terminal e gerar relatórios de teste.

2. Claude Code

Um assistente de IA de linha de comando lançado pela Anthropic. Ele pode operar em arquivos, executar comandos, executar scripts e interagir com seu ambiente de desenvolvimento local.

3. Claude Skills

Também conhecidas como Agent Skills, um mecanismo de extensão do Claude Code. Uma Skill define como o Claude deve completar uma tarefa específica, atuando essencialmente como um conjunto executável de instruções operacionais.

Neste fluxo de trabalho, o Claude Code é responsável por entender as instruções em linguagem natural. Quando a solicitação de um usuário corresponde a uma Claude Skill predefinida, o Claude executa automaticamente os comandos correspondentes do Apidog CLI e analisa os resultados.

O Que Este Fluxo de Trabalho Pode Fazer

Abaixo estão vários cenários do mundo real para ilustrar como este fluxo de trabalho pode ser usado na prática.

Executar Um Único Teste

Se você deseja executar um cenário de teste específico, pode nomeá-lo explicitamente. Por exemplo:

"Execute os testes de login em dev."

Após a conclusão do teste, o Claude analisa os resultados e fornece um resumo.

Listar Todos os Testes Disponíveis

Para ver quais cenários de teste ou pacotes de testes estão disponíveis, você pode dizer:

"Mostre-me os testes disponíveis."

O Claude executará o script relevante e listará todos os testes.

Executar Todos os Testes para Um Módulo de Negócios

Se você deseja executar todos os testes para um domínio de negócios específico — como testes relacionados a pagamentos — você pode dizer:

"Execute todos os testes de pagamento no ambiente de teste."

O Claude localizará automaticamente todos os arquivos de teste relacionados e os executará sequencialmente ou em paralelo.

Comparar Resultados de Teste Entre Ambientes

Para comparar resultados entre ambientes, você pode dizer:

"Execute os testes de login em dev e test."

O Claude executará os testes em ambos os ambientes e analisará as diferenças nos resultados.

Executar Testes Baseados em Alterações de Código

Após alterações de código, você pode pedir ao Claude para executar apenas os testes afetados:

"Com base nas recentes alterações de código, execute os testes de API impactados em dev."

O Claude analisará as alterações do Git, determinará os cenários ou pacotes de testes afetados e executará apenas esses testes — economizando tempo e recursos.

Mais cenários estão esperando por você para explorar.

Em seguida, explicaremos como instalar e configurar o Apidog CLI, o Claude Code e as Claude Skills, e como combiná-los em um fluxo de trabalho completo.

Preparação

Requisitos do Ambiente

Certifique-se de que o Node.js esteja instalado em sua máquina. Verifique-o em seu terminal:

node -v
npm -v

Instalando o Apidog CLI (instalar via npm):

npm install -g apidog-cli

Verifique a instalação:

apidog --version

Se um número de versão for exibido, a instalação foi bem-sucedida.
Você pode copiar um comando CLI para um cenário de teste ou pacote de testes de Apidog → Tests → CI/CD, adicionar seu Access Token e executá-lo no terminal.

Se a saída do teste aparecer, o Apidog CLI está funcionando corretamente.

Instalando o Claude

Code (instalar via npm):

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

Verificar:

claude --version

Na primeira execução, você precisará fazer login:

claude

Siga os passos de autorização. Uma conta Claude é necessária. Após fazer login, você entrará na interface interativa e poderá fazer perguntas básicas.

Neste ponto, o Claude ainda não sabe como executar testes Apidog. A seguir, vamos ensiná-lo usando as Claude Skills.

Construindo Claude Skills

Entendendo Como as Skills Funcionam

Ao usar o Claude Code, você não seleciona manualmente uma Skill. Você simplesmente descreve o que deseja fazer em linguagem natural.

Se sua solicitação corresponder à descrição de uma Skill, o Claude carregará automaticamente essa Skill e executará o fluxo de trabalho definido.

Passo 1: Criar a Pasta da Skill

Todas as configurações de Skill ficam na pasta .claude/skills/. Cada Skill tem sua própria subpasta.

Crie uma pasta de Skill mínima para testes de automação Apidog na raiz do projeto:

mkdir -p .claude/skills/apidog-tests

Estrutura resultante:

.claude/skills/apidog-tests/

Adicionaremos gradualmente arquivos de entrada e scripts aqui.

Passo 2: Criar SKILL.md

Cada Skill requer um arquivo SKILL.md que define como o Claude deve executar a tarefa uma vez que a Skill é acionada.

O arquivo começa com metadados YAML envoltos em ---. Os campos name e description são obrigatórios.

A description é especialmente importante — ela determina quando o Claude deve ativar esta Skill.

Abaixo do bloco YAML, o conteúdo Markdown define a lógica de execução, regras de decisão, scripts a serem invocados e restrições.

Exemplo de SKILL.md para Testes de Automação Apidog

---
name: apidog-tests
description: Executes and interprets Apidog automated API tests via Apidog CLI. Trigger this Skill whenever the user explicitly asks to run tests, test cases, test scenarios, or test suites, including requests to execute tests in a specific environment such as dev, test, or prod, to verify API behavior after code changes, to perform regression or pre-release testing, or to run API checks before git commit, push, or merge. Even if the user does not explicitly mention "Apidog" or "API", assume these requests refer to Apidog automated tests when test execution is implied. The Skill should select the appropriate test scenario or test suite, execute the tests, and explain the results without modifying test definitions or commands themselves.
---

# Apidog Tests

Executes Apidog automated tests and interprets the results.

## Workflow

1. **Select Test**:

- If the user explicitly provides:
  - Test file path
  - Test file name
  - Or a clear, uniquely matching test name
- Use that test directly without automatic selection.
- If information is unclear, prioritize running the `node ./.claude/skills/apidog-tests/scripts/list-tests.js` script to quickly retrieve all test file paths and descriptions.
- Avoid blind global searches in large project directories; instead, locate the test file directory `./.claude/skills/apidog-tests/tests/` dedicated to this skill.

2. **Multiple Test Execution Rules**

- By default, execute only one test, but offer the option for batch execution.
- If the user explicitly states:
  - "Run these few"
  - "Run them all"
- Enter **Batch Execution Mode**.

In Batch Execution Mode:
- Clearly list the tests to be executed.
- **Ask for execution method**: Let the user choose between "Sequential Execution" (better readability) or "Parallel Execution" (faster).
  - **Sequential Execution**: Run tests one by one and analyze immediately, suitable for debugging.
  - **Parallel Execution**: Start multiple tests simultaneously (using `&` or concurrent scripts), suitable for quick regression, though logs may interleave.
- Request user confirmation for the execution method and test list (Yes / No).
- Execute tests according to the chosen method.
- Finally, summarize or individually explain the results of each test.

3. **Confirm Environment**:
- Supported environments include:
  - `dev`
  - `test`
  - `prod`
- If the user has not specified an environment:
  - List the environment names above.
  - Have the user confirm which one to use.

4. **Execute Test**:
- Execute the test once the following information is clear:
  - Test file path
  - Environment name (dev / test / prod)
```bash
node ./.claude/skills/apidog-tests/scripts/run-cli.js <test_file_path> <env_name>
```

5. **Interpret Results**: Analyze Apidog CLI output and explain causes of failure.

## Failure Handling

- Do not modify test files.
- Do not modify execution commands.
- Explain failure reasons based on test names, API semantics, and CLI output.

Passo 3: Arquivos de Suporte

Nos passos anteriores, criamos o arquivo SKILL.md, que define as condições de gatilho e o fluxo de trabalho geral para esta Skill.

Com base nesta fundação, todos os arquivos restantes servem apenas como componentes de suporte para o SKILL.md. Arquivos adicionais são introduzidos sob demanda, apenas quando o fluxo de trabalho requer informações extras — como ambientes de tempo de execução, comandos de execução ou definições de teste.

Estrutura final da pasta:

.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

Abaixo, detalhamos cada arquivo de suporte, explicando seu propósito e fornecendo exemplos.

Configuração do Ambiente (env)

A pasta env/ é usada para armazenar configurações de variáveis de ambiente, como o token de acesso Apidog e o ID do ambiente.

Ao extrair o ID do ambiente para uma variável, podemos alternar rapidamente o ambiente de execução do teste (por exemplo, desenvolvimento, teste, produção) sem modificar nenhum comando ou script.

Por exemplo, crie um arquivo dev.env na pasta env/:

APIDOG_ACCESS_TOKEN=APS-your-access-token
APIDOG_ENV_ID=your-environment-id

Se vários ambientes forem necessários, você pode criar arquivos adicionais da mesma forma:

• test.env
• prod.env
• …

Cada arquivo só precisa manter as variáveis para seu ambiente correspondente.

O ID do ambiente corresponde ao valor numérico passado para o parâmetro -e no comando Apidog CLI. Cada ambiente de tempo de execução (como desenvolvimento, teste ou produção) tem um ID de ambiente exclusivo no Apidog.

Scripts de Execução (scripts)

A pasta scripts/ contém scripts executáveis responsáveis por converter definições de teste em comandos Apidog CLI reais e executáveis, injetar variáveis de ambiente e executar os testes.

Nesta Skill, o Node.js foi escolhido por duas razões principais:

1. O próprio Apidog CLI depende do Node.js Reutilizar o mesmo ambiente de tempo de execução evita a necessidade de instalar ambientes de tempo de execução adicionais, como Python.
2. Reduzindo a sobrecarga de contexto e o consumo de tokens Ao lidar com a análise de comandos, injeção de variáveis e lógica de execução dentro dos scripts, o Claude não precisa construir repetidamente comandos CLI completos durante a conversa, o que reduz significativamente o uso de contexto.

Se você não está familiarizado com scripts, pode optar por não usar scripts. Em vez disso, você pode deixar o Claude montar e executar os comandos CLI diretamente no SKILL.md.

No entanto, essa abordagem acarreta custos mais altos de contexto e token.
Crie run-cli.js na pasta scripts/. Suas responsabilidades principais são:

• Extrair o comando Apidog CLI de um arquivo de teste Markdown especificado
• Carregar o arquivo .env correspondente com base no ambiente selecionado (por exemplo, dev / test)
• Injetar variáveis de ambiente e executar o teste

Um script de exemplo pronto para uso é mostrado abaixo:

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("❌ Missing test .md file path");
    process.exit(1);
}

// env path: always relative to the skill folder
const envPath = path.join(__dirname, "..", "env", `${envName}.env`);

if (!fs.existsSync(envPath)) {
    console.error(`❌ Environment configuration not found: ${envPath}`);
    process.exit(1);
}

dotenv.config({ path: envPath });

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

if (!match) {
    console.error("❌ Bash command block not found");
    process.exit(1);
}

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

// Variable replacement
command = command
    .replaceAll("$APIDOG_ACCESS_TOKEN", process.env.APIDOG_ACCESS_TOKEN)
    .replaceAll("$APIDOG_ENV_ID", process.env.APIDOG_ENV_ID);

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

// Execute
try {
    execSync(command, { stdio: "inherit" });
} catch (e) {
    // Apidog CLI returns exit code 1 when tests fail
    process.exit(1);
}

Crie também list-tests.js na pasta scripts/. Ele é usado para:

• Escanear recursivamente a pasta tests/
• Localizar todos os arquivos de teste Markdown
• Extrair a descrição da primeira linha
• Exibir uma lista de todos os testes automatizados Apidog disponíveis

Um script de exemplo pronto para uso é mostrado abaixo:

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.isfolder()) {
            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()
                    : "No description";
                const displayPath = path.join(
                    "./.claude/skills/apidog-tests/tests",
                    relPath
                );
                console.log(`[${displayPath}] - ${description}`);
            } catch (err) {
                console.log(`[${relPath}] - (Unable to read file)`);
            }
        }
    }
}

console.log("🔍 Available Apidog automated tests:");
if (fs.existsSync(testsDir)) {
    scan(testsDir);
} else {
    console.log("❌ tests folder not found");
}

Definições de Teste (tests)

A pasta tests/ armazena definições de teste escritas em Markdown.

Princípio de Design: Cada arquivo Markdown corresponde a um cenário de teste ou pacote de testes Apidog. Você pode reutilizar diretamente estruturas de pastas existentes, nomes de cenários de teste, nomes de pacotes de testes e descrições dos testes de automação Apidog.

Cada arquivo Markdown precisa conter apenas duas partes:

1. Uma breve descrição do teste
2. Um único comando Apidog CLI que pode ser executado diretamente

No comando Apidog CLI:

• O token de acesso é substituído por $APIDOG_ACCESS_TOKEN
• O ID do ambiente passado para -e é substituído por $APIDOG_ENV_ID

Ambas as variáveis são configuradas centralmente em arquivos .env. Essa abordagem evita vazamento de tokens e permite a troca flexível de ambientes.

Exemplo: login-auth-flow.md

> Verifies core APIs such as login, token refresh, and logout.

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

Neste ponto, a Skill está totalmente construída. Você pode revisar a estrutura da pasta e compará-la com sua própria implementação para identificar quaisquer diferenças.

Usando o Fluxo de Trabalho no Claude Code

Execute claude na pasta do projeto. O Claude automaticamente escaneia .claude/skills/ e carrega a Skill apidog-tests.

Você pode listar as Skills carregadas usando /skills.

Em seguida, experimente um comando em linguagem natural:

"Execute os testes de login em dev."

O Claude localizará o teste, o executará via Apidog CLI, analisará a saída e resumirá os resultados.

Resumo

Este artigo demonstrou como construir um fluxo de trabalho de teste de API automatizado usando Claude Code, Apidog CLI e Claude Skills.

A ideia central é fazer do Claude a ponte entre humanos e ferramentas:

• Você descreve a intenção em linguagem natural
• O Claude entende e invoca scripts
• Os scripts executam o Apidog CLI
• O Claude analisa e apresenta os resultados de forma legível por humanos

Para tornar este fluxo de trabalho verdadeiramente eficaz, você deve adaptá-lo ao seu projeto — a organização dos testes, a estratégia de ambiente e a lógica de análise de resultados podem ser todas personalizadas.

Se sua equipe executa testes de API com frequência e deseja uma experiência mais automatizada e inteligente, essa abordagem vale a pena ser experimentada. Ela requer alguma configuração inicial, mas uma vez estabelecida, pode melhorar significativamente a eficiência — e continua a melhorar à medida que você a refina.