Skip to main content

Tests & Builds

Fetch test results, report pass/fail state back from your CI, and work with the builds that group them.

Endpoint
api.testingbot.com
Version
v1
Format
JSON
Auth
HTTP Basic
GET /v1/tests

List your tests

Paginated list of every test session belonging to the authenticated account, newest first. Filter by browser_id, group, or build to narrow the result. Use since to fetch only tests updated after a UNIX timestamp (poll-friendly).

Arguments

offset integer
Skip this many tests from the start of the result set.
count integer max=500
Number of tests to return .
since integer
UNIX timestamp; return only tests updated at or after this time.
browser_id integer
Filter to tests that ran on this browser_id (from /v1/browsers).
group string
Filter to tests tagged with this group name.
build string
Filter to tests in this build (matches capabilities.build).
skip_fields string
Comma-separated fields to omit (logs, thumbs).

Response fields

data array of test case objects
Test sessions for this page.
meta meta object
—
realtime object
ActionCable channel details for live updates. Only present on the since-polling form of this endpoint.
GET /v1/tests
Request
$ curl "https://api.testingbot.com/v1/tests?offset=0&count=10" \
-u key:secret
var client = new TestingBotClient(key, secret);
var tests = await client.Tests.ListAsync();
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.get_tests(0, 10)
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.tests.get_tests(offset=0, limit=10)
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->getJobs(0, 10);
TestingbotREST restApi = new TestingbotREST(key, secret);
TestingbotTestCollection tests = restApi.getTests(0, 10);
const TestingBot = require('testingbot-api');

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

const tests = await api.getTests({ offset, limit });
Response
{
  "data": [
    {
      "created_at": "2011-07-30T23:21:23Z",
      "completed_at": "2011-07-30T23:22:44Z",
      "id": 3,
      "name": "MyTest::testTitle",
      "session_id": "f7903f9e93e74fe1b0e924bf9d2ce9fc",
      "status_message": "Failed asserting that 1 equals 0.",
      "status_id": 0,
      "success": false,
      "browser": "iexplore",
      "browser_version": 8,
      "os": "WINDOWS",
      "duration": 13,
      "build": "buildid",
      "video": "https://s3.amazonaws.com/rectestingbot/sample.mp4",
      "groups": ["testingbot.com"]
    }
  ],
  "meta": { "offset": 0, "count": 10, "total": 789 }
}
GET /v1/tests/:id

Get a specific test

Returns the full detail record for a single test session: status, environment (browser/OS or device/platform), assets (video, logs, screenshots), groups, build, and duration. Accepts either the numeric test ID or the WebDriver session_id.

Arguments

id string required
Numeric test ID or WebDriver session_id (UUID).
skip_fields string
Comma-separated fields to omit from the response (logs, thumbs, visual_run, groups).

Response fields

id integer
Unique numeric test ID.
session_id string
Selenium / WebDriver session ID (UUID).
name string
Human-readable test name set via capabilities or update_test.
state string
Lifecycle state (RUNNING, COMPLETE, TIMEOUT, …).
success boolean
Whether the test passed.
status_id integer
Numeric status code (0=fail, 1=pass, 2=unknown).
unknown boolean
Convenience flag, true when status_id is 2 (the test finished without reporting a pass/fail).
status_message string
Failure reason or arbitrary status set via test[status_message].
created_at timestamp
When the test session started.
completed_at timestamp
When the session ended; null while running.
duration integer
Total run time in seconds.
browser string
Browser identifier (e.g. "iexplore", "firefox").
browser_version integer
Browser major version.
os string
OS (e.g. "WINDOWS", "MAC").
device_name string
Mobile device name when the session ran on a physical device; null otherwise.
platform_name string
Mobile OS name; null on desktop.
build string
Build identifier (free-form string set via capabilities).
groups array of string
Tag/group names attached to the test.
video string
Signed S3 URL to the recorded video, or false if video was disabled.
thumbs array of string
Signed S3 URLs to screenshot thumbnails.
logs object
Map of log names → signed S3 URLs (selenium, browser, …).
assets_available boolean
Whether assets (video, logs, screenshots) have finished processing.
extra string
Arbitrary metadata string set via test[extra].
type string
Driver type (WEBDRIVER, APPIUM).
steps string
Rendered HTML of the recorded step list. Omit with skip_fields=steps.
running integer
Completion percentage. Only present while a Codeless test is still running.
GET /v1/tests/:id
Request
$ curl "https://api.testingbot.com/v1/tests/:id" -u key:secret
var client = new TestingBotClient(key, secret);
var test = await client.Tests.GetAsync(testId);
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.get_test(test_id)
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.tests.get_test(test_id)
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->getJob($test_id);
TestingbotREST restApi = new TestingbotREST(key, secret);
TestingbotTest test = restApi.getTest(test_id);
const TestingBot = require('testingbot-api');

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

const test = await api.getTestDetails(testId);
Response
{
  "id": 3,
  "name": "MyTest::testTitle",
  "session_id": "f7903f9e93e74fe1b0e924bf9d2ce9fc",
  "state": "COMPLETE",
  "success": false,
  "status_id": 0,
  "unknown": false,
  "status_message": "Failed asserting that 1 equals 0.",
  "created_at": "2011-07-30T23:21:23Z",
  "completed_at": "2011-07-30T23:22:23Z",
  "duration": 60,
  "browser": "iexplore",
  "browser_version": 8,
  "os": "WINDOWS",
  "device_name": null,
  "platform_name": null,
  "build": null,
  "groups": ["testingbot.com"],
  "video": "https://s3.amazonaws.com/rectestingbot/sample.mp4",
  "thumbs": ["https://s3.amazonaws.com/euthumbtestingbot/3_f93782fji.jpg"],
  "logs": { "selenium": "https://s3-eu-west-1.amazonaws.com/eulogtestingbot/session.txt" },
  "assets_available": true,
  "type": "WEBDRIVER"
}
PUT /v1/tests/:id

Update a test

Updates a test's metadata after it's been recorded. Use this to mark a test as passed/failed from the test runner, attach groups/tags, set a build identifier, or add a status message. Accepts either a numeric test ID or a WebDriver session_id.

Arguments

id string required
Numeric test ID or WebDriver session_id (UUID).
test[name] string
Human-readable test name.
test[success] boolean
true=pass, false=fail.
test[status_message] string
Failure reason or arbitrary status text.
test[extra] string
Arbitrary metadata.
test[build] string
Build identifier to associate this test with.
test[public] boolean
When true, makes the test publicly viewable via share URL.
groups string
Comma-separated string or array of tag/group names to attach to the test.
build string
Build identifier (alternative location to test[build]).

Response fields

success boolean
Whether the operation succeeded.
errors object
Validation errors keyed by field name. Only present when success is false.
error string
Single human-readable reason, used by the older endpoints in place of errors. Only present when success is false.
PUT /v1/tests/:id
Request
$ curl "https://api.testingbot.com/v1/tests/:id" \
-X PUT \
-d "test[success]=1" \
-d "groups[]=regression" \
-u key:secret
var client = new TestingBotClient(key, secret);
await client.Tests.UpdateAsync(testId, new TestUpdate { Success = true, Groups = new[] { "regression" } });
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.update_test(test_id, { name: 'new_name', success: true })
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.tests.update_test(test_id, status_message='..', passed=1, build='..', name='..')
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->updateJob($test_id, ['name' => 'mytest', 'success' => true]);
TestingbotREST restApi = new TestingbotREST(key, secret);
boolean success = restApi.updateTest(testId, details);
const TestingBot = require('testingbot-api');

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

await api.updateTest({ 'test[success]': '1', 'test[status_message]': 'failure reason' }, testId);
Response
{
  "success": true
}
DELETE /v1/tests/:id

Delete a test

Permanently deletes a test session and every associated asset (video, logs, screenshots). This action cannot be undone.

Arguments

id string required
Numeric test ID or WebDriver session_id of the test to delete.
DELETE /v1/tests/:id
Request
$ curl "https://api.testingbot.com/v1/tests/:id" \
-X DELETE \
-u key:secret
var client = new TestingBotClient(key, secret);
await client.Tests.DeleteAsync(testId);
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.delete_test(test_id)
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.tests.delete_test(test_id)
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->deleteJob($test_id);
TestingbotREST restApi = new TestingbotREST(key, secret);
boolean success = restApi.deleteTest(testId);
const TestingBot = require('testingbot-api');

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

await api.deleteTest(testId);
Response
{
  "success": true
}
PUT /v1/tests/:id/stop

Stop a running test

Terminates an in-flight test session. The test is marked complete; any assets gathered (video, logs, screenshots) become available for download. Returns 404 if the test has already finished.

Arguments

id string required
Numeric test ID or WebDriver session_id of the test to stop.

Response fields

success boolean
Whether the operation succeeded.
errors object
Validation errors keyed by field name. Only present when success is false.
error string
Single human-readable reason, used by the older endpoints in place of errors. Only present when success is false.
PUT /v1/tests/:id/stop
Request
$ curl "https://api.testingbot.com/v1/tests/:id/stop" \
-X PUT \
-u key:secret
var client = new TestingBotClient(key, secret);
await client.Tests.StopAsync(testId);
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.stop_test(test_id)
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.tests.stop_test(test_id)
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->stopJob($test_id);
TestingbotREST restApi = new TestingbotREST(key, secret);
boolean success = restApi.stopTest(testId);
const TestingBot = require('testingbot-api');

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

await api.stopTest(testId);
Response
{
  "success": true
}
POST /v1/tests

Create a test record (manual sessions)

Creates a TestCase record from outside the WebDriver/Appium flow. Mainly used by clients that want to log a manual or external test result against their TestingBot account. Most users will not need this — the normal flow is to start a Selenium/Appium session, and the record is created automatically.

Arguments

test[name] string required
Test name.
test[test_environment_id] integer required
Browser environment the result is attributed to (browser_id from GET /v1/browsers).
test[success] boolean
true=pass, false=fail.
test[status_message] string
Failure reason or status string.
test[extra] string
Arbitrary metadata.
test[build] string
Build identifier.
POST /v1/tests
Request
$ curl -X POST "https://api.testingbot.com/v1/tests" \
-u key:secret \
-d "test[name]=MyTest::testTitle" \
-d "test[test_environment_id]=1" \
-d "test[success]=true"
$client = new TestingBot\Client($key, $secret);
$client->tests()->create([
    'name' => 'MyTest::testTitle',
    'test_environment_id' => 1,
    'success' => true,
]);
TestingbotREST restApi = new TestingbotREST(key, secret);
Map<String, Object> test = Map.of(
    "name", "MyTest::testTitle",
    "test_environment_id", 1,
    "success", true);
boolean success = restApi.createTest(test);
POST /v1/tests/{id}

Update a test (POST alias)

Alias of PUT /v1/tests/:id for clients that cannot send PUT requests (some older HTTP libraries). Same body schema and behavior — see PUT for the canonical form.

Arguments

id string required
Numeric test ID or WebDriver session_id (UUID).
test[name] string
Human-readable test name.
test[success] boolean
true=pass, false=fail.
test[status_message] string
Failure reason or arbitrary status text.
test[extra] string
Arbitrary metadata.
test[build] string
Build identifier to associate this test with.
test[public] boolean
When true, makes the test publicly viewable via share URL.
groups string
Comma-separated string or array of tag/group names to attach to the test.
POST /v1/tests/{id}
Request
$ curl -X POST "https://api.testingbot.com/v1/tests/{id}" \
-u key:secret
GET /v1/builds

List your builds

Returns a paginated list of test builds. A build is an aggregation of test cases that share the same capabilities.build identifier, useful for grouping CI runs.

Arguments

offset integer
Skip this many builds from the start of the result set.
count integer max=500
Number of builds to return .

Response fields

data array of build objects
Builds for this page.
meta meta object
—
GET /v1/builds
Request
$ curl "https://api.testingbot.com/v1/builds?offset=0&count=10" \
-u key:secret
var client = new TestingBotClient(key, secret);
var builds = await client.Builds.ListAsync();
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.get_builds(0, 10)
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.build.get_builds(offset=0, limit=10)
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->getBuilds(0, 10);
TestingbotREST restApi = new TestingbotREST(key, secret);
TestingbotBuildCollection builds = restApi.getBuilds(0, 10);
const TestingBot = require('testingbot-api');

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

const builds = await api.getBuilds(offset, limit);
Response
{
  "data": [
    {
      "id": 4331,
      "build_identifier": "first-build",
      "created_at": "2016-08-01T11:09:02.000Z",
      "updated_at": "2016-08-01T11:09:02.000Z"
    }
  ],
  "meta": { "offset": 0, "count": 10, "total": 3 }
}
GET /v1/builds/:id

Get tests for a build

Returns all test cases that belong to a single build, with pagination. The build can be referenced by either its numeric internal ID or the string identifier you set via capabilities.build.

Arguments

id string required
Numeric build ID or string build identifier.
offset integer
Skip this many tests in the build.
count integer max=500
Number of tests to return .
skip_fields string
Comma-separated fields to omit from each test (logs, thumbs).

Response fields

data array of test case objects
Test sessions for this page.
meta meta object
—
realtime object
ActionCable channel details for live updates. Only present on the since-polling form of this endpoint.
GET /v1/builds/:id
Request
$ curl "https://api.testingbot.com/v1/builds/:id" \
-u key:secret
var client = new TestingBotClient(key, secret);
var tests = await client.Builds.GetTestsAsync(buildId);
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.get_build(build_identifier)
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.build.get_tests_for_build(build_id)
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->getBuild($build_id);
TestingbotREST restApi = new TestingbotREST(key, secret);
TestingbotTestBuildCollection tests = restApi.getTestsForBuild(buildId);
const TestingBot = require('testingbot-api');

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

const tests = await api.getTestsForBuild(buildId);
Response
{
  "data": [
    {
      "id": 3,
      "name": "MyTest::testTitle",
      "session_id": "f7903f9e93e74fe1b0e924bf9d2ce9fc",
      "state": "COMPLETE",
      "success": false,
      "status_id": 0,
      "created_at": "2011-07-30T23:21:23Z",
      "completed_at": "2011-07-30T23:22:44Z",
      "duration": 13,
      "browser": "iexplore",
      "browser_version": 8,
      "os": "WINDOWS",
      "build": "buildid",
      "video": "https://s3.amazonaws.com/rectestingbot/sample.mp4"
    }
  ],
  "meta": { "offset": 0, "count": 10, "total": 1 }
}
DELETE /v1/builds/:id

Delete a build

Permanently deletes a build and every test, asset (video, logs, screenshots) attached to it. This action cannot be undone.

Arguments

id string required
Numeric build ID or string build identifier to delete.
DELETE /v1/builds/:id
Request
$ curl "https://api.testingbot.com/v1/builds/:id" \
-X DELETE \
-u key:secret
var client = new TestingBotClient(key, secret);
await client.Builds.DeleteAsync(buildId);
require 'testingbot'
api = TestingBot::Api.new(key, secret)
api.delete_build(build_identifier)
import testingbotclient
tb = testingbotclient.TestingBotClient(key, secret)
tb.build.delete_build(build_id)
$api = new TestingBot\TestingBotAPI($key, $secret);
$api->deleteBuild($build_id);
TestingbotREST restApi = new TestingbotREST(key, secret);
boolean success = restApi.deleteBuild(buildId);
const TestingBot = require('testingbot-api');

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

await api.deleteBuild(buildId);
Response
{
  "success": true
}
POST /v1/builds/{id}/ci

Link a build to a commit for CI status checks

Associates a CI build with the commit/PR it ran for on a code host and posts an in-progress status check. Currently supports github (requires the TestingBot GitHub App installed on the repository owner). Call this at the start of a workflow run.

Arguments

id string required
Build identifier (capabilities.build) for this run.
repo string required
Repository in owner/name form.
commit_sha string required
Head commit SHA the build ran for. For pull_request events use github.event.pull_request.head.sha (not the merge commit) so the check lands on the SHA branch protection evaluates.
provider string
Code host provider. Currently only "github".
branch string
Git branch name.
pull_request_number integer
Pull request number, if any.
POST /v1/builds/{id}/ci
Request
$ curl -X POST "https://api.testingbot.com/v1/builds/{id}/ci" \
-u key:secret \
-d "repo=my-org/my-repo" \
-d "commit_sha=9fceb02d0ae598e95dc970b74767f19372d61af8" \
-d "branch=main"
PUT /v1/builds/{id}/ci

Report a CI status-check build as finished

Signals that the CI run for this build has finished, so the status check is updated with the aggregate pass/fail result. Call this after your tests complete.

Arguments

id string required
Build identifier (capabilities.build) for this run.
provider string
Code host provider. Currently only "github".

Response fields

success boolean
Whether the operation succeeded.
errors object
Validation errors keyed by field name. Only present when success is false.
error string
Single human-readable reason, used by the older endpoints in place of errors. Only present when success is false.
PUT /v1/builds/{id}/ci
Request
$ curl -X PUT "https://api.testingbot.com/v1/builds/{id}/ci" \
-u key:secret
Was this page helpful?
Last updated
TestingBot Docs