From abde650398d9c51421790780590625b628e3347b Mon Sep 17 00:00:00 2001 From: Andrey Lushnikov Date: Wed, 20 Sep 2023 13:14:19 -0700 Subject: [PATCH] docs: clarify Locator.or element matching (#27208) Fixes https://github.com/microsoft/playwright/issues/27169 --------- Signed-off-by: Andrey Lushnikov Co-authored-by: Dmitry Gozman --- docs/src/locators.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/src/locators.md b/docs/src/locators.md index 62101bddeb..0395ee18ba 100644 --- a/docs/src/locators.md +++ b/docs/src/locators.md @@ -1165,10 +1165,15 @@ var button = page.GetByRole(AriaRole.Button).And(page.GetByTitle("Subscribe")); ### Matching one of the two alternative locators -If you'd like to target one of the two or more elements, and you don't know which one it will be, use [`method: Locator.or`] to create a locator that matches any of the alternatives. +If you'd like to target one of the two or more elements, and you don't know which one it will be, use [`method: Locator.or`] to create a locator that matches all of the alternatives. For example, consider a scenario where you'd like to click on a "New email" button, but sometimes a security settings dialog shows up instead. In this case, you can wait for either a "New email" button, or a dialog and act accordingly. +:::note +If both "New email" button and security dialog appear on screen, the "or" locator will match both of them, +possibly throwing the ["strict mode violation" error](#strictness). +::: + ```js const newEmail = page.getByRole('button', { name: 'New' }); const dialog = page.getByText('Confirm security settings');