Vue3+NaiveUI组件点击切换渲染的测试问题排查

问题场景 #

使用Vue 3、NaiveUI、Vitest + Vue Testing Library开发时，遇到组件点击切换及条件渲染的测试阻塞：组件用NaiveUI的n-button实现点击切换文本，但测试中点击后状态不更新；替换为原生button测试正常，但业务组件无法修改。

组件TSample代码 #

<template>
  <n-button role="test" @click="show = !show" text size="large" type="primary">
    <div data-testid="visible" v-if="show">visible</div>
    <div data-testid="hidden" v-else>hidden</div>
  </n-button>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
import { NButton } from 'naive-ui'

export default defineComponent({
  name: 'TSample',

  components: {
    NButton
  },

  setup() {
    const show = ref(true)
    return {
      show
    }
  }
})
</script>

测试用例代码 #

import { render, waitFor } from '@testing-library/vue'
import TSample from './TSample.vue'
import userEvent from '@testing-library/user-event'

describe('Tests TSample component', () => {
  it('toggles between visible and hidden text inside the button', async () => {
    const user = userEvent.setup()
    const { getByText, queryByText, getByRole } = render(TSample)

    expect(getByRole('test')).toBeInTheDocument()
    expect(getByText(/visible/i)).toBeInTheDocument()
    expect(queryByText('hidden')).not.toBeInTheDocument()

    await user.click(getByRole('test'))
    await waitFor(() => expect(queryByText(/hidden/i)).toBeInTheDocument()) // 测试失败
  })
})

错误信息 #

<transition-stub />
        <span
          class="n-button__content"
        >
          <div
            data-testid="visible"
          >
            visible
          </div>
        </span>
      </button>
    </div>
  </body>
</html>...Error: expect(received).toBeInTheDocument()

received value must be an HTMLElement or an SVGElement.

问题原因 #

1. NaiveUI组件的事件封装：n-button作为封装组件，其外层自定义元素并非实际触发点击事件的原生DOM节点，直接点击自定义role="test"的元素，事件无法正确传递到组件绑定的@click回调。
2. Testing Library的交互逻辑：userEvent.click需要作用于原生可交互DOM元素（如<button>），否则无法模拟真实用户的点击行为触发组件内部状态更新。

解决方案 #

方法1：定位原生按钮元素 #

n-button最终会渲染为原生<button>标签，直接通过getByRole('button')获取实际可交互的DOM元素：

it('toggles between visible and hidden text inside the button', async () => {
  const user = userEvent.setup()
  const { getByText, queryByText, getByRole } = render(TSample)

  expect(getByText(/visible/i)).toBeInTheDocument()
  expect(queryByText('hidden')).not.toBeInTheDocument()

  // 点击原生button元素
  await user.click(getByRole('button'))
  await waitFor(() => {
    expect(queryByText(/hidden/i)).toBeInTheDocument()
    expect(queryByText(/visible/i)).not.toBeInTheDocument()
  })
})

方法2：给按钮添加data-testid标记 #

给n-button添加专属测试标记，确保定位到正确的组件容器：

组件修改（仅添加data-testid）

<n-button data-testid="toggle-btn" role="test" @click="show = !show" text size="large" type="primary">
  <div data-testid="visible" v-if="show">visible</div>
  <div data-testid="hidden" v-else>hidden</div>
</n-button>

测试代码调整

it('toggles between visible and hidden text inside the button', async () => {
  const user = userEvent.setup()
  const { getByText, queryByText, getByTestId } = render(TSample)

  expect(getByText(/visible/i)).toBeInTheDocument()
  expect(queryByText('hidden')).not.toBeInTheDocument()

  await user.click(getByTestId('toggle-btn'))
  await waitFor(() => {
    expect(queryByText(/hidden/i)).toBeInTheDocument()
    expect(queryByText(/visible/i)).not.toBeInTheDocument()
  })
})

方法3：直接触发组件事件（备选方案） #

若上述方法无法生效，可直接触发组件的click事件（不推荐，违背Testing Library模拟真实用户行为的原则）：

it('toggles between visible and hidden text inside the button', async () => {
  const { getByText, queryByText, getByRole } = render(TSample)
  const buttonComp = getByRole('test')

  expect(getByText(/visible/i)).toBeInTheDocument()
  expect(queryByText('hidden')).not.toBeInTheDocument()

  // 直接触发组件的click事件
  buttonComp.$emit('click')
  await waitFor(() => {
    expect(queryByText(/hidden/i)).toBeInTheDocument()
  })
})

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