Skip to content

docs: allow all elements #683

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions docs/dom-testing-library/api-async.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ All the async utils are built on top of `waitFor`.
function waitFor<T>(
callback: () => T | Promise<T>,
options?: {
container?: HTMLElement
container?: Element
timeout?: number
interval?: number
onTimeout?: (error: Error) => Error
Expand Down Expand Up @@ -70,7 +70,7 @@ changes. When any of those changes occur, it will re-run the callback.
function waitForElementToBeRemoved<T>(
callback: (() => T) | T,
options?: {
container?: HTMLElement
container?: Element
timeout?: number
interval?: number
onTimeout?: (error: Error) => Error
Expand Down Expand Up @@ -106,14 +106,14 @@ el.parentElement.removeChild(el)
or an empty array:

```javascript
waitForElementToBeRemoved(null).catch(err => console.log(err))
waitForElementToBeRemoved(queryByText(/not here/i)).catch(err =>
waitForElementToBeRemoved(null).catch((err) => console.log(err))
waitForElementToBeRemoved(queryByText(/not here/i)).catch((err) =>
console.log(err)
)
waitForElementToBeRemoved(queryAllByText(/not here/i)).catch(err =>
waitForElementToBeRemoved(queryAllByText(/not here/i)).catch((err) =>
console.log(err)
)
waitForElementToBeRemoved(() => getByText(/not here/i)).catch(err =>
waitForElementToBeRemoved(() => getByText(/not here/i)).catch((err) =>
console.log(err)
)

Expand All @@ -128,7 +128,7 @@ The options object is forwarded to `waitFor`.
function wait<T>(
callback: () => void,
options?: {
container?: HTMLElement
container?: Element
timeout?: number
interval?: number
mutationObserverOptions?: MutationObserverInit
Expand All @@ -148,7 +148,7 @@ practice to use an empty callback because it will make the tests more fragile.

```typescript
function waitForDomChange<T>(options?: {
container?: HTMLElement
container?: Element
timeout?: number
mutationObserverOptions?: MutationObserverInit
}): Promise<T>
Expand All @@ -165,7 +165,7 @@ changed:
const container = document.createElement('div')
waitForDomChange({ container })
.then(() => console.log('DOM changed!'))
.catch(err => console.log(`Error you need to deal with: ${err}`))
.catch((err) => console.log(`Error you need to deal with: ${err}`))
container.append(document.createElement('p'))
// if 👆 was the only code affecting the container and it was not run,
// waitForDomChange would throw an error
Expand All @@ -179,7 +179,7 @@ container
```javascript
const container = document.createElement('div')
container.setAttribute('data-cool', 'true')
waitForDomChange({ container }).then(mutationsList => {
waitForDomChange({ container }).then((mutationsList) => {
const mutation = mutationsList[0]
console.log(
`was cool: ${mutation.oldValue}\ncurrently cool: ${mutation.target.dataset.cool}`
Expand Down Expand Up @@ -211,7 +211,7 @@ changes.
function waitForElement<T>(
callback: () => T,
options?: {
container?: HTMLElement
container?: Element
timeout?: number
mutationObserverOptions?: MutationObserverInit
}
Expand Down
34 changes: 17 additions & 17 deletions docs/dom-testing-library/api-events.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@ id: api-events
title: Firing Events
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'

> Most projects have a few use cases for `fireEvent`, but the majority of the
> time you should probably use
Expand All @@ -13,7 +13,7 @@ import TabItem from '@theme/TabItem';
## `fireEvent`

```typescript
fireEvent(node: HTMLElement, event: Event)
fireEvent(node: Element, event: Event)
```

Fire DOM events.
Expand All @@ -32,7 +32,7 @@ fireEvent(
## `fireEvent[eventName]`

```typescript
fireEvent[eventName](node: HTMLElement, eventProperties: Object)
fireEvent[eventName](node: Element, eventProperties: Object)
```

Convenience methods for firing DOM events. Check out
Expand Down Expand Up @@ -107,7 +107,7 @@ You can find out which key code to use at
## `createEvent[eventName]`

```typescript
createEvent[eventName](node: HTMLElement, eventProperties: Object)
createEvent[eventName](node: Element, eventProperties: Object)
```

Convenience methods for creating DOM events that can then be fired by
Expand Down Expand Up @@ -149,20 +149,20 @@ bound callback.
}>
<TabItem value="react">

```jsx
import { render, screen, fireEvent } from '@testing-library/react'
```jsx
import { render, screen, fireEvent } from '@testing-library/react'

const Button = ({ onClick, children }) => (
<button onClick={onClick}>{children}</button>
)
const Button = ({ onClick, children }) => (
<button onClick={onClick}>{children}</button>
)

test('calls onClick prop when clicked', () => {
const handleClick = jest.fn()
render(<Button onClick={handleClick}>Click Me</Button>)
fireEvent.click(screen.getByText(/click me/i))
expect(handleClick).toHaveBeenCalledTimes(1)
})
```
test('calls onClick prop when clicked', () => {
const handleClick = jest.fn()
render(<Button onClick={handleClick}>Click Me</Button>)
fireEvent.click(screen.getByText(/click me/i))
expect(handleClick).toHaveBeenCalledTimes(1)
})
```

</TabItem>
</Tabs>
47 changes: 21 additions & 26 deletions docs/dom-testing-library/api-helpers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@ id: api-helpers
title: Helpers
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'

## Custom Queries

Expand Down Expand Up @@ -68,8 +68,7 @@ module.exports = {
The `buildQueries` helper allows you to create custom queries with all standard
[variants](api-queries.mdx) of queries in testing-library.

See the
[Add custom queries](react-testing-library/setup.mdx#add-custom-queries)
See the [Add custom queries](react-testing-library/setup.mdx#add-custom-queries)
section of the custom render guide for example usage.

### Using other assertion libraries
Expand All @@ -87,7 +86,7 @@ and add it here!
## `getNodeText`

```typescript
getNodeText(node: HTMLElement)
getNodeText(node: Element)
```

Returns the complete text content of an HTML element, removing any extra
Expand Down Expand Up @@ -138,32 +137,32 @@ could do:
}>
<TabItem value="native">

```js
import { within } from '@testing-library/dom'
```js
import { within } from '@testing-library/dom'

const { getByText } = within(document.getElementById('messages'))
const helloMessage = getByText('hello')
```
const { getByText } = within(document.getElementById('messages'))
const helloMessage = getByText('hello')
```

</TabItem>
<TabItem value="react">

```jsx
import { render, within } from '@testing-library/react'
```jsx
import { render, within } from '@testing-library/react'

const { getByLabelText } = render(<MyComponent />)
const signinModal = getByLabelText('Sign In')
within(signinModal).getByPlaceholderText('Username')
```
const { getByLabelText } = render(<MyComponent />)
const signinModal = getByLabelText('Sign In')
within(signinModal).getByPlaceholderText('Username')
```

</TabItem>
<TabItem value="cypress">

```js
cy.get('form').within(() => {
cy.findByText('Button Text').should('be.disabled')
})
```
```js
cy.get('form').within(() => {
cy.findByText('Button Text').should('be.disabled')
})
```

</TabItem>
</Tabs>
Expand Down Expand Up @@ -258,11 +257,7 @@ tree of a node. This can be helpful for instance when debugging tests.
It is defined as:

```typescript
function prettyDOM(
node: HTMLElement,
maxLength?: number,
options?: Options
): string
function prettyDOM(node: Element, maxLength?: number, options?: Options): string
```

It receives the root node to print out, an optional extra parameter to limit the
Expand Down
38 changes: 19 additions & 19 deletions docs/dom-testing-library/api-queries.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@ id: api-queries
title: Queries
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Tabs from '@theme/Tabs'
import TabItem from '@theme/TabItem'

## Variants

Expand Down Expand Up @@ -127,13 +127,13 @@ screen.debug(screen.getAllByText('multi-test'))

```typescript
getByLabelText(
container: HTMLElement, // if you're using `screen`, then skip this argument
container: Element, // if you're using `screen`, then skip this argument
text: TextMatch,
options?: {
selector?: string = '*',
exact?: boolean = true,
normalizer?: NormalizerFn,
}): HTMLElement
}): Element
```

This will search for the label that matches the given [`TextMatch`](#textmatch),
Expand Down Expand Up @@ -244,12 +244,12 @@ const inputNode = screen.getByLabelText('Username', { selector: 'input' })

```typescript
getByPlaceholderText(
container: HTMLElement, // if you're using `screen`, then skip this argument
container: Element, // if you're using `screen`, then skip this argument
text: TextMatch,
options?: {
exact?: boolean = true,
normalizer?: NormalizerFn,
}): HTMLElement
}): Element
```

This will search for all elements with a placeholder attribute and find one that
Expand Down Expand Up @@ -301,14 +301,14 @@ cy.findByPlaceholderText('Username').should('exist')

```typescript
getByText(
container: HTMLElement, // if you're using `screen`, then skip this argument
container: Element, // if you're using `screen`, then skip this argument
text: TextMatch,
options?: {
selector?: string = '*',
exact?: boolean = true,
ignore?: string|boolean = 'script, style',
normalizer?: NormalizerFn,
}): HTMLElement
}): Element
```

This will search for all elements that have a text node with `textContent`
Expand Down Expand Up @@ -375,12 +375,12 @@ If you'd rather disable this behavior, set `ignore` to `false`.

```typescript
getByAltText(
container: HTMLElement, // if you're using `screen`, then skip this argument
container: Element, // if you're using `screen`, then skip this argument
text: TextMatch,
options?: {
exact?: boolean = true,
normalizer?: NormalizerFn,
}): HTMLElement
}): Element
```

This will return the element (normally an `<img>`) that has the given `alt`
Expand Down Expand Up @@ -433,12 +433,12 @@ cy.findByAltText(/incredibles.*? poster/i).should('exist')

```typescript
getByTitle(
container: HTMLElement, // if you're using `screen`, then skip this argument
container: Element, // if you're using `screen`, then skip this argument
title: TextMatch,
options?: {
exact?: boolean = true,
normalizer?: NormalizerFn,
}): HTMLElement
}): Element
```

Returns the element that has the matching `title` attribute.
Expand Down Expand Up @@ -493,12 +493,12 @@ cy.findByTitle('Close').should('exist')

```typescript
getByDisplayValue(
container: HTMLElement, // if you're using `screen`, then skip this argument
container: Element, // if you're using `screen`, then skip this argument
value: TextMatch,
options?: {
exact?: boolean = true,
normalizer?: NormalizerFn,
}): HTMLElement
}): Element
```

Returns the `input`, `textarea`, or `select` element that has the matching
Expand Down Expand Up @@ -635,7 +635,7 @@ cy.findByDisplayValue('Alaska').should('exist')

```typescript
getByRole(
container: HTMLElement, // if you're using `screen`, then skip this argument
container: Element, // if you're using `screen`, then skip this argument
role: TextMatch,
options?: {
exact?: boolean = true,
Expand All @@ -647,7 +647,7 @@ getByRole(
pressed?: boolean,
queryFallbacks?: boolean,
level?: number,
}): HTMLElement
}): Element
```

Queries for elements with the given role (and it also accepts a
Expand Down Expand Up @@ -884,12 +884,12 @@ To learn more about the `aria-level` property, see

```typescript
getByTestId(
container: HTMLElement, // if you're using `screen`, then skip this argument
container: Element, // if you're using `screen`, then skip this argument
text: TextMatch,
options?: {
exact?: boolean = true,
normalizer?: NormalizerFn,
}): HTMLElement
}): Element
```

A shortcut to `` container.querySelector(`[data-testid="${yourId}"]`) `` (and it
Expand Down Expand Up @@ -1006,7 +1006,7 @@ To override normalization to remove some Unicode characters whilst keeping some

```javascript
screen.getByText('text', {
normalizer: str =>
normalizer: (str) =>
getDefaultNormalizer({ trim: false })(str).replace(/[\u200E-\u200F]*/g, ''),
})
```
Expand Down
Loading