Suitest API without Suitest Test Launcher¶

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.

If you want to use Suitest JavaScript API for purposes other the end-to-end testing or if your CI process has very specific requirements it may be optimal to use the JavaScript API directly and without the Suitest Test Launcher. E.g. you may need to program your own test launcher.

In this case you need to make additional calls to authenticate, pair the device and set application configuration. You'll find these functions over in the commands section

Authentication¶

Authenticating with Suitest means getting a session token. Based on the type of the session token you can either operate a single device (interactive mode) or launch many tests on many devices (automated mode):

Authenticating for interactive mode¶

To enter the interactive mode you need an interactive session token. To get the token call openSession and pass your e-mail, password and Suitest organization ID (displayed in your profile summary).

// Open a session in interactive mode
const sessionInfo = await suitest.openSession({
    username: 'mr@lollipop.com',
    password: 'mypassword',
    orgId: 'xxxxxx-xxxxxxx-xxxxxx-xxxxx'
});

The sessionInfo constant will contain:

{
    deviceAccessToken: 'your session token',
    tokenValidUntil: timestamp
}

The generated token will be automatically used for all remaining API calls in this process.

Authenticating for automated mode¶

Currently the automated mode in Suitest API is limited to running a Test Pack. To enter automated mode and start the test pack call startTestPack and pass your Personal/Service token ID and password and the ID of the test pack with which this test run has to be associated. startTestPack() returns an automated session token.

// Start Test Pack run
const testPack = await suitest.startTestPack({
    accessTokenId: 'token ID',
    accessTokenPassword: 'token password',
    testPackId: 'test pack ID',
});

The testPack constant will contain the following:

{
    deviceAccessToken: 'session token',
    tokenValidUntil: 'YYYY-MM-DDTHH:MM:SS.SSSz',
    testPackRunId: 'test pack run id',
    testPack: {
        name: 'Test pack name',
        devices: [
            {deviceId: 'id of the device to run test on'},
            {deviceId: 'other device id'}
        ]
    }
};

The generated token will be automatically used for all remaining API calls in this process.

Authenticating with a pre-generated token¶

Once you call the openSession or startTestPack the generated access token will be automatically used for all remaining API calls inside this Node process.

You can use the same token inside worker processes. To use the previously generated token run openSession and submit the token.

await suitest.openSession({sessionToken: 'pre-generated token'});

Closing session¶

Suitest session tokens obtained through the JavaScript API are temporary, however, it is required to close the session after all tests have been completed. To invalidate the token and close the session call closeSession.

// Close the current session and invalidate token
await suitest.closeSession();

Connecting to device¶

After authenticated (in any mode) you can connect to a device by calling
pairDevice and submitting a device id.

// Request control over a device
await suitest.pairDevice('device id');

You should take care to properly disconnect from the device in the end. To disconnect call releaseDevice.

// Release control over remote device
await suitest.releaseDevice();

Selecting application for this session¶

In interactive mode call set setAppConfig to select application and it's configuration that will be opened when openApp is called.

// Select application configuration to work with
await suitest.setAppConfig(configId);

For automated mode this step is not necessary since the app configuration is contained in the definition of the test pack, so you are good to go.

Configuration override¶

Often it is desirable to run the test or test pack with a slightly modified configuration. For instance when implementing a CI process you may want to specify a unique app URL (or package) for every test pack execution.

To override execution parameters use the config parameter of setAppConfig (in interactive mode) and startTestPack (in automated mode).

Example value of the config parameter overriding various settings of the test pack:

{
    url: 'http://suite.st/xx/xxx.html#/xxxxx/xxxxxxxx/xxxxxxx',
    suitestify: true,
    domainList: [
        'http://suite.st',
    ],
    // `freezeRules` is a legacy name for the URL mapping configuration
    // we are going to rename it in the next major release version
    freezeRules: [
        {
            methods: [
                "GET",
            ],
            url: "http://suite.st/xx/xxx.html#/xxxxx/xxxxxxxx/xxxxxxx?channel=xxx1",
            type: "map",
            toUrl: "http://suite.st/xx/xxx.html#/xxxxx/xxxxxxxx/xxxxxxx?channel=xxx2",
        },
    ],
    codeOverrides: {
        "dev": "prod",
    },
    configVariables: [{
        key: "someVar",
        value: "someVal",
    }],
    overrideOpenApp: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
}

Suitest Network API (section Models -> AppConfigOverride) contains additional info about the available fields of the config parameter.

Previous:
Constants Next:
Log listeners