api-testing

Postman と Bruno を使用したツールベースの API テストに関するエキスパートレベルのスキルです。コレクションの整理、環境管理、テストスクリプト、レスポンス検証、CI/CD 統合を網羅します。

このスキルは testing-skill（コードベースのテスト）および api-design-skill（API 構造）を補完します。プログラムによるテストを書くのではなく、専用ツールで既存の API をテストする必要がある場合に使用します。

主な違い:

• testing-skill: コードベースのテスト（supertest、MSW、pytest requests）
• api-testing-skill: ツールベースのテスト（Postman、Bruno コレクション）
• api-design-skill: API の設計方法（構造、規約）

<quick_start> Postman クイックテスト:

// Tests tab in Postman
pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

pm.test("Response has user data", function () {
    const json = pm.response.json();
    pm.expect(json).to.have.property("id");
    pm.expect(json).to.have.property("email");
});

Bruno クイックテスト:

// tests/get-user.bru
meta {
  name: Get User
  type: http
  seq: 1
}

get {
  url: {{baseUrl}}/api/users/{{userId}}
}

tests {
  test("should return 200", function() {
    expect(res.status).to.equal(200);
  });
}

環境のセットアップ:

{
  "baseUrl": "https://api.example.com",
  "apiKey": "test_key_xxx"
}

</quick_start>

<success_criteria> API テストは、次の条件を満たす場合に成功です:

• すべてのエンドポイントに少なくとも 1 つのハッピーパステストがある
• エラーケースがテストされている（4xx、5xx レスポンス）
• レスポンススキーマが検証されている（ステータスコードだけでなく）
• すべての設定可能な値に環境変数が使用されている
• コレクションがリソース/ドメインごとに整理されている
• 認証フローがエンドツーエンドでテストされている
• CI パイプラインがすべての PR でコレクションを実行する
• テストデータが再現可能である（フィクスチャまたは動的生成） </success_criteria>

<tool_comparison>

Postman と Bruno

機能	Postman	Bruno
ストレージ	クラウド/ローカル	Git ネイティブ（.bru ファイル）
コラボレーション	チーム同期	Git ブランチ
料金	無料枠 + 有料	無料かつオープンソース
オフライン	デスクトップアプリ	完全オフライン
スクリプティング	JavaScript	JavaScript
CI/CD	Newman CLI	Bruno CLI
スキーマ	JSON	プレーンテキスト .bru
最適な用途	チーム、API ドキュメント	Git ワークフロー、プライバシー

それぞれをいつ使用するか

Postman を選ぶ場合:

• チームがリアルタイムのコラボレーションを必要としている
• API ドキュメントが主要な成果物である
• フロントエンド開発にモックサーバーが必要である
• トークンリフレッシュを伴う複雑な OAuth フローがある

Bruno を選ぶ場合:

• Git ネイティブのワークフローを好む
• プライバシー/セルフホストが必須である
• よりシンプルなテストシナリオである
• 開発者がコードライクな構文を好む </tool_comparison>

<collection_organization>

コレクション構造

フォルダ階層

my-api-tests/
├── auth/
│   ├── login.bru
│   ├── refresh-token.bru
│   └── logout.bru
├── users/
│   ├── create-user.bru
│   ├── get-user.bru
│   ├── update-user.bru
│   └── delete-user.bru
├── orders/
│   ├── create-order.bru
│   ├── get-orders.bru
│   └── cancel-order.bru
├── environments/
│   ├── local.bru
│   ├── staging.bru
│   └── production.bru
└── collection.bru

命名規則

要素	規則	例
フォルダ	kebab-case、複数形	users、auth-flows
リクエスト	動詞-名詞	create-user、get-orders
変数	camelCase	{{baseUrl}}、{{authToken}}
環境	小文字	local、staging、production

リクエストの順序

依存するリクエストには連番を使用します:

1. auth/login.bru          (seq: 1)
2. users/create-user.bru   (seq: 2) - needs auth token
3. users/get-user.bru      (seq: 3) - uses created user ID

</collection_organization>

<test_patterns>

テストアサーションのパターン

アサーションの種類	確認する内容	例
ステータスコード	200、201、400、401、404	pm.response.to.have.status(200)
レスポンスボディ	必須フィールド、型、パターン	pm.expect(json).to.have.property("id")
レスポンス時間	しきい値未満	pm.expect(pm.response.responseTime).to.be.below(500)
ヘッダー	Content-Type、X-Request-Id	pm.response.to.have.header("Content-Type")
JSON スキーマ	完全なスキーマ検証	pm.response.to.have.jsonSchema(schema)

Postman と Bruno の例を含む完全なアサーションパターンについては、reference/test-design.md を参照してください。 </test_patterns>

<environment_management>

環境管理

変数のスコープ（Postman）: グローバル → コレクション → 環境 → データ → ローカル（最優先）。

環境ごと（local/staging/production）の baseUrl、apiKey には環境ファイルを使用します。レスポンスの値を保存することでリクエストを連鎖させます（pm.environment.set("authToken", json.accessToken)）。これは後続のリクエストで使用します。

環境ファイルの形式、動的変数、リクエスト連鎖のパターンについては、reference/data-management.md を参照してください。 </environment_management>

<authentication_testing>

認証テスト

認証タイプ	メソッド	キーパターン
Bearer トークン	ログインレスポンスから保存し、Authorization ヘッダーで使用	pm.environment.set("accessToken", json.accessToken)
API キー	ヘッダー（X-API-Key）またはクエリパラメータ	{{apiKey}} 変数
OAuth 2.0	プリリクエストスクリプトで有効期限を確認し、自動的に更新	pm.sendRequest() でトークンを更新

常にテストする項目: トークンなしで 401、誤ったロールで 403。

OAuth 2.0 のリフレッシュフローと認証失敗のテストパターンについては、reference/postman-patterns.md を参照してください。 </authentication_testing>

<error_testing>

エラーレスポンスのテスト

各エラークラスをテストします: 400（details 配列を含むバリデーションエラー）、404（見つからない）、429（レート制限ヘッダーが存在する）、5xx（requestId を持つ）。

エラーレスポンスのアサーションパターンについては、reference/test-design.md を参照してください。 </error_testing>

<ci_integration>

CI/CD 統合

ツール	CLI	実行コマンド
Postman	Newman	newman run collection.json -e staging.json
Bruno	Bruno CLI	bru run --env staging

GitHub Actions 経由で統合します: CLI をインストールし、コレクションを実行し、HTML レポートをアーティファクトとしてアップロードします。機密性の高い環境変数には ${{ secrets.* }} を使用します。

GitHub Actions ワークフロー、レポーター、シークレットの扱いについては、reference/ci-integration.md を参照してください。 </ci_integration>

<data_management>

テストデータ管理

イテレーションベースのテストにはデータファイル（newman run -d test-data.json）を使用します。Postman には組み込みの動的変数（{{$guid}}、{{$randomEmail}}、{{$timestamp}}）があります。作成したリソースを削除するクリーンアップスクリプトをポストリクエストに追加します。

データファイルの形式、動的生成、クリーンアップパターンについては、reference/data-management.md を参照してください。 </data_management>

## API テストチェックリスト

コレクションを作成する前に:

• API ドキュメントを確認した
• 認証方法を特定した
• すべての環境のベース URL を定義した
• テストデータ戦略を決定した

各エンドポイントについて:

• ハッピーパステスト（期待する入力、期待する出力）
• 必須フィールドのバリデーション（400 エラー）
• 認証テスト（トークンなしで 401）
• 認可テスト（誤った権限で 403）
• 見つからない場合のテスト（無効な ID で 404）
• レスポンススキーマを検証した
• レスポンス時間をアサートした

コレクションの構成:

• リクエストをリソースごとにグループ化した
• 依存するリクエストにシーケンス番号を付けた
• ローカル/ステージング/本番用の環境を用意した
• 機密性の高い値をシークレットとしてマークした

CI 統合:

• Newman/Bruno CLI を構成した
• GitHub Actions ワークフローを作成した
• テストレポートをアーティファクトとしてアップロードした
• シークレットを CI 環境に保存した

詳細なパターンについては、適切なリファレンスを読み込んでください:

トピック	リファレンスファイル	読み込むタイミング
Postman の高度なパターン	reference/postman-patterns.md	コレクション、スクリプティング、モニター
Bruno ワークフロー	reference/bruno-patterns.md	.bru ファイル、git 統合
テストケース設計	reference/test-design.md	カバレッジ戦略、エッジケース
テストデータ戦略	reference/data-management.md	フィクスチャ、動的データ、クリーンアップ
CI/CD パイプライン	reference/ci-integration.md	Newman、GitHub Actions、レポーティング

読み込むには: 特定のトピックを尋ねるか、コンテキストが示唆しているか確認してください。

結果サイドカーの出力

最後のステップとして、~/.claude/skill-analytics/last-outcome-api-testing.json に書き込みます:

{"ts":"[UTC ISO8601]","skill":"api-testing","version":"1.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"tests_created":[n],"endpoints_tested":[n],"assertions_written":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

一部のステージが失敗しても結果が生成された場合は、ステータスに "partial" を使用してください。出力がまったく生成されなかった場合にのみ、"error" を使用してください。