From 562844016d91636ba7d4dd5beb158f250bbe2f59 Mon Sep 17 00:00:00 2001 From: Chromie Date: Fri, 23 Jan 2026 17:28:59 -0800 Subject: [PATCH 1/3] docs: add page.waitForSelector() documentation (#1554) # why missing docs for new `page.waitForSelector()` # what changed Add API reference documentation for page.waitForSelector() method including: - Method signature and parameter descriptions - All options: state, timeout, pierceShadow - Code examples for various use cases # test plan --- ## Summary by cubic Adds API reference for page.waitForSelector(), with options, defaults, and practical examples. Addresses STG-1125 by filling the missing docs. - New Features - Method signature and parameters: state, timeout, pierceShadow. - Notes on defaults: state "visible", 30s timeout, shadow DOM piercing; supports iframe hop (>>). - Examples for visible/hidden/detached, iframe, shadow DOM, XPath, and custom timeouts. Written for commit 1e90c4a3502816c1a2b506c5d836405862edbf20. Summary will update on new commits. Co-authored-by: Chromie Bot Co-authored-by: Claude Opus 4.5 --- packages/docs/v3/references/page.mdx | 74 ++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/packages/docs/v3/references/page.mdx b/packages/docs/v3/references/page.mdx index 856360728..d08be28c4 100644 --- a/packages/docs/v3/references/page.mdx +++ b/packages/docs/v3/references/page.mdx @@ -564,6 +564,45 @@ await page.waitForLoadState(state: LoadState, timeoutMs?: number): Promise **Default:** `15000` +### waitForSelector() + +Wait for an element matching the selector to reach a specific state in the DOM. Uses MutationObserver for efficiency and pierces shadow DOM by default. + +```typescript +await page.waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise +``` + + + CSS selector or XPath to wait for. Supports iframe hop notation with `>>` (e.g., `"iframe#checkout >> .submit-btn"`). + + + + The element state to wait for. + + **Options:** + - `"attached"` - Wait for element to be present in DOM (even if hidden) + - `"detached"` - Wait for element to be removed from DOM + - `"visible"` - Wait for element to be visible (default) + - `"hidden"` - Wait for element to become hidden + + **Default:** `"visible"` + + + + Maximum time to wait in milliseconds. + + **Default:** `30000` + + + + Whether to search inside shadow DOM boundaries (both open and closed). + + **Default:** `true` + + +**Returns:** `true` when the condition is met. + +**Throws:** Error if timeout is reached before the condition is met. ## Events @@ -743,6 +782,41 @@ await page.goto("https://spa-app.com", { await page.waitForLoadState("domcontentloaded"); ``` + + + +```typescript +// Wait for element to be visible (default) +await page.waitForSelector("#submit-btn"); + +// Wait for element to appear with custom timeout +await page.waitForSelector(".loading-spinner", { + state: "visible", + timeout: 10000 +}); + +// Wait for element to be removed from DOM +await page.waitForSelector(".loading-spinner", { + state: "detached" +}); + +// Wait for element to become hidden +await page.waitForSelector(".modal", { + state: "hidden" +}); + +// Wait for element inside an iframe +await page.waitForSelector("iframe#checkout >> .pay-button"); + +// Wait for element in shadow DOM (enabled by default) +await page.waitForSelector("#shadow-button", { + pierceShadow: true +}); + +// Wait for element with XPath +await page.waitForSelector("//button[@type='submit']"); +``` + From 909a02be8a28b79578f23ff38bc83be1c72f9f54 Mon Sep 17 00:00:00 2001 From: Sean McGuire Date: Fri, 23 Jan 2026 17:44:24 -0800 Subject: [PATCH 2/3] remove WaitForSelectorOptions --- packages/core/lib/v3/understudy/page.ts | 1 + packages/docs/v3/references/page.mdx | 51 ++++++++++++++++--------- packages/server/src/types/model.ts | 2 +- 3 files changed, 34 insertions(+), 20 deletions(-) diff --git a/packages/core/lib/v3/understudy/page.ts b/packages/core/lib/v3/understudy/page.ts index a34d363a9..e8f636629 100644 --- a/packages/core/lib/v3/understudy/page.ts +++ b/packages/core/lib/v3/understudy/page.ts @@ -1209,6 +1209,7 @@ export class Page { * Supports iframe hop notation with '>>' (e.g., 'iframe#checkout >> .submit-btn'). * * @param selector CSS selector to wait for (supports '>>' for iframe hops) + * @param options * @param options.state Element state to wait for: 'attached' | 'detached' | 'visible' | 'hidden' (default: 'visible') * @param options.timeout Maximum time to wait in milliseconds (default: 30000) * @param options.pierceShadow Whether to search inside shadow DOM (default: true) diff --git a/packages/docs/v3/references/page.mdx b/packages/docs/v3/references/page.mdx index d08be28c4..14efcbeeb 100644 --- a/packages/docs/v3/references/page.mdx +++ b/packages/docs/v3/references/page.mdx @@ -566,38 +566,51 @@ await page.waitForLoadState(state: LoadState, timeoutMs?: number): Promise ### waitForSelector() -Wait for an element matching the selector to reach a specific state in the DOM. Uses MutationObserver for efficiency and pierces shadow DOM by default. +Wait for an element matching the selector to reach a specific state in the DOM. Uses a MutationObserver for efficiency, pierces shadow DOM by default, and supports iframe hops when needed. ```typescript -await page.waitForSelector(selector: string, options?: WaitForSelectorOptions): Promise +await page.waitForSelector( + selector: string, + options?: { + state?: "attached" | "detached" | "visible" | "hidden"; + timeout?: number; + pierceShadow?: boolean; + } +): Promise ``` - CSS selector or XPath to wait for. Supports iframe hop notation with `>>` (e.g., `"iframe#checkout >> .submit-btn"`). + CSS selector or XPath expression to wait for. Supports iframe hops (e.g., `/html/div/iframe/html/div/button`). - - The element state to wait for. + + Optional wait configuration. - **Options:** - - `"attached"` - Wait for element to be present in DOM (even if hidden) - - `"detached"` - Wait for element to be removed from DOM - - `"visible"` - Wait for element to be visible (default) - - `"hidden"` - Wait for element to become hidden + + + Element state to wait for. - **Default:** `"visible"` - + **Options:** + - `"attached"` - Element is present in DOM (even if hidden) + - `"detached"` - Element is removed from DOM + - `"visible"` - Element is visible + - `"hidden"` - Element is hidden - - Maximum time to wait in milliseconds. + **Default:** `"visible"` + - **Default:** `30000` - + + Maximum time to wait in milliseconds before timing out. + + **Default:** `30000` + - - Whether to search inside shadow DOM boundaries (both open and closed). + + Whether to search inside open and closed shadow DOM boundaries. - **Default:** `true` + **Default:** `true` + + **Returns:** `true` when the condition is met. diff --git a/packages/server/src/types/model.ts b/packages/server/src/types/model.ts index 74cc988e7..e07130afb 100644 --- a/packages/server/src/types/model.ts +++ b/packages/server/src/types/model.ts @@ -12,7 +12,7 @@ export const AISDK_PROVIDERS = [ "perplexity", "ollama", "vertex", - "bedrock" + "bedrock", ] as const; export type AISDKProvider = (typeof AISDK_PROVIDERS)[number]; From 7df5f4b292ad24cd410a77838afc93c3959a4971 Mon Sep 17 00:00:00 2001 From: Sean McGuire Date: Fri, 23 Jan 2026 17:45:43 -0800 Subject: [PATCH 3/3] update example snippet --- packages/docs/v3/references/page.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs/v3/references/page.mdx b/packages/docs/v3/references/page.mdx index 14efcbeeb..0ef874657 100644 --- a/packages/docs/v3/references/page.mdx +++ b/packages/docs/v3/references/page.mdx @@ -827,7 +827,7 @@ await page.waitForSelector("#shadow-button", { }); // Wait for element with XPath -await page.waitForSelector("//button[@type='submit']"); +await page.waitForSelector("/html/div/button"); ```