Test operations

This part of user documentation is describing an obsolete version 2.5.* (or older) of Suitest JavaScript API and is meant only for users who have not yet switched to the version 3. If you are new to Suitest JavaScript API, please use the version 3 instead.

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 - click on element or position
  • closeApp - closes the application
  • moveTo - move mouse virtual mouse pointer to position or element
  • openApp - open application at homepage or relative URL
  • openUrl - open an absolute URL
  • press - execute a button press
  • scroll - scroll from element or position in a direction
  • sendText - send string or command to either a window or element
  • setScreenOrientation - set the orientation of the app on device screen
  • setText - set text of an element
  • suspendApp - suspends the application
  • swipe / flick - swipe or flick from the element or position in a direction
  • tap - tap on element or position

Browser command -

Other -


User input

Simulating 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();

closeApp

  • on all platforms

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();

openApp

  • Android
  • Apple iPhone / iPad (iOS)
  • Apple iOS Simulator
  • Apple TV (tvOS)
  • Apple tvOS Simulator
  • Browsers
  • HbbTV / Freeview Play
  • LG webOS
  • PlayStation 4/5
  • Roku
  • Samsung Tizen
  • VIDAA
  • Vizio SmartCast
  • Xbox (One, Series X/S)
  • Xfinity (Comcast)

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.

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');

// Choosing launchMode for Android/LG webOS apps
await suitest.openApp().launchMode(suitest.LAUNCH_MODE.RESUME);
await suitest.openApp().launchMode(suitest.LAUNCH_MODE.RESTART);

openUrl

  • Android - WebView apps
  • Browsers
  • HbbTV / Freeview Play
  • LG webOS
  • PlayStation 4/5
  • Samsung Tizen
  • VIDAA
  • Vizio SmartCast
  • Xbox (One, Series X/S) - HTML apps
  • Other Smart TVs and STBs - HTML apps

Open URL 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
  • PlayStation 4/5
  • Roku
  • Samsung Tizen
  • VIDAA
  • Vizio SmartCast
  • Xbox (One, Series X/S)
  • Xfinity (Comcast)
  • Other Smart TVs and STBs

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

Long presses are supported only by JS API v3.

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
 * @throws {SuitestError} - e.g. platform does not support this key or device disconnected during execution
 * @returns {ChainablePromise.<void|boolean>}
 */
async function press(key) {}

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

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

// Press OK exactly 10x every 10s
await suitest.press(suitest.VRC.OK)
    .repeat(10)
    .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
  • Browsers
  • LG webOS
  • Roku
  • Samsung Tizen
  • VIDAA
  • Vizio SmartCast

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
  • PlayStation 4/5
  • Roku (not Lite)
  • Samsung Tizen
  • VIDAA
  • Vizio SmartCast
  • Xbox (One, Series X/S)
  • Xfinity (Comcast)
  • 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)

Swipe or 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)

Finger taps 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

Send specific commands to the browser.

Learn more about browser command in Suitest.

acceptModal

Accept the 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 the 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
  • PlayStation 4/5
  • Samsung Tizen / Orsay
  • VIDAA
  • Vizio SmartCast
  • Xbox (One, Series X/S)
  • Xfinity (Comcast)
  • 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
  • PlayStation 4/5
  • Samsung Tizen
  • VIDAA
  • Vizio SmartCast
  • Xbox (One, Series X/S) - HTML apps
  • Other Smart TVs and STBs - HTML apps

Execute 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

Sleep 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);