
appium-qa
io.github.K11-Software-Solutions/appium-qa
Self-healing Appium locators for Android and iOS apps, healed on the screen each test failed on.
Documentation
k11 Appium QA: self-healing locators for mobile apps
When an app redesign breaks your Appium tests, fix the locators with evidence, not guesses.
Self-healing for mobile tests usually lives inside a paid device cloud, as a black box. k11 Appium QA is open source and runs wherever your tests already run: a laptop with an emulator, your CI, or any device cloud.
- Heals on the exact screen the test failed on. A small pytest plugin saves the screen (Appium's page source) at the moment an element isn't found. Healing runs against that screen, with no need to navigate back to it.
- Shows its working: confidence, the reasons ("text equivalent: Log in → Sign in", "resource id similar 62%"), the runner-up and alternatives. Accessibility ids are preferred.
- Fixes locators where they live: Python
AppiumBy/Bytuples and Page Object constants; JavaAppiumBy/MobileBy/Bycalls and@AndroidFindBy/@iOSXCUITFindByannotations (each keeps its own platform). - Verified, not hoped:
heal-cire-runs the healed tests on the device and reverts any change that doesn't pass. When a test gets further and breaks on the next locator, it heals that one too. - Android and iOS: UiAutomator2 and XCUITest screens; accessibility id, id, class name, XPath, UiSelector and iOS predicate locators are evaluated offline.
- Accessibility check: tappable elements a screen reader can't name, and duplicate accessibility ids. Bad for users, and the reason tests are fragile.
See it heal
A login screen redesign broke three locators in one test and one in another. k11-appium-qa-mcp heal-ci --apply:
3 healed and verified, 1 needs review, 1 failure not caused by locators.
Test Old locator New locator Confidence Re-run test_log_in (AppiumBy.ID, "et_email")(AppiumBy.ACCESSIBILITY_ID, "email-field")94% passed test_log_in (AppiumBy.ACCESSIBILITY_ID, "password-input")(AppiumBy.ACCESSIBILITY_ID, "password-field")100% passed test_log_in (AppiumBy.ACCESSIBILITY_ID, "login-button")(AppiumBy.ACCESSIBILITY_ID, "sign-in-button")77% passed Why "sign-in-button"? accessibility id similar (62%) · resource id similar:
btn_login→btn_sign_in· text equivalent: "Log in" → "Sign in" · class matches.Needs a person: the sign-up button lost its accessibility id; best guess
btn_registerat 42%, so it was not changed. Not caused by locators: the title changed from "Welcome back". Untouched; it may be a real change.
The changes land in the Page Object (tests/pages/login_page.py), not scattered across tests.
Tools (MCP)
Every tool works on a saved screen (page source XML, e.g. the one saved when a test failed) or on the live device when .qa-mcp/appium.yaml points at an Appium server.
| Tool | What it does |
|---|---|
inspect_screen | Elements with locators verified to match exactly one element, most stable first |
check_locator | How many elements a locator matches (1 = good) and whether it's visible |
capture_baseline | While tests pass, records each locator's element (per platform) so healing is confident later |
heal_locator | Finds the intended element and suggests a verified replacement, in Python or Java form |
accessibility_check | Unnamed tappable elements and duplicate accessibility ids |
save_screen | Saves the live device's screen for later, device-free work |
run_tests | Runs the pytest suite; failures include the locator, line, platform and saved screen |
Command: /heal-mobile-tests, a guided workflow from failing tests to healed, verified locators.
k11 Appium QA doesn't try to replace device-control servers like the official Appium MCP or mobile-mcp; use them to drive and explore the app, and this to keep your existing test suite healthy.
Install
pip install "k11-appium-qa-mcp[live]" # [live] adds the Appium client for live sessions; saved screens need nothing extra
Claude Code plugin:
/plugin marketplace add K11-Software-Solutions/k11techlab-appium-qa-mcp
/plugin install appium-qa@k11-appium-qa
Any MCP client:
{ "mcpServers": { "appium-qa": { "command": "uvx", "args": ["k11-appium-qa-mcp"] } } }
For live sessions, copy docs/appium.example.yaml to .qa-mcp/appium.yaml (server URL and capabilities; secrets as ${ENV:NAME}). Device clouds such as BrowserStack and Sauce Labs work the same way.
Healing in CI
k11-appium-qa-mcp heal-ci # dry run: suggestions only
k11-appium-qa-mcp heal-ci --apply # apply confident changes, verify on the device, revert what fails
- Runs your pytest suite with the plugin, which saves the screen of every test that fails on a missing element.
- Heals each broken locator against that screen and the committed baseline (
.qa-mcp/appium-baselines.json). - Applies a change only at 70% confidence or more (
--min-confidence), clearly ahead of the runner-up. Tests that share a broken locator are healed together, with one change. - Re-runs the healed tests on the device; a test that now breaks on another locator gets that one healed too (up to five rounds). Every change is kept only if all the tests using it pass.
- Leaves failures that aren't about locators alone, and writes
heal-report.md(for the pull request) andheal-report.json.
docs/heal-mobile-locators.yml runs it on an Android emulator in GitHub Actions and opens a pull request. The report uses the same format as k11 Playwright QA and Selenium QA, so the k11 Release Gate reads it as UI evidence.
Java projects: the MCP tools and source rewriting support Java (Page Objects with @AndroidFindBy/@iOSXCUITFindBy, AppiumBy calls). heal-ci currently runs pytest suites; for Maven or Gradle suites, save the screen on failure (driver.getPageSource()) and use heal_locator, or /heal-mobile-tests.
How it's tested
- No device needed for most tests: real-format UiAutomator2 and XCUITest page sources, and a fake Appium driver that serves them, run the whole heal-ci loop (run, heal, rewrite, re-run, report) in seconds.
- A real emulator on every push:
e2e-android.ymlstarts an Android 14 emulator and an Appium server, reads the built-in Settings app live, captures a baseline and heals a broken locator, both live and from the saved screen.
Safety
- Suggestions are never applied silently:
heal_locatornever edits files, andheal-cichanges code only above the threshold and keeps a change only when the tests pass. - Screens are parsed with entity expansion and network access disabled; paths must stay inside the project.
- Locators from tests and models are parsed, never executed.
- Capabilities and credentials come from
.qa-mcp/appium.yamlwith${ENV:NAME}secrets.
Part of the K11 QA suite
Playwright QA · Selenium QA · Appium QA · API Contract QA · API Functional QA · Performance QA · LLM Assure · Release Gate · Release Readiness Agent
Roadmap
heal-cifor Java (Maven/Gradle) suites, with a TestNG/JUnit listener that saves the screen on failure- iOS simulator job in CI (macOS runner)
- Screenshot similarity as an extra healing signal
- Flutter and React Native specifics (semantics labels, testID)
Built by K11 Software Solutions. MIT licensed.
k11-appium-qa-mcppip install k11-appium-qa-mcpRelated Servers
io.github.K11-Software-Solutions/api-contract-qa
Which services an API change breaks and why: OpenAPI, GraphQL, gRPC, AsyncAPI, SOAP.
io.github.K11-Software-Solutions/api-functional-qa
Functional API tests: story-to-flow, negative tests from the spec, DB checks, evidence.
io.github.K11-Software-Solutions/llm-assure
Red-team LLM apps: 41 OWASP LLM Top 10 probes, adaptive attacks, CI gate, audit reports.