In any asynchronous testing environment, you need to wait for things to happen in order to build robust tests, and measure the quality of components that take time to change state.

Element comes with a deep set of helpers to handle waiting for elements to appear, become enabled, or change state in other ways.

In most cases you don't want to wait for every element to appear before interacting with it, because it wouldn't make sense to interact with an invisble element. Flood Element supports automatic waiting since version 1.2, using the waitUntil: 'visible' option in Test Settings

Condition

A Condition represents a predicate which can be used to wait for an ElementHandle. They are generally created by using Until's helper methods.

Until

Until contains a set of useful methods to support waiting for specific state changes on a page. Under the hood, each state change is evaluated using reactive methods of the browser (requestAnimationFrame and change observers), instead of timers as used in most other testing tools. This means that state changes are detected as they happen, instead of polling the page continuously to check if they happened. This approach greatly improves performance.

Conditions represent predicates used to wait for something to become true, such as waiting for elements to become active, visible, invisible or disabled on the page.

You typically use these to control the flow of you test.

Methods

Until.ableToSwitchToFrame(frame)

Creates a condition that will wait until the input driver is able to switch to the designated frame.

The target frame may be specified as:

• string name of the frame to wait for matching the frame's name or id attribute.
• locator which may be used to first locate a FRAME or IFRAME on the current page before attempting to switch to it.

Example:

step('Switch frame', async browser => {

await browser.wait(Until.ableToSwitchToFrame('frame1'))

...

})

Parameters

• frame Locatable
• returns: Condition

Until.alertIsPresent()

Creates a condition that waits for an alert to be opened. Upon success, the returned promise will be fulfilled with the handle for the opened alert.

Example:

step("Handle alert", async (browser) => {

let dialog = await browser.wait(Until.alertIsPresent());

await dialog.accept();

});

Parameters

• returns: Condition

Until.elementIsDisabled(selectorOrLocator)

Creates a condition that will wait for the given element to be disabled

Example:

step("Element state", async (browser) => {

let btnLocator = By.css("button.submit");

await browser.wait(Until.elementIsDisabled(btnLocator));

let element = await browser.findElement(btnLocator);

// element disabled attribute should be true

});

Parameters

• selectorOrLocator NullableLocatable A Locatable to use to find the element.
• returns: Condition

Until.elementIsEnabled(selectorOrLocator)

Creates a condition that will wait for the given element to be enabled

Parameters

• selectorOrLocator NullableLocatable A Locatable to use to find the element.
• returns: Condition

Until.elementIsNotSelected(selectorOrLocator)

Creates a condition that will wait for the given element to be in the DOM, yet not visible to the user

Parameters

• selectorOrLocator NullableLocatable A Locatable to use to find the element.
• returns: Condition

Until.elementIsSelected(selectorOrLocator)

Creates a condition that will wait for the given element to be selected.

Parameters

• selectorOrLocator NullableLocatable A Locatable to use to find the element.
• returns: Condition

Until.elementIsNotVisible(selectorOrLocator)

Creates a condition that will wait for the given element to become invisible.

Example:

step("Step 1", async (browser) => {

await browser.click(By.css(".hide-panel"));

await browser.wait(Until.elementIsNotVisible(By.id("btn")));

});

Parameters

• selectorOrLocator NullableLocatable A Locatable to use to find the element.
• returns: Condition

Until.elementIsVisible(selectorOrLocator)

Creates a condition that will wait for the given element to become visible.

Example:

step("Step 1", async (browser) => {

await browser.wait(Until.elementIsVisible(By.partialLinkText("Start")));

});

Parameters

• selectorOrLocator NullableLocatable A Locatable to use to find the element.
• returns: Condition

Until.elementLocated(selectorOrLocator)

Creates a condition which will wait until the element is located on the page.

Parameters

• selectorOrLocator NullableLocatable
• returns: Condition

Until.elementsLocated(selectorOrLocator, desiredCount)

Creates a condition that will wait until at least the desired number of elements are found.

Parameters

• selectorOrLocator NullableLocatable
• desiredCount number (Optional, default: 1)
• returns: Condition

Until.elementTextContains(selectorOrLocator, text)

Creates a condition which will wait until the element's text content contains the target text.

Parameters

• selectorOrLocator NullableLocatable
• text string
• returns: Condition

Until.elementTextDoesNotContain(selectorOrLocator, text)

Creates a condition which will wait until the element's text content no longer contains the target text.

Parameters

• selectorOrLocator NullableLocatable
• text string
• returns: Condition

Until.elementTextIs(selectorOrLocator, text)

Creates a condition which will wait until the element's text exactly matches the target text, excluding leading and trailing whitespace.

Parameters

• selectorOrLocator NullableLocatable
• text string
• returns: Condition

Until.elementTextIsNot(selectorOrLocator, text)

Creates a condition which will wait until the element's text becomes different from the target text, excluding leading and trailing whitespace.

Parameters

• selectorOrLocator NullableLocatable
• text string
• returns: Condition

Until.elementTextMatches(selectorOrLocator, regex)

Creates a condition which will wait until the element's text matches the target Regular Expression.

Parameters

• selectorOrLocator NullableLocatable
• regex RegExp
• returns: Condition

Until.elementTextDoesNotMatch(selectorOrLocator, regex)

Creates a condition which will wait until the element's text no longer matches the target Regular Expression.

Parameters

• selectorOrLocator NullableLocatable
• regex RegExp
• returns: Condition

Until.titleContains(title)

Creates a condition which waits until the page title contains the expected text.

Parameters

• title string
• returns: Condition

Until.titleDoesNotContain(title)

Creates a condition which waits until the page title no longer contains the expected text.

Parameters

• title string
• returns: Condition

Until.titleIs(title)

Creates a condition which waits until the page title exactly matches the expected text.

Parameters

• title string
• returns: Condition

Until.titleIsNot(title)

Creates a condition which waits until the page title does not match the expected text.

Parameters

• title string
• returns: Condition

Until.titleMatches(regex)

Creates a condition which waits until the page title matches the title RegExp.

Parameters

• title RegExp
• returns: Condition

Until.titleDoesNotMatch(regex)

Creates a condition which waits until the page title no longer matches the title RegExp.

Parameters

• title RegExp
• returns: Condition

Until.urlContains(url)

Creates a condition which waits until the page URL contains the expected path.

Parameters

• url string
• returns: Condition

Until.urlDoesNotContain(url)

Creates a condition which waits until the page URL does not contain the expected path.

Parameters

• url string
• returns: Condition

Until.urlIs(url)

Creates a condition which waits until the page URL exactly matches the expected URL.

Parameters

• url string
• returns: Condition

Until.urlIsNot(url)

Creates a condition which waits until the page URL does not exactly matches the expected URL.

Parameters

• url string
• returns: Condition

Until.urlMatches(regex)

Creates a condition which waits until the page URL matches the supplied RegExp.

Parameters

• url RegExp
• returns: Condition

Until.urlDoesNotMatch(regex)

Creates a condition which waits until the page URL does not match the supplied RegExp.

Parameters

• url RegExp
• returns: Condition