Commands

Commands are instructions to Suitest or a connected device, which are universal and can be used for both test authoring and service app creation. Each command creates its own chain, and returns a Promise-like object.

List of commands:

closeSession

closeSession function invalidates the session token, this is required after all tests have been completed. It will invalidate the token and close the session and implicitly unpair you from the device you are currently connected to.

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

// Close session after work is done and there are no more calls to be made
await suitest.closeSession();
// This would also implicitly unpair you from device

getAppConfig

When opening the app using openApp or openUrl, the application configuration is used. Configuration can be defined inside a Configuration file (as appConfigId or inside a preset) or by setAppConfig command. The command getAppConfig returns details of used configuration.

/**
 * @returns {Promise<AppConfiguration|SuitestError>} configurationDetails
 */

async function getAppConfig() {}

interface AppConfiguration {
  name: string;
  url: string;
  // true if suitestify is enabled
  suitestify: boolean;
  domainList: string[];
  // property name is a variable name, property value is the content of the variable
  variables: Record<string, string>;
  platform: string;
  isHtmlBased: boolean;
}

openSession

openSession authenticates on Suitest servers and establishes a connection to allow for further requests. While the session is open, request can be made by using the other API methods.

/**
 * @param {string} tokenId
 * @param {string} tokenPassword
 * @returns {ChainablePromise.<void>}
 */
async function openSession({tokenId, tokenPassword}) {}

// Authenticate with token id and password by passing it directly
const sessionInfo = await suitest.openSession();
sessionInfo === {
    accessToken: `tokenId:tokenPassword`
};

/**
 * @param {string} sessionToken - token, received e.g. from startTestPack method
 */
async function openSession({sessionToken}) {}

pairDevice

Request control of a device. Device is paired until releaseDevice command is called.

If any of the following happen then session is also closed:

  • Session crashes and is not recovered within 90 seconds
  • Token expires
  • Token is invalidated
/**
 * @param {string} deviceId - device id to connect
 * @param {Object | undefined} recordingSettings - optional {recording, webhookUrl} object.
 *  'recording' options: "autostart", "manualstart" or "none". 
 *  'webhookUrl' is a valid webhook URL that you want to register to get information once recording is uploaded.
 * @returns {ChainablePromise.<DeviceData>}
 */
async function pairDevice(deviceId, {recording, webhookUrl}) {}

// Pair device
const deviceData = await suitest.pairDevice('uuid', {recording: 'autostart', webhookUrl: 'webhook URL'});
deviceData === {
    "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "modelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "firmware": 1,
    "recordingUrl": "a URL where recording will be stored once the upload is finished"
};

releaseDevice

Unpair device, because it is no longer needed.

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

saveScreenshot

Supported platforms

Screenshots directly from the device supported on:

  • Android
  • Apple iPhone / iPad (iOS) devices and simulators
  • Apple TV (tvOS) devices and simulators
  • Browsers
  • HbbTV (on LG webOS TVs 2016+)
  • LG webOS (2016+)
  • PlayStation 4/5
  • Roku
  • Sky (Entertainment OS)
  • VIDAA - Lite
  • Xbox (One, Series X/S)

Screenshots from Suitest Camera app supported also on:


  • NextGen TV / ATSC 3.0
  • HbbTV / Freeview Play
  • Samsung Tizen
  • Sky Q
  • VIDAA - Instrumentation library
  • Vizio SmartCast
  • Xfinity / Xumo TV / XClass TV
  • Other Smart TVs and STBs

Take a screenshot on the paired device and save it to a file. Screenshots are always in PNG format. In case the provided path is relative, it is going to be resolved relative to the current working directory. The Promise resolves after the file is saved to a disk, and rejects in the case that Suitest failed to take a screenshot or the JavaScript API could not save the file to a provided location.

/**
 * @param {string} pathToFile - relative or absolute path to file, where to save image
 * @returns {Promise<void>}
 */
async function saveScreenshot(pathToFile) {}

// Example
await suitest.saveScreenshot('./my-screenshot.png');
await suitest.saveScreenshot('/user/Me/Documents/my-screenshot.png');

If you would prefer to handle screenshots on your own (e.g. upload them to remote storage instead of saving to a file), have a look at the similar command takeScreenshot.

setAppConfig

When opening the app using openApp or openUrl, the application configuration is used. You have it already defined as appConfigId or among presets inside the configuration file. Nevertheless, you can change it by using setAppConfig with attributes configId and optionally configOverride.

/**
 * @param {string} configId - config Id
 * @param {Object} [configOverride] - an optional override of the configuration
 * @returns {ChainablePromise.<void>}
 */
async function setAppConfig(configId, configOverride) {}

startRecording

As long as you have a Suitest Camera app configured on your Android phone aimed at the device screen, any JavaScript API session can be recorded. The recording can be automatically started for the whole session (using recording-option=autostart launcher option) or ad hoc during the session with startRecording line (recording-option=manualstart launcher option).

When starting a recording, you can register a URL of a webhook - in order to receive notification once the recording is uploaded to Suitest storage thus available to you.

/**
 * @param {Object | undefined} recordingSettings
 * @param {string} [recordingSettings.webhookURL] - can be undefined or empty string, otherwise must be a valid URL of a webhook.
 * @returns {ChainablePromise.<void>}
 */
async function startRecording({webhookURL}) {}

stopRecording

This command can be used to ad hoc stop the recording of a session execution (or the part of it, depending how the recording was started). You can also select, if you want to have the recording stored (discard === false) or not (discard === true).

/**
 * @param {string} discard - if to store or discard the video, default is false
 * @returns {ChainablePromise.<void>}
 */
async function stopRecording(discard) {}

takeScreenshot

Supported platforms

Screenshots directly from the device supported on:

  • Android
  • Apple iPhone / iPad (iOS) devices and simulators
  • Apple TV (tvOS) devices and simulators
  • Browsers
  • HbbTV (on LG webOS TVs 2016+)
  • LG webOS (2016+)
  • PlayStation 4/5
  • Roku
  • Sky (Entertainment OS)
  • VIDAA - Lite
  • Xbox (One, Series X/S)

Screenshots from Suitest Camera app supported also on:


  • NextGen TV / ATSC 3.0
  • HbbTV / Freeview Play
  • Samsung Tizen
  • Sky Q
  • VIDAA - Instrumentation library
  • Vizio SmartCast
  • Xfinity / Xumo TV / XClass TV
  • Other Smart TVs and STBs

Take a screenshot on the paired device and return image data. Screenshots are always in PNG format. Image data can be provided either as raw Buffer or as base64 encoded string. The Promise resolves after a screenshot is taken and downloaded, and rejects in the case that Suitest failed to take a screenshot.

/**
 * @param {'base64'|'raw'} [format] - data format you would like to receive image in. Optional, defaults to 'raw'
 * @returns {Promise<Buffer|string>} - depending on format, resolves either to Buffer or string
 */
async function takeScreenshot(format) {}

// Example
const rawBufferWithPng = await suitest.takeScreenshot();
const base64EncodedPng = await suitest.takeScreenshot('base64');

If you would prefer Suitest's JavaScript API to handle saving PNG images to disk, have a look at the similar command saveScreenshot.