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.
Metadata
Release files for k11-appium-qa-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| k11_appium_qa_mcp-0.1.0.tar.gz | 28.8 kB | With provenance | Details for k11_appium_qa_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| k11_appium_qa_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for k11_appium_qa_mcp-0.1.0-py3-none-any.whl |
Total release size: 64.4 kB
Release files / k11_appium_qa_mcp-0.1.0.tar.gz
| Download URL | k11_appium_qa_mcp-0.1.0.tar.gz |
|---|---|
| Size | 28.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8d09b73a2cdeeeab8f81c0177ae4392f03c07486e6fb18441a34b4faf0ea026a
|
|
BLAKE2b-256 checksum How to use checksums |
d51842d6c4a91781f3664b9f51d8ef5dbfb6301cc2754b0dd31c6811ec30aa23
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / k11_appium_qa_mcp-0.1.0-py3-none-any.whl
| Download URL | k11_appium_qa_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 35.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5ec59f7257e846bdd8900f3328264191f739f642e5f78f2d8dc1193ef2f3ef20
|
|
BLAKE2b-256 checksum How to use checksums |
8e6a386bd75694c52c9021eb2d07eb84326972384272b1015a5ba430d4e0772c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for k11-appium-qa-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for k11_appium_qa_mcp-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.