断言 API

Vitest 内置集成了 @testing-library/jest-dom 库，开箱即用提供了丰富的 DOM 断言。有关这些断言的详细文档，请参阅 jest-dom 的 README：

• toBeDisabled
• toBeEnabled
• toBeEmptyDOMElement
• toBeInTheDocument
• toBeInvalid
• toBeRequired
• toBeValid
• toBeVisible
• toContainElement
• toContainHTML
• toHaveAccessibleDescription
• toHaveAccessibleErrorMessage
• toHaveAccessibleName
• toHaveAttribute
• toHaveClass
• toHaveFocus
• toHaveFormValues
• toHaveStyle
• toHaveTextContent
• toHaveValue
• toHaveDisplayValue
• toBeChecked
• toBePartiallyChecked
• toHaveRole
• toHaveErrorMessage

如果您使用 TypeScript 并希望在 expect 中获得正确的类型提示，请根据您使用的提供者，确保在您的 tsconfig 中指定 @vitest/browser/providers/playwright 或 @vitest/browser/providers/webdriverio。如果您使用默认的 preview 提供者，则可以指定 @vitest/browser/matchers。

preview

{
  "compilerOptions": {
    "types": ["@vitest/browser/matchers"]
  }
}

playwright

{
  "compilerOptions": {
    "types": ["@vitest/browser/providers/playwright"]
  }
}

webdriverio

{
  "compilerOptions": {
    "types": ["@vitest/browser/providers/webdriverio"]
  }
}

由于浏览器中的测试可能涉及异步操作，这可能导致测试结果不稳定。因此，即使存在延迟（例如，由于超时、网络请求或动画），也需要一种方法来确保断言能够通过。为此，Vitest 通过 expect.poll 和 expect.element API 开箱即用提供了可重试的断言：

import { expect, test } from 'vitest';
import { page } from '@vitest/browser/context';

test('error banner is rendered', async () => {
  triggerError();

  // @testing-library 提供了具有内置重试能力的查询方法
  // 它会尝试查找 banner 直到它被渲染
  const banner = page.getByRole('alert', {
    name: /error/i,
  });

  // Vitest 提供了具有内置重试能力的 `expect.element`
  // 它会检查 `element.textContent` 直到它等于 "Error!"
  await expect.element(banner).toHaveTextContent('Error!');
});

TIP

expect.element 是 expect.poll(() => element) 的简写，二者的工作方式完全相同。

toHaveTextContent 和所有其他 @testing-library/jest-dom 断言仍然可以在常规的 expect 上使用，但它们不具备内置的重试机制：

// 如果 .textContent 不等于 'Error!'，则会立即失败
expect(banner).toHaveTextContent('Error!');