View element - test subject

The View element test subjects represents a piece of the app's UI.


In Test editor:

Check that the logo is positioned correctly
Check that the logo is positioned correctly

In the JavaScript API:

await suitest.assert.element('logo').matches([
    PROP.HEIGHT,
    PROP.IMAGE,
    PROP.LEFT,
    PROP.TOP,
    PROP.WIDTH,
]);

Every application consists of many view elements. Suitest provides a way to select a particular element through a set of identifying properties and save it to the Element repository along with a snapshot of their state.

You can then make assertions on the elements from repository (or, in case of JavaScript API, with elements selected on the fly).

Built-in element operations

Following operations are available:

  • exists - checks that element exists.

  • does not exist - checks that the element does not exist.

  • has properties - compares the current properties of the element (such as width, color, background, etc.) with the expected values.

  • matches JS - passes a reference to the view element into a user-defined JavaScript function and expects it to return the comparison result.

Validating element existence

In Test Editor:

Check that the play button exists and the pause button is missing
Check that the play button exists and the pause button is missing

In JavaScript API:

await suitest.assert.element('logo').exists();
await suitest.assert.element('login').doesNot().exist();

This operation checks for a physical existence of the element inside the application. The element may however be hidden or obscured by other elements in which case you should use the has properties operation.

Validating element properties

The has properties action can be used to test whether specific properties of the element match the expectations of the test.

In Test Editor:

Image width expected to be between 60 and 80 pixels.
Image width expected to be between 60 and 80 pixels.

In JavaScript API:

const {assert, PROP, COMP} = suitest;
// avoid having to write suitest infront of assert, prop and comp.

await assert.element('logo').matches([
    PROP.IMAGE,
    {
        name: PROP.WIDTH,
        val: 60,
        type: COMP.EQUAL_GREATER,
    },
    {
        name: PROP.WIDTH,
        val: 80,
        type: COMP.EQUAL_LESSER,
    },
]);

To compare property values following operations are available:

  • = - equal
  • != - not equal
  • - is in range (i.e. width between 50 and 100 pixels)
  • > - greater than
  • >= - greater than or equal
  • < - less than
  • <= - less than or equal
  • contains - contains expected string
  • does not contain - does not contain the expected string
  • ends with - ends with the expected string
  • does not end with - does not end with the expected string
  • starts with - starts with the expected string
  • does not start with - does not start with the expected string

Comparing properties to the element snapshot

You can compare element properties to a static value or to a value currently contained inside the element repository. Comparing against element repository has a lot of advantage, since when the application ever changes only the repository needs to be updated to make the tests work again.

The button width is compared against repository snapshot, but the text contained inside the button is expected to always be equal to "Play now". Clicking on the yellow icon would revert the comparison back to the repository version
The button width is compared against repository snapshot, but the text contained inside the button is expected to always be equal to "Play now". Clicking on the yellow icon would revert the comparison back to the repository version

The same in JavaScript API:

await suitest.assert.element('login').matches([
    {
        name: suitest.PROP.TEXT_CONTENT,
        val: 'Play now',
    },
    suitest.PROP.WIDTH,
]);

Running a JavaScript comparison function

If you need to make a very specific comparison use the matchesJS operation.

In Test Editor:

Assert image is in 16:9 format (aspect ratio)
Assert image is in 16:9 format (aspect ratio)

In JavaScript API:

await suitest.assert.element('logo').matchesJS("function(img) { return img.offsetWidth / img.offsetHeight  === 16 / 9 }");

You can specify an arbitrary JavaScript code but be careful about the code that produces side effects. For example, consider a silly piece of code like this:

var a = 1;

This code is creating a variable in the global scope. If the application happens to use such variable internally, this code may just have corrupted its runtime and thus the test results can not be considered reliable anymore.

Generally you should use this subject only if you are sure that there is no other way to achieve the desired result. When in doubt on how to structure your JavaScript consult with your development team.