Skip to content

docs: table of contents for Queries and API pages #980

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
May 27, 2022
Merged

docs: table of contents for Queries and API pages #980

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cd2167c
docs: add toc for APIs
mdjastrzebski May 19, 2022
0c90f54
docs: add toc for Queries
mdjastrzebski May 19, 2022
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
76 changes: 55 additions & 21 deletions website/docs/API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,34 @@ id: api
title: API
---

### Table of contents:

- [`render`](#render)
- [`update`](#update)
- [`unmount`](#unmount)
- [`debug`](#debug)
- [`toJSON`](#tojson)
- [`container`](#container)
- [`cleanup`](#cleanup)
- [`fireEvent`](#fireevent)
- [`fireEvent[eventName]`](#fireeventeventname)
- [`fireEvent.press`](#fireeventpress)
- [`fireEvent.changeText`](#fireeventchangetext)
- [`fireEvent.scroll`](#fireeventscroll)
- [`waitFor`](#waitfor)
- [`waitForElementToBeRemoved`](#waitforelementtoberemoved)
- [`within, getQueriesForElement`](#within-getqueriesforelement)
- [`query` APIs](#query-apis)
- [`queryAll` APIs](#queryall-apis)
- [`act`](#act)
- [`renderHook`](#renderhook)
- [`callback`](#callback)
- [`options`](#options-optional)
- [`RenderHookResult` object](#renderhookresult-object)
- [`result`](#result)
- [`rerender`](#rerender)
- [`unmount`](#unmount-1)

This page gathers public API of React Native Testing Library along with usage examples.

## `render`
Expand Down Expand Up @@ -225,7 +253,11 @@ fireEvent[eventName](element: ReactTestInstance, ...data: Array<any>): void

Convenience methods for common events like: `press`, `changeText`, `scroll`.

### `fireEvent.press: (element: ReactTestInstance, ...data: Array<any>) => void`
### `fireEvent.press`

```
fireEvent.press: (element: ReactTestInstance, ...data: Array<any>) => void
```

Invokes `press` event handler on the element or parent element in the tree.

Expand Down Expand Up @@ -253,7 +285,11 @@ fireEvent.press(getByText('Press me'), eventData);
expect(onPressMock).toHaveBeenCalledWith(eventData);
```

### `fireEvent.changeText: (element: ReactTestInstance, ...data: Array<any>) => void`
### `fireEvent.changeText`

```
fireEvent.changeText: (element: ReactTestInstance, ...data: Array<any>) => void
```

Invokes `changeText` event handler on the element or parent element in the tree.

Expand All @@ -273,7 +309,11 @@ const { getByPlaceholderText } = render(
fireEvent.changeText(getByPlaceholderText('Enter data'), CHANGE_TEXT);
```

### `fireEvent.scroll: (element: ReactTestInstance, ...data: Array<any>) => void`
### `fireEvent.scroll`

```
fireEvent.scroll: (element: ReactTestInstance, ...data: Array<any>) => void
```

Invokes `scroll` event handler on the element or parent element in the tree.

Expand Down Expand Up @@ -519,40 +559,34 @@ A `RenderHookOptions<Props>` object to modify the execution of the `callback` fu

#### `initialProps`

The initial values to pass as `props` to the `callback` function of `renderHook`. The `Props` type is determined by the type passed to or inferred by the `renderHook` call.
The initial values to pass as `props` to the `callback` function of `renderHook`. The `Props` type is determined by the type passed to or inferred by the `renderHook` call.

#### `wrapper`

A React component to wrap the test component in when rendering. This is usually used to add context providers from `React.createContext` for the hook to access with `useContext`.

### `RenderHookResult<Result, Props>` object
### `RenderHookResult` object

```ts
interface RenderHookResult<Result, Props> {
result: { current: Result };
rerender: (props: Props) => void;
unmount: () => void;
}
```

The `renderHook` function returns an object that has the following properties:

#### `result`

```jsx
{
current: Result
}
```

The `current` value of the `result` will reflect the latest of whatever is returned from the `callback` passed to `renderHook`. The `Result` type is determined by the type passed to or inferred by the `renderHook` call.
The `current` value of the `result` will reflect the latest of whatever is returned from the `callback` passed to `renderHook`. The `Result` type is determined by the type passed to or inferred by the `renderHook` call.

#### `rerender`

```ts
function rerender(newProps?: Props): void;
```

A function to rerender the test component, causing any hooks to be recalculated. If `newProps` are passed, they will replace the `callback` function's `initialProps` for subsequent rerenders. The `Props` type is determined by the type passed to or inferred by the `renderHook` call.
A function to rerender the test component, causing any hooks to be recalculated. If `newProps` are passed, they will replace the `callback` function's `initialProps` for subsequent rerenders. The `Props` type is determined by the type passed to or inferred by the `renderHook` call.

#### `unmount`

```ts
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why remove the API here while keeping it for fireEvent.scroll: (element: ReactTestInstance, ...data: Array<any>) => void for instance?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This rerender refers to RenderHookResult type which is kinda its own section. So I've put the whole type definition just above sections for first of it (result). Do you think we should repeat it here?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No you're right, it makes sense!

function unmount(): void;
```

A function to unmount the test component. This is commonly used to trigger cleanup effects for `useEffect` hooks.

### Examples
Expand Down
31 changes: 29 additions & 2 deletions website/docs/Queries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,33 @@ id: api-queries
title: Queries
---

### Table of contents:

- [Variants](#variants)
- [`getBy`](#getby)
- [`getAllBy`](#getallby)
- [`queryBy`](#queryby)
- [`queryAllBy`](#queryallby)
- [`findBy`](#findby)
- [`findAllBy`](#findallby)
- [Queries](#queries)
- [`options`](#options)
- [`ByText`](#bytext)
- [`ByPlaceholderText`](#byplaceholdertext)
- [`ByDisplayValue`](#bydisplayvalue)
- [`ByTestId`](#bytestid)
- [`ByLabelText`](#bylabeltext)
- [`ByHintText`, `ByA11yHint`, `ByAccessibilityHint`](#byhinttext-bya11yhint-byaccessibilityhint)
- [`ByA11yStates`, `ByAccessibilityStates`](#bya11ystates-byaccessibilitystates)
- [`ByRole`](#byrole)
- [`ByA11yState`, `ByAccessibilityState`](#bya11ystate-byaccessibilitystate)
- [`ByA11Value`, `ByAccessibilityValue`](#bya11value-byaccessibilityvalue)
- [`TextMatch`](#textmatch)
- [Examples](#examples)
- [Precision](#precision)
- [Normalization](#normalization)
- [Unit testing helpers](#unit-testing-helpers)

## Variants

> `getBy` queries are shown by default in the [query documentation](#queries)
Expand Down Expand Up @@ -55,7 +82,7 @@ type ReactTestInstance = {

### Options

Query first argument can be a **string** or a **regex**. Some queries accept optional argument which change string matching behaviour. See [TextMatch](#textmatch) for more info.
Usually query first argument can be a **string** or a **regex**. Some queries accept optional argument which change string matching behaviour. See [TextMatch](#textmatch) for more info.

### `ByText`

Expand Down Expand Up @@ -128,7 +155,7 @@ const { getByLabelText } = render(<MyComponent />);
const element = getByLabelText('my-label');
```

### `ByA11yHint`, `ByAccessibilityHint`, `ByHintText`
### `ByHintText`, `ByA11yHint`, `ByAccessibilityHint`

> getByA11yHint, getAllByA11yHint, queryByA11yHint, queryAllByA11yHint, findByA11yHint, findAllByA11yHint
> getByAccessibilityHint, getAllByAccessibilityHint, queryByAccessibilityHint, queryAllByAccessibilityHint, findByAccessibilityHint, findAllByAccessibilityHint
Expand Down