Harness Engineering 全解析与应用

一、什么是 Harness Engineering

Harness Engineering 可以理解为“工程化测试与执行夹具体系”。这里的 Harness 不是单一工具，而是一套围绕代码、服务、模型、系统或业务流程搭建的可控运行环境。它负责准备输入、隔离依赖、驱动执行、采集结果、判断成功失败，并把这些能力沉淀成可复用的工程基础设施。

在软件工程里，Harness 常见于测试框架、自动化验证、持续集成、端到端测试、性能测试、AI Agent 评测、硬件调试、服务编排等场景。它的核心价值是：让复杂系统可以被稳定、重复、可观测地运行和验证。

flowchart TD
    A[被测对象] --> B[Harness 准备环境]
    B --> C[注入输入数据]
    C --> D[驱动执行]
    D --> E[采集输出结果]
    E --> F[执行断言和评估]
    F --> G[生成报告]

简单说，如果测试用例是“我要验证什么”，Harness 就是“我如何稳定地把它跑起来、观察它、判断它”。

二、为什么需要 Harness Engineering

真实系统通常不是一个纯函数。它会依赖数据库、缓存、消息队列、网络、浏览器、第三方服务、文件系统、环境变量、权限、时间、随机数、用户会话等外部因素。如果没有 Harness，测试和验证就会变得脆弱、难复现、难定位。

Harness Engineering 解决的问题包括：

• 环境如何准备。
• 依赖如何隔离或模拟。
• 输入数据如何生成。
• 执行过程如何驱动。
• 输出如何采集。
• 成功标准如何判断。
• 失败现场如何保存。
• 多次运行如何保持一致。
• 本地、CI、预发、线上巡检如何统一。

flowchart TD
    A[复杂系统验证] --> B[环境不稳定]
    A --> C[依赖难控制]
    A --> D[数据难复现]
    A --> E[失败难定位]
    B --> F[Harness 统一环境]
    C --> G[Harness 管理依赖]
    D --> H[Harness 管理数据]
    E --> I[Harness 采集证据]

没有 Harness 的测试经常是“在我电脑上能跑”；有 Harness 的测试追求的是“在任何约定环境下都能以相同方式运行”。

三、Harness 的基本组成

一个完整 Harness 通常由执行器、环境管理器、依赖管理器、数据管理器、驱动器、观察器、断言器、报告器组成。

flowchart TD
    A[Harness] --> B[执行器 Runner]
    A --> C[环境管理器 Environment]
    A --> D[依赖管理器 Dependency]
    A --> E[数据管理器 Data]
    A --> F[驱动器 Driver]
    A --> G[观察器 Observer]
    A --> H[断言器 Assertion]
    A --> I[报告器 Reporter]

各模块职责如下：

模块	作用	示例
Runner	调度用例执行	Jest runner、Playwright runner、CI job
Environment	准备运行环境	Docker、测试数据库、浏览器上下文
Dependency	管理外部依赖	Mock API、Fake 服务、真实测试环境
Data	准备和清理数据	fixture、factory、seed、cleanup
Driver	驱动系统行为	HTTP client、浏览器、CLI、SDK
Observer	采集运行证据	日志、Trace、截图、指标、事件
Assertion	判断结果是否正确	expect、schema check、snapshot
Reporter	输出结果	HTML report、JUnit XML、Allure、CI artifact

四、Harness 和测试框架的关系

测试框架通常提供断言、用例组织和执行能力，但 Harness 更关注“如何把系统稳定运行起来”。很多测试框架内部都包含 Harness 思想。

例如：

• Jest 提供单元测试 Harness。
• Playwright 提供浏览器 E2E Harness。
• Cypress 提供交互式前端测试 Harness。
• Spring Test 提供后端集成测试 Harness。
• Testcontainers 提供依赖服务 Harness。
• Locust、k6、JMeter 提供性能测试 Harness。
• AI Agent 评测平台提供模型任务执行 Harness。

flowchart TD
    A[测试目标] --> B[测试框架]
    B --> C[组织用例]
    B --> D[执行断言]
    A --> E[Harness]
    E --> F[准备环境]
    E --> G[驱动被测系统]
    E --> H[采集证据]
    E --> I[输出报告]

可以理解为：测试框架是 Harness 的一部分，Harness 是更完整的工程化执行体系。

五、Harness Engineering 的核心原则

1. 可重复

同一用例在相同输入和相同环境下应该得到相同结果。

2. 可隔离

一个用例不应该依赖另一个用例执行后的副作用。

3. 可观测

失败时应该能看到日志、截图、网络请求、输入输出、环境信息。

4. 可控制

时间、随机数、网络、权限、数据状态应尽量可控。

5. 可扩展

新增用例、环境、服务或报告方式时，不应该大面积复制粘贴。

6. 可维护

Harness 本身不能比被测系统还难懂。抽象要克制，接口要清晰。

flowchart TD
    A[优秀 Harness] --> B[可重复]
    A --> C[可隔离]
    A --> D[可观测]
    A --> E[可控制]
    A --> F[可扩展]
    A --> G[可维护]

六、Harness 的分层模型

Harness 可以按验证层级分为单元 Harness、组件 Harness、集成 Harness、端到端 Harness、系统 Harness、生产巡检 Harness。

flowchart TD
    A[Harness 分层] --> B[单元 Harness]
    A --> C[组件 Harness]
    A --> D[集成 Harness]
    A --> E[端到端 Harness]
    A --> F[系统 Harness]
    A --> G[生产巡检 Harness]

层级	关注点	特点
单元 Harness	函数和模块	快、隔离、依赖少
组件 Harness	UI 组件或业务组件	可验证局部交互
集成 Harness	多模块协作	关注接口和依赖关系
E2E Harness	用户完整路径	更接近真实用户
系统 Harness	多服务和基础设施	覆盖部署拓扑和运行环境
生产巡检 Harness	线上可用性	低侵入、只读或受控写入

不同层级 Harness 的成本和收益不同。越靠近真实环境，信心越强，成本越高，稳定性治理越重要。

七、单元测试 Harness

单元测试 Harness 的目标是让函数或模块在隔离环境中快速验证。

典型能力：

• 创建输入参数。
• Mock 外部依赖。
• 控制时间和随机数。
• 捕获函数输出。
• 验证异常和边界条件。

Jest 示例：

import { calculateDiscount } from './calculateDiscount';

describe('calculateDiscount', () => {
  it('满 100 减 10', () => {
    const result = calculateDiscount({ amount: 100, coupon: 'MINUS_10' });
    expect(result.payAmount).toBe(90);
  });
});

带时间控制：

import { isExpired } from './time';

jest.useFakeTimers();

it('超过过期时间后返回 true', () => {
  jest.setSystemTime(new Date('2026-06-16T10:00:00Z'));
  expect(isExpired('2026-06-16T09:59:59Z')).toBe(true);
});

flowchart TD
    A[单元测试 Harness] --> B[准备输入]
    B --> C[Mock 依赖]
    C --> D[调用目标函数]
    D --> E[捕获返回值]
    E --> F[执行断言]

八、前端组件 Harness

前端组件 Harness 用来验证组件在不同 props、状态、事件、插槽、上下文下的表现。

它通常包含：

• 组件渲染器。
• 状态和上下文包装器。
• 用户事件模拟器。
• DOM 查询能力。
• 可访问性断言。
• 快照或视觉检查。

React Testing Library 示例：

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { LoginForm } from './LoginForm';

it('用户可以提交登录表单', async () => {
  const onSubmit = vi.fn();
  render(<LoginForm onSubmit={onSubmit} />);

  await userEvent.type(screen.getByLabelText('用户名'), 'demo');
  await userEvent.type(screen.getByLabelText('密码'), '123456');
  await userEvent.click(screen.getByRole('button', { name: '登录' }));

  expect(onSubmit).toHaveBeenCalledWith({
    username: 'demo',
    password: '123456'
  });
});

Vue Testing Library 示例：

import { render, screen } from '@testing-library/vue';
import userEvent from '@testing-library/user-event';
import LoginForm from './LoginForm.vue';

it('Vue 登录表单可以提交', async () => {
  const user = userEvent.setup();
  const { emitted } = render(LoginForm);

  await user.type(screen.getByLabelText('用户名'), 'demo');
  await user.type(screen.getByLabelText('密码'), '123456');
  await user.click(screen.getByRole('button', { name: '登录' }));

  expect(emitted().submit[0][0]).toEqual({
    username: 'demo',
    password: '123456'
  });
});

flowchart TD
    A[组件 Harness] --> B[渲染组件]
    B --> C[注入 props 和上下文]
    C --> D[模拟用户事件]
    D --> E[观察 DOM 变化]
    E --> F[断言可见结果]

九、集成测试 Harness

集成测试 Harness 关注多个模块之间是否能正确协作。它常常需要真实数据库、真实缓存、真实消息队列，或者可控的替代服务。

常见组合：

• 应用服务加测试数据库。
• API 层加真实业务逻辑。
• 消息生产者加消费者。
• 前端页面加 Mock API。
• 后端服务加 Testcontainers。

flowchart TD
    A[集成测试 Harness] --> B[启动应用]
    B --> C[启动依赖服务]
    C --> D[准备测试数据]
    D --> E[调用接口或事件]
    E --> F[检查数据库和返回值]
    F --> G[清理环境]

Node.js API 集成测试示例：

import request from 'supertest';
import { createApp } from '../src/app';
import { resetDatabase, seedUser } from './testDb';

beforeEach(async () => {
  await resetDatabase();
});

it('用户可以创建文章', async () => {
  const user = await seedUser();
  const app = createApp();

  const response = await request(app)
    .post('/api/articles')
    .set('Authorization', `Bearer ${user.token}`)
    .send({ title: 'Harness Engineering', content: 'content' });

  expect(response.status).toBe(201);
  expect(response.body.title).toBe('Harness Engineering');
});

集成 Harness 的重点不是 Mock 一切，而是选择哪些依赖必须真实，哪些依赖可以替代。

十、E2E Harness

端到端 Harness 站在用户视角驱动完整应用。它需要启动前端、准备后端、创建测试数据、打开浏览器、执行交互、保存失败现场。

Playwright 配置示例：

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  retries: process.env.CI ? 2 : 0,
  use: {
    baseURL: 'http://127.0.0.1:5173',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure'
  },
  webServer: {
    command: 'npm run dev -- --host 127.0.0.1',
    url: 'http://127.0.0.1:5173',
    reuseExistingServer: !process.env.CI
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'mobile', use: { ...devices['Pixel 5'] } }
  ]
});

E2E 用例示例：

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

test('用户可以搜索并进入详情页', async ({ page }) => {
  await page.goto('/');
  await page.getByPlaceholder('搜索关键词').fill('Harness');
  await page.getByRole('button', { name: '搜索' }).click();

  await expect(page.getByText('搜索结果')).toBeVisible();
  await page.getByRole('link', { name: /Harness/ }).first().click();
  await expect(page.getByRole('heading', { name: /Harness/ })).toBeVisible();
});

flowchart TD
    A[E2E Harness] --> B[启动前端服务]
    B --> C[准备后端和数据]
    C --> D[启动浏览器]
    D --> E[执行用户操作]
    E --> F[断言用户可见结果]
    F --> G[保存截图和 Trace]

十一、性能测试 Harness

性能测试 Harness 用来稳定地产生压力、采集指标、判断系统是否满足性能目标。

它需要控制：

• 并发用户数。
• 请求速率。
• 测试时长。
• 数据规模。
• 预热阶段。
• 指标采集。
• 失败阈值。

k6 示例：

import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  vus: 20,
  duration: '1m',
  thresholds: {
    http_req_duration: ['p(95)<500'],
    http_req_failed: ['rate<0.01']
  }
};

export default function () {
  const response = http.get('https://example.com/api/products');
  check(response, {
    'status is 200': r => r.status === 200
  });
  sleep(1);
}

flowchart TD
    A[性能 Harness] --> B[定义负载模型]
    B --> C[执行压测]
    C --> D[采集延迟和错误率]
    D --> E[采集资源指标]
    E --> F[判断是否超过阈值]
    F --> G[输出性能报告]

性能 Harness 的难点在于环境稳定和数据真实。性能结论必须说明环境、版本、数据规模和负载模型。

十二、契约测试 Harness

契约测试 Harness 用来验证服务之间的接口约定是否一致。它特别适合微服务和前后端分离场景。

flowchart TD
    A[消费者定义期望契约] --> B[生成契约文件]
    B --> C[提供者执行契约验证]
    C --> D[验证请求和响应格式]
    D --> E[发布契约结果]

适用场景：

• 前端依赖后端 API。
• 服务 A 调用服务 B。
• 多团队并行开发。
• 接口变更需要防止破坏消费者。

契约测试关注的是“接口形状是否兼容”，不是完整业务流程。它可以在 E2E 之前更早发现接口破坏。

十三、数据 Harness

很多测试不稳定，本质是数据不稳定。数据 Harness 负责生成、隔离、清理和复用测试数据。

常见策略：

• Fixture：固定测试数据。
• Factory：按需生成数据。
• Seed：初始化环境数据。
• Snapshot：数据库快照恢复。
• Transaction rollback：每个测试回滚事务。
• Namespace：用唯一前缀隔离并发数据。

flowchart TD
    A[测试开始] --> B[生成唯一标识]
    B --> C[创建测试数据]
    C --> D[执行测试]
    D --> E[断言结果]
    E --> F[清理测试数据]

Factory 示例：

type UserInput = Partial<{
  name: string;
  email: string;
  role: string;
}>;

export function createUserInput(input: UserInput = {}) {
  const id = Date.now();
  return {
    name: input.name ?? `user-${id}`,
    email: input.email ?? `user-${id}@example.com`,
    role: input.role ?? 'member'
  };
}

好的数据 Harness 应该让每个测试独立运行，不依赖执行顺序。

十四、Mock、Stub、Fake、Spy 在 Harness 中的角色

Harness 经常需要替代真实依赖。不同替代方式含义不同。

类型	含义	例子
Mock	预设行为并验证调用	验证 sendEmail 被调用
Stub	返回固定结果	固定返回用户信息
Fake	可工作的轻量实现	内存数据库替代真实数据库
Spy	记录调用但保留原行为	监听函数调用次数

flowchart TD
    A[依赖替代] --> B[Mock]
    A --> C[Stub]
    A --> D[Fake]
    A --> E[Spy]
    B --> F[验证交互]
    C --> G[控制返回值]
    D --> H[提供轻量实现]
    E --> I[观察调用]

选择原则：

• 业务规则尽量用真实代码。
• 外部不可控依赖可以替代。
• 不要 Mock 掉测试真正想验证的部分。
• Mock 越多，测试越偏实现细节。

十五、环境 Harness

环境 Harness 负责统一运行环境。它可以是本地脚本、Docker Compose、Kubernetes namespace、测试沙箱、云环境模板。

Docker Compose 示例：

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://test:test@db:5432/app
    depends_on:
      - db

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: test
      POSTGRES_PASSWORD: test
      POSTGRES_DB: app

flowchart TD
    A[环境 Harness] --> B[启动应用]
    A --> C[启动数据库]
    A --> D[启动缓存]
    A --> E[设置环境变量]
    A --> F[健康检查]
    F --> G[开始测试]

环境 Harness 需要提供健康检查，而不是启动命令执行完就认为服务可用。

十六、观测 Harness

Harness 不只是跑测试，还要在失败时提供足够证据。

需要采集：

• 标准输出和错误输出。
• 应用日志。
• 浏览器控制台日志。
• 网络请求和响应摘要。
• 截图、视频、Trace。
• 数据库状态。
• 指标和资源使用。
• 环境变量摘要。
• 被测版本和提交号。

flowchart TD
    A[测试执行] --> B[采集日志]
    A --> C[采集截图]
    A --> D[采集网络请求]
    A --> E[采集指标]
    B --> F[生成失败报告]
    C --> F
    D --> F
    E --> F

一个好的失败报告应该让工程师不用重新猜现场。

十七、断言 Harness

断言 Harness 负责把“输出看起来对”转成明确规则。

常见断言类型：

• 值断言：返回值等于预期。
• 状态断言：按钮禁用、弹窗打开、订单状态变化。
• 结构断言：JSON schema、类型、字段存在。
• 行为断言：某函数被调用、某事件被发送。
• 视觉断言：截图和基线一致。
• 性能断言：P95 延迟小于阈值。
• 安全断言：未泄露敏感字段。

flowchart TD
    A[系统输出] --> B[值断言]
    A --> C[状态断言]
    A --> D[结构断言]
    A --> E[行为断言]
    A --> F[性能断言]
    B --> G[测试结果]
    C --> G
    D --> G
    E --> G
    F --> G

断言应尽量贴近用户或业务结果，避免过度绑定内部实现。

十八、Harness 和 CI/CD

Harness Engineering 通常最终要进入 CI/CD。它让验证从本地行为变成团队自动化门禁。

flowchart TD
    A[代码提交] --> B[安装依赖]
    B --> C[静态检查]
    C --> D[单元 Harness]
    D --> E[集成 Harness]
    E --> F[E2E Harness]
    F --> G[上传报告]
    G --> H[决定是否放行]

CI 中的 Harness 要关注：

• 可并发执行。
• 失败产物可下载。
• 日志清晰。
• 超时合理。
• 不依赖本地状态。
• 不污染共享环境。
• 能区分测试失败和环境失败。

GitHub Actions 示例：

name: test

on:
  pull_request:

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run test:unit
      - run: npm run test:e2e
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-report
          path: playwright-report/

十九、Harness 和本地开发体验

如果 Harness 只能在 CI 跑，本地调试会很痛苦。好的 Harness 应该支持本地一键运行、单用例运行、调试模式、保留现场。

本地命令示例：

{
  "scripts": {
    "test": "vitest",
    "test:unit": "vitest run",
    "test:e2e": "playwright test",
    "test:e2e:ui": "playwright test --ui",
    "test:e2e:debug": "playwright test --debug"
  }
}

flowchart TD
    A[开发者本地修改] --> B[运行相关 Harness]
    B --> C[失败]
    C --> D[进入调试模式]
    D --> E[修复问题]
    E --> F[再次运行]
    F --> G[提交代码]

本地体验越好，团队越愿意维护测试。

二十、Harness 的配置设计

Harness 通常需要配置环境、服务地址、账号、超时、重试、报告路径、并发数。配置设计不好，会让使用者很痛苦。

建议：

• 默认值可用。
• 环境变量覆盖。
• 本地和 CI 配置分离。
• 敏感信息不写入代码。
• 配置项命名清晰。
• 报错时提示缺失配置。

配置示例：

export const testConfig = {
  baseURL: process.env.E2E_BASE_URL ?? 'http://127.0.0.1:5173',
  apiURL: process.env.E2E_API_URL ?? 'http://127.0.0.1:3000',
  timeout: Number(process.env.E2E_TIMEOUT ?? 30000),
  reportDir: process.env.E2E_REPORT_DIR ?? 'test-results'
};

flowchart TD
    A[读取默认配置] --> B[读取环境变量]
    B --> C[合并配置]
    C --> D[校验必填项]
    D --> E[启动 Harness]

二十一、Harness 中的重试机制

重试可以缓解偶发环境波动，但不能掩盖真实问题。

合理重试：

• 网络偶发超时。
• 外部测试环境短暂不可用。
• 浏览器启动偶发失败。

不合理重试：

• 断言本身错误。
• 数据污染。
• 选择器不稳定。
• 产品逻辑存在竞态。

flowchart TD
    A[测试失败] --> B[判断失败类型]
    B --> C[环境波动]
    C --> D[有限重试]
    B --> E[确定性失败]
    E --> F[直接失败并报告]
    D --> G[记录重试次数]

重试次数应该被记录。如果一个用例经常靠重试通过，它就是需要治理的不稳定用例。

二十二、Harness 的并行与隔离

为了提升速度，Harness 常常并行执行。并行执行的前提是隔离做得足够好。

隔离方式：

• 每个 worker 使用独立数据库 schema。
• 每个用例使用唯一数据前缀。
• 每个浏览器上下文独立登录态。
• 每个测试 namespace 独立资源。
• 避免共享可变全局状态。

flowchart TD
    A[并行执行] --> B[Worker 1]
    A --> C[Worker 2]
    A --> D[Worker 3]
    B --> E[独立数据空间]
    C --> F[独立数据空间]
    D --> G[独立数据空间]
    E --> H[合并报告]
    F --> H
    G --> H

并行问题很隐蔽，很多“偶发失败”其实是测试之间互相污染。

二十三、Harness 的生命周期

一个 Harness 运行通常包含准备、执行、采集、清理四个阶段。

flowchart TD
    A[Setup 准备] --> B[Run 执行]
    B --> C[Observe 采集]
    C --> D[Assert 断言]
    D --> E[Teardown 清理]
    E --> F[Report 报告]

生命周期钩子示例：

beforeAll(async () => {
  await startTestServer();
});

beforeEach(async () => {
  await resetDatabase();
});

afterEach(async ({ currentTest }) => {
  if (currentTest.state === 'failed') {
    await collectDebugArtifacts();
  }
});

afterAll(async () => {
  await stopTestServer();
});

清理阶段必须可靠。清理失败会影响后续用例，甚至污染测试环境。

二十四、Harness 和 AI Agent 评测

随着 LLM 和 AI Agent 进入工程系统，Harness Engineering 也开始用于 AI 评测。AI Agent 的 Harness 不只是跑代码，还要给 Agent 准备任务、工具、环境、评分器和审计日志。

flowchart TD
    A[AI Agent 评测任务] --> B[准备初始环境]
    B --> C[注入工具和权限]
    C --> D[Agent 执行任务]
    D --> E[采集工具调用轨迹]
    E --> F[运行评分器]
    F --> G[输出评测报告]

AI Harness 通常包含：

• 任务集。
• 初始工作区。
• 可用工具列表。
• 权限和沙箱。
• 轨迹记录。
• 自动评分器。
• 人工复核入口。
• 成本和耗时统计。

示例评分维度：

• 是否完成目标。
• 是否修改了正确文件。
• 是否通过测试。
• 是否产生多余变更。
• 是否调用危险工具。
• 是否能解释证据链。

二十五、AI 代码助手 Harness

如果要评测一个 AI 编程助手，可以构建如下 Harness：

flowchart TD
    A[准备代码仓库快照] --> B[注入用户任务]
    B --> C[AI 助手搜索和修改代码]
    C --> D[运行测试和静态检查]
    D --> E[检查 git diff]
    E --> F[评分完成度和质量]

任务示例：

{
  "id": "fix-login-validation",
  "repo": "sample-app",
  "prompt": "修复登录表单未校验空密码的问题",
  "expectedTests": ["login.test.ts"],
  "successCriteria": [
    "空密码时显示错误提示",
    "原有登录成功用例仍然通过",
    "没有修改无关文件"
  ]
}

AI Harness 的难点是评分。很多任务不只有一个正确答案，因此评分器需要结合测试、静态规则、diff 检查和人工复核。

二十六、硬件和嵌入式 Harness

Harness Engineering 不只属于 Web 和后端。硬件、嵌入式、IoT 场景也大量使用 Harness。

典型能力：

• 给设备刷入固件。
• 控制电源开关。
• 发送串口命令。
• 采集传感器数据。
• 模拟网络断开。
• 验证设备状态。

flowchart TD
    A[嵌入式 Harness] --> B[刷入固件]
    B --> C[启动设备]
    C --> D[发送测试指令]
    D --> E[读取串口日志]
    E --> F[采集设备指标]
    F --> G[判断测试结果]

这类 Harness 对稳定性要求更高，因为物理设备有更多不可控因素。

二十七、生产巡检 Harness

生产巡检 Harness 用来持续验证线上关键路径是否可用。它和测试环境 E2E 不同，必须低侵入、安全、可控。

flowchart TD
    A[定时触发巡检] --> B[访问线上关键页面]
    B --> C[执行只读或受控操作]
    C --> D[采集可用性指标]
    D --> E[发现异常]
    E --> F[告警和值班处理]

生产巡检应遵守：

• 尽量只读。
• 如需写入，使用专用测试账号和可清理数据。
• 不影响真实用户。
• 不触发真实支付、短信、邮件等副作用。
• 失败时关联告警、日志和 Trace。

二十八、Harness 设计中的常见反模式

1. Harness 过度复杂

为了复用而抽象过度，导致测试看不懂。好的 Harness 应该减少复杂度，而不是制造新的复杂度。

2. 隐藏太多细节

封装后测试用例只剩一行 runHappyPath()，读者看不出到底测了什么。

3. 数据互相污染

多个测试共享同一账号、同一订单、同一数据库状态，导致偶发失败。

4. 只在 CI 能跑

本地无法复现，失败定位非常痛苦。

5. 失败证据不足

只告诉你失败了，却没有截图、日志、请求和环境信息。

flowchart TD
    A[Harness 反模式] --> B[抽象过度]
    A --> C[隐藏业务意图]
    A --> D[数据污染]
    A --> E[本地不可运行]
    A --> F[缺少失败证据]

二十九、如何从零建设 Harness

如果团队还没有体系化 Harness，不建议一步到位。可以从最高价值路径开始。

flowchart TD
    A[选择关键场景] --> B[明确成功标准]
    B --> C[准备可重复环境]
    C --> D[管理测试数据]
    D --> E[实现自动执行]
    E --> F[采集失败证据]
    F --> G[接入 CI]
    G --> H[持续治理稳定性]

落地步骤：

1. 选择一条最关键业务链路。
2. 明确输入、执行步骤和预期结果。
3. 准备最小可运行测试环境。
4. 设计测试数据创建和清理方式。
5. 写出第一条可重复执行的用例。
6. 保存失败截图、日志和报告。
7. 接入 CI。
8. 再逐步扩展更多用例和场景。

三十、Harness 的质量度量

Harness 本身也需要度量，否则它会慢慢变成维护负担。

可以关注：

• 用例通过率。
• 不稳定用例比例。
• 平均执行耗时。
• 失败定位耗时。
• 环境启动耗时。
• 数据清理失败次数。
• 重试后通过比例。
• CI 阻塞次数。
• 有效发现缺陷数量。

flowchart TD
    A[Harness 质量] --> B[稳定性]
    A --> C[速度]
    A --> D[可定位性]
    A --> E[覆盖价值]
    A --> F[维护成本]

一个好的 Harness 不一定用例最多，但应该能稳定保护关键路径。

三十一、前端项目 Harness 实践方案

一个现代前端项目可以这样组织 Harness：

project
├── src
├── tests
│   ├── unit
│   ├── component
│   ├── integration
│   └── e2e
├── test-utils
│   ├── renderWithProviders.tsx
│   ├── mockServer.ts
│   ├── dataFactory.ts
│   └── collectArtifacts.ts
├── playwright.config.ts
└── vitest.config.ts

flowchart TD
    A[前端 Harness] --> B[Vitest 单元测试]
    A --> C[Testing Library 组件测试]
    A --> D[MSW 接口模拟]
    A --> E[Playwright E2E]
    A --> F[视觉回归]
    A --> G[CI 报告]

推荐组合：

• Vitest 或 Jest 负责函数和状态逻辑。
• Testing Library 负责组件交互。
• MSW 负责前端接口模拟。
• Playwright 负责关键用户路径。
• axe-core 负责基础可访问性检查。
• CI artifacts 保存失败报告。

三十二、后端项目 Harness 实践方案

后端项目 Harness 更关注服务依赖、数据库、消息队列和接口契约。

flowchart TD
    A[后端 Harness] --> B[单元测试]
    A --> C[API 集成测试]
    A --> D[数据库迁移测试]
    A --> E[消息队列测试]
    A --> F[契约测试]
    A --> G[性能测试]

推荐实践：

• 用 Testcontainers 或 Docker Compose 启动真实依赖。
• 每个测试隔离数据。
• 数据库迁移必须在测试环境验证。
• 外部第三方服务用 Fake 或沙箱环境。
• API 响应做 schema 断言。
• 关键接口进入性能 Harness。

三十三、Harness 与工程效率

Harness Engineering 的目标不是为了测试而测试，而是提升工程效率。它让团队更敢改代码、更快定位问题、更少依赖人工回归。

flowchart TD
    A[高质量 Harness] --> B[更快反馈]
    B --> C[更少人工回归]
    C --> D[更高发布信心]
    D --> E[更低故障成本]

它带来的收益：

• 新人能更快理解系统行为。
• 重构时有自动化保护。
• 发布前风险更可控。
• 故障复现更容易。
• 测试环境更标准化。
• AI 代码助手也能借助 Harness 验证修改。

三十四、Harness Engineering 检查清单

建设或审查 Harness 时，可以使用下面的清单：

• 是否明确被测对象和成功标准。
• 是否能本地和 CI 一致运行。
• 是否有稳定的环境准备方式。
• 是否有测试数据创建和清理机制。
• 是否避免用例之间互相依赖。
• 是否支持单用例调试。
• 是否采集失败截图、日志和 Trace。
• 是否控制重试次数并记录不稳定用例。
• 是否避免过度抽象。
• 是否把关键链路接入发布门禁。
• 是否能衡量运行速度和稳定性。

flowchart TD
    A[Harness 检查] --> B[可运行]
    A --> C[可重复]
    A --> D[可隔离]
    A --> E[可观测]
    A --> F[可维护]
    A --> G[可度量]

三十五、总结

Harness Engineering 是把测试、验证、执行和观测工程化的一套方法。它不只是写几个测试用例，而是为被测对象搭建一个可重复、可隔离、可控制、可观测的运行夹具，让系统行为可以被稳定验证。

在前端项目中，Harness 可以表现为组件测试工具、接口 Mock、Playwright E2E、视觉回归和 CI 报告；在后端项目中，它可以表现为测试数据库、依赖服务、契约测试、性能压测和环境编排；在 AI Agent 场景中，它可以表现为任务集、工具沙箱、执行轨迹和评分器。

好的 Harness 应该少而稳、清晰可读、失败可定位、本地可运行、CI 可集成。它的最终目的不是追求测试数量，而是让团队在复杂系统中获得更可靠的反馈和更高的发布信心。