Skip to content

docs: add findBy query type docs. #55

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.

Sign up for GitHub

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 2 commits into from
Mar 19, 2019
Merged

docs: add findBy query type docs. #55

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ba1d1b1
docs: add `findBy` query type docs.
Mar 19, 2019
4ccf988
Update api-queries.md
Mar 19, 2019
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
38 changes: 30 additions & 8 deletions docs/api-queries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,26 @@ present.

### queryAllBy

`queryAllBy*`queries return an array of all matching nodes for a query, and
`queryAllBy*` queries return an array of all matching nodes for a query, and
return an empty array (`[]`) if no elements match.

### findBy

`findBy*` queries return a promise which resolves when an element is found which
matches the given query. The promise is rejected if no element is found after
a default timeout of `4500`ms.

> Note, this is a simple combination of `getBy*` queries and
> [`waitForElement`](/docs/api-async#waitforelement). The `findBy*` queries
> accept the `waitForElement` options as the last argument. (i.e.
> `findByText(container, 'text', queryOptions, waitForElementOptions)`)

### findAllBy

`findAllBy*` queries return a promise which resolves to an array of elements when
any elements are found which match the given query. The promise is rejected if no
elements are found after a default timeout of `4500`ms.

## Options

The argument to a query can be a _string_, _regular expression_, or _function_.
Expand All @@ -41,6 +58,7 @@ See [TextMatch](#textmatch) for documentation on what can be passed to a query.
### `ByLabelText`

> getByLabelText, queryByLabelText, getAllByLabelText, queryAllByLabelText
> findByLabelText, findAllByLabelText

```typescript
getByLabelText(
Expand Down Expand Up @@ -128,7 +146,7 @@ const inputNode = getByLabelText(container, 'username', {
### `ByPlaceholderText`

> getByPlaceholderText, queryByPlaceholderText, getAllByPlaceholderText,
> queryAllByPlaceholderText
> queryAllByPlaceholderText, findByPlaceholderText, findAllByPlaceholderText

```typescript
getByPlaceholderText(
Expand Down Expand Up @@ -182,7 +200,7 @@ cy.getByPlaceholderText('Username').should('exist')

### `ByText`

> getByText, queryByText, getAllByText, queryAllByText
> getByText, queryByText, getAllByText, queryAllByText, findByText, findAllByText

```typescript
getByText(
Expand Down Expand Up @@ -253,7 +271,8 @@ If you'd rather disable this behavior, set `ignore` to `false`.

### `ByAltText`

> getByAltText, queryByAltText, getAllByAltText, queryAllByAltText
> getByAltText, queryByAltText, getAllByAltText, queryAllByAltText, findByAltText,
> findAllByAltText

```typescript
getByAltText(
Expand Down Expand Up @@ -308,7 +327,8 @@ cy.getByAltText(/incredibles.*png$/i).should('exist')

### `ByTitle`

> getByTitle, queryByTitle, getAllByTitle, queryAllByTitle
> getByTitle, queryByTitle, getAllByTitle, queryAllByTitle, findByTitle,
> findAllByTitle

```typescript
getByTitle(
Expand Down Expand Up @@ -366,7 +386,7 @@ cy.getByTitle('Close').should('exist')
### `ByDisplayValue`

> getByDisplayValue, queryByDisplayValue, getAllByDisplayValue,
> queryAllByDisplayValue
> queryAllByDisplayValue, findByDisplayValue, findAllByDisplayValue

```typescript
getByDisplayValue(
Expand Down Expand Up @@ -501,7 +521,8 @@ cy.getByDisplayName('Alaska').should('exist')

### `ByRole`

> getByRole, queryByRole, getAllByRole, queryAllByRole
> getByRole, queryByRole, getAllByRole, queryAllByRole, findByRole,
> findAllByRole

```typescript
getByRole(
Expand Down Expand Up @@ -550,7 +571,8 @@ cy.getByRole('dialog').should('exist')

### `ByTestId`

> getByTestId, queryByTestId, getAllByTestId, queryAllByTestId
> getByTestId, queryByTestId, getAllByTestId, queryAllByTestId, findByTestId,
> findAllByTestId

```typescript
getByTestId(
Expand Down