QAPAL

Locator intelligence engine for Playwright. Analyze, fix, and heal broken test selectors — automatically.

pip install qapal
playwright install chromium

The Problem

Playwright tests break when selectors go stale. A renamed CSS class, a removed data-testid, a changed button label — and your entire CI pipeline goes red. Teams spend hours manually hunting down which selector broke and what to replace it with.

The Solution

QAPAL probes your selectors against the live page, scores them by resilience, and replaces weak ones with validated alternatives. No AI in the loop at runtime. Pure locator resolution + scoring.

# Find every weak selector in your test suite
qapal analyze tests/ --url https://staging.myapp.com

# Auto-fix them
qapal fix tests/ --url https://staging.myapp.com --apply

# CI self-healing: tests fail -> QAPAL patches -> opens a PR
qapal heal --test-results results.json --url https://staging.myapp.com --pr

Quick Start

Analyze selector health

$ qapal analyze tests/login.spec.ts --url https://myapp.com/login

File                            Line  Type         Value                          Found      Grade
-------------------------------------------------------------------------------------------------
login.spec.ts                      9  placeholder  Email address                    YES [A - 0.83]
login.spec.ts                     10  placeholder  Password                         YES [A - 0.83]
login.spec.ts                     12  css          .btn-submit                      YES [B - 0.70]
login.spec.ts                     15  testid       nonexistent                       NO [F - 0.00]

--- Summary ---
Total: 4  |  Strong: 2  |  Weak: 1  |  Broken: 1

Grades: A (>0.8) rock-solid, B (>0.6) acceptable, C (>0.4) fragile, D/F replace immediately.

Fix weak selectors

$ qapal fix tests/login.spec.ts --url https://myapp.com/login --dry-run

Found 1 selector replacement(s):

  login.spec.ts:12  page.locator(".btn-submit")  ->  page.getByRole("button", { name: "Sign In" })
                    [A - 0.88]  Replaced css with role (confidence: 0.88)

--- Diff Preview (--dry-run) ---

--- a/login.spec.ts
+++ b/login.spec.ts
@@ -9,7 +9,7 @@
   await page.getByPlaceholder('Email address').fill('user@test.com');
   await page.getByPlaceholder('Password').fill('secret');

-  await page.locator('.btn-submit').click();
+  await page.getByRole('button', { name: 'Sign In' }).click();

Happy with it? Apply:

qapal fix tests/login.spec.ts --url https://myapp.com/login --apply

Or send a PR directly:

qapal fix tests/ --url https://myapp.com --pr

Probe a single selector

$ qapal probe "page.getByTestId('email')" --url https://myapp.com/login

Selector: page.getByTestId('email')
Type:     testid
Value:    email
Probing https://myapp.com/login...

Found:       YES
Count:       1
Visible:     True
Enabled:     True
In viewport: True
Confidence:  [A - 0.95]
Strategy:    testid

Generate a test scaffold

$ qapal generate --url https://myapp.com/login --language python

Probing https://myapp.com/login...
Discovered 6 interactive elements.
Scaffold written to: tests/generated/test_login.py

Output:

"""Auto-generated scaffold by QAPAL"""
from playwright.sync_api import Page, expect

# === Validated elements on https://myapp.com/login ===
#
# Textbox "Email"        -> page.get_by_test_id("email")           [A - 0.95]
# Textbox "Password"     -> page.get_by_test_id("password")        [A - 0.95]
# Button "Sign In"       -> page.get_by_role("button", name=...)   [A - 0.88]
# Link "Forgot password" -> page.get_by_role("link", name=...)     [B - 0.72]

def test_login(page: Page):
    page.goto("https://myapp.com/login", wait_until="domcontentloaded")

    # TODO: Write your test logic using the validated selectors above
    pass

CI Self-Healing

# In your CI pipeline, after tests fail:
qapal heal --test-results results.json --url $STAGING_URL --pr

QAPAL reads the failure report, finds which selectors broke, probes for working alternatives, patches the files, and opens a PR.

How It Works

QAPAL has a 4-step locator resolution chain:

1. DB chain lookup     (cached selectors from previous crawls)
2. Primary selector    (the one in your test file)
3. Fallback selector   (testid-prefix matching, OR-locator for testid variants)
4. AI rediscovery      (one-shot AI call using accessibility snapshot -- optional)

Scoring Model

Each selector gets a confidence score (0.0 - 1.0) based on weighted factors:

Strategy scores:

CLI Reference

qapal analyze <files> --url <url> [--format table|json|github]
qapal fix     <files> --url <url> [--dry-run|--apply|--pr] [--min-confidence 0.8]
qapal generate        --url <url> [--output dir] [--language python|typescript]
qapal probe   "<sel>" --url <url>
qapal heal    --test-results <json> --url <url> [--pr]

Global Options

GitHub Actions Output

qapal analyze tests/ --url $STAGING_URL --format github

Outputs GitHub-compatible annotations:

::error file=tests/login.spec.ts,line=19::Broken selector: page.getByTestId('nonexistent') - element not found
::warning file=tests/login.spec.ts,line=12::Weak selector: page.locator('.btn') (confidence: 0.30)

GitHub Action

Add to your CI workflow:

name: Playwright Tests + QAPAL Healing

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: |
          pip install qapal[ai]
          playwright install chromium --with-deps

      - name: Run Playwright tests
        id: tests
        continue-on-error: true
        run: |
          pytest tests/ --json-report --json-report-file=results.json

      - name: QAPAL Analyze
        if: always()
        run: |
          qapal analyze tests/ --url ${{ vars.STAGING_URL }} --format github

      - name: QAPAL Heal (on failure)
        if: steps.tests.outcome == 'failure'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          qapal heal --test-results results.json --url ${{ vars.STAGING_URL }} --pr

Authentication

For apps behind login, provide a credentials file:

{
  "url": "https://myapp.com/login",
  "username": "test@example.com",
  "password": "testpass123",
  "username_field": "email",
  "password_field": "password",
  "submit_button": "sign-in"
}

qapal analyze tests/ --url https://myapp.com/dashboard --credentials-file creds.json

Python + TypeScript

QAPAL parses both languages:

Python (pytest-playwright):

page.get_by_test_id("email")
page.get_by_role("button", name="Submit")
page.locator(".css-selector")

TypeScript (@playwright/test):

page.getByTestId('email')
page.getByRole('button', { name: 'Submit' })
page.locator('.css-selector')

Fixes are generated in the correct language for each file.

Installation

pip install qapal
playwright install chromium

Optional extras

pip install "qapal[ai]"       # AI rediscovery (anthropic + openai)
pip install "qapal[all]"      # Everything

From source

git clone https://github.com/ahmadsharabati/QAPAL.git
cd QAPAL
pip install -e ".[dev]"
playwright install chromium

Environment Variables

License

MIT