如何为使用Material Stepper的Angular组件编写单元测试

问题根因 #

报错Cannot set properties of undefined (setting 'selectedIndex')的核心原因是测试执行流程中，通过@ViewChild('stepper')获取的MatStepper实例未完成初始化，代码尝试操作undefined对象的属性导致失败。

正确测试写法 #

1. 补全测试模块依赖 #

MatStepper 运行依赖动画模块，缺省会导致组件无法正常渲染，测试Bed配置阶段必须导入对应依赖：

beforeEach(async () => {
  await TestBed.configureTestingModule({
    declarations: [YourTargetComponent], // 替换为你的业务组件
    imports: [
      MatStepperModule,
      BrowserAnimationsModule, // 必选，MatStepper强制依赖
      // 如果stepper绑定了响应式表单/模板表单，补充对应模块
      ReactiveFormsModule,
      FormsModule
    ]
  }).compileComponents();
});

2. 把控变更检测时机 #

@ViewChild 引用的实例只有在组件视图完成渲染后才会被赋值，必须在第一次执行fixture.detectChanges()之后，再调用涉及stepper操作的业务方法：

• 如果stepper标签被*ngIf条件控制，需要先将*ngIf绑定的条件值设为true，再执行变更检测
• 不要在fixture.detectChanges()执行前调用任何操作stepper的组件方法

示例代码：

it('should modify stepper selectedIndex on step jump', () => {
  const fixture = TestBed.createComponent(YourTargetComponent);
  const component = fixture.componentInstance;

  // 错误写法：此时视图未渲染，component.stepper为undefined，调用方法直接报错
  // component.jumpToStep(2);

  // 正确流程：先执行变更检测完成视图初始化
  fixture.detectChanges();

  // 此时stepper实例已挂载，可以正常执行业务逻辑
  component.jumpToStep(2);
  expect(component.stepper.selectedIndex).toBe(2);
});

3. 轻量单元测试可选Mock方案 #

如果不需要测试Material Stepper本身的交互逻辑，只验证业务代码对selectedIndex的操作逻辑，可以直接手动注入mock的stepper实例，完全跳过组件渲染流程，隔离第三方依赖：

it('should update selectedIndex as expected with mock stepper', () => {
  const fixture = TestBed.createComponent(YourTargetComponent);
  const component = fixture.componentInstance;

  // 手动挂载mock stepper实例，不需要依赖真实组件渲染
  component.stepper = {
    selectedIndex: 0,
    next: jasmine.createSpy('next'),
    previous: jasmine.createSpy('previous')
  } as unknown as MatStepper;

  // 直接执行业务方法即可
  component.goToNextStep();
  expect(component.stepper.selectedIndex).toBe(1);
});

常见避坑点 #

• 不要在ngOnInit生命周期中操作stepper实例：@ViewChild的初始化时机是ngAfterViewInit，ngOnInit执行时stepper实例还未赋值，生产环境同样会触发报错，相关逻辑需要迁移到ngAfterViewInit中执行
• 如果stepper放在*ngIf、ng-template等动态渲染结构中，不要给@ViewChild设置static: true，该配置仅能获取非动态渲染的静态视图元素，动态元素会返回undefined

内容的提问来源于stack exchange，提问作者user3497702