Visitar URL original
feat!: `toHaveTextContent` is strict, add `toMatchTextContent` as alt… · vitest-dev/vitest@18f3030 · GitHub
Skip to content

Commit 18f3030

Browse files
sheremet-vasheremet-va
authored
feat!: toHaveTextContent is strict, add toMatchTextContent as alternative (#10473)
1 parent d0b4fdd commit 18f3030

10 files changed

Lines changed: 284 additions & 58 deletions

File tree

‎docs/api/browser/assertions.md‎

Lines changed: 35 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ test('error banner is rendered', async () => {
3434
// It will repeatedly check that the element exists in the DOM and that
3535
// the content of `element.textContent` is equal to "Error!"
3636
// until all the conditions are met
37-
await expect.element(banner).toHaveTextContent('Error!')
37+
await expect.element(banner).toMatchTextContent('Error!')
3838
})
3939
```
4040

@@ -56,11 +56,11 @@ interface ExpectPollOptions {
5656
::: tip
5757
Like [`expect.poll`](/api/expect#poll), `expect.element` retries DOM assertions until they pass or the timeout is reached. When it receives a locator, Vitest resolves it with [`locator.findElement()`](/api/browser/locators#findelement) before running the DOM assertion. The `timeout` option applies to the whole retry operation. The `interval` option controls how often failed DOM assertions are retried, but locator resolution uses `findElement`'s own increasing retry intervals.
5858

59-
`toHaveTextContent` and all other assertions are still available on a regular `expect` without a built-in retry-ability mechanism:
59+
`toMatchTextContent` and all other assertions are still available on a regular `expect` without a built-in retry-ability mechanism:
6060

6161
```ts
6262
// will fail immediately if .textContent is not `'Error!'`
63-
expect(banner).toHaveTextContent('Error!')
63+
expect(banner).toMatchTextContent('Error!')
6464
```
6565
:::
6666

@@ -738,12 +738,37 @@ The usual rules of css precedence apply.
738738

739739
```ts
740740
function toHaveTextContent(
741-
text: string | RegExp,
741+
text: string | number,
742742
options?: { normalizeWhitespace: boolean }
743743
): Promise<void>
744744
```
745745

746-
This allows you to check whether the given node has a text content or not. This
746+
This matcher allows you to validate that an element's text matches provided string exactly. This
747+
supports elements, but also text nodes and fragments.
748+
749+
If you wish to perform a partial check or do a case-sensitive match, use [`toMatchTextContent`](#tomatchtextcontent) instead.
750+
751+
```html
752+
<span data-testid="text-content">Text Content</span>
753+
```
754+
755+
```ts
756+
const element = getByTestId('text-content')
757+
758+
await expect.element(element).toHaveTextContent('Text Content')
759+
await expect.element(element).not.toHaveTextContent('Content')
760+
```
761+
762+
## toMatchTextContent
763+
764+
```ts
765+
function toMatchTextContent(
766+
text: string | number | RegExp,
767+
options?: { normalizeWhitespace: boolean }
768+
): Promise<void>
769+
```
770+
771+
This matcher allows you to check whether the given node has a text content or not. This
747772
supports elements, but also text nodes and fragments.
748773

749774
When a `string` argument is passed through, it will perform a partial
@@ -752,7 +777,7 @@ case-sensitive match to the node content.
752777
To perform a case-insensitive match, you can use a `RegExp` with the `/i`
753778
modifier.
754779

755-
If you want to match the whole content, you can use a `RegExp` to do it.
780+
If you want to match the whole content, you can use a `RegExp` to do it or [`toHaveTextContent`](#tohavetextcontent) matcher instead.
756781

757782
```html
758783
<span data-testid="text-content">Text Content</span>
@@ -761,12 +786,12 @@ If you want to match the whole content, you can use a `RegExp` to do it.
761786
```ts
762787
const element = getByTestId('text-content')
763788

764-
await expect.element(element).toHaveTextContent('Content')
789+
await expect.element(element).toMatchTextContent('Content')
765790
// to match the whole content
766-
await expect.element(element).toHaveTextContent(/^Text Content$/)
791+
await expect.element(element).toMatchTextContent(/^Text Content$/)
767792
// to use case-insensitive match
768-
await expect.element(element).toHaveTextContent(/content$/i)
769-
await expect.element(element).not.toHaveTextContent('content')
793+
await expect.element(element).toMatchTextContent(/content$/i)
794+
await expect.element(element).not.toMatchTextContent('content')
770795
```
771796

772797
## toHaveValue

‎docs/guide/migration.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,21 @@ Several entry points were marked as deprecated in Vitest 4.1. This release remov
110110
- `vitest/mocker` is removed completely, use `@vitest/mocker` package directly (this was published by accident at one point and never removed)
111111
- `vitest/internal/module-runner` is removed
112112

113+
### `toHaveTextContent` Now Performs Strict Equality
114+
115+
The browser-mode [`toHaveTextContent`](/api/browser/assertions#tohavetextcontent) matcher now validates that an element's text content is exactly equal to the expected string instead of performing a partial, case-sensitive match. Regular expressions are no longer accepted. The previous behaviour, including `RegExp` support, has moved to the new [`toMatchTextContent`](/api/browser/assertions#tomatchtextcontent) matcher.
116+
117+
```ts
118+
// Partial or regex matches:
119+
await expect.element(banner).toHaveTextContent('Error') // [!code --]
120+
await expect.element(banner).toHaveTextContent(/error/i) // [!code --]
121+
await expect.element(banner).toMatchTextContent('Error') // [!code ++]
122+
await expect.element(banner).toMatchTextContent(/error/i) // [!code ++]
123+
124+
// Exact matches stay on `toHaveTextContent`:
125+
await expect.element(banner).toHaveTextContent('Error!')
126+
```
127+
113128
## Migrating to Vitest 4.0 {#vitest-4}
114129

115130
::: warning Prerequisites

‎examples/lit/test/basic.test.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,13 @@ describe('Button with increment', async () => {
1414
it('should increment the count on each click', async () => {
1515
await page.getByRole('button').click()
1616

17-
await expect.element(page.getByRole('button')).toHaveTextContent('2')
17+
await expect.element(page.getByRole('button')).toMatchTextContent('2')
1818
if (import.meta.env.VITE_FAIL_TEST) {
19-
await expect.element(page.getByRole('button'), { timeout: 3000 }).toHaveTextContent('3')
19+
await expect.element(page.getByRole('button'), { timeout: 3000 }).toMatchTextContent('3')
2020
}
2121
})
2222

2323
it('should show name props', async () => {
24-
await expect.element(page.getByRole('heading')).toHaveTextContent('World')
24+
await expect.element(page.getByRole('heading')).toMatchTextContent('World')
2525
})
2626
})

‎packages/browser/jest-dom.d.ts‎

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -377,6 +377,25 @@ export interface TestingLibraryMatchers<E, R> {
377377
* @see https://vitest.dev/api/browser/assertions#tohavestyle
378378
*/
379379
toHaveStyle(css: string | Partial<CSSStyleDeclaration>): R
380+
/**
381+
* @description
382+
* Validate that the given element's text content matches the provided string exactly.
383+
*
384+
* Supports elements, but also text nodes and fragments.
385+
*
386+
* If you wish to perform a partial check or use a RegExp, use `toMatchTextContent` instead.
387+
* @example
388+
* <span data-testid="text-content">Text Content</span>
389+
*
390+
* const element = page.getByTestId('text-content')
391+
* await expect.element(element).toHaveTextContent('Text Content')
392+
* await expect.element(element).not.toHaveTextContent('Content')
393+
* @see https://vitest.dev/api/browser/assertions#tohavetextcontent
394+
*/
395+
toHaveTextContent(
396+
text: string | number,
397+
options?: {normalizeWhitespace: boolean},
398+
): R
380399
/**
381400
* @description
382401
* Check whether the given element has a text content or not.
@@ -391,15 +410,15 @@ export interface TestingLibraryMatchers<E, R> {
391410
* <span data-testid="text-content">Text Content</span>
392411
*
393412
* const element = page.getByTestId('text-content')
394-
* await expect.element(element).toHaveTextContent('Content')
413+
* await expect.element(element).toMatchTextContent('Content')
395414
* // to match the whole content
396-
* await expect.element(element).toHaveTextContent(/^Text Content$/)
415+
* await expect.element(element).toMatchTextContent(/^Text Content$/)
397416
* // to use case-insensitive match
398-
* await expect.element(element).toHaveTextContent(/content$/i)
399-
* await expect.element(element).not.toHaveTextContent('content')
400-
* @see https://vitest.dev/api/browser/assertions#tohavetextcontent
417+
* await expect.element(element).toMatchTextContent(/content$/i)
418+
* await expect.element(element).not.toMatchTextContent('content')
419+
* @see https://vitest.dev/api/browser/assertions#tomatchtextcontent
401420
*/
402-
toHaveTextContent(
421+
toMatchTextContent(
403422
text: string | number | RegExp,
404423
options?: {normalizeWhitespace: boolean},
405424
): R

‎packages/browser/src/client/tester/expect/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ import toHaveStyle from './toHaveStyle'
2424
import toHaveTextContent from './toHaveTextContent'
2525
import toHaveValue from './toHaveValue'
2626
import toMatchScreenshot from './toMatchScreenshot'
27+
import toMatchTextContent from './toMatchTextContent'
2728

2829
export const matchers: MatchersObject = {
2930
toBeDisabled,
@@ -46,6 +47,7 @@ export const matchers: MatchersObject = {
4647
toHaveFormValues,
4748
toHaveStyle,
4849
toHaveTextContent,
50+
toMatchTextContent,
4951
toHaveValue,
5052
toHaveDisplayValue,
5153
toBeChecked,

‎packages/browser/src/client/tester/expect/toHaveTextContent.ts‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,12 @@
1515

1616
import type { MatcherResult, MatcherState } from 'vitest'
1717
import type { Locator } from '../locators'
18-
import { getMessage, getNodeFromUserInput, matches, normalize } from './utils'
18+
import { getMessage, getNodeFromUserInput, normalize } from './utils'
1919

2020
export default function toHaveTextContent(
2121
this: MatcherState,
2222
actual: Element | Locator,
23-
matcher: string | RegExp,
23+
matcher: string | number,
2424
options: { normalizeWhitespace?: boolean } = { normalizeWhitespace: true },
2525
): MatcherResult {
2626
const node = getNodeFromUserInput(actual, toHaveTextContent, this)
@@ -29,10 +29,10 @@ export default function toHaveTextContent(
2929
? normalize(node.textContent || '')
3030
: (node.textContent || '').replace(/\u00A0/g, ' ') // Replace &nbsp; with normal spaces
3131

32-
const checkingWithEmptyString = textContent !== '' && matcher === ''
32+
const expectedText = String(matcher)
3333

3434
return {
35-
pass: !checkingWithEmptyString && matches(textContent, matcher),
35+
pass: textContent === expectedText,
3636
message: () => {
3737
const to = this.isNot ? 'not to' : 'to'
3838
return getMessage(
@@ -42,10 +42,8 @@ export default function toHaveTextContent(
4242
'element',
4343
'',
4444
),
45-
checkingWithEmptyString
46-
? `Checking with empty string will always match, use .toBeEmptyDOMElement() instead`
47-
: `Expected element ${to} have text content`,
48-
matcher,
45+
`Expected element ${to} have text content`,
46+
expectedText,
4947
'Received',
5048
textContent,
5149
)

‎packages/browser/src/client/tester/expect/toMatchTextContent.ts‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
/**
2+
* The MIT License (MIT)
3+
* Copyright (c) 2017 Kent C. Dodds
4+
*
5+
* Permission is hereby granted, free of charge, to any person obtaining a copy
6+
* of this software and associated documentation files (the "Software"), to deal
7+
* in the Software without restriction, including without limitation the rights
8+
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
* copies of the Software, and to permit persons to whom the Software is
10+
* furnished to do so, subject to the following conditions:
11+
*
12+
* The above copyright notice and this permission notice shall be included in all
13+
* copies or substantial portions of the Software.
14+
*/
15+
16+
import type { MatcherResult, MatcherState } from 'vitest'
17+
import type { Locator } from '../locators'
18+
import { getMessage, getNodeFromUserInput, matches, normalize } from './utils'
19+
20+
export default function toMatchTextContent(
21+
this: MatcherState,
22+
actual: Element | Locator,
23+
matcher: string | RegExp,
24+
options: { normalizeWhitespace?: boolean } = { normalizeWhitespace: true },
25+
): MatcherResult {
26+
const node = getNodeFromUserInput(actual, toMatchTextContent, this)
27+
28+
const textContent = options.normalizeWhitespace
29+
? normalize(node.textContent || '')
30+
: (node.textContent || '').replace(/\u00A0/g, ' ') // Replace &nbsp; with normal spaces
31+
32+
const checkingWithEmptyString = textContent !== '' && matcher === ''
33+
34+
return {
35+
pass: !checkingWithEmptyString && matches(textContent, matcher),
36+
message: () => {
37+
const to = this.isNot ? 'not to' : 'to'
38+
return getMessage(
39+
this,
40+
this.utils.matcherHint(
41+
`${this.isNot ? '.not' : ''}.toMatchTextContent`,
42+
'element',
43+
'',
44+
),
45+
checkingWithEmptyString
46+
? `Checking with empty string will always match, use .toBeEmptyDOMElement() instead`
47+
: `Expected element ${to} match text content`,
48+
matcher,
49+
'Received',
50+
textContent,
51+
)
52+
},
53+
}
54+
}

0 commit comments

Comments
 (0)