Reveal what your locator could not.

Revelium is a focused Selenium diagnostic layer that reveals why a locator failed, what still exists in the DOM, and what probably changed in the UI.

Explore the flow View GitHub repo

Reveal candidates that still resemble the missing target

Preserve local-first debugging with structured reports

Keep runtime diagnosis separate from exploration and mapping

Product Scope

A narrow runtime tool with a clear diagnostic job.

Revelium is not trying to become a general Selenium framework. It exists to add context at the exact moment a locator fails, then hand control back to the existing automation flow.

Diagnosis first

Revelium is built to explain UI drift and locator failures before teams reach for brittle retries or hidden healing behavior.

Focused scope

The core product stays intentionally small: Selenium runtime integration, failure snapshots, candidate analysis, heuristic ranking, and local reports.

Useful by default

When a locator fails, Revelium captures current context, ranks nearby alternatives, saves machine-readable output, and re-raises the original exception.

How It Works

Capture failure state, rank alternatives, keep the exception honest.

1
Capture page source and current URL at failure time
2
Build a failure snapshot with action, locator, hint, and timestamp
3
Extract relevant DOM candidates and score them with simple heuristics
4
Save a local report and optional DOM snapshot before re-raising the original Selenium error

Heuristics used in the MVP

tag compatibilitypartial text overlapid and name similarityaria-label similaritydata-testid similarityhint coherence

The heuristics stay intentionally simple. Revelium helps teams understand failure drift before leaning on hidden magic.

Public API

Small surface area, practical output.

ReveliumConfig controls reporting, waits, and experimental behavior
ReveliumDriver wraps a real Selenium driver
Supported actions include find, click, and type
Optional hints add human intent like "login button" or "email field"

pip install revelium

rv.click(By.ID, "submit-login", hint="login button")

Structured Failure Report

{
  "action": "click",
  "locator": {
    "by": "id",
    "value": "submit-login"
  },
  "hint": "login button",
  "page_url": "https://example.com/login",
  "revealed_candidates": [
    {
      "locator": "[data-testid='login-submit']",
      "score": 0.93,
      "reasons": [
        "attribute similarity",
        "button-like element",
        "hint match"
      ]
    }
  ],
  "probable_cause": "Locator drift after UI change"
}

Current Status

Active concept validation, still evolving.

Revelium is currently a work in progress. The product direction is already visible, but the package surface, heuristics, and runtime ergonomics are still being refined.

Follow progress on GitHub

Experimental Healing

Suggest or attempt a fallback, but keep it explicit.

Revelium can optionally suggest a candidate or attempt an auto-heal, but that behavior remains experimental. The product concept is diagnosis first, not invisible recovery.

suggest_healauto_healauto_heal_min_score

Product Boundary

Exploration and mapping live in Tabula QA.

Assisted capture, page discovery, and page mapping workflows are being kept outside Revelium on purpose. That keeps runtime diagnosis lean while Tabula QA handles pre-automation exploration.

View Tabula QA

Positioning

Built for teams that need more signal than a raw Selenium traceback.

Revelium fits QA, SDET, and platform contexts where frontend drift breaks stable suites and faster failure diagnosis matters more than another opaque exception.

Interested in Revelium? Want a tailored implementation for your team?

Schedule a callOrEmail me