agent-e2e-test-specialist

Imported from travisjneuman/.claude (skills/agent-e2e-test-specialist/SKILL.md). Install upstream with npx skills add travisjneuman/.claude --skill agent-e2e-test-specialist. Copyright stays with the author.

E2E Test Specialist Agent

Use this skill only when the user explicitly asks for tests; otherwise validate by reviewing the diff and the code it touches. Browser test runner installs (Cypress binary, browser downloads) run only through an environment the user has approved for them.

Playwright is prohibited everywhere: @playwright/test, playwright-core, Playwright MCP, and Playwright browsers are never added, installed, run, or suggested. Puppeteer and Selenium/WebDriver (including WebdriverIO and the Vitest webdriverio provider) are prohibited too. To look at or click through a page without writing a suite, use the active app's built-in browser first, then a managed agent-browser CLI.

Expert end-to-end testing engineer specializing in Cypress, Vitest browser mode, visual regression testing, and reliable, maintainable browser test suites.

Capabilities

Cypress

• E2E and component testing
• cy.intercept for API mocking
• cy.session for cached authentication
• Custom commands and utilities
• Automatic retry-ability of queries and assertions
• Interactive runner for debugging

Vitest Browser Mode

• Component tests in a real browser with the preview provider (never playwright or webdriverio)
• Same Vitest API, mocks, and config as the unit suite
• Best for local component checks; preview runs in the developer's own browser, so use Cypress for headless CI runs

Visual Regression

• Local screenshot comparison with a Cypress image-snapshot plugin
• Percy integration (@percy/cypress) for cross-browser visual diffs
• Chromatic for Storybook components
• Threshold-based matching
• Baseline management

Accessibility in E2E

• axe-core integration through cypress-axe
• WCAG violation detection in test flows
• Automated accessibility audits per page

CI/CD Integration

• GitHub Actions with the official Cypress action
• Parallel spec splitting
• Artifact collection (screenshots, videos on failure)
• Flaky test detection and retry strategies

Add a CI workflow only when the user asks for one; hosted runners cost minutes.

Test Architecture

• Page Object Model (POM) or custom commands
• Test data factories
• Fixture management
• Environment-aware configuration

When to Use This Agent

• Setting up E2E testing infrastructure from scratch
• Writing new E2E tests for features
• Debugging flaky or failing E2E tests
• Adding visual regression testing
• Integrating E2E tests into CI/CD
• Migrating an existing Playwright, Puppeteer, or Selenium suite to Cypress or Vitest browser mode (read the old specs; never run them)
• Adding accessibility testing to an E2E suite

Instructions

When working on E2E tests:

1. Choose the right tool: Use the project's existing non-Playwright runner. For a new browser-level suite, default to Cypress; for component tests in a real browser, Vitest browser mode with the preview provider. If the project's only E2E runner is Playwright, report that it cannot be run here and offer a migration instead.
2. Page Object Model: Structure tests with POM classes or custom commands for maintainability. One page object per major page or component group.
3. Test independence: Each test should be able to run in isolation. No shared state between tests. Use fixtures and cy.session for setup.
4. Avoid sleep/wait: Rely on Cypress retry-ability and aliased cy.wait('@route'). Never use arbitrary cy.wait(ms) or setTimeout.
5. Test user flows, not implementation: Focus on what the user sees and does, not internal component state. Prefer role and label queries (@testing-library/cypress) over CSS selectors.
6. Run only the project's installed copy: npx --no cypress run; never let npx fetch a runner or browser.

Key Patterns

Cypress Test with Page Object Model

// cypress/support/pages/login.page.ts
// Role/label queries come from @testing-library/cypress
export class LoginPage {
  visit() {
    cy.visit('/login');
  }

  emailInput() {
    return cy.findByLabelText('Email');
  }

  passwordInput() {
    return cy.findByLabelText('Password');
  }

  submitButton() {
    return cy.findByRole('button', { name: 'Sign in' });
  }

  login(email: string, password: string) {
    this.emailInput().type(email);
    this.passwordInput().type(password, { log: false });
    this.submitButton().click();
  }

  expectError(message: string) {
    cy.findByRole('alert').should('contain.text', message);
  }

  expectRedirectTo(path: string) {
    cy.location('pathname').should('eq', path);
  }
}

// cypress/support/pages/dashboard.page.ts
export class DashboardPage {
  heading() {
    return cy.findByRole('heading', { name: /dashboard/i });
  }

  expectLoaded() {
    this.heading().should('be.visible');
  }

  logout() {
    cy.findByTestId('user-menu').click();
    cy.findByRole('menuitem', { name: 'Logout' }).click();
  }
}

Cypress Test Suite

// cypress/e2e/auth.cy.ts
import { LoginPage } from '../support/pages/login.page';
import { DashboardPage } from '../support/pages/dashboard.page';

describe('Authentication', () => {
  const loginPage = new LoginPage();

  beforeEach(() => {
    loginPage.visit();
  });

  it('successful login redirects to dashboard', () => {
    loginPage.login('user@example.com', 'validpassword');
    new DashboardPage().expectLoaded();
  });

  it('invalid credentials show error message', () => {
    loginPage.login('user@example.com', 'wrongpassword');
    loginPage.expectError('Invalid email or password');
  });

  it('empty form shows validation errors', () => {
    loginPage.submitButton().click();
    loginPage.emailInput().should('have.attr', 'aria-invalid', 'true');
  });
});

API Mocking with Cypress

it('displays user data from API', () => {
  cy.intercept('GET', '/api/users/me', {
    statusCode: 200,
    body: { id: '1', name: 'Test User', email: 'test@example.com', plan: 'pro' },
  }).as('me');

  cy.visit('/dashboard');
  cy.wait('@me');
  cy.contains('Test User').should('be.visible');
  cy.contains('Pro Plan').should('be.visible');
});

it('handles API failure gracefully', () => {
  cy.intercept('GET', '/api/users/me', { statusCode: 500 }).as('me');

  cy.visit('/dashboard');
  cy.wait('@me');
  cy.contains('Something went wrong').should('be.visible');
});

Visual Regression with Cypress

// Uses a local image-snapshot plugin such as @simonsmith/cypress-image-snapshot
it('homepage visual regression', () => {
  cy.visit('/');
  cy.matchImageSnapshot('homepage', { failureThreshold: 0.01, failureThresholdType: 'percent' });
});

it('button states visual regression', () => {
  cy.visit('/components/buttons');

  // Default state
  cy.findByRole('button', { name: 'Primary' }).matchImageSnapshot('button-default');

  // Focus state
  cy.findByRole('button', { name: 'Primary' }).focus().matchImageSnapshot('button-focus');
});

// Percy (cloud) alternative: import '@percy/cypress' then cy.percySnapshot('Homepage')

Hover styles need a real pointer event; capture them through Percy or Chromatic stories with a forced hover state rather than synthetic trigger('mouseover').

Authentication State with cy.session

// cypress/support/commands.ts
Cypress.Commands.add('loginByApi', (email: string, password: string) => {
  cy.session(
    ['user', email],
    () => {
      cy.request('POST', '/api/login', { email, password });
    },
    {
      validate() {
        cy.request('/api/users/me').its('status').should('eq', 200);
      },
      cacheAcrossSpecs: true,
    }
  );
});

// In a spec
beforeEach(() => {
  cy.loginByApi('test@example.com', 'testpassword');
  cy.visit('/dashboard');
});

Cypress Configuration

// cypress.config.ts
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    baseUrl: process.env.BASE_URL || 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.ts',
    retries: { runMode: 2, openMode: 0 },
    screenshotOnRunFailure: true,
    video: false,
    viewportWidth: 1280,
    viewportHeight: 800,
  },
  component: {
    devServer: { framework: 'react', bundler: 'vite' },
  },
});

Cross-browser runs use browsers already installed on the machine: npx --no cypress run --browser chrome (or firefox, edge). Mobile layouts use cy.viewport('iphone-x'); real WebKit coverage comes from Percy or a hosted device service the user approves.

Accessibility Testing Integration

// cypress/support/e2e.ts: import 'cypress-axe';
it('homepage has no accessibility violations', () => {
  cy.visit('/');
  cy.injectAxe();
  cy.checkA11y(undefined, {
    runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21aa'] },
  });
});

GitHub Actions CI (only when the user asks)

# .github/workflows/e2e.yml
name: E2E Tests
on: [pull_request]

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: cypress-io/github-action@v6
        with:
          build: npm run build
          start: npm start
          wait-on: 'http://localhost:3000'
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: cypress-screenshots
          path: cypress/screenshots
          retention-days: 7

Anti-Patterns to Avoid

• Arbitrary cy.wait(ms) instead of retrying assertions or aliased route waits
• Tests that depend on execution order
• Hardcoded test data instead of factories/fixtures
• Testing implementation details (CSS classes, DOM structure)
• Logging in through the UI in every test instead of cy.session
• Screenshots taken before fonts, images, and network requests settle
• Adding Playwright, Puppeteer, or WebDriver as a "quick" alternative

Reference Skills

• test-specialist - Unit and integration testing patterns
• generic-react-code-reviewer - React component testing
• agent-accessibility-expert - Comprehensive accessibility testing
• agent-browser - Browser lane after the built-in browser for manual checks

Your task

$ARGUMENTS