api-testing

API テスト（Playwright + REST Assured）

Playwright TypeScript（request フィクスチャ、Supertest、Zod）と Java（REST Assured、AssertJ、JSON Schema Validator）の両方をカバーする、包括的な API テストスキルです。

このスキルを使用する場面

• REST または GraphQL エンドポイントの API テストを作成する
• リクエスト／レスポンスのスキーマを検証する（Zod、JSON Schema）
• 認証フローをテストする（OAuth2、JWT、API キー、Bearer トークン）
• エラー処理を検証する（400、401、403、404、409、422、500）
• ページネーション、フィルタリング、ソートのエッジケースをテストする
• PUT／DELETE 操作の冪等性を検証する
• サービス間のコントラクトテストを行う
• レート制限を検証する

使用しない場面

• ブラウザーを操作する UI フロー（Playwright の仕様には playwright-e2e-testing、Selenium には webapp-selenium-testing を使用してください）
• ライブの対話型ブラウザーセッションやスナップショット（playwright-cli を使用してください）
• 視覚やレイアウトのリグレッション（対象外 — DOM は扱いません）
• ページ間で実際のブラウザーを操作する必要があるエンドツーエンドの操作手順

前提条件

スタック	要件
TypeScript	Node.js 18+、@playwright/test または supertest、zod
Java	Java 21+、REST Assured 5.x、AssertJ、Jackson、json-schema-validator

基本原則

1. すべてのレスポンスでスキーマを検証する — 検証していないレスポンスを決して信頼しないでください
2. すべての HTTP ステータスコードをテストする — 正常系とエラー状態の両方を対象にします
3. 認証テストは必須です — 保護されたエンドポイントで 401／403 が返ることを検証します
4. データ駆動型にする — 有効値、無効値、境界値、空の値でテストします
5. 可能な限りステートレスにする — 各テストで後片付けを行うか、一意のデータを使用します

クイックリファレンス — Playwright

import { test, expect } from "@playwright/test";

test("GET /api/users returns 200 with valid schema", async ({ request }) => {
  const response = await request.get("/api/users");
  expect(response.ok()).toBeTruthy();
  const body = await response.json();
  expect(body).toMatchObject({ data: expect.any(Array) });
});

クイックリファレンス — REST Assured

import static io.restassured.RestAssured.*;
import static org.hamcrest.Matchers.*;

import java.util.List;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

@Test
@DisplayName("GET /api/users returns 200 with valid schema")
void getUsers() {
    String token = "test-token";

    given()
        .header("Authorization", "Bearer " + token)
    .when()
        .get("/api/users")
    .then()
        .statusCode(200)
        .body("data", is(instanceOf(List.class)))
        .body("data.size()", greaterThan(0));
}

---

危険信号

生成された API テストに以下のいずれかが見られる場合は、作業を止めて見直してください。

• ステータスコードのみをアサーションし、本文やスキーマを検証していない — レスポンスを検証しないと、コントラクトのずれが見えなくなります。
• テストファイルにハードコードされたシークレットやトークンをコミットしている — 環境変数またはシークレットマネージャーから読み込んでください。
• クリーンアップを行わず、テスト間で変更可能な状態を共有している — テストが不安定になり、実行順序に依存します。
• 認証テストを省略している（保護されたエンドポイントで 401／403 をアサーションしていない） — セキュリティのリグレッションにつながるリスクがあります。
• エラー状態を網羅していない（正常系の 200 のみ） — エラー処理がテストされていません。

---

参考資料

ドキュメント	内容
REST API パターン	CRUD、ページネーション、フィルタリング、エラーパターン
Playwright API テスト	request フィクスチャ、Supertest、TypeScript のパターン
REST Assured テスト	REST Assured、AssertJ、Java のパターン
スキーマ検証	Zod（TS）、JSON Schema（Java）、厳密／緩やかな検証
コントラクトテスト	リクエスト／レスポンスのコントラクト、冪等性、バージョニング

テンプレート

• Playwright API 仕様 — API テスト用のスターターファイル
• REST Assured テスト — Java テストクラスのひな型

スクリプト

• API ヘルスチェック — API エンドポイントが正しく応答することを検証します

トラブルシューティング

問題	解決策
認証が必要なエンドポイントで401	トークンが有効か確認し、有効期限を確認して再認証します
API テストが不安定	再試行ロジックを追加し、レート制限を確認して、一意のテストデータを使用します
スキーマ検証が厳しすぎる	柔軟なフィールドには .passthrough()（Zod）または additionalProperties: true を使用します
応答の遅いエンドポイントでタイムアウト	リクエストオプションの timeout を増やし、サーバーの負荷を確認します

---

検証

• スキーマ検証の実装 — すべての応答をスキーマ（Zod または JSON Schema）で検証します
• 認証のテスト — 有効な認証情報がない場合、保護されたエンドポイントが401を返すことを確認します
• 冪等性の検証 — PUT/DELETE を複数回呼び出しても同じ結果になることを確認します
• エッジケースへの対応 — 空のペイロード、無効な型、境界値、SQL インジェクションの試行を対象にします