Skip to main content

App Automate

Everything for native mobile test runs: Maestro flows, Espresso and XCUITest suites, and their reports.

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

App Automate: Espresso

POST /v1/app-automate/espresso/app

Upload an Android app for Espresso

Uploads the production .apk you want to test under Espresso. Returns the app_url to reference when starting a run.
POST /v1/app-automate/espresso/app
Request
$ curl -X POST "https://api.testingbot.com/v1/app-automate/espresso/app" \
-u key:secret
GET /v1/app-automate/espresso/{id}

Get an Espresso project

Returns the metadata and current state of an Espresso project.

Arguments

id integer required
—

Response fields

runs array of object
Runs belonging to the project.
success boolean
True when every run in the project passed.
completed boolean
True when every run has reached a terminal state.
GET /v1/app-automate/espresso/{id}
Request
$ curl "https://api.testingbot.com/v1/app-automate/espresso/{id}" \
-u key:secret
GET /v1/app-automate/espresso/{id}/report

Get the Espresso JUnit report

Returns the JUnit-format XML report for an Espresso run once it has completed.

Arguments

id integer required
—
GET /v1/app-automate/espresso/{id}/report
Request
$ curl "https://api.testingbot.com/v1/app-automate/espresso/{id}/report" \
-u key:secret
POST /v1/app-automate/espresso/{id}/run

Run an Espresso test suite

Triggers an asynchronous Espresso run across the requested device capabilities. Returns run metadata; poll status via the standard tests API.

Arguments

id integer required
—
POST /v1/app-automate/espresso/{id}/run
Request
$ curl -X POST "https://api.testingbot.com/v1/app-automate/espresso/{id}/run" \
-u key:secret
POST /v1/app-automate/espresso/{id}/tests

Upload Espresso test APK

Attaches an Espresso test .apk (the instrumented test bundle) to a project. Pair with /app to provide both halves of the test.

Arguments

id integer required
—
POST /v1/app-automate/espresso/{id}/tests
Request
$ curl -X POST "https://api.testingbot.com/v1/app-automate/espresso/{id}/tests" \
-u key:secret
GET /v1/app-automate/espresso/{project_id}/{id}

Get a specific Espresso run

Returns the detail record for a single Espresso run inside a project.

Arguments

project_id integer required
—
id integer required
—

Response fields

id integer
Unique numeric Espresso run ID.
created_at timestamp
—
status string
WAITING, READY, DONE or FAILED.
capabilities object
Capabilities the run was started with.
success boolean
Whether the run passed. False until a session has completed.
report object
Test counts and per-test results for the run.
test object
Session detail. Only present once a session has been allocated.
GET /v1/app-automate/espresso/{project_id}/{id}
Request
$ curl "https://api.testingbot.com/v1/app-automate/espresso/{project_id}/{id}" \
-u key:secret

App Automate: Maestro

GET /v1/app-automate/maestro

List your Maestro projects

Paginated list of Maestro app-automate projects (one per uploaded test bundle) on the account, newest first.

Response fields

data array of maestro project objects
Projects for this page, newest first.
meta meta object
—
GET /v1/app-automate/maestro
Request
$ curl "https://api.testingbot.com/v1/app-automate/maestro" \
-u key:secret
POST /v1/app-automate/maestro/app

Upload an Android/iOS app for Maestro

Uploads an .apk / .ipa to attach to a Maestro project. Returns the app_url (tb://<appkey>) you'll pass as a capability when running the project.

Arguments

file string required
—
checksum string
MD5 checksum (base64) of the app file for deduplication
POST /v1/app-automate/maestro/app
Request
$ curl -X POST "https://api.testingbot.com/v1/app-automate/maestro/app" \
-u key:secret \
-F "file=@/path/to/app/file/Application-debug.apk"
POST /v1/app-automate/maestro/app/checksum

Check whether an app needs uploading

Returns whether a binary identified by checksum already exists in TestingBot Storage. Used by the CLI to skip re-uploading unchanged apps.

Arguments

checksum string required
MD5 checksum (base64) of the app file
POST /v1/app-automate/maestro/app/checksum
Request
$ curl -X POST "https://api.testingbot.com/v1/app-automate/maestro/app/checksum" \
-u key:secret \
-d "checksum=$(openssl md5 -binary Application-debug.apk | base64)"
POST /v1/app-automate/maestro/other-apps

Upload additional apps for a Maestro session

Uploads supplementary .apk/.ipa binaries that should be installed alongside the primary app under test (e.g. dependent apps, test runners).

Arguments

file string required
—
POST /v1/app-automate/maestro/other-apps
Request
$ curl -X POST "https://api.testingbot.com/v1/app-automate/maestro/other-apps" \
-u key:secret \
-F "file=@/path/to/app/file/DependencyApp-debug.apk"
GET /v1/app-automate/maestro/runs

List your Maestro runs

Paginated list of Maestro app-automate runs across all projects on the account, newest first. Lightweight: no reports are inflated. Use GET /:project_id/:id for a single run's full results.

Response fields

data array of maestro run summary objects
Runs for this page, newest first.
meta meta object
—
GET /v1/app-automate/maestro/runs
Request
$ curl "https://api.testingbot.com/v1/app-automate/maestro/runs" \
-u key:secret
GET /v1/app-automate/maestro/runs/{build_name}

Look up Maestro runs by build name

Resolves a build/run name to every matching run on the account (a build can fan out to multiple device runs). Returns project_id + run_id without inflating reports. Use GET /:project_id/:id for a single run's full results.

Arguments

build_name string required
—

Response fields

data array of maestro run summary objects
Every run submitted under this build name, newest first.
GET /v1/app-automate/maestro/runs/{build_name}
Request
$ curl "https://api.testingbot.com/v1/app-automate/maestro/runs/{build_name}" \
-u key:secret
GET /v1/app-automate/maestro/{id}

Get a Maestro project

Returns the metadata and current state of a single Maestro app-automate project.

Arguments

id integer required
—

Response fields

runs array of object
Runs belonging to the project.
success boolean
True when every run in the project passed.
completed boolean
True when every run has reached a terminal state.
GET /v1/app-automate/maestro/{id}
Request
$ curl "https://api.testingbot.com/v1/app-automate/maestro/{id}" \
-u key:secret
POST /v1/app-automate/maestro/{id}/run

Run a Maestro app flow

Triggers an asynchronous Maestro run on the uploaded project against one or more device capabilities. Returns one run entry per capability.

Arguments

id integer required
—
POST /v1/app-automate/maestro/{id}/run
Request
$ curl -X POST "https://api.testingbot.com/v1/app-automate/maestro/{id}/run" \
-u key:secret
POST /v1/app-automate/maestro/{id}/step

Append a step to a Maestro run

Logs an individual Maestro step result against a running project — used by the Maestro runner to stream per-step status to the dashboard.

Arguments

id integer required
—
POST /v1/app-automate/maestro/{id}/step
Request
$ curl -X POST "https://api.testingbot.com/v1/app-automate/maestro/{id}/step" \
-u key:secret
POST /v1/app-automate/maestro/{id}/tests

Upload a Maestro test bundle

Attaches a Maestro flow archive (.zip or .yaml) to an existing Maestro project. Replaces any previously uploaded tests for that project.

Arguments

id integer required
—
POST /v1/app-automate/maestro/{id}/tests
Request
$ curl -X POST "https://api.testingbot.com/v1/app-automate/maestro/{id}/tests" \
-u key:secret
GET /v1/app-automate/maestro/{project_id}/{id}

Get a specific Maestro run

Returns the detail record for a single Maestro run inside a project, including capability used, status, and per-flow results.

Arguments

project_id integer required
—
id integer required
—

Response fields

id integer
Unique numeric Maestro run ID.
status string
WAITING, READY, DONE, FAILED or CANCELLED, computed from the newest attempt of each flow.
success integer
1 when every flow passed, 0 otherwise.
capabilities object
Capabilities the run was started with.
options object
Maestro options the run was started with; {} when none were given.
created_at timestamp
—
completed boolean
Whether every run in the parent project has reached a terminal state.
assets_synced boolean
Whether asset processing has finished for every flow in the run.
meta object
Metadata supplied at submission. Only present when the run carries any.
report string
JUnit XML for the run. Only present once a report exists.
test object
Session detail. Only present once a session has been allocated.
assets object
Logs, video and screenshots. Only present once asset processing has finished.
environment object
Device the run was allocated. Only present once one has been assigned.
flows array of maestro flow result objects
Every flow attempt, including retries. Only present once the run has flows.
error_messages array of string
Run-level failures from the newest attempt of each flow, so a failure a retry has since fixed does not linger. Only present when the latest attempts reported any.
GET /v1/app-automate/maestro/{project_id}/{id}
Request
$ curl "https://api.testingbot.com/v1/app-automate/maestro/{project_id}/{id}" \
-u key:secret
POST /v1/app-automate/maestro/{project_id}/{run_id}/cancel

Cancel a Maestro run

Immediately cancels a queued or running Maestro run. The run is marked CANCELLED so its workers stop requesting devices and stop retrying, every flow that has not finished yet is closed out as cancelled, any device session the run already acquired is released, and any request still queued on the grid is dropped. Flows that already completed keep their results and reports. Cancelling is idempotent only in the sense that it is safe to call once: a run that has already reached a terminal state (DONE, FAILED or CANCELLED) returns 409.

Arguments

project_id integer required
Numeric Maestro project ID the run belongs to.
run_id integer required
Numeric Maestro run ID to cancel.

Response fields

success boolean
Whether the cancel was applied.
run object
The run in its post-cancel state.
cancelled_flow_count integer
How many flows were still queued or running and got closed out. 0 means the run held no unfinished flows (its device session, if any, is still released).
POST /v1/app-automate/maestro/{project_id}/{run_id}/cancel
Request
$ curl -X POST "https://api.testingbot.com/v1/app-automate/maestro/{project_id}/{run_id}/cancel" \
-u key:secret
GET /v1/app-automate/maestro/{project_id}/{run_id}/flow/{flow_id}

Get a Maestro flow result

Returns the per-step results, logs, and screenshots for one flow inside a Maestro run.

Arguments

project_id integer required
—
run_id integer required
—
flow_id integer required
—

Response fields

id integer
Unique numeric flow-attempt ID.
maestro_flow_id integer
The flow this attempt ran.
status string
WAITING, READY, DONE, FAILED or CANCELLED.
name string
Flow name(s) covered by this attempt.
requested_at timestamp
—
test_case_id integer
Test session backing this attempt. Only present once one has been allocated.
completed_at timestamp
Only present once the attempt has finished.
report string
JUnit XML for this attempt. Only present once a report exists.
shard_index integer
Shard this attempt covered. Only present on a sharded run.
success integer
1 when the flow passed. Only present on a terminal status.
error_messages array of string
Failure detail. Only present on a terminal status.
test object
Session detail. Only present once a session has been allocated.
assets object
Logs, video and screenshots. Only present once asset processing has finished.
assets_synced boolean
Whether this attempt's assets have finished processing.
GET /v1/app-automate/maestro/{project_id}/{run_id}/flow/{flow_id}
Request
$ curl "https://api.testingbot.com/v1/app-automate/maestro/{project_id}/{run_id}/flow/{flow_id}" \
-u key:secret
GET /v1/app-automate/maestro/{project_id}/{run_id}/html_report

Maestro run HTML report

Returns a hosted HTML report URL summarising the Maestro run results.

Arguments

project_id integer required
—
run_id integer required
—

Response fields

html_report string
Signed URL to the rendered HTML report.
GET /v1/app-automate/maestro/{project_id}/{run_id}/html_report
Request
$ curl "https://api.testingbot.com/v1/app-automate/maestro/{project_id}/{run_id}/html_report" \
-u key:secret
GET /v1/app-automate/maestro/{project_id}/{run_id}/html_report_detailed

Maestro run detailed HTML report

Returns a detailed per-step HTML report URL for the Maestro run, including screenshots and logs.

Arguments

project_id integer required
—
run_id integer required
—

Response fields

html_report_detailed string
Signed URL to the per-step HTML report.
GET /v1/app-automate/maestro/{project_id}/{run_id}/html_report_detailed
Request
$ curl "https://api.testingbot.com/v1/app-automate/maestro/{project_id}/{run_id}/html_report_detailed" \
-u key:secret
GET /v1/app-automate/maestro/{project_id}/{run_id}/junit_report

Maestro run JUnit report

Returns a JUnit-format XML report for a completed Maestro run. Suitable for ingestion by CI systems (Jenkins, GitHub Actions, etc.).

Arguments

project_id integer required
—
run_id integer required
—

Response fields

junit_report string
JUnit XML for the run, as a string.
GET /v1/app-automate/maestro/{project_id}/{run_id}/junit_report
Request
$ curl "https://api.testingbot.com/v1/app-automate/maestro/{project_id}/{run_id}/junit_report" \
-u key:secret
POST /v1/app-automate/maestro/{project_id}/{run_id}/retry

Retry a Maestro run

Re-runs an entire Maestro run. Creates a new run on the same device configuration (capabilities) and options, re-scheduling every flow. Returns the newly created run; poll it for status.

Arguments

project_id integer required
—
run_id integer required
—
POST /v1/app-automate/maestro/{project_id}/{run_id}/retry
Request
$ curl -X POST "https://api.testingbot.com/v1/app-automate/maestro/{project_id}/{run_id}/retry" \
-u key:secret
POST /v1/app-automate/maestro/{project_id}/{run_id}/stop

Stop a Maestro run

Cancels a running Maestro run before it completes. Already-completed flows are preserved; in-flight flows are marked cancelled. Alias of the cancel endpoint, kept because testingbotctl calls it from its Ctrl-C handler; unlike cancel it always answers 200, so stopping an already-finished run is a no-op rather than a 409.

Arguments

project_id integer required
—
run_id integer required
—
POST /v1/app-automate/maestro/{project_id}/{run_id}/stop
Request
$ curl -X POST "https://api.testingbot.com/v1/app-automate/maestro/{project_id}/{run_id}/stop" \
-u key:secret
POST /v1/app-automate/maestro/{project_id}/{run_id}/{flow_id}/retry

Retry a Maestro flow

Re-runs a single flow from a Maestro run. Creates a new flow attempt inside the same run and schedules it. Returns the newly created flow record; poll the run for its status.

Arguments

project_id integer required
—
run_id integer required
—
flow_id integer required
—
POST /v1/app-automate/maestro/{project_id}/{run_id}/{flow_id}/retry
Request
$ curl -X POST "https://api.testingbot.com/v1/app-automate/maestro/{project_id}/{run_id}/{flow_id}/retry" \
-u key:secret

App Automate: XCUITest

POST /v1/app-automate/xcuitest/app

Upload an iOS app for XCUITest

Uploads the production iOS .ipa you want to test under XCUITest.
POST /v1/app-automate/xcuitest/app
Request
$ curl -X POST "https://api.testingbot.com/v1/app-automate/xcuitest/app" \
-u key:secret
GET /v1/app-automate/xcuitest/{id}

Get an XCUITest project

Returns the metadata and current state of an XCUITest project.

Arguments

id integer required
—

Response fields

runs array of object
Runs belonging to the project.
success boolean
True when every run in the project passed.
completed boolean
True when every run has reached a terminal state.
GET /v1/app-automate/xcuitest/{id}
Request
$ curl "https://api.testingbot.com/v1/app-automate/xcuitest/{id}" \
-u key:secret
GET /v1/app-automate/xcuitest/{id}/report

Get the XCUITest JUnit report

Returns the JUnit-format XML report for a completed XCUITest run.

Arguments

id integer required
—
GET /v1/app-automate/xcuitest/{id}/report
Request
$ curl "https://api.testingbot.com/v1/app-automate/xcuitest/{id}/report" \
-u key:secret
POST /v1/app-automate/xcuitest/{id}/run

Run an XCUITest suite

Triggers an asynchronous XCUITest run across the requested device capabilities.

Arguments

id integer required
—
POST /v1/app-automate/xcuitest/{id}/run
Request
$ curl -X POST "https://api.testingbot.com/v1/app-automate/xcuitest/{id}/run" \
-u key:secret
POST /v1/app-automate/xcuitest/{id}/tests

Upload XCUITest test bundle

Attaches the XCUITest test bundle (.zip) to a project. Pair with /app to provide both halves of the test.

Arguments

id integer required
—
POST /v1/app-automate/xcuitest/{id}/tests
Request
$ curl -X POST "https://api.testingbot.com/v1/app-automate/xcuitest/{id}/tests" \
-u key:secret
GET /v1/app-automate/xcuitest/{project_id}/{id}

Get a specific XCUITest run

Returns the detail record for a single XCUITest run inside a project.

Arguments

project_id integer required
—
id integer required
—

Response fields

id integer
Unique numeric XCUITest run ID.
created_at timestamp
—
status string
WAITING, READY, DONE or FAILED.
capabilities object
Capabilities the run was started with.
success boolean
Whether the run passed. False until a session has completed.
test object
Session detail. Only present once a session has been allocated.
GET /v1/app-automate/xcuitest/{project_id}/{id}
Request
$ curl "https://api.testingbot.com/v1/app-automate/xcuitest/{project_id}/{id}" \
-u key:secret
GET /v1/app-automate/xcuitest/{project_id}/{run_id}/html_report

XCUITest run HTML report

Returns a self-contained HTML report for a single XCUITest run.

Arguments

project_id integer required
—
run_id integer required
—

Response fields

html_report string
Signed URL to the rendered HTML report.
GET /v1/app-automate/xcuitest/{project_id}/{run_id}/html_report
Request
$ curl "https://api.testingbot.com/v1/app-automate/xcuitest/{project_id}/{run_id}/html_report" \
-u key:secret
GET /v1/app-automate/xcuitest/{project_id}/{run_id}/junit_report

XCUITest run JUnit report

Returns a JUnit-format XML report for a single completed XCUITest run. Suitable for ingestion by CI systems (Jenkins, GitHub Actions, etc.).

Arguments

project_id integer required
—
run_id integer required
—

Response fields

junit_report string
JUnit XML for the run, as a string.
GET /v1/app-automate/xcuitest/{project_id}/{run_id}/junit_report
Request
$ curl "https://api.testingbot.com/v1/app-automate/xcuitest/{project_id}/{run_id}/junit_report" \
-u key:secret
Was this page helpful?
Last updated
TestingBot Docs