[Feature]: waitForOneOf(Locator[], timeout: number = <global.timeout>): Locator, throws

[subpardaemon]

🚀 Feature Request

A new method that takes an array of Locators and an optional timeout, and waitFor()s for each of them. Using a Promise.any, it would throw only if none of the Locators appear (or are present) or are ambigious. If any of the waitFor()s resolve successfully first, they become the "winner".

Example

Example of not knowing what will "greet" us:

const oAuthLocator:Locator = page.locator('div.oauth_form');
const welcomeLocator = page.getByRole('heading', 'Welcome sailor!');
const timeoutLocator = page.getByRole('heading', 'Your session timed out');
const eventualLocator:Locator = page.waitForOneOf([
  oAuthLocator,
  welcomeLocator,
  timeoutLocator
]);
if (eventualLocator === oAuthLocator) {
  // ...take the OAuth path
} else if (eventualLocator === timeoutLocator) {
  // ...re-login
}
// otherwise all is well, let's proceed

Example of different implementations on different environments:

const dialogTitle:string = 'Add user';
const eventualLocator:Locator = page.waitForOneOf([
  page.locator(`.ui-dialog .ui-title:has-text("${dialogTitle}")`),
  page.getByRole('header', { name: dialogTitle })
]);
await expect(eventualLocator).toBeVisible();

Motivation

There are a lot of occasions where, depending on the tested systems' state, we might have to be waiting on for different locators and choose a path depending on which one won out. Other times, if a tested site is under heavy development, the same thing (like a modal's title) might look different in development, beta and production, and having a method like this can alleviate the pain that come come from situations like that.

[dgozman]

@subpardaemon Perhaps you are looking for locator.or()? It allows you to construct "a or b or c" locator and then wait for it if needed.

[subpardaemon]

@subpardaemon Perhaps you are looking for locator.or()? It allows you to construct "a or b or c" locator and then wait for it if needed.

are they chainable? if so, then yes, i'm probably looking for that... (how did i miss that?!)

[subpardaemon]

i mean chainable as in i can have more than 2, ideally, N alternative locators.

[dgozman]

i mean chainable as in i can have more than 2, ideally, N alternative locators.

Yes, you can call .or() as many times as you'd like. Let me know whether it works for you.

[dgozman]

It seems like the issue has been resolved. If you still encounter problems, please file a new issue with a repro and link to this one.