Playwright で要素をクリックできない(TimeoutError: locator.click)
locator.click のタイムアウトは、セレクタに一致する要素が無い・要素が actionability チェックを通らない・他要素に覆われている・iframe 内にある、の 4 系統。
trace や --debug で実際の状態を確認して切り分ける。
公開: 更新:
npx playwright test bad.spec.js --reporter=line | grep -E '^ [0-9]+\) |Error:|waiting for|not enabled|intercepts pointer|passed|failed' … TimeoutError: locator.click: Timeout 2000ms exceeded. - waiting for locator('#sumbit') 2) bad.spec.js:9:1 › 原因 2: disabled のボタン ───────────────────────────────────────────────────────── TimeoutError: locator.click: Timeout 2000ms exceeded.
2026-10-02 に node:20(Node.js 20.20.2 / npm 10.8.2) で実際に打って取った出力。検証環境の詳細
要約
TimeoutError: locator.click: Timeout 30000ms exceeded. で要素をクリックできない原因は、単純な待ち時間不足よりも、セレクタが一致していない か 要素が操作可能(actionable)になっていない ことが大半である。
Playwright は click 前に visible / enabled / stable などの actionability チェックを自動で待つ。
タイムアウトは「チェックを通らない理由」を探すサインと捉える。
実行例
セレクタのタイポ・disabled のボタン・バナーが覆っているリンク・iframe 内の入力欄は、どれも 2000ms で TimeoutError になった。
エラーには waiting for locator('#sumbit') や element is not enabled、intercepts pointer events といった待っていた条件が出た。getByRole で特定し直す・バナーを先に閉じる・frameLocator 経由にする、の 3 つの解決策はいずれもテストが通り、終了コードは 0 だった。
$ npx playwright test bad.spec.js --reporter=line | grep -E '^ [0-9]+\) |Error:|waiting for|not enabled|intercepts pointer|passed|failed'
1) bad.spec.js:4:1 › 原因 1: セレクタのタイポ ──────────────────────────────────────────────────────────────
TimeoutError: locator.click: Timeout 2000ms exceeded.
- waiting for locator('#sumbit')
2) bad.spec.js:9:1 › 原因 2: disabled のボタン ─────────────────────────────────────────────────────────
TimeoutError: locator.click: Timeout 2000ms exceeded.
- waiting for locator('#pay')
2 × waiting for element to be visible, enabled and stable
- element is not enabled
2 × waiting for element to be visible, enabled and stable
- element is not enabled
4 × waiting for element to be visible, enabled and stable
- element is not enabled
3) bad.spec.js:14:1 › 原因 3: バナーが覆っている ────────────────────────────────────────────────────────────
TimeoutError: locator.click: Timeout 2000ms exceeded.
- waiting for getByRole('link', { name: '詳細' })
2 × waiting for element to be visible, enabled and stable
- <div id="banner">…</div> intercepts pointer events
2 × waiting for element to be visible, enabled and stable
- <div id="banner">…</div> intercepts pointer events
4 × waiting for element to be visible, enabled and stable
- <div id="banner">…</div> intercepts pointer events
4) bad.spec.js:19:1 › 原因 4: iframe の中の入力欄 ────────────────────────────────────────────────────────
TimeoutError: locator.fill: Timeout 2000ms exceeded.
- waiting for getByLabel('カード番号')
4 failed$ npx playwright test fixed.spec.js --reporter=list
Running 3 tests using 1 worker
✓ 1 fixed.spec.js:4:1 › 解決策 2: ロールと名前で特定する (117ms)
✓ 2 fixed.spec.js:11:1 › 解決策 3: 覆っているバナーを先に閉じる (114ms)
✓ 3 fixed.spec.js:18:1 › 解決策 4: iframe は frameLocator で (73ms)
3 passed (819ms)
$ echo $?
0— 2026-10-02 時点の出力
検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-10-02 検証(ほか 1 件)
- 検証日
- 実行環境
node:20Debian GNU/Linux 12 (bookworm)- バージョン
- Node.js 20.20.2
- npm 10.8.2
- Python 3.11.2
- Git 2.39.5
この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。
解決策
1. 失敗時点の状態を確認する
npx playwright test --debug
# CI で落ちた場合は trace を残して確認
npx playwright show-trace trace.zipエラーメッセージには「待っていた条件」(例: element is not visible)が含まれるので、まずそこを読む。
チェック内容の一覧は 公式の Auto-waiting(新しいタブで開く) にある。
2. ユーザー視点の locator に変える
// CSS セレクタより壊れにくい
await page.getByRole("button", { name: "保存" }).click();DOM 構造依存の CSS セレクタは描画の変化で壊れやすい。
ロールやラベルで特定すれば、一致しない原因の多くを排除できる。
3. 覆っている要素を先に処理する
await page.getByRole("button", { name: "同意する" }).click(); // バナーを閉じる
await page.getByRole("link", { name: "詳細" }).click();別要素が遮っている場合は、その要素を閉じる操作をテストに含めるのが正攻法である。
どうしても回避できない装飾要素なら click({ force: true }) でチェックを飛ばせるが、実ユーザーが押せない状態を隠すリスクがあるため最終手段とする。
4. iframe は frameLocator で
await page.frameLocator("#payment-frame").getByLabel("カード番号").fill("4242...");タイムアウト値自体を伸ばしたい場合は Timeouts(新しいタブで開く) の設定で調整できるが、原因を特定せずに伸ばすのは flaky テストの温床になる。
よくある原因
- 要素が存在しない。
セレクタのタイポ、描画前、条件付きレンダリングのために、DOM に要素が無い。 - actionability チェックを通らない。
display: noneやdisabledになっているか、アニメーション中で位置が安定しない。 - 他の要素が覆っている。
モーダルの背景、Cookie バナー、固定ヘッダーがクリック位置を遮る。 - 要素が iframe 内にある。
ページ直下の locator では iframe の中に届かない。