Suitest JavaScript API basics

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

NPM/Yarn Prefixes

Examples do not include yarn or npm 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.


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:

Suitest allows for specifying shared configuration data like this in an RC file. In your home folder create a file called .suitestrc and paste the following content, replacing the values 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

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.

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.

Launching test in interactive mode

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 only run a single test on a single device at a time.

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

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

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

    console.log('Success!');
}

main();

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

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

Then save the file as test.js in your project folder and in your console navigate to your project folder and run the following:

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.

                > Hi there! This is Suitest v*.*.* test launcher
Device xxxxxxxx > Starting `node test.js`
Device xxxxxxxx > Success!
                > Test run completed successfully. Bye!

Launching the same test in automated mode

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:

tokenKey        = YOUR TOKEN KEY
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.

Mocha demo

Please do not hesitate to check our demo application which shows you how to use Suitest JavaScript API with the Mocha test runner.