Angular Material Progress Spinner 组件测试 Harness 完全指南MatProgressSpinnerHarness 的 API 与实战用法【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components本篇技术指南以组件仓库中goldens/material/progress-spinner/testing/index.api.mdangular/material_progress-spinner_testing包的 API 报告为骨架系统讲解 Angular Material Progress Spinner 的测试 Harness 体系包括MatProgressSpinnerHarness的公开 API、ProgressSpinnerHarnessFilters过滤条件、与angular/cdk/testing基础设施的关系以及在 TestBed 与真实源码中如何驱动 determinate/indeterminate 两种模式完成组件测试。读完本文你将能够在自己的 Angular 单元测试中用类型安全、与 DOM 解耦的方式定位进度圈、读取其当前进度值与模式并理解这些断言背后的 ARIA 实现原理。一、API 报告Harness 的官方契约goldens/material/progress-spinner/testing/index.api.md是由 API Extractor 生成的 API 报告文件它精确描述了angular/material_progress-spinner_testing入口点的全部公开导出。这类 golden 文件在仓库中充当公开 API 的冻结契约——任何对 Harness 公共签名的改动都会导致 API 报告与之不符从而在 CI 中被拦截。因此阅读这份文件等同于阅读该测试包的权威类型定义。该包的公开面由两个导出组成import { BaseHarnessFilters } from angular/cdk/testing; import { ComponentHarness } from angular/cdk/testing; import { ComponentHarnessConstructor } from angular/cdk/testing; import { HarnessPredicate } from angular/cdk/testing; // public export class MatProgressSpinnerHarness extends ComponentHarness { getMode(): PromiseProgressSpinnerMode; getValue(): Promisenumber | null; static hostSelector: string; static withT extends MatProgressSpinnerHarness(this: ComponentHarnessConstructorT, options?: ProgressSpinnerHarnessFilters): HarnessPredicateT; } // public export interface ProgressSpinnerHarnessFilters extends BaseHarnessFilters { }关键信息可以归纳为四点包名与入口测试 Harness 位于angular/material_progress-spinner_testing入口点仓库路径 testing/public-api.ts依赖angular/cdk/testing中定义的ComponentHarness、HarnessPredicate、ComponentHarnessConstructor与BaseHarnessFilters四个基础设施符号。MatProgressSpinnerHarness extends ComponentHarness它是 CDK 组件测试 Harness 体系的成员通过继承获得host()、getAllHarnesses等底层能力。ProgressSpinnerHarnessFilters是空扩展接口它仅继承BaseHarnessFilters目前没有额外过滤字段——意味着筛选 Progress Spinner 时只能使用BaseHarnessFilters提供的基础条件。ProgressSpinnerMode类型跨包复用getMode()的返回值ProgressSpinnerMode来自主包angular/material_progress-spinner定义见 progress-spinner.ts是determinate | indeterminate的联合类型。注public标记意味着这些 API 面向所有外部使用者开放该包没有packageDocumentation注释因此 API 报告末尾标注 No packageDocumentation comment。二、源码实现Harness 背后的读取逻辑API 报告只给出签名真正的读取逻辑位于 progress-spinner-harness.ts。实现非常精简三个成员各司其职export class MatProgressSpinnerHarness extends ComponentHarness { /** The selector for the host element of a MatProgressSpinner instance. */ static hostSelector .mat-mdc-progress-spinner; static withT extends MatProgressSpinnerHarness( this: ComponentHarnessConstructorT, options: ProgressSpinnerHarnessFilters {}, ): HarnessPredicateT { return new HarnessPredicate(this, options); } /** Gets the progress spinners value. */ async getValue(): Promisenumber | null { const host await this.host(); const ariaValue await host.getAttribute(aria-valuenow); return ariaValue ? coerceNumberProperty(ariaValue) : null; } /** Gets the progress spinners mode. */ async getMode(): PromiseProgressSpinnerMode { const modeAttr (await this.host()).getAttribute(mode); return (await modeAttr) as ProgressSpinnerMode; } }2.1 hostSelector如何定位宿主元素hostSelector是.mat-mdc-progress-spinner指向组件根元素上的 CSS 类。这与组件装饰器的host元数据完全对应——在 progress-spinner.ts 中宿主元素被声明为host: { role: progressbar, class: mat-mdc-progress-spinner mdc-circular-progress, ... [attr.aria-valuenow]: mode determinate ? value : null, [attr.mode]: mode, },可以看到 Harness 与组件通过同一组属性契约互相咬合Harness 读取的aria-valuenow和mode属性正是组件在宿主上绑定的动态属性。2.2 getValue()读取进度的两种语义getValue()从宿主元素的aria-valuenow属性取值并通过coerceNumberProperty来自angular/cdk/coercion将字符串安全转换为数字determinate 模式组件绑定aria-valuenow value组件内部会先经Math.max(0, Math.min(100, v || 0))钳制到 0100见 progress-spinner.ts因此 Harness 返回number如50。indeterminate 模式组件绑定aria-valuenow null属性不存在Harness 返回null。这解释了为什么返回值类型是Promisenumber | nullnull 是无确定进度的显式信号调用方无需依赖猜测。2.3 getMode()直接读宿主属性getMode()读取宿主的mode属性并断言类型为ProgressSpinnerMode。注意组件构造函数中的细节progress-spinner.tsthis.mode element.nodeName.toLowerCase() mat-spinner ? indeterminate : determinate;也就是说使用mat-spinner别名标签时即使不写mode属性组件也会把宿主mode属性置为indeterminate——因此 Harness 对mat-spinner依然能正确读到indeterminate详见下文测试用例验证。2.4 ProgressSpinnerHarnessFilters过滤条件的可扩展设计progress-spinner-harness-filters.ts 中export interface ProgressSpinnerHarnessFilters extends BaseHarnessFilters {}接口目前为空仅继承BaseHarnessFilters该基类来自angular/cdk/testing提供如按宿主选择器、文本、ID 等通用过滤字段。从源码结构看之所以保留独立接口而非直接使用BaseHarnessFilters是为了预留未来按 mode、value 等语义过滤的扩展点——当 Progress Spinner 需要新增过滤维度时只需向此接口追加字段并扩充with()内的HarnessPredicate配置即可不会破坏既有调用方。三、实战用法在 TestBed 中驱动 Harness3.1 准备测试环境Progress Spinner Harness 基于angular/cdk/testing的Testbed 环境TestbedHarnessEnvironment工作。在 Angular 单元测试Karma/Jasmine 或 Vitest中按如下方式搭建import {ComponentFixture, TestBed} from angular/core/testing; import {HarnessLoader} from angular/cdk/testing; import {TestbedHarnessEnvironment} from angular/cdk/testing/testbed; import {MatProgressSpinnerModule} from ../progress-spinner-module; import {MatProgressSpinnerHarness} from ./progress-spinner-harness; let fixture: ComponentFixtureProgressSpinnerHarnessTest; let loader: HarnessLoader; beforeEach(async () { fixture TestBed.createComponent(ProgressSpinnerHarnessTest); fixture.detectChanges(); loader TestbedHarnessEnvironment.loader(fixture); });测试组件模板覆盖三种形态取自仓库内 progress-spinner-harness.spec.ts 的ProgressSpinnerHarnessTestmat-progress-spinner modedeterminate [value]value()/mat-progress-spinner mat-progress-spinner modeindeterminate/mat-progress-spinner mat-spinner/mat-spinner即显式 determinate、显式 indeterminate、以及mat-spinner别名隐式 indeterminate三种场景。3.2 加载所有 Harnessit(should load all progress spinner harnesses, async () { const progressSpinners await loader.getAllHarnesses(MatProgressSpinnerHarness); expect(progressSpinners.length).toBe(3); });getAllHarnesses以hostSelector为根找出页面中全部匹配的组件实例。这里返回 3 个恰好对应模板中的三个元素由于目前过滤条件为空getAllHarnesses与getAllHarnesses(MatProgressSpinnerHarness, new ProgressSpinnerHarnessFilters())等价。3.3 断言进度值getValueit(should get the value, async () { fixture.componentInstance.value.set(50); const [determinate, indeterminate, impliedIndeterminate] await loader.getAllHarnesses(MatProgressSpinnerHarness); expect(await determinate.getValue()).toBe(50); expect(await indeterminate.getValue()).toBe(null); expect(await impliedIndeterminate.getValue()).toBe(null); });该用例验证了 2.2 节的行为只有 determinate 模式返回数值此处通过 signalvalue设为 50两种 indeterminate 形态都返回null。3.4 断言模式getModeit(should get the mode, async () { const [determinate, indeterminate, impliedIndeterminate] await loader.getAllHarnesses(MatProgressSpinnerHarness); expect(await determinate.getMode()).toBe(determinate); expect(await indeterminate.getMode()).toBe(indeterminate); expect(await impliedIndeterminate.getMode()).toBe(indeterminate); });特别注意第三个断言mat-spinner未显式书写mode属性但组件构造函数将其初始化为indeterminate见 2.3 节因此 Harness 读到的是indeterminate而非undefined。这印证了 Harness 读取的是组件渲染后的宿主属性而非模板字面量。四、ARIA 语义getValue/getMode 的事实依据两个读取方法全部基于 ARIA 与宿主属性理解这一点有助于写出更稳健的断言组件宿主声明了roleprogressbar、aria-valuemin0、aria-valuemax100并在 determinate 时绑定aria-valuenowprogress-spinner.ts。官方组件文档progress-spinner.md提醒不要擅自改动aria-valuemin/aria-valuemax否则可能与部分辅助技术不兼容同时每个 spinner 都应通过aria-label或aria-labelledby提供可访问名称。由于 Harness 读取的是宿主属性而非组件实例字段只要 DOM 属性正确Harness 断言即成立——这正是 Harness 与测试DOM 解耦但不失真实性的设计哲学测试代码不依赖组件内部结构只依赖稳定的公开属性契约。五、与主包 API 的关系ProgressSpinnerMode 与默认选项getMode()的返回类型ProgressSpinnerMode由主包导出determinate | indeterminate见 progress-spinner.ts。若要完整理解 Harness 所测组件的行为还需知道主包暴露的配置面goldens/material/progress-spinner/index.api.md导出类型说明MatProgressSpinnerclass组件主体selector 为mat-progress-spinner, mat-spinnerMatProgressSpinnerModuleNgModule同时导出组件与BidiModuleMAT_PROGRESS_SPINNER_DEFAULT_OPTIONSInjectionToken全局默认选项providedIn: root默认diameter: 100MatProgressSpinnerDefaultOptionsinterfacecolor?、diameter?、strokeWidth?、_forceAnimations?MatSpinnerconst已废弃旧版类名别名mat-spinnerselector 本身不废弃ProgressSpinnerModetypedeterminate \| indeterminate默认尺寸常量定义在 progress-spinner.ts基准直径BASE_SIZE 100、基准描边宽BASE_STROKE_WIDTH 10strokeWidth未设置时取diameter / 10progress-spinner.ts。这些默认值会直接影响 SVG 的viewBox、周长与 dashoffset 计算_viewBox()、_strokeCircumference()、_strokeDashOffset()见 progress-spinner.ts进而在视觉上决定进度圈的进度表现——不过对 Harness 断言而言getValue()始终基于 ARIA 属性不受尺寸计算影响。六、在真实项目中的接入路径要在自己的 Angular 组件测试中使用 Progress Spinner Harness只需两步引入测试包import {MatProgressSpinnerHarness} from angular/material/progress-spinner/testing;对应仓库入口 testing/public-api.ts 的export *testing/index.ts 再次转发。通过 CDK 环境加载在 TestBed 中调用TestbedHarnessEnvironment.loader(fixture)获得HarnessLoader随后使用getAllHarnesses/getHarness获取实例再调用getValue()、getMode()完成断言。Harness 的完整测试用例可参阅 progress-spinner-harness.spec.ts它同时也是本项目 CI 对angular/material_progress-spinner_testing包行为的权威验证API 的冻结契约则以 testing/index.api.md 为准改动公共签名前应先同步更新该 golden 文件。小结MatProgressSpinnerHarness是angular/material_progress-spinner_testing包的唯一 Harness 类通过.mat-mdc-progress-spinner定位组件宿主。getValue()读取aria-valuenowdeterminate 返回 0100 的数值indeterminate 返回null。getMode()读取宿主mode属性mat-spinner别名会被组件归一化为indeterminate。ProgressSpinnerHarnessFilters目前仅继承BaseHarnessFilters是预留语义过滤能力的扩展点。所有断言基于 ARIA/宿主属性契约与组件内部 SVG 渲染实现解耦保证测试的稳定性与可维护性。如需深入组件本身的行为模式、默认选项、SVG 几何计算请继续阅读 progress-spinner.ts 与 progress-spinner.md。【免费下载链接】componentsComponent infrastructure and Material Design components for Angular项目地址: https://gitcode.com/GitHub_Trending/co/components创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
