api-testing

API テスト（api-testing）

インターフェースレベルのテスト——E2E 以外のもう一つの実行経路です。

• 入力：API ドキュメント（OpenAPI/Swagger）、用例 Schema の execution_model で自動化可能なインターフェース用例、テスト対象環境の情報（base URL、アカウント/Token）；性能軸（型マトリクス軸 1）の引き継ぎパッケージ 专项移交_性能_*.yaml
• 出力（ディスクへの保存）：API テストスクリプト（pytest + requests、またはプロジェクト所定の技術スタック）+ 実行個別レポート 测试报告_api_{日期}.md（命名は ../core/report-template.md のヘッダー注記に従い、項目は同 §3 に合わせます。qa の中断判定基準ではこのファイル名を確認します）；性能テストを引き継ぐ場合は、k6 負荷テストスクリプトと負荷テストレポートも別途生成します（references/k6-conventions.md）
• 対象範囲外：Web UI のフロー → automated-e2e-testing；インターフェースの手動テスト用例設計 → test-case-writing

使用する場面

• OpenAPI/Swagger ドキュメントが与えられ、インターフェース自動テストの作成と実行が必要な場合
• 用例 Schema からインターフェースレベルで自動化可能な用例を抽出し、API スクリプトに変換して実行する場合
• 認証／権限昇格、冪等性、並行書き込み、エラーレスポンスなど、インターフェース層の個別項目を網羅する必要がある場合
• 性能テストの引き継ぎパッケージまたはインターフェース一覧が与えられ、負荷テストスクリプト（k6）の生成と実行が必要な場合——references/k6-conventions.md に従います

使用しない場面

• Web UI の操作フロー（クリック／ページ状態）→ automated-e2e-testing
• インターフェースの手動テスト用例の作成 → test-case-writing
• エンドツーエンドパイプライン → qa がオーケストレーション
• 独立した負荷テスト環境の構築と容量確保 → 運用／個別協業（エージェント側で負荷テストを引き継ぐ場合は references/k6-conventions.md を参照；外部実行の場合は test-strategy の引き継ぎパッケージに従います）
• Mock Server の構築 → 開発協業事項であり、この skill の対象範囲外です

スキャフォールド（デフォルトは pytest + requests。プロジェクト所定のスタックに置き換え可能）

api-tests/
├── conftest.py            # fixture：base_url、会话/Token、环境配置（环境变量注入，可由 .env 加载，不硬编码）
├── common/
│   └── client.py          # 统一请求封装：日志、超时、鉴权头、断言辅助
├── test_{模块}_{接口}.py   # 一个接口一个文件，test 名沿用 TC 编号
└── requirements.txt

# common/client.py —— 统一请求封装（requests.Session 不支持 base_url，必须显式拼接）
import requests

class Client:
    def __init__(self, base_url: str, token: str):
        self.base_url = base_url.rstrip("/")
        self.s = requests.Session()
        self.s.headers.update({"Authorization": f"Bearer {token}"})

    def request(self, method: str, path: str, **kwargs):
        url = f"{self.base_url}/{path.lstrip('/')}"
        kwargs.setdefault("timeout", 10)
        return self.s.request(method, url, **kwargs)

    def get(self, path, **kw):  return self.request("GET", path, **kw)
    def post(self, path, **kw): return self.request("POST", path, **kw)
    # put / delete / patch 同理扩展

def login(user: str, password: str) -> str:
    """按项目实际登录接口实现（如 POST /login 换 token）——占位，勿直接照抄"""
    raise NotImplementedError("按项目登录接口实现")

# conftest.py 关键 fixture
import os
import pytest

from common.client import Client, login

@pytest.fixture(scope="session")
def client():
    base_url = os.environ["API_BASE_URL"]          # 环境与账号不硬编码，走环境变量
    token = login(os.environ["API_USER"], os.environ["API_PASSWORD"])
    return Client(base_url, token)

機密情報（アカウント/Token/環境アドレス）はすべて環境変数から注入し、コードリポジトリには含めません（automated-e2e-testing の constants に関する規約と同じです）。

ワークフロー

1. 入力解析と範囲の確認

• OpenAPI ドキュメントから抽出：インターフェース一覧、パラメーター表（必須／型／範囲／デフォルト値）、エラーコード、認証方式
• 用例 Schema からフィルタリング：automation.framework: api の用例、および execution_model: dev-collab かつ framework が manual ではない用例 → 変換対象（test 名は TC 番号をそのまま使用：test_TC_05_01_写入字段读回一致；framework: manual の dev-collab 用例は手動協業のままとし、変換しません）
• 環境が不明 → ユーザーに確認します（base URL、アカウント、書き込み可能な本番バイパス環境かどうか）。不確かな場合は質問し、インターフェースの動作を推測しません（質問形式と判断内容の記録は ../core/clarify-pattern.md に統一し、場面には「実行確認」を指定します）

2. 用例設計（この段階で ../core/testing-principles.md を読み込みます。手法の詳細は ../core/methods/data-driven.md）

インターフェースごとにパラメーターマトリクスを 1 つ作成します（分析過程で使うツールです。内部で作成するか、下書きにとどめ、中間ファイルとしてディスクには保存しません——結論は用例に直接記載します。中間ファイルを作らない方針は test-case-writing と同じです）。パラメーターごとに各属性を確認し、以下を重点的に網羅します。

カテゴリー	必須確認項目
パラメーター	必須項目の欠落／型の誤り／境界値（空／最小・最大値／過大値。../core/methods/boundary.md を参照）
認証	Token なし／期限切れ Token／誤った Token／権限昇格（他者のリソース id）——権限昇格テストの基準は ../core/methods/permission.md（Role×Action×Resource マトリクス + 垂直・水平の 2 種類の権限昇格、すなわち型マトリクス軸 2 の実行層）
冪等性	同一のビジネスキーで重複送信 → 重複作成されないこと；再試行の安全性
並行性	同一リソースへの並行書き込み → 相互上書きや中間状態が発生しないこと
エラーレスポンス	各エラーコードの発生条件 + レスポンスボディの構造と文言
データ整合性	書き込み後の読み戻しが一致すること；連鎖操作後の関連データが一致すること

複数パラメーターを持つインターフェースの組み合わせは、../core/methods/data-driven.md 第 2 節に従って明示的に縮小して実施します（全組み合わせ → ペアワイズ組み合わせ → リスクに基づく選択）。単一パラメーターは属性ごとに全組み合わせを確認します。パラメーター間の相互作用（フィールド間ルール／パラメーター依存関係）は、カバレッジレベルを選択して確認し、デフォルトはペアワイズ組み合わせです。縮小した範囲と除外した組み合わせは rationale に記載し、黙って縮小しません。

3. スクリプト作成

• インターフェースごとに test ファイルを 1 つ作成します。各 test では 1 項目のみをテストし、TC 番号をそのまま命名に使用します
• 出力予算の規律（出力切れの防止）：同種の境界値／パラメーター検証は @pytest.mark.parametrize でまとめて 1 つのパラメーター化テストにし、値ごとに test 関数を重複して展開したり、長いアサーションを重複させたりしません——1 ファイルが約 250 行を超える場合は、パラメーター化して収束させます（生成経路には出力上限があり、超えると途中で切れてコンパイルできないコードが生成されます）
• アサーションの 3 点セット：ステータスコード + ビジネスコード + レスポンスボディの主要フィールド（「200 だけをアサート」する弱いアサーションは使いません）
• テストデータは自前で作成・削除し（setup で作成／teardown で削除）、実行順序に依存させません。データテンプレート（一意名など）は、まず資料のフィールド制約（maxLength／列挙値／形式）を確認します。テンプレートの合計長（接頭辞 + ランダム部分）は制約上限 −2 以下にします——上限ぎりぎりの値はデータ作成側の欠陥です（実測された自傷事例：一意名テンプレートが 22 文字で、契約上の maxLength 20 に抵触。2 件の実測事例と test-case-writing §4 には同じ内容のコピーがそれぞれ存在するため、改訂時は両方を同期します）。パラメーターマトリクスの各セルで、フィールド間のビジネスルールも再確認します（例：「使用条件のしきい値は額面を下回ってはならない」）——ルールに違反する組み合わせは有効な値に変更するか、明示的な負方向用例に分けます。暗黙的に不正な組み合わせは使いません（実測された自傷事例：金額の上限 1000 に額面を下回るしきい値を組み合わせた結果、400 THRESHOLD_INVALID が返り、用例では 201 を期待していた）
• 前の状態に依存する用例では、前提条件の中で明示的にデータを作成し、データベースにデータがあると仮定しません（データ作成パターン：../core/methods/data-factory.md——makeX コンストラクター／データ作成経路から 1 つ選択／プレフィックスによる分離）

4. 実行と結果

レポート項目と統計の基準は ../core/report-template.md を唯一の情報源とします（機械可読な要約スニペットを含み、終了時に読み込みます）。qa の終了時に作成する最終レポートへそのまま組み込めるようにします。

pytest api-tests/ -v --tb=short          # 全量
pytest api-tests/test_coupon_create.py   # 单文件

• 失敗した用例は、テスト対象システムの Bug／環境問題／用例自体の誤りをまず判別します——独断で推測しません。環境問題と期待結果の曖昧さを列挙してユーザーに確認します（質問形式は上記と同じで、../core/clarify-pattern.md に従います）
• 失敗が 3 件以上の場合は一括トリアージに切り替えます。まず ../core/triage.md の 4 分類で分類します（A 真の不具合／B アセットの問題〔B1 製品の期待動作の変更・B2 用例自体の誤り〕／C 環境と依存関係の障害／D 不安定）。A 分類のみを下記の Bug 記録フローに進め、1 件ずつの判別に置き換えます
• パイプラインでの実行：headless モードで PR スモークテスト／夜間タスクに入る場合、チェックポイントは未決項目に格下げし、成果物は規定どおりにディスクへ保存し、終了コードで基盤障害と真の不具合を区別します——3 つの規約については ../core/pipeline-integration.md を参照します（この段階で読み込みます）
• 構造カバレッジによる補足エビデンス（任意）：テスト対象サービスのコードがあり、テスト環境に計装できる場合（Python サービスは coverage run で起動；JVM サービスは JaCoCo agent を使用）、インターフェース用例の実行後、テスト対象サービスの行／分岐カバレッジを補足 E3 エビデンスとして取得します——これはカバレッジがゼロ、または極めて低いインターフェースや分岐の発見にのみ使用します（テスト漏れの兆候として、用例の追加または方針の引き上げにつなげます）。カバレッジを追い求めるための見栄えの指標にはしません。計装できない場合はそのまま省略し、納品を妨げません
• 発見した Bug：エビデンス（リクエスト／レスポンスの原文、タイムスタンプ）を ../core/report-template.md §3 に従って記録します。根本原因の分析は bug-analysis に引き継ぎます

5. 納品

スクリプトのパス + 実行統計（§2 実行統計：P0/P1/P2 × 成功／失敗／ブロック／未実行。../core/report-template.md に従います）+ Bug 項目 + 未解決事項一覧 + （計装した場合）構造カバレッジの概要：カバレッジがゼロ／低いインターフェースの一覧。

契約と schema の整合性（型マトリクス軸 10 の実行層）

軸 10 の判断で include となった場合は本節に従って実行します（判断とレベルは test-strategy の type_scope に基づき、本節では実行形式のみを定めます）。レポートの回収には report-template §7 の表を使用し、実行側の列には事実どおり記入します。

两层形态（分工不互替）

层	对象	做法
schema 一致性	响应体 vs OpenAPI 定义逐字段（类型/必填/枚举）	Schemathesis 一条命令接入：schemathesis run openapi.yaml --base-url $API_BASE_URL；或手写 jsonschema 断言并入现有 test 文件
结构级负向 fuzzing	结构鲁棒性（类型错位 / 超长 / 格式畸变）	Schemathesis 自动生成非法输入。与 §2 参数矩阵分工：矩阵管业务语义组合，fuzzing 管结构鲁棒性

概念边界

• schema 校验 ≠ 消费者契约：schema 只验"响应符合定义"，契约验"消费者-提供者允许的交互集合"
• Pact 式消费者驱动契约的启用判据：多消费者微服务且字段演进频繁——单系统项目 schema 一致性即可，不上契约框架
• 契约执行物按 type_scope 进执行策略裁决（脚本型消费方式）；mock/沙箱依赖不可得按矩阵 R5 记 blocked

执行纪律

• fuzzing 发现的 5xx / 未定义错误码视为候选缺陷，逐条归因（与 §4 失败分辨同流程），不自动记 Bug
• schema 校验全过 ≠ 契约没问题：字段语义变更（结构未变）schema 层不可见，语义回归靠业务用例

Common Mistakes

错误	后果	正确做法
只断言状态码不断言业务码与响应体	Bug 漏检（200 但业务失败）	状态码 + 业务码 + 关键字段三件套
硬编码环境地址与账号	无法跨环境运行、泄露敏感信息	环境变量注入
测试间共享可变状态	顺序依赖、偶发失败	自建数据 + 自清理，每条独立
重复提交不测幂等	重复创建类 Bug 上线	同业务键重复请求必测
失败一律记为 Bug	误报污染报告	先归因（系统/环境/用例），歧义问用户
无权限/越权只测前端表现	后端未拦截的越权漏检	直接调接口测鉴权（无 Token/过期/他人 id）
多参数接口逐值全展开或随手抽样	组合爆炸截断 / 参数交互缺陷静默漏测	按降档策略显式选档（全组合 → 成对 → 风险挑选），降档留痕
Schema 用例带占位符/虚构入口仍直接翻成脚本	幻觉脚本：能跑通但测的不是真实接口	转换前过 ../core/executability.md 红线闸门，补不了的暂缓进遗留清单
schema 校验全过就当契约没问题	字段语义变更（结构未变）漏检	schema 只验结构；语义回归靠业务用例（见「契约与 schema 一致性」节）