API Reference


Waits a given time in milliseconds for an element to be visible in the page before performing any other commands or assertions.

If the element fails to be present and visible in the specified amount of time, the test fails. You can change this by setting abortOnFailure to false.

You can change the polling interval by defining a waitForConditionPollInterval property (in milliseconds) in as a global property in your nightwatch.json or in your external globals file.

Similarly, a default timeout can be specified as a global waitForConditionTimeout property (in milliseconds).

Parameters

Name Type description
selector string

The selector (CSS / Xpath) used to locate the element.

time=waitForConditionTimeout
Optional
number

The total number of milliseconds to wait before failing.

poll=waitForConditionPollInterval
Optional
number

The number of milliseconds to wait between checks. You can use this only if you also specify the time parameter.

abortOnFailure=abortOnAssertionFailure
Optional
boolean

By the default if the element is not found the test will fail. Set this to false if you wish for the test to continue even if the assertion fails. To set this globally you can define a property abortOnAssertionFailure in your globals.

callback
Optional
function

Optional callback function to be called when the command finishes.

message
Optional
string

Optional message to be shown in the output; the message supports two placeholders: %s for current selector and %d for the time (e.g. Element %s was not in the page for %d ms).

Usage

this.demoTest = function (browser) {
  browser.waitForElementVisible('body', 1000);
  // continue if failed
  browser.waitForElementVisible('body', 1000, false);
  // with callback
  browser.waitForElementVisible('body', 1000, function() {
    // do something while we're here
  });
  // custom Spanish message
  browser.waitForElementVisible('body', 1000, 'elemento %s no era visible en %d ms');
  // many combinations possible - the message is always the last argument
  browser.waitForElementVisible('body', 1000, false, function() {}, 'elemento %s no era visible en %d ms');
};

API Reference

<%- content['expect-api'] %>
<%- content['expect-cookie'] %> <%- content['expect-element'] %> <% for (var methodName in api['expect.element']) { var method = api['expect.element'][methodName]; %>

<%- method.display %>Suggest edits

<%- method.descr %>

<% if (method.params.length) { %>
Parameters:
<% for (var j = 0; j < method.params.length; j++) { var param = method.params[j]; %> <% } %>
Name Type description
<%- param.name %><% if (param.optional) { %>
Optional<% } %>
<%- param.types %> <%- param.descr %>
<% } %> <% if (method.example) { %>
Usage:
<%- method.example %>
<% } %>
<% } %> <%- content['expect-elements'] %> <%- content['expect-title'] %> <%- content['expect-url'] %>
<%- content['assert-api'] %>
<% for (var i = 0; i < methods.assertions.length; i++) { var method = methods.assertions[i]; %>

assert.<%- method.name %>()

<%- method.descr %>

Parameters:
<% for (var j = 0; j < method.parameters.length; j++) { var param = method.parameters[j]; %> <% } %>
Name Type description
<%- param.name %><% if (param.optional) { %>
Optional<% } %>
<%- param.type %> <%- param.descr %>
Usage:
this.demoTest = function (browser) {
  <%- method.usage %>
};
<% } %>
<%- content['page-api'] %>
<%- content['commands-api'] %> <% var sectionsData = { 'protocol.elements' : [ 'elements-headline', 'Finding Elements', [ 'The commands listed below allow lookup of individual elements and collections of elements. Element retrieval searches are performed using a provided selector, in usually a CSS selector or, less often, an Xpath selector.', 'The convenience commands, such as .waitForElementVisible() can take a default locator strategy. More info on locator strategy can be found on the WebDriver page.', 'Each element has an associated web element reference (a UUID) that uniquely identifies the element across all browsing contexts.' ] ], 'protocol.elementinteraction' : [ 'elementinteraction-headline', 'Element Interaction' ], 'protocol.elementstate' : [ 'elementstate-headline', 'Element State', 'Details on how WebDriver checks if the element is displayed are available Element Displayedness page.' ], 'protocol.elementlocation' : [ 'elementlocation-headline', 'Element Location' ], 'protocol.document' : ['document-headline', 'Document Handling'], 'protocol.sessions' : [ 'sessions-headline', 'Sessions', 'A WebDriver session represents the connection between a client and a remote WebDriver server. Read more on WebDriver page.' ], 'protocol.navigation' : [ 'navigation-headline', 'Navigation', 'The commands in this section allow navigation to new URLs and introspection of the currently loaded url.' ], 'protocol.contexts' : ['contexts-headline', 'Window Related'], 'protocol.cookies' : ['cookies-headline', 'Cookies'], 'protocol.useractions' : ['useractions-headline', 'User Actions'], 'protocol.userprompts' : ['userprompts-headline', 'User Prompts'], 'protocol.screens' : ['screens-headline', 'Screen Capture'], 'protocol.mobile' : ['mobile-headline', 'Mobile Related'], 'protocol.utilities': ['utilities-headline', 'Utilities / Debugging'], 'protocol' : '' }; for (var section in sectionsData) { %> <% if (Array.isArray(sectionsData[section][2])) { var sectionEntry = sectionsData[section][2] || []; for (var i = 0; i < sectionEntry.length; i++) {%>

<%- sectionEntry[i] %>

<% } } else if (sectionsData[section][2]) { %>

<%- sectionsData[section][2] %>

<% } %> <% if (api[section]) { %> <% for (var i = 0; i < api[section].length; i++) { var method = api[section][i]; %>

.<%- method.name %>() Suggest edits

<%- method.descr %> <% if (method.params) {%>
Parameters:
<% for (var j = 0; j < method.params.length; j++) { var param = method.params[j]; %> <% } %>
Name Type description
<%- param.name %> <% if (param.optional) { %>
Optional<% } %>
<%- param.types %> <%- param.descr %>
<% } %> <% if (method.returns) { %>
Returns
Type description
<%- method.returns.type %> <%- method.returns.descr %>
<% } %>
<% } %> <% } %> <% } %>