tamash-selenium — Documentation & Support

Plug-and-play self-healing for Selenium Java — JUnit 5, TestNG, and Cucumber, with Page Object Model and PageFactory support out of the box.

Websites change often — a button gets renamed or moved, and findElement can't find it anymore, even though the app still works fine for real users. tamash-selenium fixes this automatically: when findElement can't find an element, it locates it on the live page — with a free rule-based matcher or an AI model — and retries. If it succeeds, your test keeps going. If not, it fails exactly as it would have without the package; healing never masks a real failure. Every attempt — healed or not — is fully logged: provider used, selector suggested, token cost.

No new framework to learn. The whole integration is one line:

WebDriver driver = SelfHealingDriver.wrap(new ChromeDriver());

This repository is both the library source and the home for documentation and support — how to install and use it, and where to raise bugs, feature requests, or support questions. A separate, runnable example lives in the sample repo linked below.

Part of the same idea across ecosystems — tamash-playwright brings the equivalent self-healing to Playwright (TypeScript, Python, Java). Same approach, separate package per framework.

Free to use, modify, and redistribute (including commercially) under the Apache License 2.0 — see License. Pick your provider — the rule-based tamash provider (free, no AI, no network), Ollama, OpenAI, Anthropic, Gemini, or your own Claude or GitHub Copilot subscription, no separate API key needed — and give it a try.

Contents

• How it works
• Package
• Full documentation
• Quick start
• Supported AI providers
• Sample implementation
• Getting support, reporting bugs, requesting features
• Filtering issues by framework
• License

How it works

1. Your test runs as normal using Selenium.
2. findElement fails to find its element (page changed, selector went stale, etc.).
3. tamash-selenium captures a JS-derived DOM accessibility snapshot of the current page.
4. It text-matches that snapshot against the element's decoded description (the free tamash provider), or sends it to your configured AI provider and asks it to find the described element.
5. If a match is found, a durable By is derived and verified against the live element, the call is retried, and the test continues.
6. If it can't be healed, the test fails normally — same as stock Selenium.
7. Every attempt (healed or not) is logged: provider, model, suggested selector, and token cost, plus an optional HTML report of the run.

Package

Full documentation

The complete guide — install steps, .env setup, every code pattern (Page Object Model, PageFactory, keyword-driven, JUnit 5 / TestNG / Cucumber), what gets healed vs. not, the doctor / apply-heals / init-skill CLIs, and how to read the report — is published on this site:

• Full guide →

The quick start below is the short version — start here if you just want a working example.

Quick start

Works with JUnit 5, TestNG, or Cucumber.

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

Wherever you create the driver:

import com.vibetestq.qtpsudhakar.tamash.SelfHealingDriver;

WebDriver driver = SelfHealingDriver.wrap(myDriver);   // RemoteWebDriver / Grid / cloud all fine

With no configuration, healing uses the free rule-based tamash provider — no key, no network, no tokens. For stronger (semantic) healing, create a .env file with your AI provider (see Supported AI providers):

HEALER_ENABLED=true
HEALER_PROVIDER=ollama
OLLAMA_MODEL=gpt-oss:120b
OLLAMA_API_KEY=your_key_here

No API key issued to you? If you have a personal Claude or GitHub Copilot subscription (including the free Copilot tier), use that instead — no key to paste anywhere:

HEALER_PROVIDER=claude-subscription
CLAUDE_SUBSCRIPTION_MODEL=claude-haiku-4-5

Verify your setup, then run tests as usual:

mvn exec:java -Dexec.args="doctor"
mvn test

Full guide: tamash-selenium docs. Working example (JUnit 5, TestNG, Cucumber, POM, PageFactory, keyword-driven, and a deliberately-broken-locator demo, run against a live app): tamash-selenium-java-sample.

Supported AI providers

Pick whichever fits your budget and environment. Configuration is via environment variables (typically loaded from a .env file).

See the full guide's provider section for exact variable names and one-time CLI setup for the two subscription providers.

Sample implementation

Want to see it wired into a real framework before you touch your own?

Getting support, reporting bugs, requesting features

All support for tamash-selenium is handled through this repository's Issues.

Open a new issue and pick the template that matches what you need:

Each template asks you to select your Framework (JUnit 5 / TestNG / Cucumber), plus the package version, provider, and relevant logs — used to automatically label your issue and route it to the right context faster.

Before opening a new issue, please search existing issues to avoid duplicates.

Filtering issues by framework

Every issue opened through a template is automatically labeled based on the Framework you selected, using labels like framework: junit5, framework: testng, framework: cucumber, along with the standard bug / enhancement / question type labels.

Use the Issues label filter or a search query to narrow things down, for example:

• All TestNG issues: label:"framework: testng"
• Open bugs: label:bug is:open

License

Apache License, Version 2.0 — free to use, modify, and redistribute, including commercially, as long as you keep the copyright and license notices. Contributions welcome — see CONTRIBUTING.md.

Links: Maven Central · Source · Sample repo · tamash-playwright (sibling project)