Physical-Device Examples

Physical-Device Integrations

The /tests/execute endpoint can run your GPT Driver test suites on real hardware by connecting to the most common device-cloud vendors—or by using GPT Driver-hosted phones if you don’t yet have a third-party account.

Good to know

• All integrations share the same security model: credentials are encrypted at rest, used only for the current execution, and never persisted in plain text.

• If any key is missing the request will fail with a 400 Invalid request response that lists the missing fields.

• The example objects below can be mixed with the other request parameters you already use (such as tests, tags, or inputs).

Provider	Required fields	Optional fields	Notes
BrowserStack	userName, accessKey	app	If app is omitted we re-use the latest build already uploaded to BrowserStack.
AWS Device Farm	accessKeyId, secretAccessKey, projectArn	appArn	The project’s default device pool will be used unless you add the devicePoolArn field.
LambdaTest	userName, accessKey	appUrl	appUrl may point to an existing LambdaTest build (lt://APP_ID) or a public artifact.
GPT Driver Hosted Devices	deviceType	osVersion, locale	Leave all keys blank to let GPT Driver choose the next available device for you.

---

1. BrowserStack

POST /tests/execute HTTP/1.1
Content-Type: application/json

{
  "organisationId": "org123",
  "browserstackData": {
    "userName": "<BROWSERSTACK_USERNAME>",
    "accessKey": "<BROWSERSTACK_ACCESS_KEY>",
    "app": "bs://<APP_ID>"  // optional
  }
}

2. AWS Device Farm

{
  "organisationId": "org123",
  "awsDeviceFarmData": {
    "accessKeyId": "<AWS_ACCESS_KEY_ID>",
    "secretAccessKey": "<AWS_SECRET_ACCESS_KEY>",
    "projectArn": "arn:aws:devicefarm:eu-west-1:123456789012:project:1111aaaa-bbbb-cccc-dddd-eeeeffff0000",
    "appArn": "arn:aws:devicefarm:eu-west-1:123456789012:upload:2222aaaa-bbbb-cccc-dddd-eeeeffff0000"  // optional
  }
}

3. LambdaTest

{
  "organisationId": "org123",
  "lambdaTestData": {
    "userName": "<LAMBDATEST_USERNAME>",
    "accessKey": "<LAMBDATEST_ACCESS_KEY>",
    "appUrl": "lt://<APP_ID>"  // optional
  }
}

4. GPT Driver-Hosted Devices

{
  "organisationId": "org123",
  "gptdriverDeviceData": {
    "deviceType": "pixel_8",      // e.g. iphone_15, galaxy_s23, pixel_8
    "osVersion": "14",            // optional – default is latest stable
    "locale": "en_US"              // optional – default is en_US
  }
}

---

Verifying the run

Once the test suite has been queued you will receive a 200 response containing a test_suite_ids array. You can poll the /tests/results/{id} endpoint—or configure a Webhook—to be notified when execution completes.

---