JSON で書く API スモークテスト（合否表と JUnit XML 出力）
API smoke test runner with JSON test files and JUnit XML
JSON ファイルに書いた HTTP リクエストと期待値（ステータス・JSON の値・応答時間）を順に確認し、合否表と JUnit XML を出力します。トークンなどの秘密情報は環境変数から読み、出力では伏せ字にします。
できること
API が正しく動いているかを、デプロイ後やローカル開発中にすばやく確認します。
- JSON のテストファイルに、メソッド・URL・ヘッダー・ボディ・期待するステータスコード・最大応答時間を書く
- JSON パス（
$.items[0].idなど）で値を確認: 存在する／しない・一致・型・長さ・含む・正規表現・大小比較 - レスポンスヘッダーと本文に含まれる文字列も確認
${API_TOKEN}のように環境変数を埋め込み、.env形式のファイルからも読み込める。埋め込んだ値は画面・JSON・JUnit XML のすべてで***に置き換え- 結果を合否表で表示し、CI 向けの JUnit XML と JSON でも保存
- POST・PUT・PATCH・DELETE は
--allow-writeを付けたときだけ送信（既定ではスキップ） - リダイレクトは既定で追わないので、301 などもそのまま確認できる
使い方
python scripts/smoke.py smoke-tests.json --env-file .env.smoke --junit smoke-junit.xmlエージェントに「この API のスモークテストを作って実行して」と頼むと、テストファイルを書いて実行し、失敗の原因の見当をつけます。Claude・Codex・Hermes Agent・Cursor で使えます。
必要な環境
- Python 3（標準ライブラリのみ）
注意点
- テストファイルに書いた URL にだけリクエストを送ります。書き込み系のテストは、書き込んでよい環境か確認してから
--allow-writeを付けてください。 - 応答時間は 1 回のリクエストを手元で測った値です。負荷試験ではありません。
- 3 文字未満の値は伏せ字にしません。秘密情報はテストファイルに直接書かないでください。
- JSON パスはワイルドカードやフィルターには対応していません。
English description
Checks HTTP endpoints described in a JSON file (status, JSON path values, latency) and prints a pass/fail table plus JUnit XML. Secrets come from environment variables and are masked.
What it does
Quickly checks that an API works, after a deploy or during local development.
- Write method, URL, headers, body, expected status and max latency per test in a JSON file
- JSON path assertions (for example
$.items[0].id): exists or absent, equals, type, length, contains, regex, numeric comparisons - Response header and body text checks
- Environment variables such as
${API_TOKEN}, also loadable from a.env-style file. Substituted values are replaced with***in the console, JSON and JUnit XML output - Pass/fail table on screen, plus JUnit XML for CI and a JSON report
- POST, PUT, PATCH and DELETE are sent only with
--allow-write(skipped by default) - Redirects are not followed by default, so a 301 can be asserted as-is
How to use
python scripts/smoke.py smoke-tests.json --env-file .env.smoke --junit smoke-junit.xmlAsk the agent to write and run smoke tests for your API. It writes the test file, runs it and explains likely causes of failures. Works with Claude, Codex, Hermes Agent and Cursor.
Requirements
- Python 3 (standard library only)
Caveats
- Requests go only to the URLs in the test file. Use
--allow-writeonly for environments that may be written to. - Latency is a single client-side measurement, not a load test.
- Values shorter than 3 characters are not masked. Do not write secrets into the test file.
- JSON paths do not support wildcards or filters.
インストール方法
- ダウンロードしたZIPを展開します（中に
api-smoke-test-runner/フォルダとSKILL.mdがあります）。 - フォルダごと、使うエージェントのスキル置き場にコピーします。
- Claude：
~/.claude/skills/（プロジェクト単位なら.claude/skills/） - Hermes Agent：
~/.hermes/skills/ - Codex：
~/.agents/skills/／Cursor：~/.cursor/skills/ - Claude アプリ（claude.ai）：「カスタマイズ → スキル」からZIPをアップロード
- Claude：
- エージェントを再起動し、スキル一覧に表示されることを確認します。
出品者
Skills that make everyday developer work faster and safer: Git, testing, APIs and security.
出品スキル 8 件