よくあるご質問 (FAQ)

いいえ、await Task.Delay(…) による固定時間の待機は基本的に不要であり、推奨されません。

HTML の解析完了（DOMContentLoaded）と、その後の非同期通信（Ajax / Fetch）による DOM の再描画はタイミングが異なります。Task.Delay(5000) のような固定秒数待機は、ネットワーク遅延によるテスト失敗（フレーキー化）やテスト実行時間の無駄を引き起こす原因になります。

ChronoATX の Runtime には、非同期処理をイベント・状態ドリブンで検知する 4 つのスマート待機 API が提供されています。用途に合わせて使い分けることで、高速かつ堅牢な自動テストを実現できます。

## 非同期待機の 4 つのアプローチ
### 1. ネットワークアイドル待機（Wait For Network Idle）
適用シーン: 検索・フィルタリング・ページ読み込み後、複数の非同期 API リクエストがすべて完了（500ms 以上通信が発生しない状態）するのを待つ場合。

// 企業名を入力して検索
await Web.ClickLinkAsync("依頼先");
await Web.InputByLabelAsync("企業名 / 業種 / 地域", "sell");
await Web.PressKeyAsync("Enter");

// ❌ 以前の書き方: 固定時間待機
// await Task.Delay(5000);

// ⭕ 推奨: 通信が完了した瞬間に即座に次へ進む
await Web.WaitForNetworkIdleAsync();

await Web.ClickButtonAsync("詳細を見る");

### 2. 特定 API レスポンス待機（Wait For Response）
適用シーン: 保存・サインイン・データ更新など、特定のバックエンド API（例: HTTP 200）の返却をピンポイントで正確に待つ場合。

// 方式 A: 操作後に特定の API レスポンス完了を待つ
await Web.ClickButtonAsync("サインイン");
await Web.WaitForResponseAsync("/api/auth/login", 200);

// 方式 B: レスポンスが極めて速い場合の競合（取りこぼし）を防ぐトリガー実行
await Web.RunAndWaitForResponseAsync(
    async () => await Web.ClickButtonAsync("保存する"),
    "/api/v1/products",
    expectedStatus: 200
);

### 3. ローディング消失・特定テキスト出現待機（Wait For Text / Hidden）
適用シーン: 「処理中…」スピナーやオーバーレイ遮蔽幕が消えるのを待つ、または新しいステータス文字が表示されるのを待つ場合。

// 「処理中...」やローディング遮蔽幕が消えるまで待機
await Web.ClickButtonAsync("提出する");
await Web.WaitForTextHiddenAsync("処理中...");

// 特定のステータス文字列が表示されるまで待機（デフォルト最大30秒）
await Web.WaitForTextAsync("発送待ち");

### 4. カスタム条件ポーリング待機（Wait Until）
適用シーン: 複数条件の組み合わせや、独自のビジネスロジック・DOM 状態の変化を待つ場合。

// いずれかの完了ステータスが表示されるまで最大 15 秒間ポーリング
await Web.WaitUntilAsync(async () => {
    return await Web.IsTextVisibleAsync("受領済み") || await Web.IsTextVisibleAsync("完了");
}, timeoutMs: 15000, pollIntervalMs: 200);

### ベストプラクティス（補足）
新しく出現するボタンやリンクをクリックする場合: ChronoATX の ClickButtonAsync や InputByLabelAsync 等の操作 API は、内部で対象要素が可視・操作可能になるまで自動待機（Auto-waiting） します。そのため、多くの場合、事前の待機コード自体を書かずに直接操作を記述するだけで正常に動作します。

検証（Verify）処理について: VerifyTextAsync や VerifyLabelValueAsync には 5秒間の自己修復リトライ機構 が内蔵されています。非同期更新後のアサーション直前に置いていた Task.Delay もそのまま削除可能です。

<div> や <span> などの要素をクリックする場合、対象要素に表示テキストが含まれているかどうかに応じて、以下の2つの方法があります。

1. 表示テキストが存在する <div> の場合（推奨）
await Web.ClickButtonAsync(“テキスト”) または await Web.ClickLinkAsync(“テキスト”) をそのまま使用できます。

ChronoATX のクリック API には3段階の自動フォールバック機能が内蔵されています。

A) <button> タグや role=”button” 属性を優先検索
B) <a> タグを検索
C) 最終フォールバック：該当テキストが含まれる任意の DOM 要素（<div>, <span>, <li> など）を自動特定してクリックを発火

// 例: <div class="card-btn">ホーム</div> をクリックする場合
await Web.ClickButtonAsync("ホーム");

2. テキストが存在しない <div> の場合（アイコンのみ、または CSS セレクターで指定する場合）
Web.FindAsync() と ClickAsync() を組み合わせて使用します。

// CSS セレクターで対象の div を取得してクリック
var myDiv = await Web.FindAsync("div.icon-close");
await myDiv.ClickAsync();

// 1 行で記述することも可能です
await (await Web.FindAsync("div.card-active")).ClickAsync();

3つのプラットフォーム（Web、Desktop、Mobile）すべてでスクロール機能をサポートしています。対象となるアプリケーションに応じて、以下の該当するメソッドを使用してください。

Web

// 1. 指定したコンテナ（またはページ全体）のスクロールバーを、指定した方向に指定したピクセル数だけドラッグします
await Web.DragScrollAsync(string direction, int distancePx, string? containerLabel = null);

// 2. 指定したコンテナ（またはページ全体）のスクロールバーを、指定した割合（0〜100%）の位置までドラッグします
await Web.DragScrollToPercentAsync(int percent, bool isVertical = true, string? containerLabel = null);

// 3. 指定したテキストがビューポート（表示領域）内に見えるようになるまでスクロールします（自己修復型検索スクロール）
await Web.ScrollToTextAsync(string targetText, string? containerLabel = null);

Desktop

// 1. 特定のウィンドウやコンテナコントロール（DataGridなど）のスクロールバーをドラッグします
await Desktop.DragScrollAsync(string direction, int distancePx, string? containerAutomationIdOrName = null);

// 2. UIA ScrollPattern を使用して、指定した割合までスクロールします
await Desktop.ScrollContainerToPercentAsync(int percent, bool isVertical = true, string? containerAutomationIdOrName = null);

Mobile

// 1. キャンバス/画面のスクロールバーを指定した開始・終了の割合（パーセント）でドラッグします
await Mobile.DragScrollAsync(int startPercent, int endPercent, bool isVertical = true);

はい、サポートされています。Web.PressKeyAsync メソッドの単一引数オーバーロードを使用することで、現在フォーカスが当たっている要素に対してキー操作を実行できます。

具体的には以下のように記述します。

// Enter キーを押す
await Web.PressKeyAsync("Enter");

// Tab キーを押す
await Web.PressKeyAsync("Tab");

// Escape キーを押す
await Web.PressKeyAsync("Escape");

補足：
その他にも、Backspace、ArrowDown、Space、Control+A などの Playwright 標準のキー名指定に対応しています。