smoke-tests

スモークテスト

低速なテストスイートの実行前に、ユーザー向けの重要な機能を検証する、最小限で高速なテストです。 スモークテストに失敗した場合、ビルドは壊れています。フルテストスイートは実行されません。 特徴： 最小限のセットアップ · 高速（数秒） · 正常系のみ · 高いシグナル対ノイズ比 · HTTP のみ — JS ランタイムもテストフレームワークも不要

対象範囲： このスキルの対象は、Hurl または curl を使って作成する HTTP API のスモークテストのみです。Jest、Vitest、その他のインプロセス JS テストランナーは対象外です。ここでのスモークテストは、実行中のアプリ（ローカル、ステージング、またはプレビュー環境）に対するブラックボックスの HTTP チェックです。

---

既存のスモークテストを特定する

パターン	検出方法
smoke-tests/ ディレクトリ	慣例に基づくディレクトリ
*.hurl ファイル	Hurl シナリオファイル
smoke.sh / smoke-test.sh	curl ベースのシェルスクリプト
# @smoke / # @critical コメント	タグを検索

---

ツールの選択

Hurl を使う場合	curl を使う場合
複数ステップのフロー（トークンを取得してリクエストを連鎖させる）	単一リクエスト／手早く行う単発のチェック
構造化された JSONPath アサーションが必要な場合	CI の依存関係をできるだけシンプルにしたい場合（curl はほとんどの環境にプリインストールされています）
シナリオごとに読みやすく宣言的なファイルを用意したい場合	hurl バイナリをインストールしたくない場合
HTML／JUnit レポートを組み込みで使いたい場合	jq でアサーションが簡単にできる場合（ステータスコードや単一フィールドなど）

単一リクエストを超えるものには、デフォルトで Hurl を使ってください。まさにこの用途向けに作られており、宣言的な記述を保てます。curl（JSON には jq、ステータスチェックには通常のシェル）を使うのは、対象環境に Hurl をインストールできない場合、またはチェックが 1 行で済む場合に限ってください。

---

実行コマンド

# Hurl — run all .hurl files as tests
hurl --test --max-time 10 smoke-tests/*.hurl

# Hurl — single file with variables
hurl --test --max-time 10 --variable base_url=http://localhost:3000 smoke-tests/health.hurl

# Hurl — variables file + HTML report
hurl --test --max-time 10 --variables-file smoke-tests/vars.env --report-html report/ smoke-tests/*.hurl

# curl — quick health check, fail on non-2xx
curl --fail --silent --show-error "$BASE_URL/health" | jq -e '.status == "ok"'

# curl — run a smoke script (see references/curl.md)
BASE_URL=https://staging.example.com bash smoke-tests/smoke.sh

---

品質テーブル

項目	推奨事項	避けること
範囲	重要なワークフローをテストする	あらゆるエッジケースをテストする
セットアップ	最小限で再利用可能なフィクスチャ	複雑で多段階のセットアップ
アサーション	リクエストごとに 1～3 個、対象を絞る	リクエストごとに多数のアサーション
時間	リクエストごとに <100ms	低速でリソースを大量に消費するテスト
保守性	安定していて、変更がまれ	実装の変更で壊れる
カバレッジ	広い範囲のパス、深掘りはしない	内部動作を深くテストする

---

CI との統合

# GitHub Actions — Hurl smoke as gate
- name: Install Hurl
  # Pin an exact version + verify checksum — don't pipe install.sh straight from
  # the web with no version pin or verification (see references/hurl.md for the
  # full snippet with the sha256sum check).
  run: |
    HURL_VERSION=4.3.0
    curl -LO https://github.com/Orange-OpenSource/hurl/releases/download/${HURL_VERSION}/hurl_${HURL_VERSION}_amd64.deb
    echo "<pin-expected-sha256-here>  hurl_${HURL_VERSION}_amd64.deb" | sha256sum -c -
    sudo dpkg -i hurl_${HURL_VERSION}_amd64.deb

- name: Run Smoke Tests
  id: smoke
  run: hurl --test --max-time 10 --variable base_url=${{ env.APP_URL }} smoke-tests/*.hurl

- name: Run Full Test Suite
  run: npm test
  if: steps.smoke.outcome == 'success'

# GitHub Actions — curl smoke as gate (no Hurl install needed)
- name: Run Smoke Tests
  id: smoke
  env:
    BASE_URL: ${{ env.APP_URL }}
  run: bash smoke-tests/smoke.sh

- name: Run Full Test Suite
  run: npm test
  if: steps.smoke.outcome == 'success'

---

クイックチェックリスト

• スモークテストの場所を特定する（smoke-tests/ ディレクトリ、.hurl ファイル、または smoke.sh）
• 重要なワークフローを列挙する：認証、作成、読み取り、一覧表示、ヘルスチェック
• 対象を絞ったチェックを 5～10 個作成する — 正常系のみ
• テストスイートの前に環境を準備する（認証トークン、ベース URL）。必要に応じて終了後に後片付けする
• 単独で実行する。すべて成功してからフルテストスイートを実行する
• CI パイプラインの最初のゲートとして組み込む

---

統合例

特定： あるオンラインストア API の最も重要な経路は、「ユーザーがログインしてカートを読み込めるか？」です。 これが失敗すれば、ほかのすべてが意味をなしません。スモークテストに最適な候補です。複数ステップの HTTP フロー（ログイン、トークンの取得、トークンの使用）なので、Hurl を使います。

作成 smoke-tests/login-cart.hurl：

POST {{base_url}}/login
{ "email": "[email protected]", "password": "{{smoke_pw}}" }
HTTP 200
[Captures]
token: jsonpath "$.token"

GET {{base_url}}/cart
Authorization: Bearer {{token}}
HTTP 200
[Asserts]
jsonpath "$.items" exists

hurl --test --variable base_url=https://staging.example.com \
            --variable smoke_pw=$SMOKE_PW smoke-tests/login-cart.hurl

CI に組み込む — フルテストスイートの実行前に通過させます：

- name: Smoke
  id: smoke
  run: hurl --test --variable base_url=${{ env.APP_URL }} smoke-tests/*.hurl
- name: Full suite
  run: npm test
  if: steps.smoke.outcome == 'success'

正常系のみ、2 つのリクエストで、1 秒未満で実行できます。ログインまたはカートに問題があれば、フル テストスイートは開始されません。

---

必要に応じて読む

読むタイミング	ファイル
Hurl のテンプレート、変数、CI スニペット、パターンが必要な場合	references/hurl.md
Hurl が利用できない場合／curl+jq のシェルスクリプトのテンプレートが必要な場合	references/curl.md

---

ベンチマーク

シナリオ：.benchmarks/scenarios/smoke-tests-001-ci-gate.md · 実行日：2026-08-31 · ログ：.benchmarks/runs/2026-08-31/smoke-tests-001-ci-gate.json

モデル	なし	あり	差分
claude-opus-4-8	50%	100%	+50%
claude-sonnet-4-6	33%	100%	+67%
claude-haiku-4-5	50%	100%	+50%

合格（実行日：2026-08-31）。すべてのモデルで一貫して向上しており、CI ゲートの基準をすべてのモデルで満たしています。.agents/skills/skill-optimizer/rules/release-gates.md に従ってゲートを設定してください。