Nocticas

Nocticas E2E Gate — GitHub Action

プッシュや PR のたびに、固定された Nocticas ゲートを対象 URL に対して実行し、判定が不合格ならビルドを失敗させます。ブラウザーは Nocticas のサーバー上で動作します。この Action は、実行を開始して判定をポーリングし、終了コードに変換する軽量なクライアントです。誤って成功と判定することはありません。ハーネスのエラーを合格として扱うことはありません。

クイックスタート

1. Nocticas でフローを作成して固定します（エージェントによる実行 → 固定 → 決定的なステップスクリプトを JSON としてエクスポート）。
2. ゲートをリポジトリにコミットします（例：.nocticas/checkout-flow.json）。
3. リポジトリのシークレットとしてキーを追加します：NOCTICAS_API_KEY。
4. ワークフローを追加します：

# .github/workflows/nocticas.yml
name: Nocticas E2E gate
on: [pull_request, workflow_dispatch]
jobs:
  verify:
    runs-on: ubuntu-latest          # standard runner = free on public repos
    steps:
      - uses: actions/checkout@v4   # so the gate file is available
      - uses: Low-Latency-Labs/nocticas-action@v1
        with:
          api-key: ${{ secrets.NOCTICAS_API_KEY }}
          gate: .nocticas/checkout-flow.json
          target: ${{ vars.PREVIEW_URL }}   # your deployed preview/staging URL

判定が不合格の場合、ジョブが失敗し、PR／マージがブロックされます。

入力

入力	必須	デフォルト	説明
api-key	はい	—	Nocticas API キー（シークレットとして保存してください）。
gate	はい	—	リポジトリ内にある固定済みゲート JSON（決定的なステップの配列）へのパス。
target	はい	—	テスト対象の URL（例：PR のプレビュー環境）。
api-base	いいえ	https://app.nocticas.com/api	Nocticas API のベース URL。
timeout-seconds	いいえ	300	判定を待つ最大時間。
poll-seconds	いいえ	3	ポーリング間隔。
fail-on-error	いいえ	true	ハーネスの error（テスト失敗ではありません）をビルド失敗として扱います。検証されていない実行が合格になることはありません。

出力

出力	説明
run-id	Nocticas の実行 ID（ログにリンクを記載してください）。
verdict	passed | failed | error | timeout。

ゲートファイル

JSON の決定的なステップの配列です。Nocticas で合格した実行を固定したときに生成されるものと同じです。例は examples/gate.example.json を参照してください。リポジトリに含めておけば、E2E テストを、テスト対象のコードとともにバージョン管理できます。

実際の認証情報はコミットしないでください。 ゲートの対象にはステージング環境またはプレビュー環境を指定し、専用のテストアカウントを使用してください。Nocticas に組み込まれたテスト用受信トレイが OTP／マジックリンクによるログインに対応しているため、ゲートにシークレットを埋め込む必要はありません。

コスト

• この Action の公開： 無料（公開リポジトリであれば、有料プランは不要です）。
• 実行（利用者の場合）： 標準ランナーを使用する公開リポジトリでは無料です。プライベートリポジトリでは、月間無料分の範囲内で利用できます。軽量なジョブが 1 つだけなので、ランナーの実行時間は数秒です。
• ブラウザー実行： Nocticas クレジットが課金されます。ただし、決定的／固定済みの実行は月間利用枠内で無料なので、通常、プッシュのたびにゲートを実行してもクレジットはかかりません。

その他の CI システム（手順）

GitHub を利用していない場合も、同じ開始 → ポーリング → 終了コードのロジックを移植可能なスクリプトとして利用できます。recipe.sh と examples/gitlab-ci.example.yml を参照してください。インターフェイスは HTTP 経由の JSON だけです：

POST {api-base}/runs   { "mode":"deterministic", "target": "...", "script": [ ...gate... ] }   → { "id": "..." }
GET  {api-base}/runs/{id}                                                                       → { "status": "passed|failed|error|..." }

ヘッダー：x-nocticas-key: <key>。status == "passed" 以外の場合は、ゼロ以外の終了コードを返します。