Commands

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.

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

endTest

Closes the current test, no further commands to this test can be made. Used in conjunction with startTest to separate test execution into logical sections resulting in clean and organized test results. Omitted if the test is closed implicitly by using startTest call or the session is closed. It is better to have endTest explicitly stated, mainly to keep the test results clean and organized.

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

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} username - your Suitest username (email)
 * @param {string} password - your Suitest password
 * @param {string} orgId - organisation id
 * @returns {ChainablePromise.<void>}
 */
async function openSession({username, password, orgId}) {}

// Authenticate with username/password/organization id by passing it directly
const sessionInfo = await suitest.openSession({username: 'some@email.com', password: 'pwd', orgId: 'org-id'});
sessionInfo === {
    token: 'uuid',
    tokenExpirationDate: timestamp,
    sessionType: enum(suitest.SESSION_AUTOMATED|suitest.SESSION_INTERACTIVE),
    orgId: 'org-id', // your current organization ID
    testPackId: 'uuid', // only available for automated session
    targetDevice: { // only available for automated session
        deviceId: 'uuid', // specific device id if available
        modelId: 'uuid', // OR modelId + firmware pair
        firmware: 'string'
    }
};

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

// Pair device
await suitest.pairDevice('uuid');

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
  • VIDAA - Lite
  • Xbox (One, Series X/S)

Screenshots from Suitest Camera app supported also on:


  • HbbTV / Freeview Play
  • Samsung Tizen
  • VIDAA - Instrumentation library
  • Vizio SmartCast
  • Xfinity (Comcast)
  • 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

Before opening the app using openApp or openUrl, you must define the application configuration. For automated session the configuration is attached to the session token. For interactive session it is however not defined, therefore it will have to be done using setAppConfig, which has 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) {}

startTest

Define that the commands following startTest() will be recorded as a new test. This allows for you to split tests into smaller sections to be able to have the results organized and readable.

/**
 * @throws {SuitestError} - occurs when context of the test run is wrong
 * @returns {ChainablePromise.<SuitestError|void>}
 */
async function startTest() {}

startTestPack

startTestPack provides an Automated session token along with test pack configuration that is populated with the app configuration.

Once startTestPack is called, the current Node.js process will be automatically logged in with the automated session token, therefore there is no need to call openSession.

If you need to execute test on multiple devices in parallel, you will create more Node.js processes (1 per device) thus you will need to login with openSession to generate an automated session token. Every test included in the test pack will be executed on each selected device.

/**
 * @param {string} accessTokenId - Access Token id
 * @param {string} accessTokenPassword - Access Token password
 * @param {number} testPackId - testPack id
 * @param {Object} [config] - optional override for the app configuration
 * @param {string} [metadata]
 * @param {string} [commitHash] - optional VCS commit hash
 * @param {string} [appVersion] - optional application version
 * @param {string} [vcsBranch] - optional branch in VSC
 * @param {bool} [allowServiceCalls] - optional flag to allow accessing service and CI part of the API with generated Session Token. By default false.
 * @throws {SuitestError} - when context of the test run is wrong
 * @returns {ChainablePromise.<Object>}
 */
async function startTestPack({
    accessTokenId,
    accessTokenPassword,
    testPackId,
    config,
    commitHash,
    appVersion,
    metadata,
    vcsBranch,
    allowServiceCalls
}) {}

// Start predefined test pack
const testPack = await suitest.startTestPack({accessTokenId, accessTokenPassword, testPackId: 'number'});
testPack === {
    sessionToken: 'uuid',
    testPack: {
        // complete JSON for test pack, including devices and app config
        // if app config overrides are used - it returns merged version, that will be used
    }
};

// Start test pack with overrides
const tokens = await suitest.startTestPack({
    accessTokenId,
    accessTokenPassword,
    testPackId,
    config: {
        // ... app configuration
    }
});

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
  • VIDAA - Lite
  • Xbox (One, Series X/S)

Screenshots from Suitest Camera app supported also on:


  • HbbTV / Freeview Play
  • Samsung Tizen
  • VIDAA - Instrumentation library
  • Vizio SmartCast
  • Xfinity (Comcast)
  • 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.