Promise Chains - Testium

`testium-driver-wd`

General Notes

browser is just a wd session with some additional helpers. Which means that all methods in the wd docs are expected to work. This page omits many things that are already part of wd.

All methods return a Promise that can be chained. So whenever it says “returns a string”, read “returns the promise of a string”. The wd docs have more examples for what that means. This also implies that the returned promises have to be passed to the test runner (e.g. mocha), either by using async functions and await or by returning the promise. Since all return values are promises, the examples assume that assert refers to a library that is promise-aware like assertive-as-promised.

Another thing to keep in mind is to always use browser.loadPage (or browser.navigateTo) and never browser.get to load a page. The reason is that browser.loadPage will properly capture status code and headers whereas browser.get will not. This is different from using wd directly because capturing status codes is not a native wd feature.

`browser.capabilities`

An object describing the WebDriver capabilities that the current browser supports.

This is not a promise but a plain JavaScript object.

Example: Capability Check

before(function requiresAlerts() {
  // Skip the current test suite unless the browser can work with alerts
  if (!browser.capabilities.handlesAlerts) this.skip();
});

`browser.getConsoleLogs(logLevel='all')`

Returns all log events with logLevel (log/warn/error/debug) since the last time this method was called. Warning: Each browser implements this differently against the WebDriver spec.

var errorLogs = browser.getConsoleLogs('error');

`browser.getScreenshot()`

Returns screenshot as a base64 encoded PNG.

`browser.assertImgLoaded(selector)`

Not implemented yet.

Asserts that the image element at selector has both loaded and been decoded successfully.

browser.assertImgLoaded('.logo');

`browser.getHeader(name)`

Returns the value of the response header with the provided name. Header names should be provided in lowercase.

`browser.getHeaders()`

Returns all response headers for the current page as a plain object. All keys in the object will be lowercase, e.g. content-type instead of Content-Type.

`browser.getPath()`

Returns the current path of the page, e.g. /some/route.

`browser.getUrl()`

Returns the current absolute url of the page, e.g. http://localhost:1234/some/route.

assert.match(/^https:/, browser.getUrl());

`browser.getStatusCode()`

Returns the response status code for the current page.

`browser.assertStatusCode(statusCode)` (deprecated)

Asserts that the most recent response status code is statusCode. Note that you get this same functionality in browser.loadPage now.

// old
browser
  .navigateTo('/products');
  .assertStatusCode(200);

browser
  .navigateTo('/page-that-redirect');
  .assertStatusCode(302);

// new
browser
  .loadPage('/products'); // implies assertStatusCode(200)

browser
  .loadPage('/page-that-redirects', { expectedStatusCode: 302 });

This is especially useful as a method to short circuit test failures.

describe('products', function() {
  before(browser.beforeHook());
  before(() =>
    browser.loadPage('/products')
  );

  it('works 1', /* ... */);
  it('works 2', /* ... */);
  it('works 3', /* ... */);
});

`browser.loadPage(url, options)`

Navigates the browser to the specificed relative or absolute url. The following options are supported:

query: An object with additional query parameters.
headers: An object with headers to inject.
expectedStatusCode: Defaults to 200, can be one of:
- An integer status code that the response should equal
- A RegExp that the status code (as a string) should match
- A Function which takes the status code and returns true or false if it is acceptable

`browser.navigateTo(url, options)` (deprecated)

This does the same thing as browser.loadPage(), but:

Doesn’t support the expectedStatusCode option
Doesn’t default to asserting status code 200

Example: Relative URL with Headers

If relative, the root is assumed to be http://127.0.0.1:#{app.port}, where app.port refers to the config option.

// Navigates to `http://127.0.0.1:${app.port}/products`
// passing along the `X-Custom-Header: Some Value` header.
browser.loadPage('/products', {
  headers: {
    'X-Custom-Header': 'Some-Value'
  }
});

Example: Absolute URL

If the url is absolute, any methods that depend on the proxy (getStatusCode and getHeaders) will not work. (e.g. browser.loadPage) This is a bug and will be fixed.

browser
  // Navigates to https://www.google.com/?q=testium+api
  .navigateTo('http://www.google.com', { query: { q: 'testium api'} });
  // But this will fail because the URL was absolute:
  .getStatusCode();

`browser.refresh()`

Refresh the current page.

`browser.waitForPath(path, timeout=5000)`

Waits timeout ms for the browser to be at the specified path. path can be a String, or a regular expression.

`browser.waitForUrl(url, timeout=5000)`

Waits timeout ms for the browser to be at the specified url.

`browser.waitForUrl(url, query, timeout=5000)`

Waits timeout ms for the browser to be at the specified url with query parameters per the query object. url can be a String, or a regular expression.

Using query instead of passing the query params in the url allows the test to accept any order of query parameters.

Example: Order Doesn’t Matter

browser
  .loadPage('/products?count=15&start=30')
  // This will return immediately even though the order of `count` and `start`
  // is reversed.
  .waitForUrl('/products', { start: 30, count: 15 });

Elements

`browser.clickOn(cssSelector)`

Calls clickOn() on the Element found by the given cssSelector.

browser.clickOn('.button');

`browser.moveTo(cssSelector, xoffset, yoffset)`

Move the mouse by an offset of the specificed element found by the given cssSelector. xoffset and y offset are optional.

browser.moveTo('.button');

`browser.getElement(cssSelector)`

Finds an element on the page using the cssSelector and returns an Element. If it fails to find an element matching the selector, it will reject with an error.

var button = browser.getElement('.button');
button.isDisplayed();

`browser.getElementOrNull(cssSelector)`

Finds an element on the page using the cssSelector. Returns null if the element wasn’t found.

browser.getElementOrNull('.button1,.button2')
  .then(button => assert.equal('OK', button && button.text()));

`browser.getElements(cssSelector)`

Finds all elements on the page using the cssSelector and returns an array of Elements.

`browser.waitForElementDisplayed(cssSelector, timeout=3000)`

Waits for the element at cssSelector to exist and be visible, then returns the Element. Times out after timeout ms.

`browser.waitForElementNotDisplayed(cssSelector, timeout=3000)`

Waits for the element at cssSelector to exist and not be visible, then returns the Element. Times out after timeout ms.

`browser.waitForElementExist(cssSelector, timeout=3000)`

Waits for the element at cssSelector to exist, then returns the Element. Times out after timeout ms. Visibility is not considered.

`browser.waitForElementNotExist(cssSelector, timeout=3000)`

Waits for the element at cssSelector to not exist, then returns null. Times out after timeout ms.

`browser.assertElementHasText(selector, textOrRegex)`

Asserts that the element at selector contains textOrRegex. Returns the element.

Throws exceptions if selector doesn’t match a single node, or that node does not contain the given textOrRegex.

browser.assertElementHasText('.user-name', 'someone');
// is the same as:
assert.equal('someone', browser.getElement('.user-name').text());

`browser.assertElementLacksText(selector, textOrRegex)`

Asserts that the element at selector does not contain textOrRegex. Returns the element.

Inverse of assertElementHasText.

`browser.assertElementHasValue(selector, textOrRegex)`

Asserts that the element at selector does not have the value textOrRegex. Returns the element.

Throws exceptions if selector doesn’t match a single node, or that node’s value is not textOrRegex.

browser.assertElementHasValue('.user-name', 'someone else');
// is the same as:
assert.equal('someone else', browser.getElement('.user-name').value());

`browser.assertElementLacksValue(selector, textOrRegex)`

Asserts that the element at selector does not have the value textOrRegex. Returns the element.

Inverse of assertElementHasValue.

`browser.assertElementHasAttributes(selector, attributesObject)`

Asserts that the element at selector contains attribute:value pairs specified by attributesObject. Returns the element.

Throws exceptions if selector doesn’t match a single node, or that node does not contain the given attribute:value pairs.

browser.assertElementHasAttributes('.user-name', {
  text: 'someone',
  name: 'username',
});

`browser.assertElementIsDisplayed(selector)`

Asserts that the element at selector exists and is visible. Returns the element.

browser.assertElementIsDisplayed('.user-name');
// is the same as
assert.expect(browser.getElement('.user-name').isDisplayed());

`browser.assertElementNotDisplayed(selector)`

Asserts that the element at selector is not visible. Returns the element.

Inverse of assertElementIsDisplayed.

`browser.assertElementExists(selector)`

Asserts that the element at selector exists. Returns the element.

browser.assertElementExists('.user-name');

`browser.assertElementDoesntExist(selector)`

Asserts that the element at selector doesn’t exist. Returns the element.

Inverse of assertElementExists.

`browser.assertElementsNumber(selector, number)`

Asserts that selector matches exactly number elements.

`element.click()`

Clicks on the element, e.g. clicking on a button or a dropdown.

`element.get(attribute)`

Returns the element’s specified HTML attribute, e.g. “value”, “id”, or “class”.

`element.text()`

Returns the element’s text contents.

Note that WebDriver (and therefore testium) will not return text of hidden elements.

var elementId = element.get('id');

`element.isDisplayed()`

Returns true if the element is visible.

Forms

`browser.clear(cssSelector)`

Clears the input found by the given cssSelector.

`browser.fillFields(fields)`

Convenience method for setting the value for multiple form fields at once. fields is an object that maps css selectors to values.

browser.fillFields({
  '.first-name': 'Jamie',
  '.last-name': 'Smith',
});
// Equivalent to:
browser
  .setValue('.first-name', 'Jamie')
  .setValue('.last-name', 'Smith');

`browser.setValue(cssSelector, value)`

Alias: browser.clearAndType

Sets the value of the Element with the given cssSelector to value.

browser
  .setValue('.first-name', 'John')
  .setValue('.last-name', 'Smith')
  .click('.submit');

`browser.type(cssSelector, value)`

Sends value to the input found by the given cssSelector.

`element.clear()`

Clears the input element.

`element.type(strings...)`

Sends strings... to the input element.

Page

`browser.getPageTitle()`

Returns the current page title.

`browser.getPageSource()`

Returns the current page’s html source. Using this method usually means that you are trying to test something that can be done without a browser.

assert.match(/body/, browser.getPageSource());

Note that if the browser is presenting something like an XML or JSON response, this method will return the presented HTML, not the original XML or JSON response. If you need to simply test such a response, use a simpler test that doesn’t involve a browser. For example you could use a normal HTTP client library to load a URL relative to browser.appUrl.

`browser.getPageSize()`

Returns the current window’s size as an object with height and width properties in pixels.

assert.deepEqual({ width: 800, height: 600 }, browser.getPageSize());

This can be useful for responsive UI testing when combined with browser.setPageSize. Testium defaults the page size to height: 768 and width: 1024.

`browser.setPageSize({height, width})`

Sets the current window’s size in pixels.

browser.setPageSize({ height: 400, width: 200 });
// Window has resized to a much smaller screen

Evaluate

Note that client-side functions will not have access to server-side values. Return values have to cleanly serialize as JSON, otherwise the behavior is undefined.

`browser.evaluate(code)`

Warning: Consider using the function variant below. Having code with proper syntax highlighting and linting can prevent frustrating debugging sessions.

Executes the given javascript code. It must contain a return statement in order to get a value back.

var code = 'return document.querySelector(\'.menu\').style;';
var style = browser.evaluate(code);

`browser.evaluate(args..., function(args...))`

Returns the result of the given function, invoked on the webdriver side (so you can not bind its this object or access context variables via lexical closure). If you provided args, testium will marshals them as JSON and passes them to the function in the given order.

Example: Messing With Globals

// Patching global state to influence the app's behavior.
browser.evaluate(function fakeConfigData() {
  window.myConfigBlob.magicalSetting = true;
});

Example: Passing Arguments

// This will return the current url fragment
browser.evaluate('hash', function getLocationProp(prop) {
  return window.location[prop];
});

Cookies

Cookie objects have the following general structure:

{
  "name",
  "value",
  "path" = "/",
  "domain" = currentPageDomain,
  "expiry" = endOfCurrentSession,
  "secure" = false,
}

Note that the defaults shown above are testium-specific and only applied if you use setCookieValue() or setCookieValues() (recommended)

`browser.setCookieValue(name, value)`

Sets a cookie on the current page’s domain to the value given. You can set cookies before loading your first page. Testium tells the browser to load a blank page first so that cookies can be set before loading a real page.

browser.setCookieValue('userId', '3');

`browser.setCookieValues({ [name]: value })`

Given an object mapping cookie names to values, sets multiple cookies by calling setCookieValue() the requisite number of times for you.

browser.setCookieValues({
  userId: '3',
  dismissedPopup: 'true',
});

`browser.setCookie(Cookie)`

This is the built-in wd setCookie() function, and applies none of the defaults above, and is only recommended for specific advanced uses.

`browser.setCookies([Cookie])` [DEPRECATED]

Sets all cookies in the array.

cookies = [
  { name: 'userId', value: '3' },
  { name: 'dismissedPopup', value: 'true' },
];
browser.setCookies(cookies);

This function calls setCookie(), and applies none of the useful testium defaults described above; it is now recommended that you instead use setCookieValues()

`browser.getCookie(name)`

Returns the cookie visible to the current page with name.

var userIdCookie = browser.getCookie('userId');
assert.equal('3', userIdCookie.value);

`browser.getCookies()`

Returns all cookies visible to the current page.

`browser.clearCookies()`

Deletes all cookies visible to the current page.

`browser.clearCookie(name)`

Delete a cookie by name that is visible to the current page.

Alerts & Confirms

This API allows you to interact with alert, confirm, and prompt dialogs.

Some browsers, notably phantomjs, don’t support this part of the WebDriver spec. You can guard against this by checking the Capabilities object.

describe('Alert-based tests', function() {
  before(browser.beforeHook());

  before(function requiresAlerts() {
    // Skip the current test suite unless the browser can work with alerts
    if (!browser.capabilities.handlesAlerts) this.skip();
  });

  // <insert actual test cases here>
});

`browser.getAlertText()`

Gets the text of a visible alert, prompt, or confirm dialog.

var alertText = browser.getAlertText();

`browser.acceptAlert()`

Accepts a visible alert, prompt, or confirm dialog.

browser.acceptAlert();

`browser.dismissAlert()`

Dismisses a visible alert, prompt, or confirm dialog.

browser.dismissAlert();

`browser.typeAlert(value)`

Types into a visible prompt dialog.

browser.typeAlert('');

Windows & Frames

`browser.closeWindow()`

Close the currently focused window.

browser.clickOn('#open-popup');
browser.switchToWindow('popup1');
browser.closeWindow();
browser.switchToDefaultWindow();

The name used to identify the popup can be set in the code used to create it. It’s the strWindowName in window.open(strUrl, strWindowName, [strWindowFeatures]).

`browser.switchToDefaultFrame()`

Switch focus to the default frame (i.e., the actual page).

browser.switchToFrame('some-frame');
browser.clickOn('#some-button-in-frame');
browser.switchToDefaultFrame();

`browser.switchToFrame(id)`

Switch focus to the frame with name or id id.

`browser.switchToDefaultWindow()`

Switch focus to the window that was most recently referenced by loadPage. Useful when interacting with popup windows.

browser.loadPage('/path');
browser.clickOn('#open-popup');
browser.switchToWindow('popup1');
browser.clickOn('#some-button-in-popup');
browser.closeWindow();
browser.switchToDefaultWindow();

`browser.switchToWindow(name)`

Switch focus to the window with name name.

testium-driver-wd

General Notes

browser.capabilities

Example: Capability Check

browser.getConsoleLogs(logLevel='all')

browser.getScreenshot()

browser.assertImgLoaded(selector)

Navigation

browser.getHeader(name)

browser.getHeaders()

browser.getPath()

browser.getUrl()

browser.getStatusCode()

browser.assertStatusCode(statusCode) (deprecated)

browser.loadPage(url, options)

browser.navigateTo(url, options) (deprecated)

Example: Relative URL with Headers

Example: Absolute URL

browser.refresh()

browser.waitForPath(path, timeout=5000)

browser.waitForUrl(url, timeout=5000)

browser.waitForUrl(url, query, timeout=5000)

Example: Order Doesn’t Matter

Elements

browser.clickOn(cssSelector)

browser.moveTo(cssSelector, xoffset, yoffset)

browser.getElement(cssSelector)

browser.getElementOrNull(cssSelector)

browser.getElements(cssSelector)

browser.waitForElementDisplayed(cssSelector, timeout=3000)

browser.waitForElementNotDisplayed(cssSelector, timeout=3000)

browser.waitForElementExist(cssSelector, timeout=3000)

browser.waitForElementNotExist(cssSelector, timeout=3000)

browser.assertElementHasText(selector, textOrRegex)

browser.assertElementLacksText(selector, textOrRegex)

browser.assertElementHasValue(selector, textOrRegex)

browser.assertElementLacksValue(selector, textOrRegex)

browser.assertElementHasAttributes(selector, attributesObject)

browser.assertElementIsDisplayed(selector)

browser.assertElementNotDisplayed(selector)

browser.assertElementExists(selector)

browser.assertElementDoesntExist(selector)

browser.assertElementsNumber(selector, number)

element.click()

element.get(attribute)

element.text()

element.isDisplayed()