Suitest JavaScript API basics

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.

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


Installation

Install Node.js (LTS or newer).

Create your project folder, navigate to the folders path in the console and input the following:

NPM

Initialize:

npm init -y

Install:

npm i suitest-js-api

To check that the package has been installed correctly run:

npm view suitest-js-api
Yarn

Initialize:

yarn init -y

Install:

yarn add suitest-js-api

To check that the package has been installed correctly run:

yarn info suitest-js-api

Environment setup

To launch a test you will need the following:

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

username    = YOUR SUITEST USERNAME
password    = YOUR SUITEST PASSWORD
orgId       = xxxxx-xxxx-xxx-xxx-xxxxxx
appConfigId = xxxxx-xxxx-xxx-xxx-xxxxxx
deviceId    = xxxxx-xxxx-xxx-xxx-xxxxxx

The RC 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.

Project setup for credentials

In a real project you should separate the project specific Suitest configuration in a .suitestrc file inside your project folder and commit that file to the VCS. Your private credentials should stay in the .suitestrc located in your home folder. Check RC standard for details on precedence.

Launching test in interactive mode

NPM/Yarn Prefixes

Examples outside this box do not include yarn or npm / npx prefixes for brevity. Add the prefixes based on your installation method to examples. We recommend setting up those commands inside package.json to avoid using the prefixes every time.

For example, you can add into the scripts part of package.json file the following structure:

"interactive": "suitest interactive node test.js"

And then execute it from the terminal as:

npm run interactive

During test creation you'll want to run the test on a device to check that it does what it's supposed to. This type of execution we call interactive mode. In interactive mode you can run tests only on one device at a time.

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');
    await suitest.closeSession();
}

myTest().then(console.log, console.error);

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

Do not forget to call closeSession to invalidate the token and session.

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

suitest interactive node ./test.js

Provided that your .suitestrc 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 in interactive mode ...
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)
Test execution time limit

In case of not using the startTest and endTest commands, the whole session is considered by Suitest as a single test run, which is limited to 60 minutes (see FAQ). To avoid such situation, please use startTest line before each test.

Launching the same test in automated mode

NPM/Yarn Prefixes

Examples outside this box do not include yarn or npm / npx prefixes for brevity. Add the prefixes based on your installation method to examples. We recommend setting up those commands inside package.json to avoid using the prefixes every time.

For example, you can add into the scripts part of package.json file the following structure:

"automated": "suitest automated node --no-timeouts --exit test.js"

And then execute it from the terminal as:

npm run automated

When your tests are ready and you want to trigger the test run to check for regression you need to run your test in automated mode.

In automated mode you can execute many tests on many devices as a Test Pack and get aggregated results. To run a test in automated mode you need to authenticate with an API token. Go create one now and add the following 3 lines to the .suitestrc file like this:

tokenId        = YOUR TOKEN ID
tokenPassword   = YOUR TOKEN PASSWORD
testPackId      = xxxxx-xxxx-xxx-xxx-xxxxxx

Now, to execute your test in automated mode run:

suitest automated node test.js

Do not forget to call closeSession to invalidate the token and session.

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: