如何在Vite中配置@testing-library/react的全局testIdAttribute？

问题背景 #

项目从Jest迁移至Vite+Vitest后，无法使@testing-library/react的全局testIdAttribute配置生效。此前在Jest环境中，我们通过setupFile.ts成功覆盖默认配置，代码如下：

// setupFile.ts（Jest环境）
import '@testing-library/jest-dom'
import '@testing-library/jest-dom/extend-expect'
import { configure } from '@testing-library/dom'

// 覆盖默认的data-testid，与Cypress测试保持一致
configure({
  testIdAttribute: 'data-test-id'
})

当前Vite环境的配置文件如下：

vite-config.ts #

import { configDefaults, defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    environment: 'jsdom',
    css: true,
    setupFiles: ['./tests/vite-setup.ts'],
    includeSource: ['src/**/*.{js,ts}'],
    exclude: [...configDefaults.exclude]
  }
})

vite-setup.ts #

import { afterEach, beforeEach, expect, vi } from 'vitest'
import { cleanup, configure } from '@testing-library/react'
import matchers from '@testing-library/jest-dom/matchers'

expect.extend(matchers)

// 此处配置不生效
configure({
  testIdAttribute: 'data-test-id'
})

afterEach(() => {
  cleanup()
})

beforeEach(() => {
  // 其他前置逻辑
})

尝试在单个测试用例中调用configure函数，同样无法生效。

解决方法 #

1. 切换configure的导入来源 #

将@testing-library/react的configure替换为@testing-library/dom的configure，修改后的vite-setup.ts如下：

import { afterEach, beforeEach, expect, vi } from 'vitest'
import { cleanup } from '@testing-library/react'
import { configure } from '@testing-library/dom' // 改为导入dom库的configure
import matchers from '@testing-library/jest-dom/matchers'

expect.extend(matchers)

// 全局配置testIdAttribute
configure({
  testIdAttribute: 'data-test-id'
})

afterEach(() => {
  cleanup()
})

beforeEach(() => {
  // 其他前置逻辑
})

2. 验证setup文件是否被正确加载 #

可以在vite-setup.ts中添加一行日志，确认Vitest是否正确执行了该文件：

console.log('Vite setup file loaded')

运行测试时如果控制台输出该日志，说明路径配置正确；若未输出，检查vite-config.ts中setupFiles的路径是否与实际文件位置匹配。

原理说明 #

@testing-library/react的configure方法本质上是对@testing-library/dom配置的封装，但在Vitest环境下，直接导入并调用@testing-library/dom的configure能确保配置全局生效，避免封装层可能存在的加载时序或作用域问题。

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