npm package: @sridharkikkeri/playwright-common
Description: Production-grade Playwright framework with AI-powered self-healing, visual regression, and enterprise features
Author: HealthEdge
Latest version: 1.0.49

# HealthEdge Playwright Framework

A production-grade, resilient Playwright framework built with **SOLID Architecture** and **AI-Powered Self-Healing**.

## 🚀 Key Features
- **Resilient UI Interactions**: Powered by a custom `ElementWrapper` and `ActionOrchestrator`.
- **AI Self-Healing**: Automatically recovers from broken locators using element fingerprinting and LLM analysis.
- **Smart Configuration**: Centrally managed settings via `framework.config.json`.
- **Full API Support**: Robust `ApiClient` with integrated authentication strategies.
- **Enterprise Ready**: Includes Localization (i18n), Allure Reporting, ESLint, and Semgrep.

---

## 📦 Getting Started

### 1. Installation
Install the framework in your existing Playwright project:
```bash
npm install @sridharkikkeri/playwright-common
```

### 2. Scaffold a New Project
Or bootstrap a complete HealthEdge-ready environment:
```bash
npx create-healthedge-tests my-project
cd my-project
npm install
npm run test:dev
```

---

## 🏗️ Page Object Model (POM)

In a consumer project, extend `BasePage` and import it from the framework package.

### Creating a Page Object
```typescript
import { Page } from '@playwright/test';
import { BasePage } from '@sridharkikkeri/playwright-common';

export class LoginPage extends BasePage {
  constructor(page: Page) {
    super(page, { pageName: 'LoginPage' }); // pageName used for AI profiling
  }

  // Define resilient elements
  private readonly username = this.element('#username');
  private readonly loginBtn = this.element('button.submit');

  async login(user: string) {
    await this.username.fill(user, 'Enter Username');
    await this.loginBtn.click('Click Login Button');
  }
}
```

---

## 🧪 Testing Guide

### Enterprise Fixtures (Recommended)
The framework provides an extended `test` object. Instead of importing from `@playwright/test`, use the framework version.

#### **1. Usage in Tests**
```typescript
// ✅ Correct: Import 'test' from the framework package
import { test } from '@sridharkikkeri/playwright-common';

test('Login with Fixtures', async ({ loginPage }) => {
  await loginPage.navigate('https://example.com/login');
  await loginPage.login('admin', 'password');
});
```

#### **2. Extending Fixtures**
If you have a project-specific `fixtures.ts` (scaffolded by the generator), you can add your pages there:

```typescript
import { test as baseTest } from '@sridharkikkeri/playwright-common';
import { HomePage } from '../pages/HomePage';

export const test = baseTest.extend<{ homePage: HomePage }>({
  homePage: async ({ page, orchestrator }, use) => {
    await use(new HomePage(page, orchestrator));
  },
});
```

---

## 🌍 Advanced Features

### API Testing
```typescript
import { ApiClient } from '@sridharkikkeri/playwright-common';

test('API User Fetch', async ({ apiClient }) => {
  // apiClient is provided as a fixture!
  const response = await apiClient.get('/api/users/1');
  expect(response.status).toBe(200);
});
```

### Localization (i18n)
```typescript
import { Localization } from '@sridharkikkeri/playwright-common';

const welcomeMsg = Localization.get('welcome_message', 'en');
```

---

## ⚙️ Configuration

Control global settings in `framework.config.json` at your project root.

```json
{
  "healingEnabled": true,
  "environment": "dev",
  "baseUrl": "https://dev.example.com"
}
```

---

## 📚 Documentation
Full Javadoc-style documentation is available in the `api-docs` folder or at the [Package Homepage](https://www.npmjs.com/package/@sridharkikkeri/playwright-common).