Exit course
Chapter 5 of 10 Beginner 6 min read 2 quick checks Updated

Your First Appium Test on a Real Device

On this page
  1. What happens in an Appium session
  2. Set up
  3. The test
  4. What each part does
  5. Pass or fail is your job
  6. 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 then turns this into a maintainable suite with locators, waits, page objects and reporters.

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#

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

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#

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.

// 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:

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#

  • 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?

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#

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?

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#

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 shows how to keep such platform differences out of your tests.

For other languages, the TestingBot docs have the same first test in Java, Python, C# and Ruby, and the capabilities builder generates valid device combinations.