# Getting Started with iVisionQA

iVisionQA is an AI-powered visual testing and accessibility auditing framework built on [Playwright](https://playwright.dev) and [Claude Vision](https://anthropic.com). It replaces pixel-diff tools like Applitools with semantic AI analysis that understands your UI the way a human QA engineer would.

## What iVisionQA Does

- **AI Visual Review** --- Claude Vision analyzes screenshots and scores UI quality (layout, typography, spacing, color, accessibility) on a 0--100 scale
- **Visual Regression Testing** --- Compares baseline and current screenshots using AI to detect unintended changes while ignoring expected ones (timestamps, dynamic data, avatars)
- **Accessibility Auditing** --- axe-core WCAG 2.1 AA scanning integrated as a Playwright fixture

## Prerequisites

- Node.js 18+
- An [Anthropic API key](https://console.anthropic.com) (for Claude Vision analysis)
- A running web application to test

## Quick Setup

### 1. Install dependencies

```bash
npm install --save-dev @anthropic-ai/sdk @axe-core/playwright @playwright/test dotenv
npx playwright install chromium
```

### 2. Create the AI analyzer

Create `lib/ivisionqa/ai-analyzer.ts` in your project root. This is the core engine that sends screenshots to Claude Vision and returns structured quality reports.

> If you're setting up from scratch, run the setup script:
>
> ```bash
> bash setup-visionqa.sh
> ```
>
> This creates all directories, files, and installs dependencies automatically.

### 3. Create the environment file

Create `.env.ivisionqa` in your project root:

```env
ANTHROPIC_API_KEY=sk-ant-your-key-here
BASE_URL=http://localhost:3000
TEST_EMAIL=your-test-user@example.com
TEST_PASSWORD=your-test-password
```

### 4. Create your first test

Create `tests/ivisionqa/my-app.spec.ts`:

```typescript
import { test, expect } from "./fixtures";

const PAGES = [
  {
    name: "Home",
    path: "/",
    description: "Landing page with hero section and feature highlights",
    expectedElements: ["Navigation", "Hero section", "CTA button"],
  },
  {
    name: "Dashboard",
    path: "/dashboard",
    description: "User dashboard with stats and activity feed",
    expectedElements: ["Stats cards", "Activity list", "Sidebar nav"],
  },
];

for (const pg of PAGES) {
  test.describe(pg.name, () => {
    // AI analyzes the screenshot and scores UI quality
    test(`${pg.name} -- AI visual review @ai-review`, async ({
      page,
      aiAnalyze,
    }) => {
      await page.goto(pg.path);
      await page.waitForLoadState("networkidle");

      const result = await aiAnalyze({
        pageName: pg.name,
        pageDescription: pg.description,
        expectedElements: pg.expectedElements,
        strictness: "medium",
      });

      expect(
        result.passed,
        `AI score ${result.score}/100: ${result.summary}`,
      ).toBe(true);
      expect(
        result.issues.filter((i) => i.severity === "critical"),
      ).toHaveLength(0);
    });

    // Compare current screenshot against a saved baseline
    test(`${pg.name} -- visual regression @visual`, async ({
      page,
      aiCompare,
    }) => {
      await page.goto(pg.path);
      await page.waitForLoadState("networkidle");

      const result = await aiCompare(`my-app-${pg.name.toLowerCase()}`, {
        pageName: pg.name,
        allowedChanges: ["Dynamic data", "Timestamps"],
        strictness: "medium",
      });

      expect(result.passed).toBe(true);
    });

    // WCAG 2.1 AA accessibility scan (no AI cost)
    test(`${pg.name} -- accessibility @a11y`, async ({ page, a11yScan }) => {
      await page.goto(pg.path);
      await page.waitForLoadState("networkidle");

      const results = await a11yScan();
      const serious = results.violations.filter(
        (v: any) => v.impact === "critical" || v.impact === "serious",
      );
      expect(serious).toHaveLength(0);
    });
  });
}
```

### 5. Run the tests

```bash
# Run just accessibility tests (free, no API calls)
npx playwright test --grep @a11y

# Run AI visual reviews (uses Anthropic API)
npx playwright test --grep @ai-review

# Run visual regression tests (uses Anthropic API)
npx playwright test --grep @visual

# Run everything
npx playwright test
```

### 6. View results

```bash
npx playwright show-report
```

Reports are saved to:

- `test-results/screenshots/` --- captured screenshots
- `test-results/ai-reports/` --- JSON analysis reports from Claude
- `playwright-report/` --- Playwright HTML report with attached screenshots and AI reports

## How Scoring Works

Claude Vision assigns a 0--100 quality score based on the analysis context you provide. The `strictness` setting determines the pass/fail threshold:

| Strictness | Threshold | Use Case                      |
| ---------- | --------- | ----------------------------- |
| `low`      | 50        | Early development, prototypes |
| `medium`   | 70        | Staging, pre-release          |
| `high`     | 85        | Production, polished UI       |

### Issue Severities

| Severity     | Icon      | Meaning                                       |
| ------------ | --------- | --------------------------------------------- |
| `critical`   | Red       | Broken layout, missing elements, unusable UI  |
| `major`      | Orange    | Significant visual issues affecting usability |
| `minor`      | Yellow    | Cosmetic issues, minor misalignments          |
| `suggestion` | Lightbulb | Improvements that would enhance quality       |

## Test Tags

iVisionQA uses Playwright's `@tag` convention to organize tests:

| Tag          | What It Tests                   | API Cost    |
| ------------ | ------------------------------- | ----------- |
| `@a11y`      | WCAG accessibility (axe-core)   | Free        |
| `@ai-review` | AI screenshot quality analysis  | ~$0.01/page |
| `@visual`    | AI visual regression comparison | ~$0.02/page |

Run specific tags with `--grep`:

```bash
npx playwright test --grep @a11y          # free
npx playwright test --grep @ai-review     # AI analysis
npx playwright test --grep "@a11y|@visual" # combine tags
```

## Next Steps

- [API Reference](./api-reference.md) --- Full TypeScript API for the AI analyzer
- [Playwright Fixtures](./playwright-fixtures.md) --- Custom fixtures for `aiAnalyze`, `aiCompare`, and `a11yScan`
- [CI/CD Integration](./ci-cd-integration.md) --- GitHub Actions, GitLab CI, and other pipelines
- [Configuration](./configuration.md) --- Playwright config, multi-app projects, and environment setup