> For the complete documentation index, see [llms.txt](https://chaoslabz.gitbook.io/viewgraph/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://chaoslabz.gitbook.io/viewgraph/features/playwright.md).

# Playwright Integration

Capture structured DOM snapshots during Playwright E2E tests. Generate tests from browser captures. Bridge the gap between what you see in the browser and what your test suite covers.

## The Problem

Writing E2E tests is slow:

* **Manual element discovery** - open DevTools, inspect elements, copy selectors. 20-30 minutes per page.
* **Stale selectors** - someone renames a class, test breaks, 15 minutes to debug.
* **Incomplete coverage** - you test the happy path but miss buttons without testids, inputs without labels.

## Two Workflows

### Generate tests from captures (new projects)

1. Capture a page with the ViewGraph extension
2. Tell your agent: `@vg-tests`
3. Agent generates a complete Playwright test file with correct locators for every interactive element

![Generating tests from a capture](/files/PY9sbN14Ay62eYKC49zT)

**20-30 minutes of manual inspection reduced to one prompt.**

### Capture during tests (existing suites)

```js
import { test } from '@viewgraph/playwright/fixture';

test('checkout flow', async ({ page, viewgraph }) => {
  await page.goto('/cart');
  await viewgraph.capture('cart-page');

  await page.click('[data-testid="checkout-btn"]');
  await viewgraph.capture('checkout-page');
});
```

After tests run, your agent can diff captures between runs, audit accessibility, and detect structural regressions.

### Flag issues from test assertions

```js
test('form validation', async ({ page, viewgraph }) => {
  await page.goto('/signup');

  if (!await page.getByTestId('email').getAttribute('aria-label')) {
    await viewgraph.annotate('[data-testid="email"]', 'Missing aria-label', {
      severity: 'major',
      category: 'a11y',
    });
  }

  await viewgraph.captureWithAnnotations('signup-a11y-issues');
});
```

## Install

```bash
npm install @viewgraph/playwright
```

[![npm](https://img.shields.io/npm/v/@viewgraph/playwright)](https://www.npmjs.com/package/@viewgraph/playwright)

## API

### Fixture

```js
import { test, expect } from '@viewgraph/playwright/fixture';

test('my test', async ({ page, viewgraph }) => {
  await page.goto('/login');
  const capture = await viewgraph.capture('login-page');
  expect(capture.metadata.stats.totalNodes).toBeGreaterThan(10);
});
```

### Standalone

```js
import { createViewGraph } from '@viewgraph/playwright';

const vg = await createViewGraph(page, { capturesDir: './test-captures' });
const capture = await vg.capture('dashboard');
```

### Methods

| Method                                  | Description                                            |
| --------------------------------------- | ------------------------------------------------------ |
| `capture(label?)`                       | Capture DOM as ViewGraph JSON. Writes to captures dir. |
| `snapshot()`                            | Capture HTML snapshot string.                          |
| `annotate(selector, comment, options?)` | Add a programmatic annotation.                         |
| `captureWithAnnotations(label?)`        | Capture with pending annotations attached.             |

Full documentation: [@viewgraph/playwright on GitHub](https://github.com/sourjya/viewgraph/tree/main/packages/playwright)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://chaoslabz.gitbook.io/viewgraph/features/playwright.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.