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
 * @returns {ChainablePromise.<DeviceData>}
 */
async function pairDevice(deviceId) {}

// Pair device
const deviceData = await suitest.pairDevice('uuid');
deviceData === {
    "deviceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "modelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "firmware": 1
};

releaseDevice

Unpair device, because it is no longer needed.

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

saveScreenshot

Supported platforms

  • 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
  • Xbox (One, Series X/S)
Currently not supported on

  • HbbTV / Freeview Play
  • Samsung Tizen
  • 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) {}

takeScreenshot

Supported platforms

  • 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
  • Xbox (One, Series X/S)
Currently not supported on

  • HbbTV / Freeview Play
  • Samsung Tizen
  • 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.