Suitest API without Suitest Test Launcher

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.

To get the session token, call the openSession command and pass it your tokenId and tokenPassword.

// Open a session
const sessionInfo = await suitest.openSession({
    tokenId: 'xxxxxxxx',
    tokenPassword: 'xxxxxxxxxxx'
});

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.

Once you call the openSession the provided 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

By default, the application and configuration is used from the configuration file. However, if you want to switch to another application or configuration, 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);

Locations for configuration files

If the configuration file is not defined in an execution script by --base-config-file Suitest JavaScript API searches for it in your local drive. When the first configuration file is found, it is considered as a base and the search stops.

Please do not user more than one configuration file (using different extensions) in each of these locations (e.g. .suitestrc and .suitestrc.json).

The configuration file is searched based on the following rules in the corresponding order:

  1. .suitestrc.* file in the current working directory

  2. .suitestrc.* file in the parent directories, (e.g. ./../, ./../../) … until the root of the file system is reached

  3. suitest.* file in $HOME/.config/ (macOS, Linux) or %USERPROFILE%\.config\ (MS Windows)

  4. config.* file in $HOME/.suitest/ (macOS, Linux) or %USERPROFILE%\.suitest\ (MS Windows)

  5. .suitestrc.* file in $HOME/ (macOS, Linux) or %USERPROFILE%\ (MS Windows)

  6. .suitestrc.* file in /etc/ (macOS, Linux)

Merging configuration files

Suitest allows users to use several different configuration files in order to cover more complex use cases. This can be achieved by using extends property inside the configuration file. Use it with a relative path.

{project root folder}/.baserc.json file content:

{
    "tokenId": "your token ID",
    "tokenPassword": "your token password",
    /* other basic configurations */
}

{project root folder}/.app1rc.json file content:

{
    "extends": ".baserc.json",
    /* application specific configurations */
}

In such case, you would use the configuration for application1 the following way:

suitest run node --config-file .app1rc.json ...

Configuration override

Often it is desirable to run a test with slightly modified configuration.

Using CLI command

For instance when implementing a CI process you may want to specify a unique app URL (or package) for every test execution.

To override execution parameters use the config parameter of setAppConfig.

Example value of the config parameter overriding various settings application configuration set up in Web UI:

{
    url: 'http://suite.st/xx/xxx.html#/xxxxx/xxxxxxxx/xxxxxxx',
    suitestify: true,
    domainList: [
        'http://suite.st',
    ],
    // `mapRules` is a legacy name for the URL mapping configuration
    // we are going to rename it in the next major release version
    mapRules: [
        {
            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.

Using presets

You can overwrite the app configuration values inside your configuration file. See example in JSON below:

    {
        // ... main JavaScript API configuration properties ...
        "preset": ["myPreset"],
        "presets": {
            "myPreset": {
                "device": "your device ID",
                "config": {
                    "configId": "your configuration ID",
                    "url": "URL to be used e.g. https://somedomain.com/testapp",
                    "suitestify": {
                        "domainList": [
                            "somedomain.com"
                        ]
                    }
                }
            }
        }
    }