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

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. After the command has gone through, the interactive or automated time starts being billed. Minutes are subtracted until calling releaseDevice command, session crashes and is not recovered within 90 seconds, token expires or is invalidated. The type of minutes subtracted is based on the authentication method.

/**
 * @param {string} deviceId - device id to connect
 * @returns {ChainablePromise.<DeviceData>}
 */
async function pairDevice(deviceId) {}

// Pair device
const deviceData = await suitest.pairDevice('uuid');
deviceData === {
    "deviceId": "25892e17-80f6-415f-9c65-7395632f0223",
    "manufacturer": "Organization",
    "model": "Model",
    "owner": "CompanyName",
    "platforms": ["browser"],
    "firmware": 1,
    "isShared": false,
    "modelId": "acdefg7-80f6-415f-9c65-7395632f0223",
    "status": "READY"
};

releaseDevice

Unpair device, because it is no longer needed. Session minutes stop being subtracted once the command has gone through.

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

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.

/**
 * @param {string} clientTestId - user-defined id of the test, must be unique per test pack
 * @param {string} [name] - human readable name of the test
 * @param {string} [description] - arbitrary description of the test
 * @throws {SuitestError} - occurs when context of the test run is wrong
 * @returns {ChainablePromise.<SuitestError|void>}
 */
async function startTest(clientTestId, {name, description}) {}

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.

/**
 * @param {string} accessTokenKey - Access Token key
 * @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({
    accessTokenKey,
    accessTokenPassword,
    testPackId,
    config,
    commitHash,
    appVersion,
    metadata,
    vcsBranch,
    allowServiceCalls
}) {}

// Start predefined test pack
const testPack = await suitest.startTestPack({accessTokenKey, 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({
    accessTokenKey,
    accessTokenPassword,
    testPackId,
    config: {
        // ... app configuration
    }
});