Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

Your First Appium Test

Walk through a complete first Appium test: options, session, locating elements, actions, assertions and cleanup, with a runnable stand-in driver to practice the flow.

A first Appium test has the same shape as every later one: describe the device and app, start a session, find an element, act on it, check the result, and always end the session. Once you can read this shape, the rest of the course is just making each step more robust.

Below you will read a real test in Python and Java (read-only, because it needs a device), then rebuild the flow with a stand-in driver that runs in your browser.

The scenario

Our imaginary shop app has a login screen: a username field, a password field and a Log in button. After a successful login it shows a greeting. The test must open the app, log in as a test user and verify the greeting.

The real test in Python

This uses the Appium-Python-Client package. It assumes an Appium server is running on 127.0.0.1:4723 with the uiautomator2 driver installed and an Android emulator started.

Python
from appium import webdriver
from appium.options.android import UiAutomator2Options
from appium.webdriver.common.appiumby import AppiumBy

options = UiAutomator2Options()
options.platform_name = "Android"
options.device_name = "Pixel_8"
options.app = "/builds/shop-debug.apk"

driver = webdriver.Remote("http://127.0.0.1:4723", options=options)
try:
    driver.find_element(AppiumBy.ACCESSIBILITY_ID, "username").send_keys("tester")
    driver.find_element(AppiumBy.ACCESSIBILITY_ID, "password").send_keys("s3cret")
    driver.find_element(AppiumBy.ACCESSIBILITY_ID, "login").click()

    greeting = driver.find_element(AppiumBy.ACCESSIBILITY_ID, "greeting")
    assert greeting.text == "Welcome, tester"
finally:
    driver.quit()

The same test in Java

Java
UiAutomator2Options options = new UiAutomator2Options()
    .setPlatformName("Android")
    .setDeviceName("Pixel_8")
    .setApp("/builds/shop-debug.apk");

AndroidDriver driver = new AndroidDriver(new URL("http://127.0.0.1:4723"), options);
try {
    driver.findElement(AppiumBy.accessibilityId("username")).sendKeys("tester");
    driver.findElement(AppiumBy.accessibilityId("password")).sendKeys("s3cret");
    driver.findElement(AppiumBy.accessibilityId("login")).click();

    String greeting = driver.findElement(AppiumBy.accessibilityId("greeting")).getText();
    assertEquals("Welcome, tester", greeting);
} finally {
    driver.quit();
}

Step by step

  1. Options. A typed object that collects capabilities. UiAutomator2Options knows which names are valid for the Android driver, and adds the appium: prefix on the wire for you.
  2. Session. Constructing the driver sends POST /session. The server installs the app, launches it and returns a session id. If anything is wrong (no device, bad path) this line throws.
  3. Locate. find_element with a strategy and a value. Here the strategy is accessibility id, the most portable choice.
  4. Act. send_keys types; click taps.
  5. Assert. Read state back with .text and compare. The assertion belongs to your test framework (pytest, JUnit, and so on), not to Appium.
  6. Clean up. quit() ends the session and releases the device. Put it in finally (or a framework teardown) so it runs even when the test fails; a leaked session blocks the device and, in the cloud, costs money.

Never skip quit(). A session that stays open keeps the app running, may hold a device lock and can make the next test fail in a confusing way.

Practice the flow in a stand-in

The stand-in driver below mimics the method names of the Python client. It serves a fake screen tree, so you can run a whole login test, see a failure and fix it.

JS Stand-in: run a login test against a fake screen

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Change s3cret to something else and run again: the assertion fails because the fake app shows "Invalid credentials". That is how a real failing test looks, with the assertion message pointing at the difference.

Make failures easier to read

Real tests fail for dull reasons: wrong locator, slow screen, wrong data. Two habits help. First, give assertions a message. Second, take a screenshot on failure. The stand-in below wraps a test function so a failure is reported with a label, and quit always runs.

JS Stand-in: a tiny test runner with cleanup

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common first-test problems

  • Session fails to start. Check that the server is running, the driver is installed, an emulator or device is connected and the app path exists on the machine where the server runs.
  • Element not found. The screen may not be ready yet; see Waits and Synchronization. Or the locator is wrong; see Locator Strategies.
  • App crashes at launch. A debug build for the wrong CPU architecture or an emulator without Google Play services can cause this.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does constructing the driver object do?

    Creating the driver triggers POST /session; if the device or app is wrong, the error appears right there.
  2. 2. Where should driver.quit() be called?

    Failing tests must release the device too, so cleanup belongs in finally or a framework teardown.
  3. 3. Who provides the assert statement in an Appium test?

    Appium only drives and reads the app. Assertions come from the language's testing framework.
  4. 4. Which locator strategy is used in the examples because it works on both platforms?

    Accessibility id maps to content-desc on Android and the accessibility identifier on iOS.

Summary

  • A test has six parts: options, session, locate, act, assert, quit.
  • Options objects add the appium: prefix for you and validate names.
  • Accessibility id is the most portable locator.
  • Always end the session in finally or a teardown.
  • Most first failures are environment, locator or timing problems.

Next: Appium vs Other Mobile Testing Tools