JavaScript
JavaScript OpenSDK
To get started, you need to complete the following prerequisites checklist:
You must have Node.js v12 or newer installed.
The TestProject JavaScript OpenSDK is available on NPM. All you need to do is add it as an NPM module using:
npm install @tpio/javascript-opensdk
and you're good to go.
Using a TestProject driver is exactly identical to using a Selenium driver. Changing the import statement is enough in most cases.
Following examples are based on theChrome
driver, however are applicable to any other supported drivers.
Here's an example of how to create a TestProject version of the
Chrome
driver:// import { Builder } from 'selenium-webdriver'; <-- replace this import
import { Builder } from '@tpio/javascript-opensdk';
const createChromeDriver = async () => {
const driver = await new Builder().forBrowser('chrome').build();
//////////////////////////////
// Your test code goes here //
//////////////////////////////
await driver.quit();
};
Here's a complete test example:
import { By } from 'selenium-webdriver';
import { Builder } from '@tpio/javascript-opensdk';
export const simpleTest = async (): Promise<void> => {
const driver = await new Builder().forBrowser('chrome').build();
await driver.get('https://example.testproject.io/web/');
await driver.findElement(By.css('#name')).sendKeys('John Smith');
await driver.findElement(By.css('#password')).sendKeys('12345');
await driver.findElement(By.css('#login')).click();
const passed = await driver.findElement(By.css('#logout')).isDisplayed();
console.log(passed ? 'Test Passed' : 'Test Failed');
await driver.quit();
};
TestProject's OpenSDK overrides standard Selenium/Appium drivers with extended functionality. Below is the package's structure containing all supported drivers:
src
└── sdk
└── drivers
├── web
│ ├── chrome
│ ├── edge
│ ├── firefox
│ ├── ie (Legacy Internet Explorer)
│ └── safari
└── mobile
├── androidDriver
└── iosDriver
The SDK uses a development token for communication with the Agent and the TestProject platform. Drivers search for the development token in an environment variable called
TP_DEV_TOKEN
. Alternatively, the token can be set using the withToken
method on the builder:import { Builder } from '@tpio/javascript-opensdk';
const createChromeDriver = async () => {
const driver = await new Builder().forBrowser('chrome').withToken('YOUR_TOKEN_GOES_HERE').build();
//////////////////////////////
// Your test code goes here //
//////////////////////////////
await driver.quit();
};
Agent URL (host and port), can be also provided explicitly using driver builder:
driver = new Builder().forBrowser('chrome').withToken('YOUR_DEV_TOKEN').withRemoteAgent('http://URL:PORT').build();
It can also be set using the
TP_AGENT_URL
environment variable.NOTE: By default, the agent binds to localhost. In order to allow the SDK to communicate with agents running on a remote machine (On the same network), the agent should bind to an external interface. For additional documentation on how to achieve such, please refer here
The SDK will attempt to infer Project and Job names automatically when running tests using the Mocha framework. For example:
- Directory
e2e_tests/chrome
containsmy_tests.spec.ts
test file. - When executing
my_tests.spec.ts
, the SDK will infere2e_tests/chrome
as the project name (replacing any slashes/
with dots.
). - The job name will be set to the file name, skipping the
.spec.ts
suffix. In this example:my_tests
.
Project and Job names can be also specified explicitly using the
withProjectName
and withJobName
methods of the builder:import { Builder } from '@tpio/javascript-opensdk';
const createChromeDriver = async () => {
const driver = await new Builder()
.forBrowser('chrome')
.withProjectName('PROJECT NAME')
.withJobName('JOB_NAME')
.build();
//////////////////////////////
// Your test code goes here //
//////////////////////////////
await driver.quit();
};
Tests are reported automatically when a test ends or when the driver quits. This behavior can be overridden or disabled (see Disabling Reports section below).
To report tests manually, use the
driver.report().tests()
method and its overloads. For example:import { Builder } from '@tpio/javascript-opensdk';
const createChromeDriver = async () => {
const driver = await new Builder().forBrowser('chrome').build();
let passed = true;
//////////////////////////////
// Your test code goes here //
//////////////////////////////
driver.report().test('My test name', passed);
await driver.quit();
};
Steps are reported automatically when driver commands are executed. If this feature is disabled (or in addition to automatic reports) manual reports can be performed. For example:
import { Builder } from '@tpio/javascript-opensdk';
const testReportStepManually = async () => {
const driver = await new Builder().forBrowser('chrome').build();
driver.report().step('First Step', 'Completed successfully', true);
driver.report().step('Second Step', 'Failed', false);
driver.report().test('My Test', false); // Report the test as failed
await driver.quit();
};
TestProject OpenSDK reports all driver commands and their results to the TestProject Cloud. Doing so allows us to present beautifully designed reports and statistics in its dashboards.
Reports can be completely disabled using the
setDisableReporting
method of the builder:import { Builder } from '@tpio/javascript-opensdk';
const testWithoutReports = async () => {
const disableReports = true;
const driver = await new Builder().forBrowser('chrome').setDisableReporting(true).build();
//////////////////////////////
// Your test code goes here //
//////////////////////////////
await driver.quit();
};
If reports were not disabled when the driver was created, they can be disabled or enabled later. However, if reporting was explicitly disabled when the driver was created, they cannot be enabled later.
Reports can be temporarily disable using the
disableAutoTestReports
method of report()
and enabled later:import { Builder } from '@tpio/javascript-opensdk';
const testTemporarilyDisableAllReportingThenReenableItLater = async () => {
const driver = await new Builder().forBrowser('chrome').build();
driver.report().disableAutoTestReports(true);
await this.driver.get('https://example.testproject.io/web/'); //This statement will not be reported
driver.report().disableAutoTestReports(false);
await driver.quit();
};
Even more so than with regular Selenium-based tests, it is important to make sure that you call the
quit()
method of the driver object at the end of every test that uses the TestProject SDK. Upon calling quit()
, the SDK will send all remaining report items to the Agent, ensuring that your report on the TestProject platform is complete.Examples are available at the OpenSDK Examples repo, but tests from this repo can be used as simple examples as well:
The TestProject JavaScript OpenSDK is licensed under the LICENSE file in the root directory of the project source tree.
Last modified 1yr ago