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:
- A Suitest username, password and organization ID
- An app configuration ID
- A device ID
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:
- For Mocha test runner, please use:
- The latest version of this demo application is meant to be used with JS API v3.
- For Suitest JS API v2, please checkout this commit.
- For Cucumber test runner, please use:
- For Suitest JS API v2, please checkout this commit.
- For Gauge test runner, please use:
- For Suitest JS API v2, please checkout this commit.