Capabilities
Every capability a mobile session accepts — what it does, and one line showing how to send it.
A capability is a note you attach to your test. It says which device you want, what it should open, and what you want kept.
You send them once, when the test connects.
Not sure what to put? The capability generator lists every phone, tablet, simulator and OS version we have right now, and writes the snippet for you.
These are the mobile capabilities. Desktop browsers have their own set.
Your access key
The one thing every session needs. Copy it from the Access key page.
Two places to put it — either is fine:
// in the capabilities
"testkase:options": { accessKey: "xyz_your_access_key_here" }
// or in the address you connect to
"https://x:[email protected]/wd/hub"Choosing the device
| Capability | What it does | Example |
|---|---|---|
platformName | iOS or Android. Required. | {"platformName": "iOS"} |
appium:deviceName | A specific model. Leave it out and you get whichever matching device is free. | {"appium:deviceName": "iPhone 16"} |
appium:platformVersion | A specific OS version. Leave it out for any. | {"appium:platformVersion": "18.6"} |
testkase:options.virtual | Asks for a simulator or emulator instead of real hardware. See Real devices and virtual ones. | {"testkase:options": {"virtual": true}} |
Choosing what it opens
Every session drives either an app or the device browser. You must send one, and sending both is refused.
| Capability | What it does | Example |
|---|---|---|
appium:app | The app to install and launch, by its farm URL. Use farm://app-sample for our demo app — nothing to upload, and it works on every kind of device. | {"appium:app": "farm://app-1234"} |
browserName | Drives the device browser instead. Safari on iOS, Chrome on Android — those are the only two. | {"browserName": "Safari"} |
farm://app-1234 works. farm://app/1234 is refused. It used to be accepted and ignored. Your test then ran against whatever was on screen, and still reported passed.You do not need appium:automationName. We set it for you — XCUITest on iOS, UiAutomator2 on Android.
The four you will actually use
| Capability | What it does | Example |
|---|---|---|
name | What this session is called in your dashboard. | {"testkase:options": {"name": "Sign in — new user"}} |
recording | Records a video of the session. You get no video unless you ask for it. | {"testkase:options": {"recording": true}} |
runId | Groups sessions together. Give every test in one CI job the same value and they appear as a single run. | {"testkase:options": {"runId": "ci-8891"}} |
build | A label, like a version number, shown next to the session. Unlike runId, it does not group anything. | {"testkase:options": {"build": "nightly-42"}} |
The rest
| Capability | What it does | Example |
|---|---|---|
tags | Your own labels on a session, so you can find it later. | {"testkase:options": {"tags": ["smoke"]}} |
network | Captures every request the device made as a real HAR file. See Network capture. | {"testkase:options": {"network": true}} |
idleTimeout | How long your test may go quiet before we assume it died and stop it. Five minutes by default, up to twenty. | {"testkase:options": {"idleTimeout": 900}} |
maxQueueWaitSeconds | If every matching device is busy, how long to wait in line. Five minutes by default, up to nine. Waiting is not billed. | {"testkase:options": {"maxQueueWaitSeconds": 600}} |
All together:
const capabilities = {
platformName: "iOS",
"appium:deviceName": "iPhone 16",
"appium:app": "farm://app-sample",
"testkase:options": {
accessKey: "xyz_your_access_key_here",
name: "Sign in — new user",
build: "nightly-42",
runId: "ci-8891",
recording: true,
},
};idleTimeoutSeconds instead of idleTimeout looks accepted while your setting does nothing. Copy the names from this page or from the generator.Questions
▶Can I run headless?
No. A phone has a screen and no way to hide it, so headless here is refused rather than ignored. It works only with Playwright on desktop.
▶What happens if I send neither an app nor a browserName?
The session is refused.
Every device arrives freshly cleaned, sitting on its home screen. A session with nothing to open would have nothing to test, and would still cost you minutes.
▶Do I have to name a device?
No. Leave appium:deviceName out and you get whichever matching device is free. That usually starts faster.
Name a model when your test depends on that exact phone or screen size.
▶What ends a session besides my own code?
Two clocks: two hours in total, and five minutes of going quiet. Raise the quiet one with idleTimeout if your test has long legitimate pauses.