Assertions and Test subjects

Suitest lets you inspect different objects inside the application and provides flexible ways to create assertions about the object's properties. This is done with the use of different test subjects combined with chain modifiers.

List of assertions and test subjects:

application

application() defines an Application subject. Needs to be combined with hasExited.

/**
 * @returns {ChainablePromise.<void|boolean>}
 */
async function application() {}

// Check if application has exited
const ApplicationHasExited = await suitest.application().hasExited();

cookie() defines a Cookie subject.

/**
 * @param {string} name - cookie name
 * @returns {ChainablePromise.<void|boolean|string>}
 */
async function cookie(name) {}

const cookieValue = await suitest.cookie('cookieName');

With the extensive features of our Lite solution on some of the platforms, you can validate more details of cookies as well as check the 3rd party cookies. See more information.

element

element() defines a View element subject.

The element apiId can be found in the element repository.

/**
 * @param {string} apiId - Api ID of the element from Element repository
 */
async function element(apiId) {}

/**
 * @param {string} [css] - CSS selector, e.g. ”#elementID > .child-element”
 * @param {string} [xpath] - XPath selector. Note that not all platforms support XPath
 * @param {number} [index] - which element should be taken when more then one match found
 * @param {string} [attributes] - select element by it's attributes
 * @param {string} [text] - select element by inner text
 * @param {string} [position] - select element by it's position
 * @param {string} [size] - select element by it's size
 * @param {string} [color] - select element by color
 * @param {boolean} [video] - select video element
 * @returns {ChainablePromise.<void|boolean|Object>}
 */
async function element({css, xpath, index, attributes, text, position, size, color, video}) {}

// Look up element by API ID in Element repository
const elementProps = await suitest.element('ElementApiID');

// Look up element by complex selector. All keys are optional, but at least one must exist
const elementProps = await suitest.element({
    css: 'css selector',
    xpath: 'xpath selector',
    index: 1,
}).exists();

// registering a handle
const menuItemHandle = await suitest.element({
    css: '.menu-item'
}).handle();

// using the handle
await suitest.element({handle:menuItemHandle}).exists();

image

image() defines an image taken from a screenshot using image capture to be compared with a reference image as a subject. Be aware that images are compared in grayscale. Can be used with the following chain modifiers:

/**
 * Define image subject
 * @param {ImageData | string} - for more info see ImageData below
 * @returns {ImageChain}
 */

async function image(ImageData);

// Example of an assertion on image:
//  - displayed anywhere on a screen
//  - with a reference image stored inside the image repository

await suitest.assert.image('mylogo').visible().timeout(5000);

// Example of an assertion on image:
//  - displayed in the middle 20% of the screen
//  - with a reference image stored on a URL
//  - with low accuracy due to differences in colors caused by using mobile phone as image capture device

await suitest.assert.image({
    url: 'http://myserver.com/myimage.png'
}).inRegion([40, 40, 20, 20]).visible().timeout(5000);

ImageData

Image assertion can compare images on the screen with reference images stored on several different locations (only one can be used at the time):

  • inside the image repository - use apiId property (type string) or insert the value instead of the ImageData object
  • inside the network - use url property (type string)
  • on a local machine - use filepath property (type string)

Examples above.

jsExpression

jsExpression() defines a JavaScript expression subject.

INFO: The assertion is called every 500 ms.

/**
 * @param {string|Function} expression - source to be executed on device
 * @returns {ChainablePromise.<void|boolean|string>}
 */
async function jsExpression(expression) {}

// Parameter passed as string
const evaluationResult = await suitest.jsExpression('1+2');

// Parameter passed as JS function. Executed on device in a global scope
const evaluationResult = await suitest.jsExpression(function () {return 1 + 2;});

location

location() defines a Current location subject.

/**
 * @returns {ChainablePromise.<void|boolean|string>}
 */
async function location() {}

const currentLocation = await suitest.location();

networkRequest

networkRequest() defines a Network request subject. Used in conjunction with .wasMade(), .willBeMade(), requestMatches() and responseMatches chain modifiers.

Suitest does not allow to assert on a body of a network request/response bigger than 20 KB.

/**
 * @returns {ChainablePromise.<void|boolean>}
 */
async function networkRequest(target, req, res, countPrevious) {}

// Find POST to http://suite.st with response status 200 only in new logs
const requestWillBeMade = await suitest.networkRequest()
    .contains('http://file.suite.st')
    .requestMatches(suitest.NETWORK_PROP.METHOD, suitest.NETWORK_METHOD.POST)
    .responseMatches(suitest.NETWORK_PROP.STATUS, 200)
    .willBeMade();

ocr

ocr defines a text read from the screen using image capture. Can be used with .lang() chain modifier.

/**
 * Define ocr subject (text read by image capture method)
 * @param {ocrObjects[]} - for more info see ocrObjects below
 * @returns {ChainablePromise.<void|boolean|string[]>} - assert.ocr() returns boolean while ocr() returns void|string[] with read text
 */

async function ocr(ocrObjects) {}

// Example of an assertion on:
//
//  Object 1: an application name
//  - displayed as a single line of dark color text
//  - in top left corner between 10 and 20 % of the screen both from top and left
//
//  Object 2: a settings menu
//  - displayed as a single word
//  - in top right corner, region 15 % from the top and right of the screen
//  - where the text contains ':' character that is supposed to be avoided in the comparison (blacklisted)

await suitest.assert.ocr([{
    val: 'my app name',
    type: suitest.COMP.EQUAL,
    readAs: suitest.OCR_READ_AS.LINE,
    color: suitest.OCR_COLOR.DARK,
    region: [10, 10, 20, 20],//left, top, width, height
},{
    val: 'Settings',
    type: suitest.COMP.EQUAL,
    readAs: suitest.OCR_READ_AS.WORD,
    blacklist: ':',
    region: [0, 0, 25, 25],
}]);

ocrObjects

OCR can read multiple texts from the screen at the same time. Each of them is defined by an object having several properties.

  1. val - a string value that is compared with text read from the screen

  2. type (optional) - type of comparison between reference val value and the text read from the screen. The following comparisons are available:

    Comparator (suitest.COMP.*) constant
    equals (default value) EQUAL
    does not equal NOT_EQUAL
    contains CONTAIN
    does not contain NOT_CONTAIN
    starts with START
    does not start with NOT_START
    ends with END
    does not end with NOT_END

  3. region (optional) - area on the screen where the text is read from. Defined by 4 elements: left, top, width, height (all as values in % part of the screen, where the whole screen means 100%). If not defined, whole screen is used. For additional information see ocr assertion location section in our docs.

  4. color (optional) - the color of the text. Currently we support basic split into dark and light colors.

    Option (suitest.OCR_COLOR.*) constant
    A dark color DARK
    A light color LIGHT

  5. readAs (optional) - how the text should be read:

    Option (suitest.OCR_READ_AS.*) constant
    As a single word WORD
    As a single line LINE
    As a single block of text BLOCK
    Whole read text (default) - no value -

  6. whitelist - list of characters, defined as a string, that should only be considered for the evaluation/returned value. Useful in cases when you are interested only in certain characters.

    //example of searching for a number in the top right corner

const readWholeNumber = await sutiest.ocr({
    whitelist: '0123456789',
    region: [75, 0, 25, 25],
});

  7. blacklist - list of characters, defined as a string, that should not be considered for the evaluation/returned value. May be useful for example when some character is wrongly identified, in order to remove it from the evaluation.

    //example of searching for a text excluding the special characters

const readText = await sutiest.ocr({
    blacklist: '.:,;()',
    region: [75, 0, 25, 25],
});

  8. align - if the image capture device is not aligned with the screen. Defined as boolean.

position

position() defines the position subject, takes coordinates as x and y axis for position on subject.

/**
 * Define position subject
 * @param {number} x - horizontal position
 * @param {number} y - vertical position
 * @returns {ChainablePromise.<void|boolean>}
 */
async function position(x, y) {}

// Click on position
await suitest.position(100, 200)
    .click();

relativePosition

  • LG webOS

relativePosition() defines the position subject, takes coordinates as x and y axis for position on subject with current position of the cursor as the base. If the cursor is our of the reach, middle of the screen is used.

/**
 * Define relative position
 * @param {number} x - horizontal position
 * @param {number} y - vertical position
 * @returns {ChainablePromise.<void|boolean>}
 */
async function relativePosition(x, y) {}

// Click on position relative to the current cursor location
await suitest.relativePosition(100, 200).click();

runTest

runTest() runs a test that is defined and saved inside of the normal Suitest Test editor. Test is ran based on test ID. The test ID can be found inside the Test editor.

Beware of the version change list

By default, the unapplied changes are not included. If you want to use it, please use --include-changelist option in your execution script.

// Run test once
await suitest.assert.runTest('test-id');

// Run test exactly 5x
await suitest.assert.runTest('test-id').repeat(5);

// Run test until ... max 5x
await suitest.assert.runTest('test-id').until(
    suitest.location.equals('https://example.com')
).repeat(5);

// Run test only if ...
if (suitest.location.equals('https://example.com')) {
    await suitest.assert.runTest('test-id');
}

video

video() defines a Video subject.

/**
 * Look up video element
 * @returns {ChainablePromise.<void|boolean|Object>}
 */
async function video() {}

// Look up video element
const elementProps = await suitest.video();

window

window() defines the current window subject, needs to be combined with chain methods and test operation browser commands.

// Current browser window
async function window() {}

//for example - refresh the current browser window
await suitest.window().refresh();