Jest测试隐藏元素报错：toBeVisible/toHaveStyle不是函数

问题背景 #

通过CSS设置按钮隐藏：

button {
    display: none
}

编写Jest测试验证元素隐藏状态时，使用toBeVisible或toHaveStyle匹配器均报错：TypeError: expect(...).not.toBeVisible is not a function，测试代码示例：

// 测试代码1
it('should not show empty button', async () => {
    const { container } = renderComponent();

    await waitFor(() => {
        expect(container.querySelector('button')).not.toBeVisible();
    });
});

// 测试代码2
expect(container.querySelector('.ag-floating-filter-button-button')).toHaveStyle('display: none')

问题原因 #

toBeVisible和toHaveStyle并非Jest核心自带的匹配器，它们属于@testing-library/jest-dom扩展库提供的增强匹配器，未安装或未引入该库时就会出现上述报错。

解决步骤 #

1. 安装扩展库
   在项目中安装@testing-library/jest-dom作为开发依赖：

   npm install --save-dev @testing-library/jest-dom
   

2. 引入扩展库
   有两种引入方式：

   • 单文件引入：在需要使用这些匹配器的测试文件顶部添加导入语句：

     import '@testing-library/jest-dom';
     

   • 全局引入：创建Jest配置文件（如jest.setup.js），在文件中添加导入语句，然后在jest.config.js中配置全局生效：

     // jest.setup.js
     import '@testing-library/jest-dom';
     
     // jest.config.js
     module.exports = {
       setupFilesAfterEnv: ['./jest.setup.js'],
     };
     

3. 优化测试代码（可选）
   如果你使用React Testing Library，推荐使用库提供的查询方法（如queryByRole）替代原生querySelector，代码更简洁且符合测试最佳实践：

   it('should not show empty button', async () => {
     const { queryByRole } = renderComponent();
     await waitFor(() => {
       // 验证元素不可见
       expect(queryByRole('button')).not.toBeVisible();
       // 若元素完全不在DOM中，可使用
       // expect(queryByRole('button')).not.toBeInTheDocument();
     });
   });
   

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