mrnewdelhi/self-healing-locator-framework

Self-healing-locator-framework is a TypeScript project that shows how to keep UI automation tests working even when a website's elements change unexpectedly. It is aimed at teams running automated tests against CMS driven or black box products they do not fully control. The problem it addresses: element identifiers like button ids, page markup, and visible text can change without warning, for example when a client updates content through a CMS. When that happens, automated test locators break even though the test itself is still logically correct, and teams end up spending time updating locators by hand. This framework adds a self healing layer between the test and the browser rather than changing the test flow. When a test asks for an element, it first checks a local JSON cache of previously successful locators. Each cached entry has a confidence score that rises when it works and falls when it fails. If the cache misses, or a cached locator stops working, the framework calls the Google Gemini SDK to suggest up to five ranked replacement candidates. The first attempt uses a faster text based Gemini model working from DOM and accessibility snapshots, and if that does not produce anything usable and a screenshot is available, captured through Playwright, it escalates to a vision capable Gemini model that can also look at the page image. Whichever candidate the browser can actually locate is saved back to the cache with an updated confidence score. Element identity is kept stable through DOM fingerprinting, so the framework can still recognize an element even after its id or surrounding markup has changed. The included demo runs against a public sample website, and falls back to a deterministic local mode when no Gemini API key is present, so continuous integration pipelines keep working without needing a live key. The README also notes that adapting this approach to mobile testing through Appium requires extra handling, since mobile accessibility trees are usually limited to what is currently visible on screen.