使用@web/test-runner测试Lit Element时Web组件未注册实例化失败

核心根因：测试环境未执行自定义元素注册逻辑，浏览器无法识别<my-custom-component>标签，fixture插入的仅为未知类型普通HTML节点，不会触发Lit组件生命周期，也不会挂载组件类定义的实例属性。

排查修复步骤 #

1. 补全组件注册逻辑的导入 #

• Lit组件必须通过customElements.define('标签名', 组件类)完成注册后，浏览器才能识别对应自定义标签。先检查组件文件内是否包含这段注册代码：

// 写法1：使用Lit提供的装饰器（本质是语法糖）
@customElement('my-custom-component')
export class CustomComponent extends LitElement { /* 组件逻辑 */ }

// 写法2：手动调用注册API
customElements.define('my-custom-component', CustomComponent);

• 如果注册逻辑统一抽离在入口文件维护，必须在测试文件顶部显式导入该入口文件，保证注册代码在fixture执行前完成加载。仅导入组件类本身不会触发注册逻辑。

常见踩坑点：很多开发者会误以为导入组件类就会自动完成注册，实际上如果组件文件的注册逻辑因为tree-shaking、导入路径错误没被执行，就会出现元素不识别的问题。

2. 增加实例类型校验，避免TS类型欺骗 #

• 现有代码里的泛型写法fixture<CustomComponent>仅为TypeScript层面的类型标注，不会做实际的实例转换。当组件未注册时，fixture返回的是普通HTMLElement，访问类上定义的customData属性必然返回undefined。
• 修复注册逻辑后，在beforeEach里增加实例校验，提前暴露注册失败问题：

beforeEach(async () => {
  const el = await fixture(html`<my-custom-component></my-custom-component>`);
  if (!(el instanceof CustomComponent)) {
    throw new Error('自定义元素未注册，无法获取组件实例');
  }
  component = el;
});

3. 修正WTR与TS编译配置 #

• 现有web-test-runner配置里的esbuild插件缺少target配置，补充target: 'auto'，让esbuild根据测试运行的浏览器环境自动适配编译语法，避免装饰器、类字段等语法兼容问题导致组件类加载失败：

// web-test-runner.config.mjs
import { esbuildPlugin } from '@web/dev-server-esbuild';
import { fileURLToPath } from 'url';

export default {
  files: ['src/**/*.test.ts'],
  nodeResolve: true,
  plugins: [
    esbuildPlugin({
      ts: true,
      target: 'auto',
      tsconfig: fileURLToPath(new URL('./tsconfig.json', import.meta.url))
    })
  ]
};

• 核对tsconfig.json配置，确保开启experimentalDecorators: true，useDefineForClassFields配置与Lit官方要求匹配，避免TS编译后类字段默认值初始化逻辑失效。

4. 修正断言逻辑 #

• 原测试用例用to.equal做对象断言属于引用相等判断，即使组件正常初始化了空对象，也会因为和测试代码里新建的{}引用不一致报错，建议改为深度相等判断：

it('should set the default data', () => {
  expect(component.customData).to.deep.equal({});
});

验证标准 #

修复后重新执行wtr命令，若控制台能正常输出你在组件构造函数、生命周期钩子中添加的日志，说明组件实例化流程正常，原属性undefined问题会同步解决。

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