Skip to content

add "screen" docs #351

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

Merged
merged 1 commit into from
Dec 27, 2019
Merged
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
33 changes: 33 additions & 0 deletions docs/dom-testing-library/api-queries.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,41 @@ There are also options to adjust how node text is parsed.

See [TextMatch](#textmatch) for documentation on what can be passed to a query.

## `screen`

All of the queries exported by DOM Testing Library accept a `container` as the
first argument. Because querying the entire `document.body` is very common, DOM
Testing Library also exports a `screen` object which has every query that is
pre-bound to `document.body` (using the
[`within`](/docs/dom-testing-library/api-helpers#within-and-getqueriesforelement-apis)
functionality).

Here's how you use it:

```javascript
import { screen } from '@testing-library/dom'
// NOTE: many framework-implementations of Testing Library
// re-export everything from `@testing-library/dom` so you
// may be able to import screen from your framework-implementation:
// import {render, screen} from '@testing-library/react'

const exampleHTML = `
<label for="example">Example</label>
<input id="example" />
`
document.body.innerHTML = exampleHTML
const exampleInput = screen.getByLabelText(/example/i)
```

## Queries

> NOTE: These queries are the base queries and require you pass a `container` as
> the first argument. Most framework-implementations of Testing Library provide
> a pre-bound version of these queries when you render your components with them
> which means you do not have to provide a container. In addition, if you just
> want to query `document.body` then you can use the [`screen`](#screen) export
> as demonstrated above.

### `ByLabelText`

> getByLabelText, queryByLabelText, getAllByLabelText, queryAllByLabelText
Expand Down