@sridharkikkeri/playwright-common 1.0.22 → 1.0.24

package/VISUAL_TESTING.md

@@ -1,319 +0,0 @@
-# Visual Regression Testing
-
-## Overview
-The framework includes built-in visual regression testing using Playwright's snapshot comparison, wrapped in `VisualTesting` utility with Allure integration.
-
----
-
-## Quick Start
-
-### 1. Basic Usage
-
-```typescript
-import { test } from '@healthedge/common';
-import { VisualTesting } from '@healthedge/common';
-
-test('Visual regression - Homepage', async ({ page }) => {
-  const visual = new VisualTesting(page);
-  
-  await page.goto('https://example.com');
-  
-  // Compare full page
-  await visual.compareFullPage({ name: 'homepage' });
-});
-```
-
-### 2. Element-Specific Comparison
-
-```typescript
-test('Visual regression - Login button', async ({ page }) => {
-  const visual = new VisualTesting(page);
-  const loginBtn = page.locator('#login-btn');
-  
-  await visual.compareElement(loginBtn, { 
-    name: 'login-button',
-    threshold: 0.02  // Allow 2% difference
-  });
-});
-```
-
-### 3. Masking Dynamic Content
-
-```typescript
-test('Visual regression - Mask timestamps', async ({ page }) => {
-  const visual = new VisualTesting(page);
-  
-  await page.goto('/dashboard');
-  
-  // Mask elements that change frequently
-  await visual.compareFullPage({
-    name: 'dashboard',
-    mask: [
-      page.locator('.timestamp'),
-      page.locator('.user-avatar'),
-      page.locator('[data-dynamic="true"]')
-    ]
-  });
-});
-```
-
----
-
-## API Reference
-
-### compareFullPage(options?)
-Compare entire page screenshot against baseline.
-
-**Options:**
-- `name`: Snapshot filename (default: 'full-page')
-- `threshold`: Max pixel difference ratio 0-1 (default: 0.01)
-- `mask`: Array of locators to mask
-- `fullPage`: Capture full scrollable page (default: true)
-
-### compareElement(locator, options?)
-Compare specific element screenshot.
-
-**Options:**
-- `name`: Snapshot filename (default: 'element')
-- `threshold`: Max pixel difference ratio 0-1 (default: 0.01)
-
-### compareViewport(options?)
-Compare visible viewport only (no scrolling).
-
-**Options:**
-- `name`: Snapshot filename (default: 'viewport')
-- `threshold`: Max pixel difference ratio 0-1 (default: 0.01)
-- `mask`: Array of locators to mask
-
-### captureBaseline(name, fullPage?)
-Manually capture baseline (for documentation purposes).
-
----
-
-## Workflow
-
-### 1. Create Baselines (First Run)
-```bash
-# Generate baseline snapshots
-npx playwright test --update-snapshots
-```
-
-Baselines are stored in `**/__snapshots__/` directories.
-
-### 2. Run Visual Tests
-```bash
-# Compare against baselines
-npx playwright test
-```
-
-### 3. Review Failures
-When visual tests fail, Playwright generates:
-- **Actual**: Current screenshot
-- **Expected**: Baseline screenshot
-- **Diff**: Highlighted differences
-
-Located in: `test-results/*/`
-
-### 4. Update Baselines
-```bash
-# Update specific test
-npx playwright test visual.spec.ts --update-snapshots
-
-# Update all
-npx playwright test --update-snapshots
-```
-
----
-
-## Configuration
-
-### Playwright Config
-```typescript
-// playwright.config.ts
-export default defineConfig({
-  expect: {
-    toHaveScreenshot: {
-      maxDiffPixels: 100,        // Max different pixels
-      threshold: 0.2,            // Per-pixel color threshold
-      animations: 'disabled',    // Disable CSS animations
-    }
-  }
-});
-```
-
-### Per-Test Override
-```typescript
-await visual.compareFullPage({
-  threshold: 0.05,  // Allow 5% difference for this test
-});
-```
-
----
-
-## Best Practices
-
-### 1. Stable Test Data
-```typescript
-// ❌ Bad: Random data causes failures
-await page.fill('#name', Math.random().toString());
-
-// ✅ Good: Fixed test data
-await page.fill('#name', 'Test User');
-```
-
-### 2. Mask Dynamic Content
-```typescript
-// Mask timestamps, user-specific data, ads
-await visual.compareFullPage({
-  mask: [
-    page.locator('.timestamp'),
-    page.locator('.ad-banner'),
-    page.locator('[data-user-id]')
-  ]
-});
-```
-
-### 3. Wait for Stability
-```typescript
-// Wait for animations/loading
-await page.waitForLoadState('networkidle');
-await page.waitForTimeout(500);  // Allow CSS transitions
-
-await visual.compareFullPage();
-```
-
-### 4. Descriptive Names
-```typescript
-// ❌ Bad
-await visual.compareFullPage({ name: 'test1' });
-
-// ✅ Good
-await visual.compareFullPage({ name: 'checkout-page-logged-in' });
-```
-
-### 5. Cross-Browser Baselines
-```bash
-# Generate baselines per browser
-npx playwright test --update-snapshots --project=chromium
-npx playwright test --update-snapshots --project=firefox
-```
-
-Snapshots are stored separately: `homepage-chromium.png`, `homepage-firefox.png`
-
----
-
-## CI/CD Integration
-
-### GitHub Actions
-```yaml
-- name: Run Visual Tests
-  run: npx playwright test
-
-- name: Upload Visual Diffs
-  if: failure()
-  uses: actions/upload-artifact@v3
-  with:
-    name: visual-diffs
-    path: test-results/
-```
-
-### Baseline Management
-**Option 1**: Commit baselines to Git
-```bash
-git add **/__snapshots__/
-git commit -m "Update visual baselines"
-```
-
-**Option 2**: Store in artifact repository (S3, Artifactory)
-
----
-
-## Troubleshooting
-
-### Issue: Flaky Visual Tests
-**Causes:**
-- Animations not disabled
-- Fonts not loaded
-- Network requests pending
-
-**Solution:**
-```typescript
-await page.waitForLoadState('networkidle');
-await page.evaluate(() => document.fonts.ready);
-await page.waitForTimeout(500);
-```
-
-### Issue: Cross-Platform Differences
-**Cause**: Font rendering differs between OS
-
-**Solution**: Run tests in Docker with consistent environment
-```dockerfile
-FROM mcr.microsoft.com/playwright:v1.42.0-focal
-```
-
-### Issue: Large Snapshot Files
-**Solution**: Use viewport comparison instead of full page
-```typescript
-await visual.compareViewport({ name: 'above-fold' });
-```
-
----
-
-## Example Test Suite
-
-```typescript
-import { test } from '@healthedge/common';
-import { VisualTesting } from '@healthedge/common';
-
-test.describe('Visual Regression Suite', () => {
-  test.beforeEach(async ({ page }) => {
-    await page.goto('/');
-    await page.waitForLoadState('networkidle');
-  });
-
-  test('Homepage - Desktop', async ({ page }) => {
-    const visual = new VisualTesting(page);
-    await visual.compareFullPage({ name: 'homepage-desktop' });
-  });
-
-  test('Homepage - Mobile', async ({ page }) => {
-    await page.setViewportSize({ width: 375, height: 667 });
-    const visual = new VisualTesting(page);
-    await visual.compareFullPage({ name: 'homepage-mobile' });
-  });
-
-  test('Login Modal', async ({ page }) => {
-    const visual = new VisualTesting(page);
-    await page.click('#login-btn');
-    
-    const modal = page.locator('.login-modal');
-    await visual.compareElement(modal, { name: 'login-modal' });
-  });
-
-  test('Dashboard - Mask Dynamic', async ({ page }) => {
-    const visual = new VisualTesting(page);
-    await page.goto('/dashboard');
-    
-    await visual.compareFullPage({
-      name: 'dashboard',
-      mask: [
-        page.locator('.last-login-time'),
-        page.locator('.notification-badge')
-      ]
-    });
-  });
-});
-```
-
----
-
-## Allure Integration
-
-Visual test results automatically appear in Allure reports:
-- ✅ **Passed**: Green checkmark
-- ❌ **Failed**: Diff image attached
-- 📸 **Baseline**: Attached for reference
-
-```bash
-npm run report  # View in Allure
-```