Skip to main content

k11 Appium QA: self-healing locators for mobile apps

PyPI CI E2E Android License: MIT

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/By tuples and Page Object constants; Java AppiumBy/MobileBy/By calls and @AndroidFindBy/@iOSXCUITFindBy annotations (each keeps its own platform).
  • Verified, not hoped: heal-ci re-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_register at 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
  1. Runs your pytest suite with the plugin, which saves the screen of every test that fails on a missing element.
  2. Heals each broken locator against that screen and the committed baseline (.qa-mcp/appium-baselines.json).
  3. 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.
  4. 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.
  5. Leaves failures that aren't about locators alone, and writes heal-report.md (for the pull request) and heal-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.yml starts 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_locator never edits files, and heal-ci changes 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.yaml with ${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-ci for 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)

Source distribution for k11-appium-qa-mcp 0.1.0
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)

Table of built distributions (wheels) for k11-appium-qa-mcp 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page