Test Commander

--- name: test-commander description: Generate unit, integration, E2E, and visual regression tests following the Testing Trophy methodology (80% integration). Covers Vitest/Jest, Testing Library, Playwright, MSW for API mocking, snapshot strategy, visual regression (Chromatic/Percy/Playwright), test factories with Faker, and CI sharding. Use when user asks to write tests, set up testing framework, mock API/dependencies, improve coverage, or add visual regression. Do NOT use for performance/load testing, production monitoring, or type testing (covered by TypeScript). triggers: - "write tests" - "unit test" - "integration test" - "E2E test" - "test coverage" - "Vitest" - "Jest" - "Playwright test" - "Testing Library" - "MSW" - "mock API" - "visual regression" - "test setup" negatives: - "performance testing" - "load testing" - "production monitoring" - "type testing" - "TypeScript" license: MIT compatibility: opencode metadata: workflow: quality audience: developers version: "4.0.0" author: shokunin allowed-tools: Read Bash Write Grep Glob

Test Commander

Tests that catch real bugs. Following the Testing Trophy (Kent C. Dodds): 80% integration, 10% unit, 10% E2E. Based on patterns from Testing Library, Playwright, MSW, and Chromatic.

Testing Trophy (visual)

        /\
       /E2E\        ← 2-3 critical flows
      /------\
     / Visual \     ← Visual regression on key components
    /----------\
   /Integration\    ← 80% of tests. Components + API + store.
  /--------------\
 /     Unit       \ ← Pure logic. Utils, helpers, formatters.
/------------------\
     Static         ← TypeScript + ESLint

Workflow

Step 1: Determine test level

Default: Integration. Catches 80% of bugs with 20% of maintenance cost.

Step 2: Write integration tests (5 mandatory states)

Every data-fetching component must test ALL five states:

describe('UserProfile', () => {
  it('shows loading skeleton initially', async () => {
    render(<UserProfile userId="123" />)
    expect(screen.getByRole('status')).toHaveTextContent('Loading...')
  })

  it('shows error state with retry button', async () => {
    server.use(http.get('/api/users/123', () => new HttpResponse(null, { status: 500 })))
    render(<UserProfile userId="123" />)
    await waitFor(() => {
      expect(screen.getByRole('alert')).toHaveTextContent('Failed to load')
    })
    expect(screen.getByRole('button', { name: /retry/i })).toBeInTheDocument()
  })

  it('shows empty state when no data', async () => {
    server.use(http.get('/api/users/123', () => HttpResponse.json(null)))
    render(<UserProfile userId="123" />)
    await waitFor(() => {
      expect(screen.getByText(/no user found/i)).toBeInTheDocument()
    })
  })

  it('renders user data on success', async () => {
    render(<UserProfile userId="123" />)
    await screen.findByText('Alice')
    expect(screen.getByText('alice@example.com')).toBeInTheDocument()
  })

  it('handles race condition: fast re-fetch', async () => {
    const { rerender } = render(<UserProfile userId="123" />)
    await screen.findByText('Alice')
    rerender(<UserProfile userId="456" />)
    await screen.findByText('Bob')
    expect(screen.queryByText('Alice')).not.toBeInTheDocument()
  })
})

Step 3: MSW setup (exact pattern)

import { http, HttpResponse } from 'msw'
import { setupServer } from 'msw/node'

const server = setupServer(
  http.get('/api/users', () => {
    return HttpResponse.json([
      { id: '1', name: 'Alice', email: 'alice@example.com' },
      { id: '2', name: 'Bob', email: 'bob@example.com' },
    ])
  }),

  http.post('/api/users', async ({ request }) => {
    const body = await request.json()
    return HttpResponse.json({ id: '3', ...body }, { status: 201 })
  })
)

beforeAll(() => server.listen({ onUnhandledRequest: 'warn' }))
afterEach(() => server.resetHandlers())
afterAll(() => server.close())

Step 4: Test factories (Faker)

import { faker } from '@faker-js/faker'

function createUser(overrides: Partial<User> = {}): User {
  return {
    id: faker.string.uuid(),
    name: faker.person.fullName(),
    email: faker.internet.email(),
    createdAt: faker.date.recent().toISOString(),
    ...overrides,
  }
}

const admin = createUser({ name: 'Admin User' })
const emptyUser = createUser({ email: '' })  // Edge case factory

Step 5: E2E tests (Playwright)

test('checkout flow', async ({ page }) => {
  await page.goto('/products')
  await page.getByTestId('add-to-cart').click()
  await page.getByTestId('cart-count').toHaveText('1')
  await page.getByTestId('checkout').click()
  await page.getByLabel('Email').fill('test@example.com')
  await page.getByRole('button', { name: 'Pay $29.99' }).click()
  await expect(page.getByTestId('order-confirmed')).toBeVisible()
  await expect(page.getByTestId('order-id')).not.toBeEmpty()
})

Always record traces on failure:

npx playwright test --trace on

Step 6: Visual regression

test('homepage visual', async ({ page }) => {
  await page.goto('/')
  await expect(page).toHaveScreenshot('homepage.png', {
    fullPage: true,
    maxDiffPixelRatio: 0.01,
  })
})

Step 7: CI sharding

test:
  strategy:
    matrix:
      shard: [1/4, 2/4, 3/4, 4/4]
  run: npx vitest --shard=${{ matrix.shard }}

Flaky Test Protocol

If a test flakes more than once: fix it same day or skip it with test.skip() + a comment explaining why. Never let flaky tests accumulate.

Anti-Patterns

Production Checklist

• Every data-fetching component: loading + empty + error + success tests
• MSW: onUnhandledRequest: 'warn' + reset between tests
• Factory functions with Faker for all fixtures
• E2E: 3-5 critical flows (checkout, signup, key feature)
• Visual regression: key pages + components
• CI: 4 shards minimum for integration tests
• E2E: only on merge to main. Blocking merge on failure.
• Flaky tests: zero tolerance. Fix or skip within 24 hours.
• Accessibility: axe-core in E2E for key pages
• Coverage: not a metric. Focus on behavior coverage, not line coverage.

Test Data Factories

import { faker } from '@faker-js/faker'

function createUser(overrides: Partial<User> = {}): User {
  return {
    id: faker.string.uuid(),
    name: faker.person.fullName(),
    email: faker.internet.email(),
    role: faker.helpers.arrayElement(['admin', 'editor', 'viewer']),
    createdAt: faker.date.recent({ days: 30 }).toISOString(),
    ...overrides
  }
}

// Edge cases
const adminUser = createUser({ role: 'admin' })
const emptyEmail = createUser({ email: '' })
const longName = createUser({ name: 'a'.repeat(256) })
const futureDate = createUser({ createdAt: faker.date.future().toISOString() })

Visual Regression Testing

// Playwright
test('homepage visual check', async ({ page }) => {
  await page.goto('/')
  await expect(page).toHaveScreenshot('homepage.png', {
    fullPage: true,
    maxDiffPixelRatio: 0.01,
  })
})

// CI update: npx playwright test --update-snapshots

Flaky Test Protocol

Rule: one flake = fix today. Two flakes = skip with test.skip() + comment. Never let flaky tests accumulate.

Sources

• Kent C. Dodds — Testing Trophy (kentcdodds.com)
• Testing Library — Guiding Principles
• Playwright — Best Practices
• MSW (mswjs.io) — API mocking
• Chromatic — Visual testing
• Martin Fowler — TestCoverage
• Google Testing Blog — Flaky test elimination

Error Handling

Checklist

• Skill loads without errors in the AI agent
• YAML frontmatter is valid (description, compatibility, audience)
• Workflow section provides clear step-by-step instructions
• Error handling section covers common failure modes
• All referenced files (references/, scripts/, assets/) exist
• Skill triggers correctly for intended use cases
• No broken links or missing resources