Skip to content

Commit 464e986

Browse files
mdjastrzebskimdjastrzebski
authored
docs: jsdoc for Jest matchers (#1548)
* docs: add jsdocs for jest matchers * docs: fix formatting issues * docs: tweaks
1 parent 4c20d70 commit 464e986

File tree

2 files changed

+250
-3
lines changed

2 files changed

+250
-3
lines changed

‎src/matchers/types.ts

+249-1
Original file line numberDiff line numberDiff line change
@@ -6,26 +6,274 @@ import { Style } from './to-have-style';
66

77
export interface JestNativeMatchers<R> {
88
/**
9-
* Assert whether an element is present in the element tree or not.
9+
* Assert whether a host element is present in the element tree (screen) or not.
10+
*
11+
* @see
12+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobeonthescreen)
13+
*
14+
* @example
15+
* <Text>Hello</Text>
16+
*
17+
* expect(getByText('Hello')).toBeOnTheScreen()
18+
* expect(queryByText('Other')).not.toBeOnTheScreen()
1019
*/
1120
toBeOnTheScreen(): R;
1221

22+
/**
23+
* Assert whether a host element is checked based on accessibility props.
24+
*
25+
* @see
26+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobechecked)
27+
*
28+
* @see {@link toBePartiallyChecked} for a related matcher.
29+
*
30+
* @example
31+
* <View accessible role="checkbox" aria-checked aria-label="Enable" />
32+
*
33+
* expect(getByRole('checkbox', { name: "Enable" })).toBeChecked()
34+
*/
1335
toBeChecked(): R;
36+
37+
/**
38+
* Assert whether a host element is collapsed based on accessibility props.
39+
*
40+
* @see
41+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobeexpanded)
42+
*
43+
* @see {@link toBeExpanded} for an inverse matcher.
44+
*
45+
* @example
46+
* <View testID="details" aria-expanded={false} />
47+
*
48+
* expect(getByTestId('details').toBeCollapsed()
49+
*/
1450
toBeCollapsed(): R;
51+
52+
/**
53+
* Assert whether a host element is disabled based on accessibility props.
54+
*
55+
* This matcher will check ancestor elements for their disabled state as well.
56+
*
57+
* @see
58+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobeenabled)
59+
*
60+
* @see {@link toBeEnabled} for an inverse matcher.
61+
*
62+
* @example
63+
* <View role="button" aria-disabled />
64+
*
65+
* expect(getByRole('button').toBeDisabled()
66+
*
67+
*/
1568
toBeDisabled(): R;
69+
70+
/**
71+
* Assert whether a host element is busy based on accessibility props.
72+
*
73+
* This matcher will check ancestor elements for their disabled state as well.
74+
*
75+
* @see
76+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobebusy)
77+
*
78+
* @example
79+
* <View testID="loader" aria-busy />
80+
*
81+
* expect(getByTestId('loader')).toBeBusy()
82+
*/
1683
toBeBusy(): R;
84+
85+
/**
86+
* Assert whether a host element has no host children or text content.
87+
*
88+
* @see
89+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobeemptyelement)
90+
*
91+
* @example
92+
* <View testID="not-empty">
93+
* <View testID="empty" />
94+
* </View>
95+
*
96+
* expect(getByTestId('empty')).toBeEmptyElement()
97+
* expect(getByTestId('not-mepty')).not.toBeEmptyElement()
98+
*/
1799
toBeEmptyElement(): R;
100+
101+
/**
102+
* Assert whether a host element is enabled based on accessibility props.
103+
*
104+
* This matcher will check ancestor elements for their disabled state as well.
105+
*
106+
* @see
107+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobeenabled)
108+
*
109+
* @see {@link toBeDisabled} for inverse matcher.
110+
*
111+
* @example
112+
* <View role="button" aria-disabled={false} />
113+
*
114+
* expect(getByRole('button').toBeEnabled()
115+
*/
18116
toBeEnabled(): R;
117+
118+
/**
119+
* Assert whether a host element is expanded based on accessibility props.
120+
*
121+
* @see
122+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobeexpanded)
123+
*
124+
* @see {@link toBeCollapsed} for inverse matcher.
125+
*
126+
* @example
127+
* <View testID="details" aria-expanded />
128+
*
129+
* expect(getByTestId('details').toBeExpanded()
130+
*/
19131
toBeExpanded(): R;
132+
133+
/**
134+
* Assert whether a host element is partially checked based on accessibility props.
135+
*
136+
* @see
137+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobechecked)
138+
*
139+
* @see {@link toBeChecked} for related matcher.
140+
*
141+
* @example
142+
* <View accessible role="checkbox" aria-checked="mixed" aria-label="Enable" />
143+
*
144+
* expect(getByRole('checkbox', { name: "Enable" })).toBePartiallyChecked()
145+
*/
20146
toBePartiallyChecked(): R;
147+
148+
/**
149+
* Assert whether a host element is selected based on accessibility props.
150+
*
151+
* @see
152+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobeselected)
153+
*
154+
* @example
155+
* <View testID="view" aria-selected />
156+
*
157+
* expect(getByTestId('view')).toBeSelected()
158+
*/
21159
toBeSelected(): R;
160+
161+
/**
162+
* Assert whether a host element is visible based on style and accessibility props.
163+
*
164+
* This matcher will check ancestor elements for their visibility as well.
165+
*
166+
* @see
167+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tobevisible)
168+
*
169+
* @example
170+
* <View testID="visible" />
171+
* <View testID="not-visible" style={{ display: 'none' }} />
172+
*
173+
* expect(getByTestId('visible')).toBeVisible()
174+
* expect(getByTestId('not-visible')).not.toBeVisible()
175+
*/
22176
toBeVisible(): R;
177+
178+
/**
179+
* Assert whether a host element contains another host element.
180+
*
181+
* @see
182+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tocontainelement)
183+
*
184+
* @example
185+
* <View testID="outer">
186+
* <View testID="inner" />
187+
* </View>
188+
*
189+
* expect(getByTestId('outer')).toContainElement(getByTestId('inner'));
190+
*/
23191
toContainElement(element: ReactTestInstance | null): R;
192+
193+
/**
194+
* Assert whether a host element has a given accessbility value.
195+
*
196+
* @see
197+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tohaveaccessibilityvalue)
198+
*
199+
*
200+
* @example
201+
* <View testID="view" aria-valuetext="33%" />
202+
*
203+
* expect(getByTestId('view')).toHaveAccessibilityValue({ text: '33%' });
204+
*/
24205
toHaveAccessibilityValue(expectedValue: AccessibilityValueMatcher): R;
206+
207+
/**
208+
* Assert whether a host element has a given accessibile name based on the accessibility label or text content.
209+
*
210+
* @see
211+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tohaveaccessiblename)
212+
*
213+
* @example
214+
* <View testID="view" aria-label="Hello" />
215+
*
216+
* expect(getByTestId('view')).toHaveAccessibleName('Hello');
217+
*/
25218
toHaveAccessibleName(expectedName?: TextMatch, options?: TextMatchOptions): R;
219+
220+
/**
221+
* Assert whether a host `TextInput` element has a given display value based on `value` and `defaultValue` props.
222+
*
223+
* @see
224+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tohavedisplayvalue)
225+
*
226+
* @example
227+
* <TextInput testID="input" value="Hello" />
228+
*
229+
* expect(getByTestId('input')).toHaveDisplayValue('Hello');
230+
*/
26231
toHaveDisplayValue(expectedValue: TextMatch, options?: TextMatchOptions): R;
232+
233+
/**
234+
* Assert whether a host element has a given prop.
235+
*
236+
* @see
237+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tohaveprop)
238+
*
239+
* @example
240+
* <Text testID="text" numberOfLines={1]} />
241+
*
242+
* expect(getByTestId('text')).toHaveProp('numberOfLines');
243+
* expect(getByTestId('text')).toHaveProp('numberOfLines', 1);
244+
*/
27245
toHaveProp(name: string, expectedValue?: unknown): R;
246+
247+
/**
248+
* Assert whether a host element has a given style.
249+
*
250+
* @see
251+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tohavestyle)
252+
*
253+
* @example
254+
* <View testID="view" style={{ width: '100%' }} />
255+
*
256+
* expect(getByTestId('view')).toHaveStyle({ width: '100%' });
257+
* expect(getByTestId('view')).not.toHaveStyle({ width: '50%' });
258+
*/
28259
toHaveStyle(style: StyleProp<Style>): R;
260+
261+
/**
262+
* Assert whether a host element has a given text content.
263+
*
264+
* @see
265+
* [Jest Matchers docs](https://callstack.github.io/react-native-testing-library/docs/jest-matchers#tohavetextcontent)
266+
*
267+
* @example
268+
* <View testID="view">
269+
* <Text>Hello World</Text>
270+
* </View>
271+
*
272+
* expect(getByTestId('view')).toHaveTextContent('Hello World');
273+
* expect(getByTestId('view')).toHaveTextContent('Hello', { exact: false }});
274+
* expect(getByTestId('view')).toHaveTextContent(/hello/i);
275+
* expect(getByTestId('view')).not.toHaveTextContent('Hello');
276+
*/
29277
toHaveTextContent(expectedText: TextMatch, options?: TextMatchOptions): R;
30278
}
31279

‎website/docs/JestMatchers.md

+1-2
Original file line numberDiff line numberDiff line change
@@ -144,10 +144,9 @@ expect(element).toBePartiallyChecked();
144144
These allow you to assert whether the given element is checked or partially checked from the user's perspective. It relies on the accessibility checked state as set by `aria-checked` or `accessibilityState.checked` props.
145145

146146
:::note
147-
148147
- `toBeChecked()` matcher works only on elements with the `checkbox` or `radio` role.
149148
- `toBePartiallyChecked()` matcher works only on elements with the `checkbox` role.
150-
:::
149+
:::
151150

152151
### `toBeExpanded()` / `toBeCollapsed()` {#tobeexpanded}
153152

0 commit comments

Comments
 (0)