senior-qa

资深 QA 工程师

面向 React 和 Next.js 应用的测试自动化、覆盖率分析与质量保障模式。

---

快速开始

# Generate Jest test stubs for React components
python scripts/test_suite_generator.py src/components/ --output __tests__/

# Analyze test coverage from Jest/Istanbul reports
python scripts/coverage_analyzer.py coverage/coverage-final.json --threshold 80

# Scaffold Playwright E2E tests for Next.js routes
python scripts/e2e_test_scaffolder.py src/app/ --output e2e/

---

工具概览

1. 测试套件生成器

扫描 React/TypeScript 组件，并生成结构规范的 Jest + React Testing Library 测试桩。

输入： 包含 React 组件的源码目录 输出： 包含 describe 块、渲染测试、交互测试的测试文件

用法：

# Basic usage - scan components and generate tests
python scripts/test_suite_generator.py src/components/ --output __tests__/

# Include accessibility tests
python scripts/test_suite_generator.py src/ --output __tests__/ --include-a11y

# Generate with custom template
python scripts/test_suite_generator.py src/ --template custom-template.tsx

支持的模式：

• 使用 Hooks 的函数组件
• 使用 Context Provider 的组件
• 包含数据获取的组件
• 包含校验的表单组件

---

2. 覆盖率分析器

解析 Jest/Istanbul 覆盖率报告，识别覆盖缺口和未覆盖分支，并给出可执行的建议。

输入： 覆盖率报告（JSON 或 LCOV 格式） 输出： 包含建议的覆盖率分析结果

用法：

# Analyze coverage report
python scripts/coverage_analyzer.py coverage/coverage-final.json

# Enforce threshold (exit 1 if below)
python scripts/coverage_analyzer.py coverage/ --threshold 80 --strict

# Generate HTML report
python scripts/coverage_analyzer.py coverage/ --format html --output report.html

---

3. E2E 测试脚手架

扫描 Next.js pages/app 目录，并生成包含常见交互的 Playwright 测试文件。

输入： Next.js pages 或 app 目录 输出： 按路由组织的 Playwright 测试文件

用法：

# Scaffold E2E tests for Next.js App Router
python scripts/e2e_test_scaffolder.py src/app/ --output e2e/

# Include Page Object Model classes
python scripts/e2e_test_scaffolder.py src/app/ --output e2e/ --include-pom

# Generate for specific routes
python scripts/e2e_test_scaffolder.py src/app/ --routes "/login,/dashboard,/checkout"

---

QA 工作流

单元测试生成工作流

在为新建或已有的 React 组件设置测试时使用。

第 1 步：扫描项目中未测试的组件

python scripts/test_suite_generator.py src/components/ --scan-only

第 2 步：生成测试桩

python scripts/test_suite_generator.py src/components/ --output __tests__/

第 3 步：审查并定制生成的测试

// __tests__/Button.test.tsx (generated)
import { render, screen, fireEvent } from '@testing-library/react';
import { Button } from '../src/components/Button';

describe('Button', () => {
  it('renders with label', () => {
    render(<Button>Click me</Button>);
    expect(screen.getByRole('button', { name: /click me/i })).toBeInTheDocument();
  });

  it('calls onClick when clicked', () => {
    const handleClick = jest.fn();
    render(<Button onClick={handleClick}>Click</Button>);
    fireEvent.click(screen.getByRole('button'));
    expect(handleClick).toHaveBeenCalledTimes(1);
  });

  // TODO: Add your specific test cases
});

第 4 步：运行测试并检查覆盖率

npm test -- --coverage
python scripts/coverage_analyzer.py coverage/coverage-final.json

---

覆盖率分析工作流

在提升测试覆盖率或准备发布时使用。

第 1 步：生成覆盖率报告

npm test -- --coverage --coverageReporters=json

第 2 步：分析覆盖率缺口

python scripts/coverage_analyzer.py coverage/coverage-final.json --threshold 80

第 3 步：识别关键路径

python scripts/coverage_analyzer.py coverage/ --critical-paths

第 4 步：生成缺失的测试桩

python scripts/test_suite_generator.py src/ --uncovered-only --output __tests__/

第 5 步：验证改进效果

npm test -- --coverage
python scripts/coverage_analyzer.py coverage/ --compare previous-coverage.json

---

E2E 测试搭建工作流

在为 Next.js 项目配置 Playwright 时使用。

第 1 步：初始化 Playwright（如未安装）

npm init playwright@latest

第 2 步：根据路由生成 E2E 测试脚手架

python scripts/e2e_test_scaffolder.py src/app/ --output e2e/

第 3 步：配置认证 fixtures

// e2e/fixtures/auth.ts (generated)
import { test as base } from '@playwright/test';

export const test = base.extend({
  authenticatedPage: async ({ page }, use) => {
    await page.goto('/login');
    await page.fill('[name="email"]', '[email protected]');
    await page.fill('[name="password"]', 'password');
    await page.click('button[type="submit"]');
    await page.waitForURL('/dashboard');
    await use(page);
  },
});

第 4 步：运行 E2E 测试

npx playwright test
npx playwright show-report

第 5 步：加入 CI 流水线

# .github/workflows/e2e.yml
- name: "run-e2e-tests"
  run: npx playwright test
- name: "upload-report"
  uses: actions/upload-artifact@v4
  with:
    name: "playwright-report"
    path: playwright-report/

---

参考文档

文件	内容	使用场景
references/testing_strategies.md	测试金字塔、测试类型、覆盖率目标、CI/CD 集成	设计测试策略
references/test_automation_patterns.md	Page Object Model、Mock（MSW）、fixtures、异步模式	编写测试代码
references/qa_best_practices.md	可测试代码、不稳定测试、调试、质量指标	提升测试质量

---

常用模式速查

React Testing Library 查询

// Preferred (accessible)
screen.getByRole('button', { name: /submit/i })
screen.getByLabelText(/email/i)
screen.getByPlaceholderText(/search/i)

// Fallback
screen.getByTestId('custom-element')

异步测试

// Wait for element
await screen.findByText(/loaded/i);

// Wait for removal
await waitForElementToBeRemoved(() => screen.queryByText(/loading/i));

// Wait for condition
await waitFor(() => {
  expect(mockFn).toHaveBeenCalled();
});

使用 MSW 进行 Mock

import { rest } from 'msw';
import { setupServer } from 'msw/node';

const server = setupServer(
  rest.get('/api/users', (req, res, ctx) => {
    return res(ctx.json([{ id: 1, name: "john" }]));
  })
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

Playwright 定位器

// Preferred
page.getByRole('button', { name: "submit" })
page.getByLabel('Email')
page.getByText('Welcome')

// Chaining
page.getByRole('listitem').filter({ hasText: 'Product' })

覆盖率阈值（jest.config.js）

module.exports = {
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80,
    },
  },
};

---

常用命令

# Jest
npm test                           # Run all tests
npm test -- --watch                # Watch mode
npm test -- --coverage             # With coverage
npm test -- Button.test.tsx        # Single file

# Playwright
npx playwright test                # Run all E2E tests
npx playwright test --ui           # UI mode
npx playwright test --debug        # Debug mode
npx playwright codegen             # Generate tests

# Coverage
npm test -- --coverage --coverageReporters=lcov,json
python scripts/coverage_analyzer.py coverage/coverage-final.json