Open Source · Java · Python · Apache 2.0

The page moved on.
Your suite doesn't have to.

TAMASH-Selenium is plug-and-play self-healing for Selenium. Wrap your WebDriver once and every findElement through it — in Page Objects, @FindBy fields, helper layers, inside a wait — recovers when a locator breaks. Rule-based and free by default; point it at an AI model only if you want to.

Get Started View on GitHub
Maven Central PyPI Java repo Python repo Using Playwright? Try TAMASH-Playwright

How It Works

One wrapped driver. No new framework.

Your tests run exactly as you wrote them. TAMASH-Selenium only steps in the moment a locator would otherwise throw.

1

A locator fails

The app shipped a change — an id got regenerated, a button moved — and findElement throws, even though the page still works fine for real users.

2

The element is found

TAMASH captures an accessibility-tree snapshot of the live page and matches your intent against it — with the built-in rule-based matcher, or an AI provider if you configured one.

3

Heal and continue

The match is converted into a durable By — id, name, data attribute, link text, then structural XPath — cached for the rest of the run, and logged in an HTML report.

Quick Start

One line to switch it on

Same self-healing behavior in both languages, native to how you already write Selenium tests.

Java

Maven Central · Java 21+ · Selenium 4.6+

<dependency>
  <groupId>com.vibetestq.qtpsudhakar</groupId>
  <artifactId>tamash-selenium</artifactId>
  <version>0.2.0</version>
</dependency>
import com.vibetestq.qtpsudhakar
       .tamash.SelfHealingDriver;

WebDriver driver =
    SelfHealingDriver.wrap(myDriver);
Working example

Python

PyPI · Python 3.9+ · pytest, Behave, unittest

pip install tamash-selenium
from selenium import webdriver
from tamash_selenium import (
    SelfHealingDriver)

driver = SelfHealingDriver.wrap(
    webdriver.Chrome())
Working example

That one wrap covers everything downstream — Page Objects, @FindBy fields, utility layers, and elements resolved inside a WebDriverWait. No test rewrite, no new API to learn.

Framework Support

Fits the runner you already use

Hook it in the way each framework expects — an annotation, a base class, a fixture, or a glue package.

JUnit 5

Add the @UseTamashSelenium annotation to your test class and the driver is wrapped and tracked per test.

TestNG

Extend TamashSeleniumTestNgTest — setup, teardown, and per-test attribution are handled for you.

Cucumber (Java)

Point Cucumber at the bundled glue package and every scenario picks up healing automatically.

pytest

The plugin auto-loads on install — request the driver or tamash_driver fixture and start writing steps.

pytest-bdd & Behave

pytest-bdd uses the same fixtures; Behave wires in through the hooks in tamash_selenium.integrations.behave.

unittest & custom runners

Extend TamashSeleniumTestCase, or call CurrentTest.set(…) yourself from any runner you've built.

Beyond Runtime Healing

Fix it once, not every run

A runtime heal keeps today's run green. Writing the fix back into your source is what stops the same locator from costing you again next week.

apply-heals CLI

Turns a runtime heal into a permanent source change — a surgical edit to the locator that actually broke, so the next run needs no healing at all.

HTML step reports

Every run writes a report to TAMASH_REPORT: each step, which locators healed, what they healed to, and which provider did it. Nothing happens invisibly.

Action recovery

Sometimes the element is found but the click isn't landing. Optional action recovery scrolls, waits, and re-dispatches instead of failing on a covered or off-screen element.

Implicit wait pinned to zero

Implicit waits and explicit waits don't mix. TAMASH pins the implicit wait to 0 by default so your WebDriverWait behaves predictably — override it with TAMASH_KEEP_IMPLICIT_WAIT if you must.

Healing Providers

Start free. Add AI only if you need it.

Providers are selected with the HEALER_PROVIDER environment variable, typically loaded from a .env file.

Default — no key, no network, no tokens

tamash — rule-based

Matches your locator's intent against the page's own accessibility tree. No API key, no subscription, no network call, no token cost. Never guesses — it declines rather than risk a wrong heal.

Bring your own API key

Ollama

Free, runs locally (or Ollama Cloud) — a good step up from rule-based without a bill.

OpenAI

Requires an OpenAI API key.

Anthropic

Requires an Anthropic API key.

Gemini

Requires a Google Gemini API key.

Already have a subscription? No API key needed

Claude subscription

Uses your existing Claude plan via claude-subscription.

GitHub Copilot subscription

Uses your Copilot seat via copilot-subscription (Python 3.11+).

Configuration

Environment variables, nothing else

No config class to extend, no YAML to maintain. Set what you need; every default is sensible on its own.

Variable What it does Example
HEALER_PROVIDER Chooses the healing strategy. tamash (default)
HEALER_ENABLED Turns healing off globally — useful for verifying that a fix works on its own. false
HEALER_ASSERTIONS How an assertion failure is treated when healing was involved. warn / strict
HEALER_ACTION_RECOVERY_ENABLED Recovers blocked actions by scrolling, waiting, and re-dispatching. true
TAMASH_KEEP_IMPLICIT_WAIT Keeps your implicit wait instead of pinning it to 0. true
TAMASH_REPORT Where the HTML step report is written. target/tamash-report.html

The Python package adds a few more for driver management — TAMASH_BROWSER, HEADLESS, TAMASH_REUSE_DRIVER, HEALER_PARALLEL, and TAMASH_ACTION_TIMEOUT_MS. Full reference in the docs.

Why Teams Switch

Free to use — including commercially

Apache 2.0 licensed. Most Selenium suites in the wild are years old and full of locators nobody wants to touch. This is for those suites.

Stock Selenium

  • A regenerated id or moved button breaks the locator
  • The test fails even though the app works fine for users
  • Someone has to notice, reproduce, and hand-fix the selector
  • No record of which locators are quietly fragile

With TAMASH-Selenium

  • One wrapped driver covers the whole suite — no test rewrite
  • Heals and continues when the element is genuinely there
  • Fails normally when it isn't — it declines rather than guess
  • A durable selector is derived, not another brittle XPath
  • Every heal logged in an HTML report, with attribution
  • apply-heals writes the fix back into your source, permanently

Samples & Support

See it wired into a real suite

Runnable samples for both languages, full documentation, and a direct line for anything else.

Sample Implementations

Page Object Model suites against OrangeHRM — Java with JUnit 5, TestNG, and Cucumber; Python with pytest, pytest-bdd, Behave, unittest, and data-driven styles.

Java sample

Python sample

Documentation

Installation, framework wiring, the full configuration reference, provider setup, and the apply-heals workflow — all in one place.

Read the docs

Bugs & Support

Raise bugs and feature requests on the repository that matches your language, or email us directly for anything that doesn't fit an issue.

Open an issue

support@vibetestq.com

Your Selenium suite isn't legacy.
It just needs to survive the next release.

Install it for free in Java or Python, wrap your driver, and point it at the locators that keep breaking.

Get Started on GitHub Talk to Us