dom-locator-guard

v1.0.7

Published

5 days ago

Core engine: snapshot, diff, similarity scoring, report

🛡️ dom-locator-guard

Stop broken tests before they happen.

Detect unintended locator changes in your HTML before they silently break your automation tests.

"If your tests ever failed because of a renamed id or data-testid, this tool is for you."

😵 The Problem

Your test targets:

#loginbtn

A developer refactors the UI and changes it to:

#loginBtn

✅ UI still works perfectly 💥 But your entire test suite fails

And you only find out... in CI. 😐

🚀 The Solution

dom-locator-guard catches this instantly — before it reaches CI.

It:

📸 Snapshots your HTML
🔍 Tracks critical locators (id, class, data-testid, etc.)
⚠️ Detects changes the moment they happen
📍 Shows exact line + what changed + what to fix

📦 Install

npm install --save-dev dom-locator-guard

⚡ Quick Start

# 1. Initialize (one-time setup)
npx dlg init

# 2. Save baseline — your "source of truth"
npx dlg baseline .

# 3. After changes, detect locator drift
npx dlg check .

# 4. View reports in browser
npx dlg dashboard

🧠 Why This Matters

| Without this tool | With dom-locator-guard | |---|---| | ❌ Tests fail randomly | ✅ Catch issues before push | | ❌ Debugging takes hours | ✅ See the exact line that changed | | ❌ CI gets noisy | ✅ Keep your pipeline clean | | ❌ QA & dev blame each other 😅 | ✅ Ship faster with confidence |

🧰 Commands

| Command | Description | |---|---| | npx dlg init | Setup project, create .dlg/, install git hook | | npx dlg baseline <file\|.> [files...] | Save baseline snapshot | | npx dlg check <file\|.> [files...] | Detect locator changes | | npx dlg report | Show summary in terminal | | npx dlg dashboard | Open web dashboard |

🎯 Targeting Files

All files:

npx dlg baseline .
npx dlg check .

Single file:

npx dlg baseline login.html
npx dlg check login.html

Multiple files:

npx dlg baseline login.html register.html checkout.html
npx dlg check login.html register.html checkout.html

📌 Supported: .html · .jsx · .tsx

⚙️ How It Works

1️⃣ Save baseline

npx dlg baseline login.html

Stores the current locator state as the reference point.

2️⃣ Developer changes something

<!-- before -->
<button id="loginbtn">Login</button>

<!-- after (no one notices 👀) -->
<button id="loginBtn">Login</button>

3️⃣ Run check

npx dlg check login.html

⚠  login  ·  login.html

1 locator change(s) detected

┌ <button> "Login"  (93% confidence)
│
│  📍 Line 9, Col 3
│
│     7      </head>
│     8      <body>
│     9      <button id="loginBtn">Login</button>  ← changed
│    10      </body>
│
│  action  →  #loginBtn
│  id changed from "loginbtn" to "loginBtn". Update your test from #loginbtn to #loginBtn.
└──────────────────────────────────────────────────

4️⃣ Decide

❌ Not intended → ask developer to revert → run check again → clean
✅ Intended → update baseline: npx dlg baseline login.html

🔐 Git Pre-Push Protection

Automatically installed when you run npx dlg init.

Every git push triggers a locator check:

🛡  Locator Guard — running pre-push checks...

  ✓  login.html — all locators stable
  ✓  checkout.html — all locators stable

✅  All checks passed — push allowed

If something changed:

❌  Push blocked — fix the locator changes above, then push again.
  Or if intentional, run: npx dlg baseline checkout.html

No more surprises in CI.

📊 Web Dashboard

npx dlg dashboard

🌐 Open: http://localhost:3333

See:

📈 Change history across all features
🎯 Confidence score per element
📍 Exact code diff with line numbers
📂 All tracked files in one place

🧬 Tracked Attributes

| Attribute | Severity | |---|---| | data-testid, data-cy | 🔴 Critical | | id, name | 🟠 High | | aria-label, role, class | 🟡 Medium |

⚙️ Configuration

npx dlg init creates dlg.config.json:

{
  "threshold": 0.75,
  "trackedAttributes": ["id", "name", "dataTestId", "dataCy", "ariaLabel", "class"],
  "ignoreSelectors": []
}

| Option | Description | |---|---| | threshold | Similarity score (0–1) for element matching. Default: 0.75 | | trackedAttributes | Attributes to monitor | | ignoreSelectors | Selectors to ignore (e.g. ad banners, dynamic timestamps) |

🗂 Project Structure

your-project/
├── .dlg/                  ← gitignored automatically
│   ├── baselines/         ← stored snapshots
│   └── reports/           ← generated reports
├── .git/hooks/
│   └── pre-push           ← auto-installed by dlg init
├── dlg.config.json
└── .gitignore             ← .dlg/ and node_modules/ added automatically

💡 Pro Tip

Run this before every commit:

npx dlg check .

Think of it like:

ESLint → catches code issues
Prettier → catches formatting issues
dom-locator-guard → catches locator drift 🔥

🧾 License

MIT — Joan Purba