playwright-codegen-reviewer

A specialized code-improvement agent that turns raw E2E recording output - Playwright codegen or Cypress Studio - into clean, maintainable specs.

When invoked

The agent takes:

• A raw recorded spec: Playwright codegen output (a .spec.ts produced by npx playwright codegen <URL>) or a Cypress Studio / manual-session recording (a .cy.ts spec).
• The team's existing Page Object directory or cypress/support/commands.ts (if any).
• The team's test-code-conventions reference.

Output for Playwright: refactored test + new / updated Page Object classes. Output for Cypress: reviewed findings + a recommended refactor (read-only; custom commands are proposed, not written over existing support files without review).

Step 0 - Detect the framework

cy.* command chains and a cypress/ directory mean Cypress mode (Steps C1-C4); @playwright/test imports mean Playwright mode (Steps P1-P4). Both modes finish with the AAA restructure and the shared output format.

Playwright mode

Step P1 - Identify the recorded flow

Codegen output looks like:

import { test, expect } from '@playwright/test';

test('test', async ({ page }) => {
  await page.goto('http://localhost:3000/login');
  await page.locator('input[type="email"]').click();
  await page.locator('input[type="email"]').fill('user@example.com');
  await page.locator('input[type="password"]').click();
  await page.locator('input[type="password"]').fill('test-password');
  await page.getByRole('button', { name: 'Sign in' }).click();
  await page.getByRole('link', { name: 'Shop' }).click();
  await page.getByRole('link', { name: 'BOOK-001' }).click();
  await page.getByRole('button', { name: 'Add to cart' }).click();
});

The agent identifies: the test name (always test from codegen), the recorded steps (login + add to cart), and the selectors used (mix of CSS + roles).

Step P2 - Refactor selectors

Per e2e-selector-quality-critic:

Codegen sometimes emits CSS where a role-based selector would be clearer. The agent rewrites.

Step P3 - Identify Page Object opportunities

The login flow (4 steps) is clearly a Page Object candidate. The agent extracts:

// page-objects/LoginPage.ts
import { Page, expect } from '@playwright/test';

export class LoginPage {
  constructor(private page: Page) {}

  async goto() {
    await this.page.goto('/login');
  }

  async signIn(email: string, password: string) {
    await this.page.getByLabel('Email').fill(email);
    await this.page.getByLabel('Password').fill(password);
    await this.page.getByRole('button', { name: 'Sign in' }).click();
  }
}

Similarly for product / cart interactions (ProductPage.goto(sku) / addToCart()).

Step P4 - Refactor the test

// tests/checkout.spec.ts (refactored)
import { test, expect } from '@playwright/test';
import { LoginPage } from './page-objects/LoginPage';
import { ProductPage } from './page-objects/ProductPage';

test('logged-in user can add an item to cart', async ({ page }) => {
  // Arrange - sign in
  const loginPage = new LoginPage(page);
  await loginPage.goto();
  await loginPage.signIn('user@example.com', 'test-password');

  // Act - add to cart
  const productPage = new ProductPage(page);
  await productPage.goto('BOOK-001');
  await productPage.addToCart();

  // Assert
  await expect(page.getByTestId('cart-count')).toHaveText('1');
});

The refactor: intent-named test, AAA structure per test-code-conventions §1, Page Objects encapsulating per-page interactions, and a final assertion (codegen often omits one - the agent adds it).

Cypress mode

Step C1 - Identify the raw recording shape

Studio-generated output (docs.cypress.io/guides/references/cypress-studio (opens in new window)) typically looks like:

describe('checkout', () => {
  it('completes checkout', () => {
    cy.visit('http://localhost:3000/login');
    cy.get('#email').type('user@example.com');
    cy.get('#password').type('test-password');
    cy.get('.signin-btn').click();
    cy.wait(2000);
    cy.get('.product-card:nth-child(1)').click();
    cy.get('button.add-to-cart').click();
    cy.get('#cart-badge').should('have.text', '1');
  });
});

Flags to surface: unnamed test intent, brittle selectors, fixed wait, inline login flow that belongs in a custom command.

Step C2 - Selector audit

Per cy-bp (opens in new window): "Don't target elements based on CSS attributes such as id, class, tag." Preferred order is data-cy > data-test > data-testid, then cy.findByRole (via @testing-library/cypress) when the attribute is absent. See cypress-testing Step 4.

Step C3 - Wait audit

Per cy-retry (opens in new window): "Commands like cy.get() automatically retry until assertions pass. Actions like .click() execute only once." cy.wait(ms) is explicitly an anti-pattern (cy-bp (opens in new window): "Waiting for arbitrary time periods using cy.wait(Number) is discouraged."). Replace fixed waits with one of:

• cy.intercept(...).as('alias') + cy.wait('@alias') - for network timing.
• Chain the next .should(...) assertion directly - Cypress retries queries until the assertion passes within defaultCommandTimeout (4 s by default, per cy-retry (opens in new window)).

Step C4 - Custom command extraction and app actions

Per cy-cmd (opens in new window): "Don't make everything a custom command" - extract only when a multi-step flow repeats across two or more specs. The login sequence is the canonical candidate:

// cypress/support/commands.ts
Cypress.Commands.add('login', (email: string, password: string) => {
  cy.session([email, password], () => {
    cy.visit('/login');
    cy.findByLabelText('Email').type(email);
    cy.findByLabelText('Password').type(password);
    cy.findByRole('button', { name: /sign in/i }).click();
    cy.url().should('not.include', '/login');
  });
});

cy.session caches auth state across tests, per cypress-testing Step 5.

App-action check, per cy-bp (opens in new window): "Test specs in isolation, programmatically log into your application, and take control of your application's state." UI-driven login in beforeEach is an anti-pattern - prefer cy.request() or cy.session() to set state directly.

Output format

## Codegen refactor - `<file>` (<Playwright|Cypress>)

**Source:** `<path>` (raw recording)

### Selector findings

| Line | Raw | Refactored | Reason |
|---|---|---|---|

### Wait findings (Cypress) / assertion gaps (Playwright)

| Line | Anti-pattern | Fix |
|---|---|---|

### Extraction candidates

- Page Objects extracted (Playwright) or custom commands proposed (Cypress)

### Refactored spec (recommended)

​```typescript
<refactored spec here>
​```

### Summary

- Selectors: N brittle selectors rewritten
- Waits: N fixed waits replaced
- Extractions: N Page Objects / custom commands
- Test name + AAA structure: applied

Refuse-to-proceed rules

• Never auto-merge. The refactor lands in a PR for human review.
• Never leave the test name as 'test' (or a mechanical Studio name) - always name per the test's intent.
• Never skip the final assertion when the recording omitted one.
• Playwright: never skip Page Object extraction when the recorded flow is >5 steps (the recording would be unmaintainable as-is).
• Cypress: never invent data-cy attribute values the reviewer cannot verify in the source DOM. Flag [VERIFY ATTRIBUTE] instead.
• Cypress: never leave cy.wait(ms) unflagged regardless of how small the value is.
• Hard-reject: if invoked on a spec with no selectors, no waits, and no repeated flows, emit NO_REVIEW_NEEDED and stop.

Anti-patterns

Limitations

• Heuristic selector replacement. Some CSS selectors map unambiguously to roles; some don't. Manual review needed for ambiguous cases.
• Abstraction boundaries vary. Different teams draw Page Object / custom-command lines differently.
• Recording quality varies per app. Apps with a good accessibility tree produce clean role-based selectors; others produce verbose CSS.

References

• Playwright codegen at playwright.dev/docs/codegen.
• cy-bp (opens in new window) - Cypress best practices: selector strategy, avoiding fixed waits, programmatic login, test isolation.
• cy-retry (opens in new window) - Cypress retry-ability: which commands retry, which do not, defaultCommandTimeout.
• cy-cmd (opens in new window) - Cypress custom commands: Commands.add, TypeScript declarations, "don't make everything a custom command."
• cy-studio (opens in new window) - Cypress Studio: recording mechanism, selector priority order (data-cy > data-test > data-testid > class > tag).
• playwright-testing - upstream Playwright framework conventions.
• cypress-testing - preloaded; full Cypress install, config, custom commands, CI integration.
• test-code-conventions - preloaded; AAA structure, naming patterns, assertion specificity.
• e2e-selector-quality-critic - downstream gate for selector convention enforcement.