auto-heal-utility/README.md

A Playwright utility for auto-healing broken locators.

# Auto-Healer Utility for Playwright

This utility provides a way to auto-heal broken locators in your Playwright tests. It works by logging locator failures and then using that data to intelligently select the best locator from a list of alternatives.

## Installation

```bash
npm install auto-healer-utility
```

## Usage

```typescript
import { WaitHelper } from 'auto-healer-utility';
import { test } from '@playwright/test';

test('my test', async ({ page }) => {
  const waitHelper = new WaitHelper(page);

  // Use the waitHelper to interact with elements
  await waitHelper.waitForElementAndClick([page.locator('#button1'), page.locator('#button2')], {
    feature: 'my feature',
    scenario: 'my scenario',
    step: 'click button',
  });
});
```

## How it Works

The `WaitHelper` class is the main entry point for the utility. It takes a Playwright `Page` object in its constructor. The `waitForElementAndClick` and `waitForElementAndFill` methods take an array of locators and a metadata object. The metadata object is used to log information about the test that is running.

The `AutoHeal` class is responsible for the core auto-healing logic. It works by:

1.  **Logging failures:** When a locator fails, the `AutoHeal` class logs the failure to a file. The log entry includes the locator, the reason for the failure, and the metadata.
2.  **Analyzing logs:** The `AutoHeal` class analyzes the log file to determine which locators are the most reliable. It does this by counting the number of times each locator has failed.
3.  **Selecting the best locator:** When you call `waitForElementAndClick` or `waitForElementAndFill`, the `AutoHeal` class selects the best locator from the array of locators that you provide. It does this by selecting the locator that has failed the least number of times.

## Configuration

The `AutoHeal` class can be configured with the following options:

*   `timeout`: The timeout in milliseconds to wait for a locator to be attached to the DOM. Defaults to 60 seconds.
*   `logFile`: The path to the log file. Defaults to `logs/locator_failures.log`.