Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Architecture and Setup

Appium Inspector and Environment Checks

Use Appium Inspector to explore the element tree, try locators and record steps, and learn the checks that tell you whether your environment is ready.

Writing locators blind is slow. Appium Inspector is a free desktop application that connects to your Appium server, shows a screenshot of the app next to its element tree, and lets you click an element to see all of its attributes. It is the single most useful tool for a new Appium user. Together with a few environment checks, it makes setup problems and locator problems easy to diagnose.

This lesson describes Inspector's workflow in words (a desktop app cannot run here), shows the environment diagnostics Appium offers, and gives you stand-ins for the reasoning behind both.

Installing and starting Inspector

Appium Inspector is distributed as a standalone app for Windows, macOS and Linux, and there is also a browser-hosted build. Start your Appium server first, with the driver for your platform installed. For local use, bind it so Inspector can reach it. If your browser-hosted Inspector must call the server across origins, start the server with the CORS option (--allow-cors); the desktop app does not need it.

Starting an Inspector session

  1. Open Inspector. In Appium Server, enter the host (127.0.0.1), port (4723) and, for Appium 2 and later, leave the remote path as /.
  2. In Desired Capabilities, build the JSON for your device and app. A minimal Android example:
JSON
{
  "platformName": "Android",
  "appium:automationName": "UiAutomator2",
  "appium:deviceName": "Pixel_8_API_35",
  "appium:app": "/builds/shop-debug.apk"
}
  1. Press Start Session. The app launches on the device and Inspector shows its first screen.

Inspector can save capability sets so you can reuse them. Saved sets belong in your team's wiki or repository, not just on one laptop.

Reading the Inspector screen

The window has three main areas:

  • App Source (left): the screenshot with a hover highlight, or the XML tree. Click an element on the screenshot or in the tree to select it.
  • Selected Element (right): every attribute: resource-id, content-desc (Android), name, label and value (iOS), class, text, bounds, enabled, displayed. It also suggests locator strategies for that element, ranked from most to least stable, such as accessibility id first and XPath last.
  • Toolbar: refresh the source, tap, swipe by gesture, go back, search for elements and toggle recording.

Trying a locator

Inspector has a Search for element panel. Choose a strategy (accessibility id, id, xpath, class name and so on), type a selector and press Search. It reports how many elements match. A good locator matches exactly one element. Three matches means the locator is ambiguous; zero means it is wrong or the element is not on screen yet.

Recording

Inspector can record your clicks and generate code in several languages (Java, Python, JavaScript, Ruby, and more). Treat recorded code as a draft, never final code:

  • It uses whatever locator Inspector picked, often XPath.
  • It contains no waits.
  • It is one long script with no structure.

Use it to learn the syntax, then restructure with page objects in later chapters. For now the lesson on locator strategies explains how to choose better selectors than the first suggestion.

Source freezes and refreshes

The screen in Inspector is a snapshot. After you interact with the app, press Refresh to update the tree. This leads to a frequent confusion: you copy a locator from an old snapshot and it fails in the test. Always refresh first when the UI changed.

Environment checks

Appium also offers diagnostics. Recent Appium versions include a doctor command for drivers (run appium driver doctor uiautomator2, and the equivalent for xcuitest), which checks things such as ANDROID_HOME, the JDK, adb and for iOS the Xcode and command line tools. In older setups the separate appium-doctor npm package did the same job. If the command exists in your version, run it before every first session on a new machine; read its output carefully, because it lists exactly what is missing. The output format changes between versions, so we do not reproduce it here.

Manual checks are still valuable:

Terminal
node --version
appium --version
appium driver list --installed
adb devices                      # Android
xcrun simctl list devices available   # iOS (Mac only)
curl http://127.0.0.1:4723/status

A checklist in a stand-in

The stand-in below turns the checklist into code. You provide the facts about your machine in an object (we cannot detect them from a web page), and it reports what to fix first. This is the reasoning a doctor tool follows.

JS Stand-in: environment diagnostic

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

No output.

Ranking locator suggestions

Inspector ranks locator suggestions. The stand-in below does the same with a simple rule set, showing why accessibility id and id beat XPath. It also warns when a locator is ambiguous. (The rank order is a widely used team convention, not a protocol rule.)

JS Stand-in: rank locator suggestions

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

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is Appium Inspector mainly used for?

    Inspector shows the app screen and element attributes and lets you try locators.
  2. 2. A locator search in Inspector returns three matches. What does that tell you?

    find_element returns the first match, which may be the wrong one; make the locator more specific.
  3. 3. Why is recorded code only a draft?

    Recorders produce quick linear scripts; robust tests need good locators, waits and page objects.
  4. 4. You copied a locator from Inspector but the test fails. A common cause is:

    The tree is a snapshot of one moment; refresh after the UI changes.

Summary

  • Appium Inspector connects to the server with your capabilities and shows the screen and element tree.
  • Use it to read attributes and test locators; a good locator matches exactly one element.
  • Recorded code is a starting point, not production code.
  • Run the driver doctor (if your version has it) and manual checks on every new machine.
  • Refresh the source after the UI changes.

Next: Capabilities Explained