testingbot-api

Official NodeJS client for the TestingBot REST API.

TestingBot provides a cloud-based test infrastructure for automated cross-browser testing. This client library allows you to interact with the TestingBot API to manage tests, retrieve browser information, handle test artifacts, and more.

Table of Contents

- Features
- Requirements
- Installation
- Quick Start
- API Reference
- Browser & Device Management
- Session Management
- User Management
- Test Management
- Tunnel Management
- Build Management
- Storage Management
- Screenshots
- Team Management
- Codeless Tests
- CLI Usage
- Installation
- Authentication
- Available Commands
- CLI Examples
- Complete Examples
- Testing
- Contributing
- License
- Support
- More Documentation

Features

$3

- Full support for all TestingBot REST API endpoints
- Both callback and async/await patterns supported
- Manage browser sessions and tests
- Upload and manage test artifacts
- Team management capabilities
- Screenshot generation across multiple browsers
- Tunnel management for local testing

Requirements

- NodeJS >= 10.0.0
- A TestingBot account with API credentials

Installation

``shell
npm install testingbot-api
`

Quick Start

$3

Sign up for a TestingBot account and obtain your API key and secret from the account settings.

$3

You can authenticate in three ways:

#### Environment variables (recommended)
`bash
export TESTINGBOT_KEY="your-api-key"
export TESTINGBOT_SECRET="your-api-secret"
`

#### Constructor options
`javascript
const tb = new TestingBot({
api_key: 'your-api-key',
api_secret: 'your-api-secret'
});
`

#### Configuration file
Create a ~/.testingbot file with your credentials

$3

`javascript
const TestingBot = require('testingbot-api');

const tb = new TestingBot({
api_key: process.env.TESTINGBOT_KEY,
api_secret: process.env.TESTINGBOT_SECRET
});
`

Usage

All methods support both callback style and async/await patterns. When using async/await, simply omit the callback parameter.

API Reference

$3

#### getBrowsers
Gets a list of browsers you can test on

`javascript
// Callback style
tb.getBrowsers(type, function(error, browsers) {});

// Async/await style
const browsers = await tb.getBrowsers();

// With optional type parameter (e.g., 'web' or 'mobile')
const webBrowsers = await tb.getBrowsers('web');
`

#### getDevices
Gets a list of physical mobile devices you can test on

`javascript
// Callback style
tb.getDevices(function(error, devices) {});

// Async/await style
const devices = await tb.getDevices();
`

#### getAvailableDevices
Gets a list of available physical mobile devices for your account

`javascript
// Callback style
tb.getAvailableDevices(function(error, availableDevices) {});

// Async/await style
const availableDevices = await tb.getAvailableDevices();
`

#### getDevice
Gets details for a specific physical device

`javascript
// Callback style
tb.getDevice(deviceId, function(error, deviceDetails) {});

// Async/await style
const deviceDetails = await tb.getDevice(deviceId);
`

$3

#### createSession
Creates a remote browser on TestingBot and returns its CDP URL, which can be used to interface with the remote browser.

`javascript
const options = {
capabilities: {
browserName: 'chrome',
browserVersion: 'latest',
platform: 'WIN11'
}
};

// Callback style
tb.createSession(options, function(error, data) {});

// Async/await style
const session = await tb.createSession(options);
`

This will return a response with this structure:
`json
{
"session_id": "cb8aaba38ddb-88fd98fca537-a0070d8f1815-175888519321-14646637",
"cdp_url": "wss://cloud.testingbot.com/session/cb8aaba38ddb-88fd98fca537-a0070d8f1815-175888519321-14646637"
}
`

You can now connect to the cdp_url with a CDP client to instruct the remote browser.

$3

#### getUserInfo
Gets your user information

`javascript
// Callback style
tb.getUserInfo(function(error, userInfo) {});

// Async/await style
const userInfo = await tb.getUserInfo();
`

#### updateUserInfo
Updates your user information

`javascript
// Callback style
tb.updateUserInfo(newUserdata, function(error, userInfo) {});

// Async/await style
const userInfo = await tb.updateUserInfo(newUserdata);
`

$3

#### getTests
Gets list of your latest tests

`javascript
// Callback style
tb.getTests(offset, limit, function(error, tests) {});

// Async/await style
const tests = await tb.getTests();

// With pagination
const tests = await tb.getTests(10, 20); // offset: 10, limit: 20
`

#### getTestDetails
Gets details for a single test, pass the WebDriver's SessionID

`javascript
// Callback style
tb.getTestDetails(sessionId, function(error, testDetails) {});

// Async/await style
const testDetails = await tb.getTestDetails(sessionId);
`

#### updateTest
Updates a single test. For example, update the passed state of a test (whether it was successful or not).

`javascript
const testData = { "test[success]" : "1", "test[status_message]" : "test" };

// Callback style
tb.updateTest(testData, sessionId, function(error, testDetails) {});

// Async/await style
const testDetails = await tb.updateTest(testData, sessionId);
`

#### deleteTest
Deletes a single test, pass the WebDriver's SessionID

`javascript
// Callback style
tb.deleteTest(sessionId, function(error, success) {});

// Async/await style
const success = await tb.deleteTest(sessionId);
`

#### stopTest
Stops a single test, pass the WebDriver's SessionID

`javascript
// Callback style
tb.stopTest(sessionId, function(error, success) {});

// Async/await style
const success = await tb.stopTest(sessionId);
`

$3

#### getTunnelList
Gets list of active tunnels

`javascript
// Callback style
tb.getTunnelList(function(error, tunnelList) {});

// Async/await style
const tunnelList = await tb.getTunnelList();
`

#### deleteTunnel
Deletes a single Tunnel

`javascript
// Callback style
tb.deleteTunnel(tunnelId, function(error, success) {});

// Async/await style
const success = await tb.deleteTunnel(tunnelId);
`

$3

#### getBuilds
Retrieves the latest builds

`javascript
// Callback style
tb.getBuilds(offset, limit, function(error, builds) {});

// Async/await style
const builds = await tb.getBuilds();

// With pagination
const builds = await tb.getBuilds(10, 20); // offset: 10, limit: 20
`

#### getTestsForBuild
Retrieves the tests for a single build

`javascript
// Callback style
tb.getTestsForBuild(buildId, function(error, tests) {});

// Async/await style
const tests = await tb.getTestsForBuild(buildId);
`

#### deleteBuild
Deletes a single build

`javascript
// Callback style
tb.deleteBuild(buildId, function(error, success) {});

// Async/await style
const success = await tb.deleteBuild(buildId);
`

$3

#### uploadFile
Uploads a local file to TestingBot Storage

`javascript
// Callback style
tb.uploadFile(localFilePath, function(error, appUrl) {});

// Async/await style
const appUrl = await tb.uploadFile(localFilePath);
`

#### uploadRemoteFile
Uploads a remote file to TestingBot Storage

`javascript
// Callback style
tb.uploadRemoteFile(remoteFileUrl, function(error, appUrl) {});

// Async/await style
const appUrl = await tb.uploadRemoteFile(remoteFileUrl);
`

#### getStorageFile
Retrieve data from a previously uploaded file

`javascript
// Callback style
tb.getStorageFile(appUrl, function(error, fileDetails) {});

// Async/await style
const fileDetails = await tb.getStorageFile(appUrl);
`

#### getStorageFiles
Retrieve list of previously uploaded files

`javascript
// Callback style
tb.getStorageFiles(offset, limit, function(error, fileDetails) {});

// Async/await style
const fileDetails = await tb.getStorageFiles();

// With pagination
const fileDetails = await tb.getStorageFiles(10, 20); // offset: 10, limit: 20
`

#### deleteStorageFile
Delete a previously uploaded file

`javascript
// Callback style
tb.deleteStorageFile(appUrl, function(error, success) {});

// Async/await style
const success = await tb.deleteStorageFile(appUrl);
`

#### getAuthenticationHashForSharing
Calculates the authentication hash for sharing, pass the WebDriver's SessionID.
This is used to share a test's detail page on TestingBot

`javascript
// This method is synchronous and returns the hash directly
const hash = tb.getAuthenticationHashForSharing(sessionId);
`

$3

#### takeScreenshot
Takes screenshots for the specific browsers

`javascript
// Callback style
tb.takeScreenshot(url, browsers, waitTime, resolution, fullPage, callbackURL, function(error, screenshots) {});

// Async/await style
const screenshots = await tb.takeScreenshot(
'https://example.com', // url - required
[{ browserName: 'chrome', version: 'latest', os: 'WIN11' }], // browsers - required
'1920x1080', // resolution - required
5000, // waitTime (ms) - optional
true, // fullPage - optional
'https://your-callback.com' // callbackURL - optional
);
`
Once a screenshot job is running, you can use retrieveScreenshots to poll for the results.

#### retrieveScreenshots
Retrieves screenshots for a specific takeScreenshot call

`javascript
// Callback style
tb.retrieveScreenshots(screenshotId, function(error, screenshots) {});

// Async/await style
const screenshots = await tb.retrieveScreenshots(screenshotId);
`

#### getScreenshotList
Retrieves all screenshots previously generated with your account

`javascript
// Callback style
tb.getScreenshotList(offset, limit, function(error, screenshots) {});

// Async/await style
const screenshots = await tb.getScreenshotList();

// With pagination
const screenshots = await tb.getScreenshotList(10, 20); // offset: 10, limit: 20
`

$3

#### getTeam
Retrieves team settings

`javascript
// Callback style
tb.getTeam(function(error, data) {});

// Async/await style
const teamInfo = await tb.getTeam();
`

#### getUsersInTeam
Get all users in your team

`javascript
// Callback style
tb.getUsersInTeam(function(error, users) {});

// Async/await style
const users = await tb.getUsersInTeam();
`

#### getUserFromTeam
Retrieves information about a specific user in your team

`javascript
// Callback style
tb.getUserFromTeam(userId, function(error, user) {});

// Async/await style
const user = await tb.getUserFromTeam(userId);
`

#### createUserInTeam
Add a user to your team. You need ADMIN rights for this.

`javascript
const userData = {
'user[first_name]': 'John',
'user[last_name]': 'Doe',
'user[email]': 'john@example.com'
};

// Callback style
tb.createUserInTeam(userData, function(error, result) {});

// Async/await style
const result = await tb.createUserInTeam(userData);
`

#### updateUserInTeam
Update a user in your team. You need ADMIN rights for this.

`javascript
const userData = {
'user[first_name]': 'Jane',
'user[last_name]': 'Smith'
};

// Callback style
tb.updateUserInTeam(userId, userData, function(error, result) {});

// Async/await style
const result = await tb.updateUserInTeam(userId, userData);
`

#### resetCredentials
Resets credentials for a specific user in your team. You need ADMIN rights for this.

`javascript
// Callback style
tb.resetCredentials(userId, function(error, result) {});

// Async/await style
const result = await tb.resetCredentials(userId);
`

$3

Codeless tests allow you to create automated tests without writing code. These tests can be configured to run on a schedule and include AI-powered test generation.

#### getCodelessTests
Retrieves a list of codeless tests

`javascript
// Callback style
tb.getCodelessTests(offset, limit, function(error, tests) {});

// Async/await style
const tests = await tb.getCodelessTests(0, 10); // offset: 0, limit: 10
`

#### createCodelessTest
Creates a new codeless test

`javascript
const testData = {
name: 'My Codeless Test', // Required: Test name
url: 'https://example.com', // Required: URL to test
cron: '0 0 *', // Optional: Cron schedule
screenshot: true, // Optional: Take screenshots
video: false, // Optional: Record video
idletimeout: 60, // Optional: Idle timeout in seconds
screenresolution: '1920x1080', // Optional: Screen resolution
ai_prompt: 'Test the login flow' // Optional: AI test agent prompt
};

// Callback style
tb.createCodelessTest(testData, function(error, result) {});

// Async/await style
const result = await tb.createCodelessTest(testData);
`

#### updateCodelessTest
Updates an existing codeless test

`javascript
const updateData = {
test: {
name: 'Updated Test Name',
cron: '0 12 *'
}
};

// Callback style
tb.updateCodelessTest(updateData, testId, function(error, result) {});

// Async/await style
const result = await tb.updateCodelessTest(updateData, testId);
`

#### deleteCodelessTest
Deletes a codeless test

`javascript
// Callback style
tb.deleteCodelessTest(testId, function(error, result) {});

// Async/await style
const result = await tb.deleteCodelessTest(testId);
`

CLI Usage

The TestingBot API package includes a command-line interface for quick access to API functionality.

$3

`bash


Install globally for CLI access

npm install -g testingbot-api

Or use npx with local installation

npx testingbot
`

$3

The CLI uses the same authentication methods as the API client:
- Environment variables: TB_KEY and TB_SECRET or TESTINGBOT_KEY and TESTINGBOT_SECRET
- Configuration file: ~/.testingbot with api_key and api_secret

$3

`bash


User management

testingbot user info # Get user information
testingbot user update # Update user information

Test management

testingbot tests list [offset] [limit] # List tests
testingbot tests get # Get test details
testingbot tests delete # Delete a test
testingbot tests stop # Stop a running test

Codeless tests (Lab)

testingbot lab list [offset] [limit] # List codeless tests
testingbot lab create # Create a codeless test
testingbot lab update # Update a codeless test
testingbot lab delete # Delete a codeless test

Browsers and devices

testingbot browsers list [type] # List browsers (type: all|web|mobile|real)
testingbot devices list # List all devices
testingbot devices available # List available devices

Storage

testingbot storage upload # Upload a file
testingbot storage list [offset] [limit] # List stored files
testingbot storage delete # Delete a stored file

Help

testingbot --help # Show help
testingbot --version # Show version
`

$3

`bash


Create a codeless test

testingbot lab create '{
"name": "Homepage Test",
"url": "https://example.com",
"cron": "0 0 *",
"screenshot": true,
"ai_prompt": "Test the homepage loads correctly"
}'

List recent tests

testingbot tests list 0 20

Get browser list

testingbot browsers list web

Upload a file to storage

testingbot storage upload ./test-app.zip
`

Complete Examples

$3

`javascript
const TestingBot = require('testingbot-api');

const tb = new TestingBot({
api_key: "your-tb-key",
api_secret: "your-tb-secret"
});

async function runTests() {
try {
// Get user information
const userInfo = await tb.getUserInfo();
console.log('User:', userInfo);

// Get available browsers
const browsers = await tb.getBrowsers();
console.log('Available browsers:', browsers.length);

// Get recent tests
const tests = await tb.getTests(0, 10);
console.log('Recent tests:', tests.length);

// Get test details for the first test
if (tests.length > 0) {
const testDetails = await tb.getTestDetails(tests[0].session_id);
console.log('Test details:', testDetails);
}

// Upload a file
const appUrl = await tb.uploadFile('/path/to/your/app.apk');
console.log('Uploaded file:', appUrl);

// Take screenshots
const screenshots = await tb.takeScreenshot(
'https://testingbot.com',
[{ browserName: 'chrome', version: 'latest', os: 'WIN11' }],
'1280x1024'
);
console.log('Screenshots:', screenshots);

} catch (error) {
console.error('Error:', error);
}
}

runTests();
`




Testing

Run the test suite:

`bash
npm test
`

Note: Tests require valid TestingBot credentials set as environment variables (TB_KEY and TB_SECRET`).

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

See the LICENSE file for details.

Support

- Documentation: TestingBot REST API
- Issues: GitHub Issues

More documentation

Check out the TestingBot REST API for more information.