如何使用React Testing Library mock Stencil Web组件解决测试事件不生效问题

核心问题根源 #

Stencil 生成的 Web Component 抛出的是原生 CustomEvent 类型的自定义事件，React 测试环境下有两个常见的触发失败原因：

1. React Testing Library 提供的 fireEvent.click 只会触发原生 click 事件，不会自动触发 Stencil 组件内部自定义派发的 stencilClick 事件
2. 自定义事件如果需要穿过 Shadow DOM 边界，必须携带 composed: true 属性，否则 React 层无法捕获到该事件

方案1：不 mock 组件，手动派发自定义事件（最推荐，最贴近真实运行逻辑） #

直接找到对应的 Stencil 组件 DOM 节点，手动派发它要触发的自定义事件即可，示例代码如下：

// 业务组件示例
import { useState } from 'react';

function Counter() {
  const [count, setCount] = useState(0);
  return (
    <div>
      <p>当前计数：{count}</p>
      <stencil-button onStencilClick={() => setCount(prev => prev + 1)}>
        计数+1
      </stencil-button>
    </div>
  )
}

// 测试用例代码
import { render, screen, fireEvent } from '@testing-library/react';

test('点击按钮后计数正常更新', () => {
  render(<Counter />);
  const stencilBtn = screen.getByRole('button', { name: /计数\+1/ });

  // 手动派发 Stencil 组件的自定义事件
  fireEvent(
    stencilBtn,
    new CustomEvent('stencilClick', {
      bubbles: true,
      cancelable: true,
      composed: true // *必须开启，允许事件穿过 Shadow DOM*
    })
  );

  expect(screen.getByText('当前计数：1')).toBeInTheDocument();
});

如果你的自定义事件需要传递 detail 参数，直接在 CustomEvent 第二个参数中添加 detail 字段即可。

方案2：mock 整个 Stencil 组件，适配 React 事件绑定 #

如果需要批量处理大量 Stencil 组件的测试，也可以直接 mock 组件，把自定义事件绑定到原生事件上，示例 mock 代码：

// 在测试文件顶部加入 mock 逻辑
jest.mock('你的Stencil组件库引入路径', () => ({
  StencilButton: (props) => {
    // 把传入的 onStencilClick 绑定到原生 button 的 onClick 事件
    return <button onClick={props.onStencilClick}>{props.children}</button>
  }
}));

mock 完成后，直接用 fireEvent.click 触发点击即可触发 onStencilClick 回调。

注意事项 #

不要使用 userEvent.click 来触发这类自定义事件，userEvent 模拟的是真实用户交互行为，只会触发浏览器原生事件，无法触发 Stencil 组件内部自定义派发的事件。

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