From dd8a1193fca349425b1ff13cf65d8c3413b7f67c Mon Sep 17 00:00:00 2001 From: Dmitry Gozman Date: Tue, 12 Mar 2024 12:02:25 -0700 Subject: [PATCH] cherry-pick(#29909): docs: mark addLocatorHandler as experimental --- docs/src/api/class-page.md | 30 +++++++++++++---------- packages/playwright-core/types/types.d.ts | 16 ++++++------ 2 files changed, 26 insertions(+), 20 deletions(-) diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md index c0cd3d0bea..9fc0ac7638 100644 --- a/docs/src/api/class-page.md +++ b/docs/src/api/class-page.md @@ -3146,7 +3146,11 @@ return value resolves to `[]`. ## async method: Page.addLocatorHandler * since: v1.42 -When testing a web page, sometimes unexpected overlays like a coookie consent dialog appear and block actions you want to automate, e.g. clicking a button. These overlays don't always show up in the same way or at the same time, making them tricky to handle in automated tests. +:::warning Experimental +This method is experimental and its behavior may change in the upcoming releases. +::: + +When testing a web page, sometimes unexpected overlays like a "Sign up" dialog appear and block actions you want to automate, e.g. clicking a button. These overlays don't always show up in the same way or at the same time, making them tricky to handle in automated tests. This method lets you set up a special function, called a handler, that activates when it detects that overlay is visible. The handler's job is to remove the overlay, allowing your test to continue as if the overlay wasn't there. @@ -3168,12 +3172,12 @@ Another example is a series of mouse actions, where [`method: Mouse.move`] is fo **Usage** -An example that closes a cookie consent dialog when it appears: +An example that closes a "Sign up to the newsletter" dialog when it appears: ```js // Setup the handler. -await page.addLocatorHandler(page.getByRole('button', { name: 'Accept all cookies' }), async () => { - await page.getByRole('button', { name: 'Reject all cookies' }).click(); +await page.addLocatorHandler(page.getByText('Sign up to the newsletter'), async () => { + await page.getByRole('button', { name: 'No thanks' }).click(); }); // Write the test as usual. @@ -3183,8 +3187,8 @@ await page.getByRole('button', { name: 'Start here' }).click(); ```java // Setup the handler. -page.addLocatorHandler(page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Accept all cookies")), () => { - page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Reject all cookies")).click(); +page.addLocatorHandler(page.getByText("Sign up to the newsletter"), () => { + page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("No thanks")).click(); }); // Write the test as usual. @@ -3195,8 +3199,8 @@ page.getByRole("button", Page.GetByRoleOptions().setName("Start here")).click(); ```python sync # Setup the handler. def handler(): - page.get_by_role("button", name="Reject all cookies").click() -page.add_locator_handler(page.get_by_role("button", name="Accept all cookies"), handler) + page.get_by_role("button", name="No thanks").click() +page.add_locator_handler(page.get_by_text("Sign up to the newsletter"), handler) # Write the test as usual. page.goto("https://example.com") @@ -3206,8 +3210,8 @@ page.get_by_role("button", name="Start here").click() ```python async # Setup the handler. def handler(): - await page.get_by_role("button", name="Reject all cookies").click() -await page.add_locator_handler(page.get_by_role("button", name="Accept all cookies"), handler) + await page.get_by_role("button", name="No thanks").click() +await page.add_locator_handler(page.get_by_text("Sign up to the newsletter"), handler) # Write the test as usual. await page.goto("https://example.com") @@ -3216,8 +3220,8 @@ await page.get_by_role("button", name="Start here").click() ```csharp // Setup the handler. -await page.AddLocatorHandlerAsync(page.GetByRole(AriaRole.Button, new() { Name = "Accept all cookies" }), async () => { - await page.GetByRole(AriaRole.Button, new() { Name = "Reject all cookies" }).ClickAsync(); +await page.AddLocatorHandlerAsync(page.GetByText("Sign up to the newsletter"), async () => { + await page.GetByRole(AriaRole.Button, new() { Name = "No thanks" }).ClickAsync(); }); // Write the test as usual. @@ -3230,7 +3234,7 @@ An example that skips the "Confirm your security details" page when it is shown: ```js // Setup the handler. await page.addLocatorHandler(page.getByText('Confirm your security details'), async () => { - await page.getByRole('button', 'Remind me later').click(); + await page.getByRole('button', { name: 'Remind me later' }).click(); }); // Write the test as usual. diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts index e8f1bb9c20..8b39e75561 100644 --- a/packages/playwright-core/types/types.d.ts +++ b/packages/playwright-core/types/types.d.ts @@ -1781,9 +1781,11 @@ export interface Page { prependListener(event: 'worker', listener: (worker: Worker) => void): this; /** - * When testing a web page, sometimes unexpected overlays like a coookie consent dialog appear and block actions you - * want to automate, e.g. clicking a button. These overlays don't always show up in the same way or at the same time, - * making them tricky to handle in automated tests. + * **NOTE** This method is experimental and its behavior may change in the upcoming releases. + * + * When testing a web page, sometimes unexpected overlays like a "Sign up" dialog appear and block actions you want to + * automate, e.g. clicking a button. These overlays don't always show up in the same way or at the same time, making + * them tricky to handle in automated tests. * * This method lets you set up a special function, called a handler, that activates when it detects that overlay is * visible. The handler's job is to remove the overlay, allowing your test to continue as if the overlay wasn't there. @@ -1817,12 +1819,12 @@ export interface Page { * * **Usage** * - * An example that closes a cookie consent dialog when it appears: + * An example that closes a "Sign up to the newsletter" dialog when it appears: * * ```js * // Setup the handler. - * await page.addLocatorHandler(page.getByRole('button', { name: 'Accept all cookies' }), async () => { - * await page.getByRole('button', { name: 'Reject all cookies' }).click(); + * await page.addLocatorHandler(page.getByText('Sign up to the newsletter'), async () => { + * await page.getByRole('button', { name: 'No thanks' }).click(); * }); * * // Write the test as usual. @@ -1835,7 +1837,7 @@ export interface Page { * ```js * // Setup the handler. * await page.addLocatorHandler(page.getByText('Confirm your security details'), async () => { - * await page.getByRole('button', 'Remind me later').click(); + * await page.getByRole('button', { name: 'Remind me later' }).click(); * }); * * // Write the test as usual.