run-smoke-tests

スモークテストの実行

実際のビルドに対して、幅広いユーザージャーニーを実行し、判断を人が監査できるだけの証拠を残します。製品を起動したり、その状態を変更したりする前に、ホストプロジェクトを理解してください。

運用上の契約

• Markdown は、コードにコンパイルするソースではなく、実行時の指示として扱ってください。
• サポートされているユーザー向けのインターフェース（Web UI、API、CLI、デスクトップ、モバイル、または文書化された組み合わせ）でテストしてください。
• 実行と修正を分けてください。実行中に製品、テスト、ジャーニーを編集しないでください。修正を依頼された場合も、修正に着手する前にレポートを完成させてください。
• 原則として、ローカル、テスト、プレビュー、またはステージング環境を使用してください。明示的な許可がない限り、本番環境を変更したり、費用を発生させたり、実際の招待を送信したり、実際のユーザーデータを変更したりしないでください。
• 合格または不合格の判断はすべて、記録した証拠にたどれるようにしてください。
• 最初の失敗した実行を残してください。成功するまで再試行して証拠を消さないでください。

ワークフロー

1. リポジトリ理解のゲートを通過する

最も近いリポジトリの指示、製品 README、運用手順書、コントリビューションガイド、マニフェスト、起動スクリプト、既存のスモークテストまたはエンドツーエンドテスト、および関連する最小限の製品ドキュメントを読みます。認証設定、シードデータ、テストアカウント、機能フラグ、オブザーバビリティ、成果物の規約、クリーンアップコマンドを検索します。関連する UI、サービス、状態、外部システムの境界をたどり、失敗の原因を製品の適切な部分に特定できるようにします。

何かを起動する前に、以下を説明できる状態にしてください。

product and user surface:
authoritative journey source:
relevant architecture and system boundaries:
build and start commands:
target environment and data boundary:
interaction driver or available tools:
authentication and human checkpoints:
evidence capture capabilities:
safe cleanup path:
known abort conditions:

コマンド、URL、認証情報、権限が不明な場合は、推測しないでください。不明な項目のために安全に実行できない場合は、事前確認の阻害要因として報告してください。

2. ジャーニーの契約を検証する

references/smoke-format.md を読みます。与えられた文章を、製品の動作を暗黙に追加することなく、標準化します。

ジャーニーが以下を満たしていることを確認してください。

• 一貫性のあるユーザー目標を表している。
• 環境と、許可される変更を明示している。
• 重要なオラクルと重要でないオラクルを定義している。
• 認証、支払い、セキュリティ、または破壊的な操作のチェックポイントを特定している。
• クリーンアップまたは隔離の計画がある。
• 直ちに中止すべき条件を明示している。

小規模で決定論的な動作はシナリオテストに移します。より大きな経路とシステム間の接合部は、スモークテストの対象として維持してください。

3. 製品の動作を変更せずに事前確認する

文書化されたコマンドで製品をビルドまたは起動します。正常性、テストデータの利用可能性、ドライバーの接続性、記録機能、成果物に十分なストレージがあることを確認します。

リポジトリに既存の成果物ディレクトリがある場合は、それを優先して使用してください。それ以外の場合、.context がすでに存在していれば .context/smoke-runs/ を使用し、存在しなければ一時ディレクトリを作成して絶対パスを報告してください。ユーザーから依頼されない限り、生成した証拠をバージョン管理に追加しないでください。

以下を含む実行マニフェストを作成します。

journey ID and source path
commit or build identifier
environment and base URL or executable
start time and executor
human checkpoints
recording and log sources

ビルドが正常でない場合、環境が不適切な場合、アカウントまたはデータの境界が安全でない場合、あるいは重要なオラクルに必要な証拠を記録できない場合は、ステップ 1 の前に中止してください。

4. Markdown を解釈して実行する

実際の製品インターフェースを通じて、ジャーニーを順番どおりに進めます。各ステップについて、以下を記録します。

timestamp
instruction
action taken
observable result
evidence path or log reference
provisional judgment
deviation, latency, or uncertainty

通常のユーザー向け操作を使用してください。ジャーニーで API を明示的にテストしている場合、または分離されたフィクスチャの準備にのみセットアップ API を使用する場合を除き、UI のステップを回避するために内部 API を呼び出さないでください。

宣言された人間によるチェックポイントでは一時停止してください。必要な操作を正確に伝え、人間が完了したら同じ状態から再開してください。ユーザーにチャットへシークレットを貼り付けるよう求めてはいけません。

ドライバーが動画に対応している場合は、実行全体を記録し、ステップのタイムラインから字幕またはタイムスタンプ付きのトランスクリプトを生成してください。対応していない場合は、スクリーンショット、ターミナル出力、構造化ログ、状態のスナップショットを記録してください。環境で動画を作成できない場合は、動画を記録したと主張しないでください。

5. 一度判定し、慎重に再試行する

主判定を 1 つ割り当てます。

• PASS：すべての重要なオラクルが確認され、中止条件も発生していない場合。
• FAIL：重要なオラクルに違反した場合、または予期しない製品エラーによって目標を達成できなかった場合。
• BLOCKED：外部の前提条件、権限、環境、または人間によるチェックポイントが原因で、有効な判定を下せなかった場合。

同じビルドと入力で結果に一貫性がない場合は、フラグとして FLAKY を追加します。

証拠がないことを合格にしてはいけません。重要でない問題があっても、レポートで別途明記する場合に限り、合格を維持できます。

再試行は最大 1 回とし、証拠から製品の不具合ではなく、環境またはドライバーの問題が示されている場合に限ります。両方の実行結果を保持し、再試行を許可した理由を説明します。

6. クリーンアップして引き継ぐ

ジャーニーで許可されたクリーンアップのみを実行します。クリーンアップに失敗した場合は、テストデータを隔離し、識別子を記録して、残存物を報告します。クリーンアップの失敗を、製品判定が合格であることの陰に隠してはいけません。

次の内容を含むレポートを作成します。

1. 判定、確信度、ビルド、環境、所要時間。
2. タイムスタンプ付きのステップ表。
3. 重要なオラクルの結果と証拠へのリンク。
4. 人間によるチェックポイントと逸脱。
5. コンソール、ネットワーク、ログ、スクリーンショット、録画の保存場所。
6. クリーンアップの結果と残存データ。
7. 実行中に見つかった、決定論的なテストの候補。

最終的なユーザーメッセージでは、製品の不具合、テスト環境の不具合、不確かな判定を区別しなければなりません。

実演例

• SaaS チームのオンボーディング。認証チェックポイントと監査済みレポートのサンプルが含まれています。
• 開発者向け CLI の初回実行。インストール、認証、無効な設定からの復旧、隔離されたプロジェクトでのクリーンアップを取り上げています。

実行時の解釈を示すには、これらの例を使用します。すべてのコマンド、URL、アカウント、期待される結果を、ホストリポジトリから得た証拠に置き換えます。

障害への対応

• 製品を起動できない場合：ビルドと起動の出力を取得し、BLOCKED と判定します。別の環境を独断で使用してはいけません。
• 認証を利用できない場合：チェックポイントで一時停止するか、BLOCKED と判定します。承認されていない認証情報で回避してはいけません。
• 製品の動作が Markdown の説明と異なる場合：証拠を保持し、動作の情報源に真の矛盾がある場合を除き、FAIL と判定します。
• 実行中に証拠の取得に失敗した場合：重要なオラクルに影響する場合は中止します。それ以外の場合は、制約が明らかになるようにしたうえで続行します。
• 不具合が見つかった場合：まずレポートを完成させます。診断や修正は、別途ユーザーから依頼された場合に限って行います。