Test operations

Test operations consist of user input, browser commands and other miscellaneous operations which are however still very useful. Using test operations you can simulate users input or interaction with the application as well as with the browser.

List of test operations:

User input -

  • click - clicks on element or position
  • closeApp - closes the application
  • moveTo - moves mouse virtual mouse pointer to position or element
  • openApp - opens application at homepage or relative URL
  • openDeepLink - opens a deep link in the application
  • openUrl - opens an absolute URL
  • press - executes a button press
  • scroll - scrolls from element or position in a direction
  • sendText - sends string or command to either a window or element
  • setScreenOrientation - set the orientation of the app on device screen
  • setText - sets text of an element
  • suspendApp - suspends the application
  • swipe / flick - swipes or flicks from the element or position in a direction
  • tap - taps on element or position

Browser command -

Other -

User input

Simulates a user interaction with the application.

click

  • Browsers
  • LG webOS

Simulates a mouse (left) / LG Magic remote click on element or position.

Learn more about click on in Suitest.

async function click() {}

// Click on element
await suitest.element('elementName').click();

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

/*
 * Available only on LG webOS:
 *  - click 100 px down from the current cursor positions
 */
await suitest.relativePosition(0,-100).click();

closeApp

  • Android
  • Apple iPhone / iPad (iOS)
  • Apple iOS Simulator
  • Apple TV (tvOS)
  • Apple tvOS Simulator
  • Browsers
  • LG webOS
  • PlayStation 4/5
  • Roku
  • Samsung Tizen
  • Sky
  • VIDAA
  • Vizio SmartCast
  • Xbox (One, Series X/S)
  • Xumo (Entertainment OS)
  • Xfinity / Xumo TV / XClass TV

Not supported on

  • HbbTV / Freeview Play

Closes the running application.

Learn more about Close app in Suitest.

/**
 * @returns {ChainablePromise.<void>}
 */
async function closeApp() {}

await suitest.closeApp();

moveTo

  • Browsers
  • LG webOS

Moves the (virtual) mouse / LG Magic remote pointer to either an element or position.

Learn more about move to in Suitest.

async function moveTo() {}

 // Move to element's centre
await suitest.element('elementName').moveTo();

// Move to position given x and y coordinates
await suitest.position(100, 200).moveTo();

/*
 * Available only on LG webOS:
 *  - move the cursor by 100 px down
 */
await suitest.relativePosition(0,-100).moveTo();

openApp

  • Android
  • Apple iPhone / iPad (iOS)
  • Apple iOS Simulator
  • Apple TV (tvOS)
  • Apple tvOS Simulator
  • Browsers
  • HbbTV / Freeview Play
  • LG webOS
  • NextGen TV / ATSC 3.0
  • PlayStation 4/5
  • Roku
  • Samsung Tizen
  • Sky
  • VIDAA
  • Vizio SmartCast
  • Xbox (One, Series X/S)
  • Xfinity / Xumo TV / XClass TV
  • Xumo (Entertainment OS)

The following platforms are supported only when Open App override feature is used.

  • LG Netcast
  • Philips NetTV
  • Samsung Orsay
  • Other Smart TVs and STBs

See here and here for more information.

This operation installs and opens the application on the device.

Launches an applications either at the homepage or at a relative URL, it is mainly used at initial start of the application.

Learn more about Open app in Suitest.

/**
 * @param {string} [relativeUrl] - optional relative URL to navigate
 * @throws {AssertionError} - in case Suitest can't open application
 * @throws {SuitestError} - in case relativeUrl is of wrong type or empty string
 * @returns {ChainablePromise.<void>}
 */
async function openApp(relativeUrl) {}

// Open app at homepage
await suitest.openApp();

// Open app at relative URL
await suitest.openApp('/login');

// Open app on Roku at defined deep link
await suitest.openApp().deepLink('contentID=2c4e8ea1ad2f4a8d9d244f5dd4cc47b6&mediaType=movie');

// Choosing launchMode for Android/LG webOS apps
await suitest.openApp().launchMode(suitest.LAUNCH_MODE.RESUME);
await suitest.openApp().launchMode(suitest.LAUNCH_MODE.RESTART);
  • Roku
  • Xfinity / Xumo TV / XClass TV

Opens a specified deep link in the application.

Learn more about Open deep link in Suitest.

/**
 * @param {string} deepLink - deep link to navigate to
 * @throws {AssertionError} - in case Suitest can't open the deep link
 * @throws {SuitestError} - in case command tries to run on a non-supported platform
 * @returns {Promise.<void|boolean>}
 */
async function openDeepLink(deepLink) {}

// Open a deep link
await suitest.openDeepLink('contentID=2c4e8ea1ad2f4a8d9d244f5dd4cc47b6&mediaType=movie');

openUrl

  • Android - WebView apps
  • Browsers
  • HbbTV / Freeview Play
  • LG webOS
  • NextGen TV / ATSC 3.0
  • PlayStation 4/5
  • Samsung Tizen
  • Sky
  • VIDAA
  • Vizio SmartCast
  • Xbox (One, Series X/S) - HTML apps
  • Xfinity / Xumo TV / XClass TV
  • Xumo (Entertainment OS)
  • Other Smart TVs and STBs - HTML apps

Navigates to an absolute URL when called on an HTML-based platform.

Learn more about Open URL in Suitest.

/**
 * @param {string} absoluteUrl - absolute URL to navigate
 * @throws {AssertionError} - in case Suitest can't open URL
 * @throws {SuitestError} - in case command tries to run on non-HTML platform
 * @returns {Promise.<void|boolean>}
 */
async function openUrl(absoluteUrl) {}

// Open URL
await suitest.openUrl('https://suite.st/');

press

  • Android
  • Apple iPhone / iPad (iOS)
  • Apple iOS Simulator
  • Apple TV (tvOS)
  • Apple tvOS Simulator
  • HbbTV / Freeview Play
  • LG webOS
  • NextGen TV / ATSC 3.0
  • PlayStation 4/5
  • Roku
  • Samsung Tizen
  • Sky
  • VIDAA
  • Vizio SmartCast
  • Xbox (One, Series X/S)
  • Xfinity / Xumo TV / XClass TV
  • Xumo (Entertainment OS)
  • Other Smart TVs and STBs

Executes a press of a button. Can be used in conjunction with .repeat, .interval and .until chain modifiers.

Long press support

Suitest supports long presses on the following platforms:

  • Android TV
  • HbbTV / Freeview Play
  • LG webOS - IR controlled
  • NextGen TV / ATSC 3.0
  • PlayStation 4/5
  • Roku
  • Samsung Tizen
  • Sky - IR controlled
  • VIDAA - IR controlled
  • Vizio SmartCast - IR controlled
  • Xfinity - IR controlled
  • Xumo (Entertainment OS)
  • Other Smart TVs and STBs
Currently not supported on

  • Android mobile
  • Apple iPhone / iPad (iOS)
  • Apple iOS Simulator
  • Apple TV (tvOS)

  • Apple tvOS Simulator
  • LG webOS - API controlled
  • Sky - API controlled
  • VIDAA - API controlled
  • Vizio SmartCast - API controlled
  • Xbox (One, Series X/S)
  • Xfinity - API controlled

To see all Virtual Remote Control button options please refer to constants.

/**
 * @param {Symbol|Array<Symbol>} key - either a single key or array of keys
 * @param {String|Number} longPressMs - optional, duration of the button press
 *                                      in milliseconds, max 10 000
 * @throws {SuitestError} - e.g. platform does not support this key or device disconnected
 *                          during execution
 * @returns {ChainablePromise.<void|boolean>}
 */
async function press(key, {longPressMs}) {}

// Press OK once
await suitest.press(suitest.VRC.OK);

// Press OK once for 2s
await suitest.press(suitest.VRC.OK, {longPressMs: 2000});

// Press OK, UP once
await suitest.press([suitest.VRC.OK, suitest.VRC.UP]);

// Press OK exactly 10x with 10s pause between presses
await suitest.press(suitest.VRC.OK)
    .repeat(10)
    .interval(10000);

// Press OK 2x for 3s with 10s pause between presses
await suitest.press(suitest.VRC.OK, {longPressMs: 3000})
    .repeat(2)
    .interval(10000);

// Press OK only if [condition]
if (await suitest.element('Element name').exists()) {
    await suitest.assert.press(suitest.VRC.OK);
}

// Press Ok until [condition]
await suitest.assert.press(suitest.VRC.OK).until(
    suitest.element('Element name').doesNot().exist()
).repeat(10).interval(1000);

scroll

  • Android - mobile devices
  • Apple iPhone / iPad (iOS)
  • LG webOS
LG webOS limitations

When using scroll with LG webOS platform, you cannot define the size of the scroll (simulates the Magic remote action) and you can scroll only vertically (up, down).

Simulates a finger movement / LG Magic remote action to scroll from element or position by size and in defined direction.

As this function simulates the finger movement, directions of the content movement are always opposite. E.g. if you move your finger on the screen up, the content is scrolling down. Learn more about scroll gesture in the operation description.

/**
 * @param {string} direction - direction of the movement (up, down, left, right)
 * @param {number} size - count of pixels length of the movement
 */

async function scroll(direction, size) {}

// Scroll from element’s centre 
await suitest.element('elementName').scroll(suitest.DIRECTIONS.LEFT, 800);

// Scroll from a position with given x and y coordinates 
await suitest.position(100, 200).scroll(suitest.DIRECTIONS.DOWN, 100);

sendText

  • Android
  • Apple iPhone / iPad (iOS)
  • Apple iOS Simulator
  • Apple TV (tvOS)
  • Apple tvOS Simulator
  • Browsers
  • LG webOS
  • Roku
  • Samsung Tizen
  • VIDAA
  • Vizio SmartCast

Using the send text feature with iOS and tvOS apps requires setting up the property accessibilityIdentifier.

Sends a string or keyboard button to a window or element.

Learn more about send text in Suitest. Also check the constants that can be used.

/**
 * @param {string} text - text to be send, including special keys in double square brackets
 * @returns {ChainablePromise.<void|boolean>}
 */
async function sendText(text) {}

// Send plain text to a window
await suitest.window()
    .sendText('Some string');

// Send text to an element with the `Alt` key pressed
await suitest.element('elementName')
    .sendText(`${suitest.KEY.ALT}complex string${suitest.KEY.NULL}`);

// Using constant
await suitest.element('elementName')
    .sendText(suitest.KEY.BACK_SPACE);

setScreenOrientation

  • Android - mobile devices
  • Apple iPhone / iPad (iOS)

Sets the orientation of the app on the device screen to one of the below mentioned values. Since developers of Android and iOS applications are using different names for screen orientations, we have made them interchangeable for the case of cross-platform tests.

You can use the screen orientation constants or one of the following string values.

  • portrait
  • portraitReversed or portraitUpsideDown
  • landscape or landscapeLeft
  • landscapeReversed or landscapeRight

Values portraitReversed and portraitUpsideDown do not work on iOS devices when Face ID is used for authentication.

Learn more about Set screen orientation in Suitest.

/**
 * @param {string} orientation - an orientation to be switched to
 */
async function setScreenOrientation(orientation) {}

// set screen orientation using string value
await suitest.setScreenOrientation('landscape');
// set screen orientation using constant
await suitest.setScreenOrientation(suitest.SCREEN_ORIENTATION.LANDSCAPE_REVERSED);

setText

  • Android
  • Apple iPhone / iPad (iOS)
  • Apple iOS Simulator
  • Apple TV (tvOS)
  • Apple tvOS Simulator
  • Browsers
  • HbbTV / Freeview Play
  • LG webOS
  • NextGen TV / ATSC 3.0
  • PlayStation 4/5
  • Roku (not Lite)
  • Samsung Tizen
  • Sky
  • VIDAA
  • Vizio SmartCast
  • Xbox (One, Series X/S)
  • Xfinity / Xumo TV / XClass TV
  • Xumo (Entertainment OS)
  • Other Smart TVs and STBs - HTML apps

This operations sets text of an element such as a text field / input to specified string.

In HTML-based apps, Set text is supported on contenteditable elements and most of <input> types (excl. button, checkbox, color, file, hidden, image, radio, range, reset).

Can be performed on the following subjects:

Learn more about set text in Suitest.

/**
 * @param {string} text - text to be set
 * @returns {ChainablePromise.<void|boolean>}
 */
async function setText(text) {}

await suitest.element('textBox')
    .setText('text');

suspendApp

  • Android

Suspends the running application.

Learn more about Suspend app in Suitest.

/**
 * @returns {ChainablePromise.<void>}
 */
async function suspendApp() {}

await suitest.suspendApp();

swipe / flick

  • Android - mobile devices
  • Apple iPhone / iPad (iOS)

Simulates a finger swipe / flick from element or position by size and in defined direction and time. Speed calculated from size and time determines if swipe or flick happens.

As this function simulates the finger movement, directions of the content movement are always opposite. E.g. if you swipe up with your finger on the screen, the content is moving down. Learn more about swipe / flick in the operation description.

/**
 * @param {string} direction - direction of the movement (up, down, left, right)
 * @param {number} size - count of pixels length of the movement
 * @param {number} time - count of miliseconds for the movement
 */

async function swipe(direction, size, time) {}
async function flick(direction, size, time) {}

// Swipe/Flick from element’s centre 
await suitest.element('elementName').swipe('up', 800, 50);

// Swipe/Flick from a position with given x and y coordinates 
await suitest.position(100, 200).swipe('left', 100, 250);

tap

  • Android - mobile devices
  • Apple iPhone / iPad (iOS)

Simulates a finger tap on element or position.

Learn more about tap in Suitest.

/**
 * @param {string} type - type of the tap (single, double, long)
 * @param {number} duration in miliseconds - only for long tap type, lowest allowed value is 1000
 */

async function tap(type) {}

// Tap on element’s centre 
await suitest.element('elementName').tap('single');

// Tap on a position with given x and y coordinates 
await suitest.position(100, 200).tap('long', 2000);

Browser command

  • Browsers

Sends specific commands to the browser.

Learn more about browser command in Suitest.

acceptModal

Accepts a modal dialog (if one exists), with an option to send text if it's a prompt dialog.

Learn more about browser commands in Suitest.

// @param {string} [text] - text to be send to modal dialog
async function acceptModal(text) {}

// accept modal dialog
await suitest.window()
    .acceptModal();

// send text to modal dialog and accept it
await suitest.window()
    .acceptModal('Some text sent to the prompt');

dismissModal

Dismisses a modal dialog (if one exists) to proceed.

Learn more about browser commands in Suitest.

async function dismissModal() {}

await suitest.window()
    .dismissModal();

goBack

Returns to the previous page, used in conjunction with subject window.

async function goBack() {}

await suitest.window()
    .goBack();

goForward

Moves forward through the navigation history (only works after moving backwards), used in conjunction with subject window.

async function goForward() {}

await suitest.window()
    .goForward();

refresh

Refreshes the web page, used in conjunction with subject window.

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

await suitest.window()
    .refresh();

setSize

Sets the size, used in conjunction with subject window.

/**
 * @param {number} width - new width for the browser window, px
 * @param {number} height - new height for the browser window, px
 * @returns {ChainablePromise.<void|boolean>}
 */
async function setSize(width, height) {}

await suitest.window()
    .setSize(1024, 720);

Other

Other operations which you can use to adjust the behavior or set up aspects of your applications.

clearAppData

  • Android
  • Browsers
  • HbbTV / Freeview Play
  • LG webOS / Netcast
  • NextGen TV / ATSC 3.0
  • PlayStation 4/5
  • Samsung Tizen / Orsay
  • Sky
  • VIDAA
  • Vizio SmartCast
  • Xbox (One, Series X/S)
  • Xfinity / Xumo TV / XClass TV
  • Xumo (Entertainment OS)
  • Other Smart TVs and STBs - HTML apps

Clears applications data - cookies and local storage.

Learn more about clear app data in Suitest.

/**
 * @throws {SuitestError}
 * @returns {Promise.<void|boolean>}
 */
async function clearAppData() {}

await suitest.clearAppData();

executeCommand

  • Android - WebView apps
  • Browsers
  • HbbTV / Freeview Play
  • LG webOS
  • NextGen TV / ATSC 3.0
  • PlayStation 4/5
  • Samsung Tizen
  • Sky
  • VIDAA
  • Vizio SmartCast
  • Xbox (One, Series X/S) - HTML apps
  • Xfinity / Xumo TV / XClass TV
  • Xumo (Entertainment OS)
  • Other Smart TVs and STBs - HTML apps

Executes arbitrary JavaScript code on the device. Any HTML-based platforms are supported.

Learn more about Execute command in Suitest.

/**
 * @param {string|Function} command - a piece of JS to run on device
 * @throws {SyntaxError} - Error was thrown during evaluation on device
 * @throws {SuitestError} - e.g. platform does not support js
 * @returns {ChainablePromise.<void|boolean>}
 */
async function executeCommand(command) {}

await suitest.executeCommand("window.myApp.debugMode = 1");

pollUrl

  • on all platforms

Poll URL lets you continuously poll a particular URL, until you get an expected response.

Learn more about Poll URL in Suitest.

/**
 * @param {string} url
 * @param {string} response
 * @returns {ChainablePromise.<void|boolean>}
 */
async function pollUrl(url, response) {}

// Poll URL and expect 200 repsonse
await suitest.pollUrl('https://www.example.com/', '200');

sleep

  • on all platforms

Pauses test execution for an amount of time in milliseconds.

Learn more about Sleep in Suitest.

/**
 * @param {number} ms - how long to sleep
 * @throws {SuitestError} - if something unexpected happened, e.g. device disconnected
 * @returns {ChainablePromise.<void|boolean>}
 */
async function sleep(ms) {}

// sleep for 3s
await suitest.sleep(3000);