Setting up the Suitest JavaScript API

Before writing your first test you'll need a Suitest account with at least one configured device and at least one application.

Installation

  1. Download and install Node.js (LTS or newer).
  2. Open any file explorer and create a project folder
  3. Open a terminal / command prompt and navigate to that folder

  4. Choose a package manager (NPM or Yarn) and install the Suitest JavaScript API with the following commands:

    When using NPM

    npm init -y
npm i suitest-js-api

    When using Yarn

    yarn init -y
yarn add suitest-js-api

  5. Check that the package has been installed correctly

    When using NPM 

    npm view suitest-js-api

    When using Yarn 

    yarn info suitest-js-api

Environment setup

To launch a test you will need the following:

The configuration file

Once you have collected these information, you can create a Suitest JavaScript API configuration file. To do so, create a file called .suitestrc inside your project folder and paste the following content (replace the values on the right side with your own, example in JSON format):

{
    "tokenId"           : "xxxxxxxxxx",
    "tokenPassword"     : "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "appConfigId"       : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "deviceId"          : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

There are other places where configuration file is searched. It is described in advanced topics.

Supported formats

The configuration file can be formatted in JavaScript, JSON, JSON5, YAML and INI. Please, make sure to use the file extension corresponding with chosen format (.js, .json, .json5, .yaml, .yml, .ini). If no extension defined, file is considered having JSON or INI format.

The appConfigId and deviceId can be replaced by presets. See related documentation for more information.

The configuration file is only read by the Suitest Test Launcher. It is optional to use the launcher, so if you choose not to, you'll need to provide the data to the appropriate API calls yourself. Launcher also provides you the possibility to use --base-config-file and --override-config-file options in order to change or extend the default configuration file.

Project setup security

In a real project you should separate the project specific Suitest configuration in the configuration file inside your project folder and commit that file to the VCS. Your private token credentials should stay in the configuration file located in your home folder. See the advanced topic to find out more about configuration file locations and merging options.

Launching a test

Examples below contain npm / npx prefixes. If you are using yarn, please replace them respectively.

To create your first test with Suitest JavaScript API open your favorite IDE, create new JavaScript file and paste the following contents:

const suitest = require('suitest-js-api');

async function myTest() {
    await suitest.openApp();
    await suitest.assert.location().equals('https://example.com');
}

myTest().finally(() => suitest.closeSession());

Replace https://example.com with the expected homepage of your application.

Save the file as test.js in your project folder. Open the console, navigate to your project folder and run the following command:

npx suitest-js-api run node ./test1.js

Provided that your configuration file contains correct values the specified app will open on the target device, the test will pass and you should see the following output.

Jan 1 11:11:11 Launcher  Hi there! This is Suitest test launcher vX.XX.X.
Jan 1 11:11:11 Launcher  Preparing to start execution ...
Jan 1 11:11:11 Launcher  
Jan 1 11:11:11 Launcher  Connected to Suitest
Jan 1 11:11:11 Launcher  Test command: node ./test.js
Jan 1 11:11:11 Launcher  Execution log: undefined
Jan 1 11:11:11 Launcher  Device: Google Chrome @ Cookie Monster
Jan 1 11:11:11 Launcher  
Jan 1 11:11:11 Launcher  TIP: Assertions are marked with "A", chain evaluations are marked with "E".
Jan 1 11:11:11 Launcher  
Jan 1 11:11:11 Launcher  Connected to Suitest
Jan 1 11:11:11 Chrome (aaa)  Connected to "Google Chrome @ Cookie Monster" (ae6a2f6f-d6cf-4f2c-8af7-aaaaaaaaaa)
Time limit for a single test

When using Suitest JavaScript API, there is no test start and end (unlike in Test editor). Therefore, the whole session is limited to 12 hours to avoid blocking of devices and unwanted spending of testing minutes.

Defining scripts in one place

When using several different test execution scripts, we recommend setting them up inside the package.json to ease your work. For that, you should use the scripts part of package.json file inside your project folder.

Example of script setup inside package.json:

```
"scripts": {
    "smoke": "suitest run --preset preset1 node ./smoke_test.js",
    "regression": "suitest run --preset preset1 --preset preset2 node ./regression_test.js"
}
```

Example of the smoke script execution from the terminal:

```
npm run smoke
```

Demo applications

For an easier start with using our Suitest JavaScript API, we have prepared demo application for several widely used test runners. Go ahead and try out the one that suits you the best: