---
title: Your First Appium Test on a Real Device | TestingBot
description: 'This chapter runs one Appium test on a physical Android phone in TestingBot&#39;s
  device cloud. It is deliberately small: one file, no test runner, no page…'
source_url:
  html: https://testingbot.com/resources/courses/mobile-app-testing/first-appium-test
  md: https://testingbot.com/resources/courses/mobile-app-testing/first-appium-test.md
---

Course

[Mobile App Testing: From First Test to CI](https://testingbot.com/resources/courses/mobile-app-testing)

Chapter 5 of 10

1. [1 Mobile App Testing: What Makes It Different](https://testingbot.com/resources/courses/mobile-app-testing)
2. [2 Emulators, Simulators and Real Devices](https://testingbot.com/resources/courses/mobile-app-testing/emulators-simulators-and-real-devices)
3. [3 Choosing a Framework: Appium, Espresso, XCUITest, Maestro](https://testingbot.com/resources/courses/mobile-app-testing/choosing-a-framework)
4. [4 Uploading and Managing App Builds](https://testingbot.com/resources/courses/mobile-app-testing/app-builds-and-uploads)
5. [5 Your First Appium Test on a Real Device](https://testingbot.com/resources/courses/mobile-app-testing/first-appium-test)
6. [6 Your First Maestro Flow on TestingBot](https://testingbot.com/resources/courses/mobile-app-testing/first-maestro-flow)
7. [7 Running Espresso and XCUITest Suites in the Cloud](https://testingbot.com/resources/courses/mobile-app-testing/espresso-and-xcuitest)
8. [8 Device Matrix, Parallel Runs and CI](https://testingbot.com/resources/courses/mobile-app-testing/device-matrix-parallel-ci)
9. [9 Debugging Failed Mobile Test Runs](https://testingbot.com/resources/courses/mobile-app-testing/debugging-failed-runs)
10. [10 Knowledge Check](https://testingbot.com/resources/courses/mobile-app-testing/knowledge-check)

[Exit course](https://testingbot.com/resources/courses)

 Chapter 5 of 10 Beginner 6 min read 2 quick checks Updated Nov 2026 

# Your First Appium Test on a Real Device
On this page
1. [What happens in an Appium session](https://testingbot.com#what-happens-in-an-appium-session)
2. [Set up](https://testingbot.com#set-up)
3. [The test](https://testingbot.com#the-test)
4. [What each part does](https://testingbot.com#what-each-part-does)
5. [Pass or fail is your job](https://testingbot.com#pass-or-fail-is-your-job)
6. [The same test on iOS](https://testingbot.com#the-same-test-on-ios)

This chapter runs one Appium test on a physical Android phone in TestingBot's device cloud. It is deliberately small: one file, no test runner, no page objects. The point is to see every moving part of a cloud mobile session once. The [Appium with WebdriverIO course](https://testingbot.com/resources/courses/appium-webdriverio) then turns this into a maintainable suite with locators, waits, page objects and reporters.

## What happens in an Appium session[#](https://testingbot.com#what-happens-in-an-appium-session)

1. Your test code (here WebdriverIO, but any WebDriver client works) sends a "new session" request with **capabilities** : which platform, which device, which app.
2. The grid finds a matching device, installs the app and starts an Appium server with the right driver: UiAutomator2 for Android, XCUITest for iOS.
3. Every command (find an element, type, read text) is an HTTP request to that server, which the driver executes on the device.
4. When the test ends, it deletes the session. The grid keeps the video, screenshots and logs.

## Set up[#](https://testingbot.com#set-up)

You need Node.js and your TestingBot key and secret:

```bash
mkdir first-mobile-test && cd first-mobile-test
npm init -y
npm install webdriverio@10.2.0
export TB_KEY=your_key
export TB_SECRET=your_secret
```

## The test[#](https://testingbot.com#the-test)

The calculator sample app has two number fields and a sum field, with the accessibility ids `inputA`, `inputB` and `sum`. In WebdriverIO, `~` locates by accessibility id.

```javascript
// first-test.mjs: one Appium session on a TestingBot Android device
import { remote } from 'webdriverio'

const driver = await remote({
  hostname: 'hub.testingbot.com',
  protocol: 'https',
  port: 443,
  path: '/wd/hub',
  user: process.env.TB_KEY,
  key: process.env.TB_SECRET,
  logLevel: 'warn',
  connectionRetryTimeout: 420000, // a busy real device can queue for minutes
  connectionRetryCount: 0,
  capabilities: {
    platformName: 'Android',
    'appium:automationName': 'UiAutomator2',
    'appium:deviceName': 'Pixel [89]',
    'appium:app': process.env.TB_APP ?? 'https://testingbot.com/appium/sample.apk',
    'tb:options': {
      realDevice: true,
      name: 'Calculator adds two numbers',
      build: 'mobile-app-testing-course'
    }
  }
})

const sessionId = driver.sessionId
let passed = false
try {
  await driver.$('~inputA').setValue('10')
  await driver.$('~inputB').setValue('5')
  const sum = await driver.$('~sum').getText()
  console.log(`sum = ${sum}`)
  passed = sum === '15'
} finally {
  // Tell TestingBot whether the test passed, then end the session.
  await driver.execute(`tb:test-result=${passed ? 'passed' : 'failed'}`)
  console.log(`session ${sessionId}: ${passed ? 'passed' : 'failed'}`)
  await driver.deleteSession()
}
// A failed check must fail the process, so CI goes red.
if (!passed) process.exitCode = 1
```

Run it:

```bash
node first-test.mjs
```

```
sum = 15
session 2c724aa5c2cf-4f82bf2b2fc1-7c9f0379820f-179449850487-1840159: passed
```

That session ran on a real Pixel 8. With the upload from chapter 3, `TB_APP=tb://c4a7a3347e4af6304bbca538 node first-test.mjs` ran the same test against the private copy of the app (session `8d537427e923-...`, also a real Pixel 8, passed).

## What each part does[#](https://testingbot.com#what-each-part-does)

- **`hostname`, `path`, `user`, `key`** send the session to TestingBot's hub instead of a local Appium server.
- **`appium:deviceName: 'Pixel [89]'`** is a regular expression: the first free Pixel 8 or Pixel 9. A pattern rather than one exact model means you rarely wait for a busy phone. Keep the pattern narrow, though: chapter 7 shows what happened when this course used `Pixel.*`.
- **`appium:app`** is the build to install: a public URL or a `tb://` id from TestingBot Storage.
- **`tb:options.realDevice: true`** asks for a physical device. Remove it, and ask for an exact emulator such as `'appium:deviceName': 'Pixel 8'` with `'appium:platformVersion': '14'`, and the same code runs on an Android emulator. This course ran that variant too.
- **`name` and `build`** label and group the session in the dashboard.
- **`connectionRetryTimeout: 420000`** gives the grid up to seven minutes to answer the new-session request, because a real device can be in use or still being cleaned. **`connectionRetryCount: 0`** stops WebdriverIO from sending a second request while the first is still queued.

Your real-device test often fails at start-up with a client-side timeout, although the dashboard shows the session starting a minute later. What do you change?

 Add `driver.pause(60000)` before the first command Raise `connectionRetryTimeout` and keep `connectionRetryCount` at 0 Switch to an exact device name Remove `tb:options`

The client gave up on the new-session request while the device was still being allocated. A longer connection timeout lets it wait, and no retries avoids queueing a second device. A pause cannot help because the session does not exist yet; an exact name makes queueing more likely, not less.

## Pass or fail is your job[#](https://testingbot.com#pass-or-fail-is-your-job)

The grid sees WebDriver commands, not your assertions. Without the `tb:test-result` call the dashboard would show the session as finished but not whether it passed. The `try`/`finally` makes sure the result is reported and the session is closed even when a command throws, so a failing test does not keep a real device busy until it times out. The last line sets a non-zero exit code when the check failed, so a CI job running `node first-test.mjs` goes red; a variant that expected 16 instead of 15 (session `41413734fcc0-...`, Pixel 8 emulator) exited with 1. The session id is read before `deleteSession()`, which clears it. Test runners do this for you: the WebdriverIO TestingBot service, for example, reports each test's result automatically, as the Appium course shows.

A teammate removes the `finally` block and calls `deleteSession()` at the end of the `try`. What happens when `~sum` cannot be found?

 Nothing changes; WebdriverIO always closes the session The dashboard marks the session as failed automatically No result is reported and the session stays open on the device until the idle timeout ends it

The exception skips the rest of the `try`, so neither the result nor the delete is sent. The device stays reserved for your account until the grid's timeout, which also blocks one of your parallel slots.

## The same test on iOS[#](https://testingbot.com#the-same-test-on-ios)

On iOS the capabilities change (`platformName: 'iOS'`, `appium:automationName: 'XCUITest'`, an iPhone device name, and `sample.zip` for the simulator or `sample.ipa` for a real iPhone). One locator detail changes as well: in the iOS sample app the ids appear on more than one element, so the test pins the element type with a predicate string. Chapter 7 runs both platforms from one file, and the Appium course's [page object chapter](https://testingbot.com/resources/courses/appium-webdriverio/page-object-model) shows how to keep such platform differences out of your tests.

For other languages, the TestingBot docs have the same first test in [Java](https://testingbot.com/support/app-automate/appium/java), [Python](https://testingbot.com/support/app-automate/appium/python), [C#](https://testingbot.com/support/app-automate/appium/csharp) and [Ruby](https://testingbot.com/support/app-automate/appium/ruby), and the [capabilities builder](https://testingbot.com/support/app-automate/appium/capabilities) generates valid device combinations.

[Previous · Chapter 4 Uploading and Managing App Builds](https://testingbot.com/resources/courses/mobile-app-testing/app-builds-and-uploads) [Next · Chapter 6 Your First Maestro Flow on TestingBot](https://testingbot.com/resources/courses/mobile-app-testing/first-maestro-flow)

On this page

1. [What happens in an Appium session](https://testingbot.com#what-happens-in-an-appium-session)
2. [Set up](https://testingbot.com#set-up)
3. [The test](https://testingbot.com#the-test)
4. [What each part does](https://testingbot.com#what-each-part-does)
5. [Pass or fail is your job](https://testingbot.com#pass-or-fail-is-your-job)
6. [The same test on iOS](https://testingbot.com#the-same-test-on-ios)

Certification

Earn the free, resume-worthy TestingBot Mobile App Testing Certification for this course.

[How it works](https://testingbot.com/resources/courses/mobile-app-testing/certification)
