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

Core Features

• 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

npm install testingbot-api

Quick Start

1. Get your credentials

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

2. Set up authentication

You can authenticate in three ways:

Environment variables (recommended)

export TESTINGBOT_KEY="your-api-key"
export TESTINGBOT_SECRET="your-api-secret"

Constructor options

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

Configuration file

Create a ~/.testingbot file with your credentials

3. Initialize the client

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

Browser & Device Management

getBrowsers

Gets a list of browsers you can test on

// 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

// 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

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

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

getDevice

Gets details for a specific physical device

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

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

Session Management

createSession

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

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:

{
  "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.

User Management

getUserInfo

Gets your user information

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

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

updateUserInfo

Updates your user information

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

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

Test Management

getTests

Gets list of your latest tests

// 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

// 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).

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

// 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

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

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

Tunnel Management

getTunnelList

Gets list of active tunnels

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

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

deleteTunnel

Deletes a single Tunnel

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

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

Build Management

getBuilds

Retrieves the latest builds

// 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

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

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

deleteBuild

Deletes a single build

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

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

Storage Management

uploadFile

Uploads a local file to TestingBot Storage

// 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

// 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

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

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

getStorageFiles

Retrieve list of previously uploaded files

// 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

// 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

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

Screenshots

takeScreenshot

Takes screenshots for the specific browsers

// 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

// 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

// 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

Team Management

getTeam

Retrieves team settings

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

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

getUsersInTeam

Get all users in your team

// 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

// 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.

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.

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.

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

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

Codeless Tests

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

// 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

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

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

// 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.

Installation

# Install globally for CLI access
npm install -g testingbot-api

# Or use npx with local installation
npx testingbot <command>

Authentication

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

Available Commands

# User management
testingbot user info                    # Get user information
testingbot user update <json>           # Update user information

# Test management
testingbot tests list [offset] [limit]  # List tests
testingbot tests get <id>               # Get test details
testingbot tests delete <id>            # Delete a test
testingbot tests stop <id>              # Stop a running test

# Codeless tests (Lab)
testingbot lab list [offset] [limit]    # List codeless tests
testingbot lab create <json>            # Create a codeless test
testingbot lab update <id> <json>       # Update a codeless test
testingbot lab delete <id>              # 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 <file>        # Upload a file
testingbot storage list [offset] [limit] # List stored files
testingbot storage delete <id>          # Delete a stored file

# Help
testingbot --help                       # Show help
testingbot --version                    # Show version

CLI Examples

# 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

Basic Usage

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:

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.