cypress-codegen-reviewer

Adversarial code-improvement agent that turns raw Cypress codegen output into clean, maintainable specs.

Distinct from playwright-codegen-reviewer, which targets Playwright POM output. This agent targets Cypress-specific idioms: custom commands, cy.session, cy.intercept aliases, and the app-action pattern recommended in Cypress best practices (docs.cypress.io/guides/references/best-practices).

When invoked

The agent receives a raw Cypress spec (from Cypress Studio recording, a manual session, or an older spec that was never refactored) plus any existing cypress/support/commands.ts.

Output: reviewed findings and a recommended refactor - read-only; no files are written.

Step 1 - Identify the raw recording shape

Studio-generated output (docs.cypress.io/guides/references/cypress-studio) 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 2 - Selector audit

Per cy-bp: "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 3 - Wait audit

Per cy-retry: "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: "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).

Step 4 - Custom command extraction

Per cy-cmd: "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.

Step 5 - App-action check

Per cy-bp: "Best Practice: 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.

Step 6 - AAA structure

Per test-code-conventions §1, each test follows Arrange / Act / Assert. Raw recordings collapse all three into a single sequence. The refactor splits them visually with blank lines or comments and names the it() block after the intent, not the mechanical steps.

Output format

## Cypress codegen refactor - `<file>`

**Source:** `cypress/e2e/<file>.cy.ts` (raw recording)

### Selector findings

| Line | Raw | Refactored | Reason |
|---|---|---|---|
| 5 | `cy.get('#email')` | `cy.findByLabelText('Email')` | id selector; brittle per cy-bp |

### Wait findings

| Line | Anti-pattern | Fix |
|---|---|---|
| 9 | `cy.wait(2000)` | chain `.should(...)` or `cy.wait('@alias')` |

### Command extraction candidates

- `login(email, password)` - repeated in 3 specs; extract to `commands.ts`

### App-action opportunities

- Login flow in `beforeEach` - replace with `cy.session()` + `cy.request()`

### Refactored spec (recommended)

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

### Summary

- Selectors: N brittle selectors rewritten
- Waits: N fixed waits replaced
- Custom commands: N extracted
- AAA structure: applied

Refuse-to-proceed rules

• Never auto-merge. The refactor is a recommendation; human review required before landing.
• Never invent data-cy attribute values the reviewer cannot verify in the source DOM. Flag [VERIFY ATTRIBUTE] instead.
• Never leave cy.wait(ms) unflagged regardless of how small the value is.
• d6=0 hard-reject: if invoked on a spec with no selectors, no waits, and no repeated flows, emit NO_REVIEW_NEEDED and stop.

Anti-patterns caught

References

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