Angular 测试实战指南：ECC 规则体系下的组件、服务与路由测试全解析

Angular 测试实战指南：ECC 规则体系下的组件、服务与路由测试全解析

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

本文基于 ECC 仓库中的 Angular 语言级测试规则文档（docs/ja-JP/rules/angular/testing.md，英文原版见 rules/angular/testing.md）展开，系统讲解 Angular 项目中组件测试、Signal 输入、组件 Harness、路由测试、异步/HTTP 测试与 E2E 测试的完整方法论，并结合仓库内angular-developer技能参考文档与通用测试规则进行源码级印证。读完本文，你将掌握一套可直接复制到实际 Angular 项目中的测试骨架、命令与覆盖策略。

规则定位：这份文档管什么

该规则文档通过 frontmatter 声明了生效范围：

paths: - "**/*.spec.ts" - "**/*.test.ts"

即所有*.spec.ts与*.test.ts测试文件都属于该规则的管辖范围。文档开头明确说明它是对通用测试规则的 Angular 专属扩展，对应文件为 docs/ja-JP/rules/common/testing.md（英文版见 rules/common/testing.md）。这意味着 Angular 测试除了遵循本文件的专属约定外，还必须同时满足通用测试规则中关于最低 80% 覆盖率、测试驱动开发（TDD）工作流与AAA 测试结构的硬性要求。

在 ECC 的规则体系里，rules/angular/目录下还并列存放着coding-style.md、hooks.md、patterns.md、security.md，本测试规则与它们共同构成完整的 Angular 开发约束；更深入的测试模式、Harness 用法与异步最佳实践则由技能angular-developer（见 skills/angular-developer/SKILL.md）提供支撑，本文后面的内容会持续交叉引用这些参考文档。

测试运行器：先确认项目配置，再决定命令

Angular 生态中测试运行器并不唯一。规则要求使用项目已配置好的运行器，而不是自行引入新框架。判断依据是两个文件：

• angular.json：查看 builder 配置（如@angular-devkit/build-angular:vitest、karma等）；
• package.json：查看scripts段与 devDependencies 中安装的是 Vitest、Jest 还是 Jasmine + Karma。

Angular 项目中最常见的三种选择是Vitest、Jest和Jasmine + Karma。无论底层是哪一种，CLI 入口通常统一为：

ng test # 监听模式（watch），开发时使用 ng test --no-watch # CI 模式，跑完即退出

从 skills/angular-developer/references/testing-fundamentals.md 可以印证同样原则：测试应使用项目已配置的 runner。在 CI 流水线中务必使用--no-watch，避免进程因监听而永不退出导致流水线挂起。

TestBed 配置与组件夹具

组件测试的核心入口是TestBed。对于Standalone 组件，直接在imports中导入组件类本身即可，无需再声明模块：

describe('UserCardComponent', () => { let fixture: ComponentFixture<UserCardComponent>; beforeEach(async () => { await TestBed.configureTestingModule({ imports: [UserCardComponent], }).compileComponents(); fixture = TestBed.createComponent(UserCardComponent); }); });

规则特别提醒：对于使用外部模板（external template）的组件，必须调用compileComponents()，等待模板与样式编译完成后再创建夹具；Standalone 组件若模板内联也可省略，但统一调用更稳妥。

创建后的ComponentFixture提供三个常用访问入口：

• fixture.componentInstance：组件类实例，可直接访问属性和方法；
• fixture.nativeElement：组件根 DOM 元素；
• fixture.debugElement：Angular 的 DebugElement 包装，提供query(By.css(...))等平台无关的查询方式（参见 testing-fundamentals.md）。

异步优先的测试哲学

testing-fundamentals.md强调现代 Angular 应用常以异步方式调度状态更新，尤其在引入 Signal 或 zoneless 变更检测后，测试必须主动等待。推荐的模式是Act–Wait–Assert：

1. Act：更新状态或执行动作（设置输入、点击按钮）；
2. Wait：await fixture.whenStable()让框架处理完排队的更新并完成渲染；
3. Assert：对结果做断言。

it('should display the default title', async () => { // ACT：组件以默认状态创建 // WAIT：等待初始数据绑定完成 await fixture.whenStable(); // ASSERT expect(h1.textContent).toContain('Default Title'); });

Signal 输入的测试方式

Angular Signal 化的组件输入（input()）不能再通过直接赋值属性来设置，规则明确要求使用fixture.componentRef.setInput()：

fixture.componentRef.setInput('user', mockUser); fixture.detectChanges();

setInput()走的是与真实模板绑定相同的输入通道，会正确触发 Signal 的写入与下游计算更新，随后调用detectChanges()将新值反映到视图中。这是测试 Signal 输入组件的标准姿势，比操作componentInstance更贴近真实运行语义。

组件 Harness：优先于直接 DOM 查询

规则给出了一个明确的取舍：UI 交互测试优先使用 Angular CDK 组件 Harness，而不是手写querySelector。理由是 Harness 对标记（markup）变更具有更强的耐性——重构内部 HTML 或 CSS 类时测试不会跟着碎掉。

组件 Harness 的三重价值（详见 component-harnesses.md）：

• 健壮性：不因组件内部 DOM 结构调整而失效；
• 可读性：以用户视角描述交互，如button.click()、slider.getValue()，而非querySelector链；
• 可复用性：同一套 Harness 可同时用于单元测试与 E2E 测试。

在单元测试中通过TestbedHarnessEnvironment获取 loader：

import { HarnessLoader } from '@angular/cdk/testing'; import { TestbedHarnessEnvironment } from '@angular/cdk/testing/testbed'; import { MatButtonHarness } from '@angular/material/button/testing'; let loader: HarnessLoader; beforeEach(() => { loader = TestbedHarnessEnvironment.loader(fixture); }); it('triggers save on button click', async () => { const button = await loader.getHarness(MatButtonHarness.with({ text: 'Save' })); await button.click(); expect(saveSpy).toHaveBeenCalled(); });

几个关键概念：

1. HarnessLoader：查找并创建 Harness 实例的入口，通过TestbedHarnessEnvironment.loader(fixture)获得；
2. loader.getHarness(HarnessClass)：异步返回第一个匹配组件的 Harness 实例；
3. HarnessClass.with({...})：多数 Harness 提供静态with方法返回HarnessPredicate，可基于文本、selector、禁用状态等属性精确定位目标组件；
4. Harness API：.click()、.getText()、.getValue()等方法内部会自动处理异步等待与变更检测，测试代码无需手动detectChanges。

路由测试：RouterTestingHarness 而非 mock Router

对依赖路由的组件，规则推荐使用RouterTestingHarness，而不是 mock 掉Router服务。核心原因是：使用真实 harness 才能测试到实际的路由配置、守卫（guards）与解析器（resolvers），测试才有意义（参见 router-testing.md）。

配合provideRouter在 TestBed 中提供测试专用路由：

import { RouterTestingHarness } from '@angular/router/testing'; it('renders user on navigation', async () => { const harness = await RouterTestingHarness.create(); const component = await harness.navigateByUrl('/users/1', UserDetailComponent); expect(component.userId()).toBe('1'); });

完整用法要点：

• provideRouter([...])：在TestBed.configureTestingModule的providers中注入测试路由表；
• RouterTestingHarness.create()：异步创建 harness 并完成到根路径/的首次导航；
• harness.navigateByUrl(url, ComponentType)：模拟导航，Promise 解析为激活后的组件实例；
• harness.router.url：访问真实 Router 实例断言当前 URL；
• 导航动作后记得await harness.fixture.whenStable()等待路由完成再断言。

异步测试：fakeAsync 与 waitForAsync 的取舍

规则给出两种异步策略的使用边界：

• 受控异步：用fakeAsync+tick，可精确控制时间推进；
• 真实异步：用waitForAsync+fixture.whenStable()，适合真实计时器或真实异步任务。

it('loads user after delay', fakeAsync(() => { const service = TestBed.inject(UserService); vi.spyOn(service, 'getUser').mockReturnValue(of(mockUser)); fixture.detectChanges(); tick(); fixture.detectChanges(); expect(fixture.nativeElement.querySelector('.name').textContent).toBe(mockUser.name); }));

注意示例中的vi.spyOn表明它面向 Vitest 运行器；若项目使用 Jasmine（Karma）或 Jest，将vi.前缀替换为对应的spyOn语法即可。tick()会同步推进fakeAsync区域内的定时器/微任务，随后再次detectChanges()完成渲染，最终对 DOM 文本做断言。

HTTP 测试：HttpTestingController 模拟请求

通过provideHttpClientTesting()启用 Angular 的 HTTP 测试后端，并用HttpTestingController手动断言请求：

import { provideHttpClientTesting } from '@angular/common/http/testing'; import { HttpTestingController } from '@angular/common/http/testing'; beforeEach(() => { TestBed.configureTestingModule({ providers: [provideHttpClient(), provideHttpClientTesting()], }); httpMock = TestBed.inject(HttpTestingController); }); afterEach(() => httpMock.verify());

两个容易踩坑的点：

• 必须同时提供provideHttpClient()（真实 HttpClient 的基础能力）与provideHttpClientTesting()（测试后端），二者缺一不可；
• 每个用例结束后调用httpMock.verify()，它会断言没有未处理的意外请求，防止测试之间互相污染。

服务测试：无需组件夹具，直接注入

服务（Service）的测试不需要创建任何组件夹具，直接在 TestBed 中声明 provider 并注入：

describe('UserService', () => { let service: UserService; beforeEach(() => { TestBed.configureTestingModule({ providers: [provideHttpClient(), provideHttpClientTesting()], }); service = TestBed.inject(UserService); }); });

若服务内部依赖 HttpClient，同样需要provideHttpClient()+provideHttpClientTesting()组合。这种直注方式让服务的每个公共方法都能被独立验证，配合 80% 覆盖率要求，是整套规则中最基础也最重要的测试形态。

测试对象清单：什么该测、怎么测

其中管道（Pipe）是特例：它是纯函数，直接new出来传参断言即可，完全不需要引入 TestBed，测试成本最低。

E2E 测试：真实浏览器中的关键用户流

关键用户流程（登录、下单、支付等）使用项目配置的 E2E 框架，常见为Cypress或Playwright（详见 e2e-testing.md）。运行命令以项目实际配置为准，常见有npm run e2e、pnpm e2e或ng e2e。

Cypress 示例（与规则文档一致）：

describe('Login flow', () => { it('redirects to dashboard on valid credentials', () => { cy.visit('/login'); cy.get('[data-cy=email]').type('user@example.com'); cy.get('[data-cy=password]').type('password123'); cy.get('[data-cy=submit]').click(); cy.url().should('include', '/dashboard'); }); });

E2E 的两条硬性纪律：

1. 为可交互元素添加data-cy属性，作为稳定选择器；
2. 不要依赖 CSS 类名或文本内容做选择器——它们极易随样式与文案调整而失效。

若项目使用 Playwright，则更推荐无障碍定位器（getByRole、getByLabel）或稳定的data-*属性，并等待特定 UI 状态/路由/网络响应而非固定 sleep（见 e2e-testing.md）。另外保持冒烟测试短小，把完整流程覆盖留给价值最高的路径。

覆盖率与通用质量门禁

规则的覆盖率底线继承自通用测试规则 rules/common/testing.md：

• 服务与管道：目标 ≥80% 覆盖率；
• 组件：测试行为而非实现细节（test behaviour, not implementation details）——不要为了凑覆盖率去断言内部私有方法或中间状态。

通用规则还强制 TDD 工作流（RED → GREEN → IMPROVE）与AAA 结构（Arrange–Act–Assert），并给出了行为化的命名规范：

test('returns empty array when no markets match query', () => {}) test('throws error when API key is missing', () => {}) test('falls back to substring search when Redis is unavailable', () => {})

遇到测试失败时按通用规则依次排查：先借助tdd-guideagent，再检查测试隔离性与 mock 正确性，最后遵循"修复实现而非测试"（除非测试本身写错了）的原则。

与 ECC 规则体系的协同查阅

• 通用测试基线（覆盖率/TDD/AAA）：rules/common/testing.md
• Angular 测试规则日文版：docs/ja-JP/rules/angular/testing.md
• Angular 开发者技能入口：skills/angular-developer/SKILL.md，其中与测试直接相关的参考文档包括：
  • testing-fundamentals.md（TestBed、异步模式、Act–Wait–Assert）
  • component-harnesses.md（Harness 原理与 HarnessPredicate）
  • router-testing.md（RouterTestingHarness 与 provideRouter）
  • e2e-testing.md（Cypress/Playwright 最佳实践）

总结：一份可直接落地的 Angular 测试清单

1. 先看配置：以angular.json与package.json为准选择 runner，用ng test（watch）/ng test --no-watch（CI）；
2. 组件测试：Standalone 组件直接imports，外部模板必须compileComponents()，Signal 输入用fixture.componentRef.setInput()；
3. 交互测试：优先 CDK Harness（TestbedHarnessEnvironment+with({...})谓词），拒绝脆弱 DOM 查询；
4. 路由相关：用RouterTestingHarness+provideRouter，不要 mock Router，同时覆盖守卫/解析器的放行与拒绝分支；
5. 异步与 HTTP：fakeAsync+tick控制时序，provideHttpClientTesting()+HttpTestingController.verify()守护请求；
6. 服务/管道：服务直注测试公共方法与错误路径，管道做纯函数单测；
7. E2E：关键流程交给 Cypress/Playwright，坚持data-cy稳定选择器；
8. 覆盖率：服务与管道 ≥80%，组件测行为不测实现，全程遵循 TDD 与 AAA。

这套规则同时约束着 Agent 与人类开发者，既保证了 Angular 测试的规范统一，也让测试代码本身具备高可维护性——这正是 ECC 将语言级测试规则沉淀为仓库知识的价值所在。

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC