フック（Hooks）

フックは、各ステップの前後やテストの前後に、既存の共有ステップや共有グループを実行する仕組みです。設定後は通常どおりテストを実行でき、フックは他のステップ同様に実行されます。実行後、結果の可視化も可能です。

よくある用途

Before test の例

テスト開始前に特定の処理を実行します。

• 変数の初期化: 各テストで使用する変数を事前に初期化する処理。
• テスト環境の準備: DB 接続の確立、必要なディレクトリの作成、サーバー起動など、テスト実行前に環境を整える処理。
• 前のテストのクリーンアップ: 前回テストの残骸を削除し、毎回クリーンな状態からテストを開始するための処理。
• 複数テストで共通のセットアップ: 複数テストで共通して必要な前処理をまとめ、重複したロジックを減らすための処理。

After test の例

テスト終了後に特定の処理を実行します。

• テスト環境のクリーンアップ: DB 接続のクローズ、一時ファイルの削除、サーバー停止など、テスト後のクリーンアップ処理。
• 結果の検証: ファイル内容や DB の状態を確認するなど、テスト結果が期待どおりか追加で検証する処理。
• 元の状態への復元: 次のテストをクリーンな状態で開始できるよう、環境を元の状態に戻す処理。
• 複数テストで共通の後処理: 複数テストで共通して必要なクリーンアップ処理をまとめ、重複したロジックを減らすための処理。

Before/After each step の例

Before/After each step フックは、テスト内の「各ステップの直前・直後」にロジックを挿入したい場合に使用します。

• デバッグ用途: 各ステップの前後でログを出力し、アプリケーションの状態やパラメーターの値を確認する。
• 中間結果の検証: ステップ実行後に変数の値などをチェックし、中間状態が期待どおりか検証する。
• ステップ間で共有するセットアップ: 複数ステップで共通して必要な前処理をまとめ、重複したロジックを減らす。
• 進捗のモニタリング: 各ステップの結果を計測・記録し、テストの進行状況を監視する。

Before/After フックの作成 {#creating-before-after-hooks}

フックはテスト設定の構成（Test Configuration）と／または設定ファイル（Config File）で作成します。新規／既存の構成で設定可能な方法:

• プロパティパネルから作成 — テスト内で選択した構成を編集
• 構成リストから作成 — 構成一覧画面で新規作成／編集し、対象テストに適用
• 既定構成から作成 — テストのデフォルト構成を編集（既存編集／新規作成）

上記の 3 つの方法（プロパティパネル／構成リスト／既定構成）から、どの種類のフックを設定できるかを表にまとめると次のとおりです。

テスト構成からフックを作成する {#creating-hooks-via-the-test-configuration}

Test Configuration Hooks は、プロパティパネル／構成リスト画面／テストの既定構成から作成できます。

プロパティパネルからフックを作成する {#creating-hooks-via-the-properties-panel}

テストのプロパティパネルから作成できるフック:

• Before test handler – テスト実行前に実行されるフック
• Before each step handler – テスト内の各ステップ実行前に実行されるフック
• After each step handler – 各ステップ実行後に実行されるフック
• After test handler – テスト実行後に実行されるフック

プロパティパネルからフックを作成する手順:

1. 対象テストを開き、Show Test Properties ボタンをクリックします。

2. Properties パネルの Configuration セクションで Edit ボタンをクリックします。

Edit Configuration ペインが表示されます。

3. Before/After Hooks セクションで作成したいフックタイプにチェックを入れます。
   例: _Before test handler – テスト前に実行
   _ Before each step handler – 各ステップ前に実行
   _After each step handler – 各ステップ後に実行
   _ After test handler – テスト後に実行

4. ドロップダウンから、フックとして実行したい共有ステップまたは共有グループを選択します。

5. After each step handler または After test handler を選択した場合、Run on オプションで実行条件を選びます。

• Always – 常に実行
• Success – ステップ／テストが成功した場合のみ実行
• Failure – ステップ／テストが失敗した場合のみ実行

6. Save をクリックしてテストを保存します。
   これで、選択したテストにフックが追加されます。

Configuration List 画面からフックを作成する {#creating-hooks-via-the-configuration-list-screen}

Configuration List 画面からは、次のフックを作成できます。

• Before test handler – テスト前に実行
• Before each step handler – 各ステップ前に実行
• After each step handler – 各ステップ後に実行
• After test handler – テスト後に実行

Configuration List からフックを作成するには:

1. メニューから Runs > Configuration List を開きます。
2. Create New をクリックします。

3. Add New Configuration 画面で Advanced をクリックします。

4. Before/After Hooks セクションで作成したいフックタイプにチェックを入れます。

• Before test handler – テスト前に実行
• Before each step handler – 各ステップ前に実行
• After each step handler – 各ステップ後に実行
• After test handler – テスト後に実行

5. ドロップダウンから、フックとして実行したい共有ステップまたは共有グループを選択します。
6. After each step handler または After test handler を選択した場合、Run on で実行条件を選びます。

• Always – 常に実行
• Success – ステップ／テストが成功した場合のみ実行
• Failure – ステップ／テストが失敗した場合のみ実行

7. Add をクリックします。
   これで、作成したフック構成が関連テストで利用可能になります。

Default Configuration 設定からフックを作成する {#creating-hooks-via-the-default-configuration-setting}

Default Configuration からフックを作成するには:

1. テストの Default Configuration 設定で Edit ボタンをクリックします。

2. 新しい構成を作成するには、ドロップダウン内の新規作成オプションを選びます。このオプションは画面上で「カスタム」（新規作成）の項目として表示されます。

Change Default Configuration ダイアログが表示されます。

3. Before/After Hooks セクションで作成したいフックタイプにチェックを入れます。

• Before test handler – テスト前に実行
• Before each step handler – 各ステップ前に実行
• After each step handler – 各ステップ後に実行
• After test handler – テスト後に実行

4. ドロップダウンから、フックとして実行したい共有ステップまたは共有グループを選択します。
5. After each step handler または After test handler を選択した場合、Run on で次のいずれかを選びます。

• Always – 常に実行
• Success – ステップ／テストが成功した場合のみ実行
• Failure – ステップ／テストが失敗した場合のみ実行

6. Change をクリックして保存します。
   これで、そのテストは新しいデフォルト構成（フック設定を含む）を使用するようになります。

Test Configuration Hooks の実行パラメーター {#test-configuration-hooks-run-parameters}

一部の Test Configuration Hooks には、テスト実行時の情報を取得するための追加パラメーターが用意されています。これらはステップ／テスト側から参照できるため、カスタムステップ内でログ出力やカスタム検証に利用できます。

• After each step handler parameters – After each step フックで利用できるオブジェクトとパラメーター:

• _stepData

• testName – テスト名

• name – ステップ名

• _stepInternalData

• hookType – フック種別（例: afterStep）

• path – ステップの URL

• stepId – ステップ ID

• projectId – プロジェクト ID

• branch – ブランチ名

• testId – テスト ID

• testResultId – テスト結果 ID

• type – ステップ種別（例: action-code-step）

• failureReason – 失敗理由（失敗時）

• errorType – エラータイプ（エラーがある場合）

• After test handler parameters – After test フックで利用できるオブジェクトとパラメーター:

• _stepData

• testName – テスト名

• _stepInternalData

• hookType – フック種別（例: afterTest）

• projectId – プロジェクト ID

• branch – ブランチ名

• testId – テスト ID

• testResultId – テスト結果 ID

• failureReason – 失敗理由（失敗時）

• errorType – エラータイプ（エラーがある場合）

Config File でフックを作成する {#creating-hooks-via-the-config-file}

Config File は、テスト／テストスイートの実行に必要なパラメーターと run hooks を定義する CommonJS 形式のファイルです。バックエンドのセットアップや、単一テスト／すべてのテストの前後で実行したい処理をまとめて定義できます。Config File で設定できるフックタイプは次のとおりです。

• Before test – テスト実行前に実行
• After test – テスト実行後に実行
• Before Suite – スイート実行前に実行
• After Suite – スイート実行後に実行

Config File 経由での Before/After フック設定の詳細手順は、以下のガイドを参照してください。Config file の概要: Configuration File (Run Hooks)。フック経由で Config file パラメーターを追加する方法: 設定ファイルでの定義

フックの可視化（Hooks Visualizations）

Hooks を含むテストを実行すると、エディター上でさまざまなビジュアル表示が行われます。

Before/After each step フックの可視化 {#viewing-before-after-each-step-hooks}

Before/After each step フックが設定されているステップには、実行後にステップ上へ「Hook」ボタンが表示されます（ステップにカーソルを合わせたときに表示）。

Hook ボタンをクリックすると、そのステップに紐づいている共有ステップ／共有グループが展開され、フックとして実行されたステップが前後に表示されます。

複数のステップに対してフックをまとめて確認したい場合は、対象ステップを複数選択し、エディターツールバーの Hook ボタンをクリックします。

フックとして設定されているステップが共有グループの場合、そのステップをダブルクリックすると共有グループの中身（内部ステップ）が表示されます。

テストステップとフックステップの関係は、円と点線の矢印で示されます。これにより、どのフックがどのステップの前後に実行されたかが視覚的に分かります。

フックステップ自体は、フックアイコン付きのグレーのボックスとして表示され、通常のステップより太い枠線で区別されます。共有ステップと同様に、フックステップをダブルクリックすることで詳細を確認できます。右上の数字は、その共有ステップを利用しているテスト数を示します（フックは共有ステップとして管理されています）。

Before/After test フックの可視化 {#viewing-before-after-test-hooks}

Before/After test フックはテストごとに 1 回、テストの開始前／終了後に実行されます。実行後、最初のステップ（Setup ステップ）にカーソルを合わせると「Hook」ボタンが表示されます。

Hook ボタンをクリックすると、テスト前後に実行された共有ステップ／共有グループが Setup ステップの前後に展開されます。

テスト本体のステップと Before/After test フックの関係は、円と点線の矢印で示されます。

フックステップは、フックアイコン付きのグレーのボックスとして太い枠線で表示されます。ダブルクリックすると詳細を確認でき、右上の数字はその共有ステップを使用しているテスト数を示します。Setup ステップの右側に矢印が表示されている場合は After test フックも存在し、矢印をクリックするとテスト末尾のフック表示に切り替わります。

成功／失敗条件により実行されなかったフックの確認 {#viewing-hooks-that-did-not-run-due-to-success-failure-conditions}

フック作成時に、ステップ／グループが成功した場合のみ／失敗した場合のみ実行するように条件を設定できます。この条件により実行されなかったフックは、青いドットでマークされます。

実行されなかったフックステップには、青い「info」アイコンが付き、関連する接続矢印も青で表示されます。

マウスを info アイコンに乗せると、そのフックが実行されなかった理由（成功条件／失敗条件など）が表示されます。

フックに関連するエラーの確認 {#viewing-errors-related-to-hooks}

テスト実行後にエラーが発生した場合、そのエラーがフックステップに起因することがあります。フックステップでエラーが発生した場合、関連ステップの左側（before each step / before test のフックエラー）または右側（after each step / after test のフックエラー）に赤いドットが表示されます。

Hook ボタンをクリックすると、該当するフックステップが表示されます。

グループ内にあるフックステップのエラーでも、1 クリックで直接そのエラー箇所まで辿ることができます。
エラー箇所を直接表示するには:

1. See Error リンクをクリックします。

エラーを含む共有グループ／共有ステップが表示され、その中で問題のあるステップがハイライトされます。