Apidog CLIとClaudeスキル：API自動テストを開発ワークフローに統合

この記事では、Apidog CLIとClaude Skillsを組み合わせて、自然言語駆動型API自動テストのための効率的なワークフローを構築する方法を紹介します。

このワークフローでは、ターミナルでClaude Codeに一文を伝えるだけで済みます。例えば、次のようにです。

「dev環境でユーザー注文フローテストを実行して。」

Claude Codeはあなたの意図を自動的に理解し、対応するテストシナリオまたはテストスイートを特定してテストを実行し、その結果を要約して解釈します。

Apidog CLI + Claude Skills: API自動テストを開発ワークフローに統合する

ツール概要

このワークフローは3つのツールで構成されています。

1. Apidog CLI

Apidogが提供するコマンドラインインターフェースです。ターミナルからAPI自動テストを実行し、テストレポートを生成するために使用されます。

2. Claude Code

AnthropicがリリースしたコマンドラインAIアシスタントです。ファイル操作、コマンド実行、スクリプト実行、およびローカル開発環境との対話が可能です。

3. Claude Skills

Agent Skillsとも呼ばれ、Claude Codeの拡張メカニズムです。スキルは、Claudeが特定のタスクをどのように完了すべきかを定義し、本質的には実行可能な一連の操作指示として機能します。

このワークフローでは、Claude Codeが自然言語の指示を理解する役割を担います。ユーザーのリクエストが事前に定義されたClaude Skillに一致すると、Claudeは対応するApidog CLIコマンドを自動的に実行し、結果を分析します。

このワークフローでできること

以下に、このワークフローを実際にどのように使用できるかを示すいくつかの実世界シナリオを紹介します。

単一テストの実行

特定のテストシナリオを実行したい場合は、明示的に名前を挙げることができます。例えば、次のとおりです。

「dev環境でログインテストを実行して。」

テストが完了すると、Claudeは結果を分析し、概要を提示します。

利用可能なすべてのテストをリスト表示

どのテストシナリオまたはテストスイートが利用可能かを確認するには、次のように言うことができます。

「利用可能なテストを表示して。」

Claudeは関連するスクリプトを実行し、すべてのテストをリスト表示します。

ビジネスモジュールに対するすべてのテストを実行

決済関連テストなど、特定のビジネスドメインに対するすべてのテストを実行したい場合は、次のように言うことができます。

「テスト環境で全ての決済テストを実行して。」

Claudeは関連するすべてのテストファイルを自動的に探し出し、順次または並行して実行します。

環境間のテスト結果比較

環境間で結果を比較するには、次のように言うことができます。

「dev環境とtest環境でログインテストを実行して。」

Claudeは両方の環境でテストを実行し、結果の違いを分析します。

コード変更に基づいたテストの実行

コード変更後、影響を受けるテストのみを実行するようClaudeに依頼できます。

「最近のコード変更に基づいて、影響を受けるAPIテストをdev環境で実行して。」

ClaudeはGitの変更を分析し、影響を受けるテストシナリオやスイートを特定し、それらのテストのみを実行することで、時間とリソースを節約します。

さらに多くのシナリオが、あなたの探索を待っています。

次に、Apidog CLI、Claude Code、およびClaude Skillsのインストールと設定方法、そしてこれらを組み合わせて完全なワークフローを構築する方法を順を追って説明します。

準備

環境要件

お使いのマシンにNode.jsがインストールされていることを確認してください。ターミナルで次のように確認します。

node -v
npm -v

Apidog CLIのインストール

npm経由でインストール:

npm install -g apidog-cli

インストールを確認します。

apidog --version

バージョン番号が表示されれば、インストールは成功しています。
Apidog → テスト → CI/CDから、テストシナリオまたはテストスイートのCLIコマンドをコピーし、アクセストークンを追加してターミナルで実行できます。

テスト出力が表示されれば、Apidog CLIは正常に動作しています。

💡

注意: 最新のテストスイート機能を使用するには、ApidogデスクトップクライアントとApidog CLIの両方を最新バージョンに更新する必要があります。

Claude Codeのインストール

npm経由でインストール:

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

確認:

claude --version

初回実行時にはログインが必要です。

claude

認証手順に従ってください。Claudeアカウントが必要です。ログイン後、対話型インターフェースに入り、基本的な質問をすることができます。

この時点では、ClaudeはまだApidogテストの実行方法を知りません。次に、Claude Skillsを使用してそれを学習させます。

Claude Skillsの構築

スキルがどのように機能するかを理解する

Claude Codeを使用する際、手動でスキルを選択する必要はありません。自然言語で何をしたいかを記述するだけです。

あなたのリクエストがスキルの説明と一致すると、Claudeはそのスキルを自動的にロードし、定義されたワークフローを実行します。

ステップ1: スキルフォルダの作成

すべてのスキル設定は.claude/skills/フォルダの下に配置されます。各スキルは独自のサブフォルダを持ちます。

プロジェクトのルートにApidog自動テスト用の最小限のスキルフォルダを作成します。

mkdir -p .claude/skills/apidog-tests

結果として得られる構造:

.claude/skills/apidog-tests/

ここにエントリファイルとスクリプトを徐々に追加していきます。

ステップ2: `SKILL.md`の作成

各スキルには、スキルがトリガーされたときにClaudeがタスクをどのように実行すべきかを定義するSKILL.mdファイルが必要です。

ファイルは---で囲まれたYAMLメタデータで始まります。nameおよびdescriptionフィールドは必須です。

descriptionは特に重要で、Claudeがこのスキルをいつアクティブ化すべきかを決定します。

YAMLブロックの下には、Markdownコンテンツで実行ロジック、決定ルール、呼び出すスクリプト、および制約が定義されます。

Apidog自動テスト用のSKILL.md例

---
name: apidog-tests
description: Apidog自動APIテストをApidog CLI経由で実行し、解釈します。このスキルは、ユーザーがテスト、テストケース、テストシナリオ、またはテストスイートの実行を明示的に要求した場合、あるいはdev、test、prodなどの特定の環境でテストを実行してコード変更後のAPI動作を検証したり、回帰テストやリリース前テストを実行したり、gitコミット、プッシュ、マージ前にAPIチェックを実行したりする場合にトリガーされます。ユーザーが「Apidog」や「API」を明示的に言及しなくても、テスト実行が暗示されている場合は、これらのリクエストがApidog自動テストを指していると仮定します。スキルは適切なテストシナリオまたはテストスイートを選択し、テストを実行し、テスト定義やコマンド自体を変更することなく結果を説明する必要があります。
---

# Apidogテスト

Apidog自動テストを実行し、結果を解釈します。

## ワークフロー

1. **テストの選択**:

- ユーザーが明示的に以下を提供した場合:
  - テストファイルパス
  - テストファイル名
  - または明確で一意に一致するテスト名
- 自動選択なしでそのテストを直接使用します。
- 情報が不明確な場合は、`node ./.claude/skills/apidog-tests/scripts/list-tests.js`スクリプトを実行して、すべてのテストファイルパスと説明を迅速に取得することを優先します。
- 大規模なプロジェクトディレクトリで盲目的なグローバル検索を行うことは避け、代わりにこのスキル専用のテストファイルディレクトリ`./.claude/skills/apidog-tests/tests/`を特定します。

2. **複数テスト実行ルール**

- デフォルトでは1つのテストのみを実行しますが、バッチ実行のオプションを提供します。
- ユーザーが明示的に以下を述べた場合:
  - 「これらのいくつかを実行」
  - 「全てを実行」
- **バッチ実行モード**に入ります。

バッチ実行モードでは:
- 実行するテストを明確にリスト表示します。
- **実行方法を尋ねる**: ユーザーに「順次実行」（可読性が高い）または「並列実行」（高速）のどちらかを選択させます。
  - **順次実行**: テストを1つずつ実行し、すぐに分析します。デバッグに適しています。
  - **並列実行**: 複数のテストを同時に開始します（`&`または並行スクリプトを使用）。ログが混在する可能性がありますが、迅速な回帰テストに適しています。
- 実行方法とテストリスト（はい/いいえ）についてユーザーの確認を求めます。
- 選択された方法に従ってテストを実行します。
- 最後に、各テストの結果を要約または個別に説明します。

3. **環境の確認**:
- サポートされている環境は次のとおりです。
  - `dev`
  - `test`
  - `prod`
- ユーザーが環境を指定していない場合:
  - 上記の環境名をリスト表示します。
  - ユーザーに使用する環境を確認させます。

4. **テストの実行**:
- 次の情報が明確になったらテストを実行します。
  - テストファイルパス
  - 環境名 (dev / test / prod)
```bash
node ./.claude/skills/apidog-tests/scripts/run-cli.js  
```

5. **結果の解釈**: Apidog CLI出力を分析し、失敗の原因を説明します。

## 障害処理

- テストファイルを変更しないでください。
- 実行コマンドを変更しないでください。
- テスト名、APIセマンティクス、およびCLI出力に基づいて失敗の原因を説明します。

ステップ3: サポートファイル

前のステップでは、このスキルのトリガー条件と全体的な実行ワークフローを定義するSKILL.mdファイルを作成しました。

この基盤に基づき、残りのすべてのファイルはSKILL.mdのサポートコンポーネントとしてのみ機能します。追加のファイルは、実行環境、実行コマンド、テスト定義などの追加情報がワークフローで必要になる場合にのみ、オンデマンドで導入されます。

最終的なフォルダ構造:

.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

以下では、各サポートファイルについて、その目的と例を説明します。

環境設定 (`env`)

env/フォルダは、Apidogアクセストークンや環境IDなどの環境変数設定を保存するために使用されます。

環境IDを変数として抽出することで、テスト実行環境（例：開発、テスト、本番）をコマンドやスクリプトを一切変更することなく迅速に切り替えることができます。

例えば、env/フォルダの下にdev.envファイルを作成します。

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

複数の環境が必要な場合は、同様の方法で追加のファイルを作成できます。

test.env
prod.env
…

各ファイルは、対応する環境の変数のみを保持する必要があります。

環境IDは、Apidog CLIコマンドの-eパラメーターに渡される数値に対応します。各ランタイム環境（開発、テスト、本番など）は、Apidog内で一意の環境IDを持っています。

💡

注意: env/フォルダの下にある.envファイルにはアクセストークンが含まれており、これは機密情報であるため、Gitにコミットしてはなりません。

実行スクリプト (`scripts`)

scripts/フォルダには、テスト定義を実際に実行可能なApidog CLIコマンドに変換し、環境変数を挿入してテストを実行する役割を担う実行可能スクリプトが含まれています。

このスキルでは、主に2つの理由からNode.jsが選択されています。

Apidog CLI自体がNode.jsに依存しているため同じランタイムを再利用することで、Pythonなどの追加のランタイムをインストールする必要がなくなります。
コンテキストオーバーヘッドとトークン消費の削減コマンド解析、変数挿入、実行ロジックをスクリプト内で処理することで、Claudeは会話中に完全なCLIコマンドを繰り返し構築する必要がなくなり、コンテキスト使用量が大幅に削減されます。

スクリプトに慣れていない場合は、スクリプトを一切使用しないことも選択できます。その代わりに、ClaudeにSKILL.md内でCLIコマンドを直接組み立てて実行させることも可能です。

ただし、このアプローチはコンテキストとトークンのコストが高くなります。
scripts/フォルダの下にrun-cli.jsを作成します。その主な役割は次のとおりです。

指定されたMarkdownテストファイルからApidog CLIコマンドを抽出
選択された環境（例: dev / test）に基づいて対応する.envファイルをロード
環境変数を挿入し、テストを実行

すぐに使えるスクリプトの例を以下に示します。

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);
}

また、scripts/フォルダの下にlist-tests.jsを作成します。これは以下のために使用されます。

tests/フォルダを再帰的にスキャン
すべてのMarkdownテストファイルを特定
最初の行から説明を抽出
利用可能なすべてのApidog自動テストのリストを出力

すぐに使えるスクリプトの例を以下に示します。

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");
}

テスト定義 (`tests`)

tests/フォルダには、Markdownで記述されたテスト定義が保存されます。

設計原則: 各Markdownファイルは1つのApidogテストシナリオまたはテストスイートに対応します。Apidog自動テストから既存のフォルダ構造、テストシナリオ名、テストスイート名、および説明を直接再利用できます。

各Markdownファイルには、次の2つの部分のみを含める必要があります。

短いテストの説明
直接実行できる単一のApidog CLIコマンド

Apidog CLIコマンドでは:

アクセストークンは$APIDOG_ACCESS_TOKENに置き換えられます
-eに渡される環境IDは$APIDOG_ENV_IDに置き換えられます

両方の変数は.envファイルで一元的に設定されます。このアプローチにより、トークン漏洩を防ぎ、柔軟な環境切り替えが可能になります。

例: login-auth-flow.md

> ログイン、トークン更新、ログアウトなどのコアAPIを検証します。

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

この時点で、スキルは完全に構築されました。フォルダ構造を確認し、ご自身の実装と比較して違いを特定できます。

Claude Codeでのワークフローの使用

プロジェクトフォルダでclaudeを実行します。Claudeは自動的に.claude/skills/をスキャンし、apidog-testsスキルをロードします。

ロードされているスキルは/skillsを使ってリスト表示できます。

次に、自然言語コマンドを試します。

「dev環境でログインテストを実行して。」

Claudeはテストを特定し、Apidog CLIを介して実行し、出力を分析して結果を要約します。

まとめ

この記事では、Claude Code、Apidog CLI、およびClaude Skillsを使用して、API自動テストワークフローを構築する方法を実演しました。

核となるアイデアは、Claudeを人間とツールの橋渡し役にすることです。

自然言語で意図を記述する
Claudeが理解し、スクリプトを呼び出す
スクリプトがApidog CLIを実行する
Claudeが結果を分析し、人間が読める形式で提示する

このワークフローを真に効果的にするには、プロジェクトに合わせて調整する必要があります。テストの構成、環境戦略、結果分析ロジックはすべてカスタマイズ可能です。

あなたのチームが頻繁にAPIテストを実行し、より自動化されインテリジェントな体験を求めているなら、このアプローチは試してみる価値が十分にあります。初期設定には多少の労力がかかりますが、一度確立すれば効率が大幅に向上し、改善を重ねるごとにさらに良くなるでしょう。