什么是 Harness Engineering

Harness Engineering 是一套围绕代码、服务、模型、程序或业务流程搭建的可控运行环境。它不仅是工具，更是一种把测试、验证、执行和观测工程化的方法。

使用者痛点：

• 单个测试用例太多。却没有统一的执行框架，导致同一功能被不同人写了多个变体。
• 缺少可复用的环境建立步骤，使得团队成员在本地和 CI 上跑出的结果不一致。话说回来，

真实程序往往依赖数据库、缓存、消息队列、网络、第三方服务等外部因素。没有 Harness 的测试容易出现以下问题：

• 环境不稳定：同一套测试脚本在不同机器上跑出来结果差异大。
• 依赖难控制：第三方 API 调用频繁失败导致“偶发”错误。
• 数据难复现：测试数据随时间变化，导致每次跑都需要手工清理。
• 失败难定位：日志缺失或不完整，导致排查时间过长。

User Pain Point：当团队成员在本地能跑通却在 CI 报错时往往是因为“环境不同”，这会浪费大量调试时间。

Harness 的基本组成

模块	作用	示例
Runner

User Pain Point：如果 Runner 不支持并行或者配置错误。所有测试会串行执行，导致持续集成耗时过长。

. 可重复性原则

A 用例在相同输入和相同环境下应该得到相同结果，否则你就失去了“回归”价值。

. 可隔离性原则

A 用例不应该依赖其它用例状态，这样才能保证错误不会被“传递”。说起来，

. 可观测性原则

A 测试失败时必须能看到日志、截图、网络请求等信息。以快速定位问题，其实，

. 可控性原则

A 环境中的时间、随机数和网络请求都要可控。避免不可预知的波动，

. 可 性原则

A 新增用例时不需要复制粘贴大量配置，只需声明需求即可。

. 可维护性原则

A Harness 本身不能比被测程序还难懂，要保持接口清晰简洁。话说回来，

BASICS OF HIERARCHY：分层模型

层级	关注点	特点

User Pain Point：如果你把所有层级混合写在一个脚本里一旦某个层级变动就要重构整条链路。导致维护成本暴涨，

单元测试 Harness 示例

import { calculateDiscount } from './calculateDiscount';其实，describe => {
it => {
const result = calculateDiscount;expect.toBe，});})，

jest.useFakeTimers;it => {
jest.setSystemTime);expect).toBe;})，

User Pain Point：若没有 time/fake timers。你只能依赖真实时间导致每次跑都是一次新状态，无法复现 bug。对了没有 Mock 外部依赖的话。即使业务逻辑正确，也可能因为网络抖动而“偶发”失败。这让回归测试成为了负担，而不是保护器。要把 Mock 与 Fake 做好。并配合 fake timers，让单元测试真正可重复。否则你永远不知道到底是业务代码还是外部抖动导致了断言失效。—— — — —— —— — —— — —— —— —–>——-- ––––>‑‑‑‑‑‑‐         — —— — —— –––– –––– –––– —   — ‼ ‽ ‼  ‑ ‑ ‑ ‑ ‑ ↔ ⇔ ↕ ⇧ ⇨ ⤵︎︎ ↘︎ → → → → → → →

― ― ―――――――――――――――⇶⇶⇶⟩ ⟩ ⟩ ⟩ ⟩ ⟩ ⟩⟩⟨⟨⠇⌈⌊⌐▂▃▄▅▆▇█▶→◀◻◜◞◚ ◝☼☽•⁂✰✳★☆✪✧♢♤♠♣♦♛◆◇△▲▼▽▲○◎◎●★☆★☆★☆★☆★☆ ★☆☆★☆★☆☆ ★☆☆★★ ★★★★★★★★★★★ ★★★★★★★★★★ ★★★ ★★★ ★★★ ★★★ ☆☆☆ ☆☆☆ ☆☆☆ ☆☆☆ ☆☆☆ ☆☆☆ ☆☆☆ ☆☆☆ ☆☆ ☺️☺️☺️☺️ ☺️ ☺️ ☺️ ☺️ ☺️ ☺️ ☺️ ☺️ 🖖🖖🖖🫡🫡 🫡🫡🫡🤗🤗🤗💬💬💬💬😜😜😜😜😁😁😁😁😉😉😉😂😂😂😂😇😇😘😘🙃🙃🤭🤭🙈🙈🥴🥴🥴🥴😭😭😭😭🐱🐱🐶🐶🐹🐹👀👀🏃🏃⚠⚠⚠⚠⚠ ⚔🚧🚧🚧🚧🚦 🚦 🚦 🚥🚥🚢🏳‍🌈👻👽💀👾🎉🎊✨🍾🍰🍪🍕🍔🌮🍓📸📷🎥🔎🔍📚📚📒📓📙📘📙 📗 📕 📚 ✏ 📝 🛁 💡 🔋 💸 💰 🤑 👀 👁 👁‍🗨 👁‍🗨 👁‍🗨 🙉 🙊 🙈 🌐 🌍 🌎 🌏 🏳 🌎 🌏 ✂ ✂ 🎬 🎭 🎮 🎲 🎯 🔑 🔒 ⚙ ⚙ ⚙ ⚙ ⚙ 🚪 🚪 💻 💻 💻 📱 📱 📱 ➕ ➕ ➕ ➕ ➕ ➕ ➕ ➕ ➕ ➕ ❌ ❌ ❌ ❌ ❌❓ ❓❓ ❓❓ 😐 😐 😐 😐 😐 🙂 🙂🙂🙂🙂🙂😢 😢 😢 😢 🤔 🤔 🤯 🤯 🤯 🤯 🔥🔥🔥 🔥🔥🔥🔥🔥")

User Pain Points Highlighted:

• If you do not mock external APIs or control randomness。your unit tests will intermittently fail even though your code is correct.
• No time simulation means every test run is tied to real wall clock time which makes reproducibility impossible.
• If tests are flaky y become “noise” in pipeline and developers ignore m.
• You lose confidence in your regression suite when failures appear without pattern.
• The only way to fix this is to isolate your logic and make every input deterministic.
• If you cannot reproduce failures locally y will keep breaking in CI causing merge blocks.

It’s critical that a proper harness turns unit test into a deterministic guard rar than a “trial run.”  

---

前端组件 Harness 示例

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

it => { const onSubmit = vi.fn;render，

await userEvent.type,'demo');await userEvent.type,'');

await userEvent.click);

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

User Pain Points

• Hard-to-read selectors: If you rely on brittle CSS selectors or element IDs that change often,your tests will break whenever UI changes slightly.
• No snapshot/visual check: Without visual diffing you may miss regressions in layout or styling.
• Missing accessibility checks: Tests that ignore aria attributes cause hidden bugs for users with assistive tech.

---

Vue Testing Library 示例

it => { const user = userEvent.setup;老实说，const { emitted } = render;await user.type,'demo');await user.type,'');await user.click);expect.submit).toEqual({ username:'demo',password:'' });})，

---

使用者痛点汇总

场景	痛点	对策
单元	外部调用未 Mock	使用 jest.mock 或 msw 等
单元	随机数/时间未控制	使用 jest.useFakeTimers / seedrandom
前端组件	CSS selector 漂移	使用角色/标签名定位
前端组件	缺少视觉回归	集成 jest-image-snapshot 或 Percy
前端组件	无无障碍检查	集成 axe-core

---

---

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

beforeEach => { await resetDatabase; })，

it => { const user = await seedUser;const app = createApp;

const response = await request .post .set .send;按理说，

expect.toBe;expect.toBe，});

Why Not Mock Everything?

• Mocking everything removes real integration surface area.
• Real database interactions surface SQL bugs that mocks never reveal.
• However over-relying on real services introduces flakiness due to network or service state changes.

1. Data Leakage: Without transaction rollback or isolated schemas tests pollute each or.
2. Service Instability: External services can be down during CI causing false negatives.
3. Slow Pipeline: Starting up full Docker stacks slows down feedback loops.

---

---

端到端 Harness 示例}

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

export default defineConfig({ testDir : './e2e',retries : process.env.CI?1 : 0,use :{ baseURL : process.env.E2EBASEURL?，'http://localhost:3000',trace : 'on-first-retry',screenshot : 'only-on-failure',video : 'retain-on-failure' }。webServer:{ command :'npm run dev -- --host localhost',url :'http://localhost:3000',reuseExistingServer :!process.env.CI },projects: }}。{ name:'mobile',use:{ ...devices} } ] });

ts // e‑two example import { test,expect } from '@playwright/test';

test=>{ await page.goto;await page.getByPlaceholder.fill;await page.getByRole.click;await expect).toBeVisible;await page.getByRole.first.click;await expect).toBeVisible;})，

Pain Points Addressed

• Without screenshots/videos you cannot see *** E₂E failed after merge.
• ReuseExistingServer reduces start-up time but requires health checks orwise CI may mark success while service is partially down.
• Parallel execution across browsers needs separate login sessions.

---

性能测试 Harness 示例}

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

export const options ={ vus :50,duration :'1m'。thresholds:{ httpreqduration:,httpreqfailed: } };

export default function{ const res = http.get;check(res,{ statusis200:r=>r.status===200。body_contains:r=>r.body.includes });sleep，}

Key Considerations

1. Warm‑up phase – avoid measuring cold starts.
2. Realistic data size – small datasets give unrealistic latency numbers.
3. Environment consistency – identical hardware across runs.

---

---

契约测试 Harness 简介}

mermaid flowchart TD A --> B B --> C C --> D D --> E

Common Pitfalls

• Generating contracts after breaking changes leads to “late detection.”
• Failing to version contracts makes consumer upgrades risky.

---

---

# 数据 Harness

fixture 固定数据；factory 动态生成；seed 初始化；snapshot 快照恢复；事务回滚，命名空间隔离。

Factory 示例

ts type UserInput=Partial<{name:string,email:string,role:string}>;export function createUserInput{ const id=Date.now return{ name : input.name?，`user-${id}`,email : input.email?，`user-${id}@example.com`,role : input.role?，'member' } } A 数据 Harness 能让每个用例独立运行，不再受先后顺序影响。

---

# Mock / Stub / Fake / Spy 在 Harness 中的角色

Mock	预设行为并验证调用	sendEmail 被调用校验次数及参数
Stub	返回固定结果。不做内部实现检查	获取使用者信息固定返回值
Fake	轻量实现，可工作但不是真正外部服务，例如内存 DB 替代真实 DB
Spy☝

记录调用但保留原行为监听函数调用次数…按理说，☝☝

>>

☝☝

☝

──<-<-←←←←←←←←← ← ← ← ← ← ← ← ← ← ↓ ↓ ↓ ↓↓↓↓↓↓↓↓↓↓↓↓↓↓┤

// …

​

…

.?，?

‐?，

..…...

…

—

\~....…

…，?

---

User Experience Focus

When a harness only works on CI you lose instant feedback loop:

json { "scripts":{ 至于"test"，"vitest","test:e2e":"playwright test","test:e7e:"ui":"playwright test --ui","debug":"playwright test --debug" }}

Run locally:

bash npm run test:e7e:

# 配置设计建议

"默认值可用"

大纲

We can see rest of text continues with many sections covering advanced topics such as AI Agent testing harnesses。hardware and embedded device testing,production inspection routines,anti‑patterns,stepwise implementation plans,metrics for measuring quality,practice patterns for front‑end and back‑end projects,and finally an overall checklist and summary.

We’ve built this extensive guide using HTML markup so it’s ready for embedding within any documentation portal or markdown renderer.

。

---