feat: ...byRole type queries accepts second arg

package.json

@@ -1,6 +1,6 @@
 {
  "name": "@testing-library/react-native",
- "version": "9.1.0",
+ "version": "9.0.0-alpha.0",
  "description": "Simple and complete React Native testing utilities that encourage good testing practices.",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",

src/__tests__/a11yAPI.test.tsx

@@ -1,11 +1,13 @@
 import * as React from 'react';
-import { TouchableOpacity, Text } from 'react-native';
+import { TouchableOpacity, Text, View } from 'react-native';
 import { render } from '../index';
 
 const BUTTON_LABEL = 'cool button';
 const BUTTON_HINT = 'click this button';
 const TEXT_LABEL = 'cool text';
 const TEXT_HINT = 'static text';
+const ONE_OCCURANCE = 'more words';
+const TWO_OCCURANCE = 'cooler text';
 // Little hack to make all the methods happy with type
 const NO_MATCHES_TEXT: any = 'not-existent-element';
 const FOUND_TWO_INSTANCES = 'Expected 1 but found 2 instances';
@@ -69,6 +71,22 @@ function Section() {
  );
 }
 
+function ButtonsWithText() {
+ return (
+ <>
+ <TouchableOpacity accessibilityRole="button">
+ <Text>{TWO_OCCURANCE}</Text>
+ </TouchableOpacity>
+ <TouchableOpacity accessibilityRole="button">
+ <Text>{TWO_OCCURANCE}</Text>
+ </TouchableOpacity>
+ <TouchableOpacity accessibilityRole="button">
+ <Text>{ONE_OCCURANCE}</Text>
+ </TouchableOpacity>
+ </>
+ );
+}
+
 test('getByLabelText, queryByLabelText, findByLabelText', async () => {
  const { getByLabelText, queryByLabelText, findByLabelText } = render(
  <Section />
@@ -183,7 +201,7 @@ test('getByRole, queryByRole, findByRole', async () => {
 
  const asyncButton = await findByRole('button');
  expect(asyncButton.props.accessibilityRole).toEqual('button');
- await expect(findByRole(NO_MATCHES_TEXT, waitForOptions)).rejects.toThrow(
+ await expect(findByRole(NO_MATCHES_TEXT, {}, waitForOptions)).rejects.toThrow(
  getNoInstancesFoundMessage('accessibilityRole')
  );
  await expect(findByRole('link')).rejects.toThrow(FOUND_TWO_INSTANCES);
@@ -201,9 +219,64 @@ test('getAllByRole, queryAllByRole, findAllByRole', async () => {
  expect(queryAllByRole(NO_MATCHES_TEXT)).toEqual([]);
 
  await expect(findAllByRole('link')).resolves.toHaveLength(2);
- await expect(findAllByRole(NO_MATCHES_TEXT, waitForOptions)).rejects.toThrow(
- getNoInstancesFoundMessage('accessibilityRole')
+ await expect(
+ findAllByRole(NO_MATCHES_TEXT, {}, waitForOptions)
+ ).rejects.toThrow(getNoInstancesFoundMessage('accessibilityRole'));
+});
+
+describe('findBy options deprecations', () => {
+ let warnSpy: jest.SpyInstance;
+ beforeEach(() => {
+ warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+ });
+ afterEach(() => {
+ warnSpy.mockRestore();
+ });
+
+ test('findByText queries warn on deprecated use of WaitForOptions', async () => {
+ const options = { timeout: 10 };
+ // mock implementation to avoid warning in the test suite
+ const { rerender, findByText } = render(<View />);
+ await expect(findByText('Some Text', options)).rejects.toBeTruthy();
+
+ setTimeout(
+ () =>
+ rerender(
+ <View>
+ <Text>Some Text</Text>
+ </View>
+ ),
+ 20
+ );
+
+ await expect(findByText('Some Text')).resolves.toBeTruthy();
+
+ expect(warnSpy).toHaveBeenCalledWith(
+ expect.stringContaining('Use of option "timeout"')
+ );
+ }, 20000);
+});
+
+test('getAllByRole, queryAllByRole, findAllByRole with name', async () => {
+ const { getAllByRole, queryAllByRole, findAllByRole } = render(
+ <ButtonsWithText />
+ );
+
+ expect(getAllByRole('button', { name: TWO_OCCURANCE })).toHaveLength(2);
+ expect(getAllByRole('button', { name: ONE_OCCURANCE })).toHaveLength(1);
+ expect(queryAllByRole('button', { name: TWO_OCCURANCE })).toHaveLength(2);
+
+ expect(() => getAllByRole('button', { name: NO_MATCHES_TEXT })).toThrow(
+ getNoInstancesFoundMessage('accessibilityRole', 'button')
  );
+ expect(queryAllByRole('button', { name: NO_MATCHES_TEXT })).toEqual([]);
+
+ await expect(
+ findAllByRole('button', { name: TWO_OCCURANCE })
+ ).resolves.toHaveLength(2);
+ await expect(
+ findAllByRole('button', { name: NO_MATCHES_TEXT })
+ ).rejects.toThrow(getNoInstancesFoundMessage('accessibilityRole', 'button'));
 });
 
 // TODO: accessibilityStates was removed from RN 0.62

src/helpers/a11yAPI.ts

@@ -1,5 +1,5 @@
 import type { ReactTestInstance } from 'react-test-renderer';
-import type { AccessibilityRole, AccessibilityState } from 'react-native';
+import type { AccessibilityState } from 'react-native';
 import type { WaitForOptions } from '../waitFor';
 import type { TextMatch } from '../matches';
 import makeA11yQuery from './makeA11yQuery';
@@ -11,6 +11,34 @@ type A11yValue = {
  now?: number;
  text?: string;
 };
+type A11yRole =
+ | 'none'
+ | 'button'
+ | 'link'
+ | 'search'
+ | 'image'
+ | 'keyboardkey'
+ | 'text'
+ | 'adjustable'
+ | 'imagebutton'
+ | 'header'
+ | 'summary'
+ | 'alert'
+ | 'checkbox'
+ | 'combobox'
+ | 'menu'
+ | 'menubar'
+ | 'menuitem'
+ | 'progressbar'
+ | 'radio'
+ | 'radiogroup'
+ | 'scrollbar'
+ | 'spinbutton'
+ | 'switch'
+ | 'tab'
+ | 'tablist'
+ | 'timer'
+ | 'toolbar';
 
 type GetReturn = ReactTestInstance;
 type GetAllReturn = Array<ReactTestInstance>;
@@ -19,6 +47,10 @@ type QueryAllReturn = Array<ReactTestInstance>;
 type FindReturn = Promise<GetReturn>;
 type FindAllReturn = Promise<GetAllReturn>;
 
+export type QueryOptions = {
+ name?: string | RegExp;
+};
+
 export type A11yAPI = {
  // Label
  getByLabelText: (label: TextMatch) => GetReturn;
@@ -61,16 +93,30 @@ export type A11yAPI = {
  ) => FindAllReturn;
 
  // Role
- getByRole: (role: AccessibilityRole | RegExp) => GetReturn;
- getAllByRole: (role: AccessibilityRole | RegExp) => GetAllReturn;
- queryByRole: (role: AccessibilityRole | RegExp) => QueryReturn;
- queryAllByRole: (role: AccessibilityRole | RegExp) => QueryAllReturn;
+ getByRole: (
+ role: A11yRole | RegExp,
+ queryOptions?: QueryOptions
+ ) => GetReturn;
+ getAllByRole: (
+ role: A11yRole | RegExp,
+ queryOptions?: QueryOptions
+ ) => GetAllReturn;
+ queryByRole: (
+ role: A11yRole | RegExp,
+ queryOptions?: QueryOptions
+ ) => QueryReturn;
+ queryAllByRole: (
+ role: A11yRole | RegExp,
+ queryOptions?: QueryOptions
+ ) => QueryAllReturn;
  findByRole: (
- role: AccessibilityRole,
+ role: A11yRole,
+ queryOptions?: QueryOptions & WaitForOptions,
  waitForOptions?: WaitForOptions
  ) => FindReturn;
  findAllByRole: (
- role: AccessibilityRole,
+ role: A11yRole,
+ queryOptions?: QueryOptions & WaitForOptions,
  waitForOptions?: WaitForOptions
  ) => FindAllReturn;
 

src/helpers/makeA11yQuery.ts

@@ -1,5 +1,6 @@
 import type { ReactTestInstance } from 'react-test-renderer';
 import waitFor from '../waitFor';
+import { getQueriesForElement } from '../within';
 import type { WaitForOptions } from '../waitFor';
 import {
  ErrorWithStack,
@@ -17,6 +18,39 @@ function makeAliases(aliases: Array<string>, query: Function) {
  .reduce((acc, query) => ({ ...acc, ...query }), {});
 }
 
+// The WaitForOptions has been moved to the third param of findBy* methods with the addition of QueryOptions.
+// To make the migration easier and to avoid a breaking change, keep reading these options from second param
+// but warn.
+const deprecatedKeys: (keyof WaitForOptions)[] = [
+ 'timeout',
+ 'interval',
+ 'stackTraceError',
+];
+const warnDeprectedWaitForOptionsUsage = (queryOptions?: WaitForOptions) => {
+ if (queryOptions) {
+ const waitForOptions: WaitForOptions = {
+ timeout: queryOptions.timeout,
+ interval: queryOptions.interval,
+ stackTraceError: queryOptions.stackTraceError,
+ };
+ deprecatedKeys.forEach((key) => {
+ if (queryOptions[key]) {
+ // eslint-disable-next-line no-console
+ console.warn(
+ `Use of option "${key}" in a findBy* query's second parameter, QueryOptions, is deprecated. Please pass this option in the third, WaitForOptions, parameter. 
+Example: 
+ findByText(text, {}, { ${key}: ${queryOptions[key]} })`
+ );
+ }
+ });
+ return waitForOptions;
+ }
+};
+
+type QueryOptions = {
+ name: string | RegExp;
+};
+
 type QueryNames = {
  getBy: Array<string>;
  getAllBy: Array<string>;
@@ -31,8 +65,27 @@ const makeA11yQuery = <P extends unknown, M extends unknown>(
  queryNames: QueryNames,
  matcherFn: (prop: P, value: M) => boolean
 ) => (instance: ReactTestInstance) => {
- const getBy = (matcher: M) => {
+ const filterWithName = (
+ node: ReactTestInstance,
+ options: QueryOptions,
+ matcher: M
+ ) => {
+ const matchesRole =
+ isNodeValid(node) && matcherFn(node.props[name], matcher);
+
+ return (
+ matchesRole && !!getQueriesForElement(node).queryByText(options.name)
+ );
+ };
+
+ const getBy = (matcher: M, queryOptions?: QueryOptions) => {
  try {
+ if (queryOptions?.name) {
+ return instance.find((node) =>
+ filterWithName(node, queryOptions, matcher)
+ );
+ }
+
  return instance.find(
  (node) => isNodeValid(node) && matcherFn(node.props[name], matcher)
  );
@@ -44,10 +97,18 @@ const makeA11yQuery = <P extends unknown, M extends unknown>(
  }
  };
 
- const getAllBy = (matcher: M) => {
- const results = instance.findAll(
- (node) => isNodeValid(node) && matcherFn(node.props[name], matcher)
- );
+ const getAllBy = (matcher: M, options?: QueryOptions) => {
+ let results = [];
+
+ if (options?.name) {
+ results = instance.findAll((node) =>
+ filterWithName(node, options, matcher)
+ );
+ } else {
+ results = instance.findAll(
+ (node) => isNodeValid(node) && matcherFn(node.props[name], matcher)
+ );
+ }
 
  if (results.length === 0) {
  throw new ErrorWithStack(
@@ -59,28 +120,50 @@ const makeA11yQuery = <P extends unknown, M extends unknown>(
  return results;
  };
 
- const queryBy = (matcher: M) => {
+ const queryBy = (matcher: M, options?: QueryOptions) => {
  try {
- return getBy(matcher);
+ return getBy(matcher, options);
  } catch (error) {
  return createQueryByError(error, queryBy);
  }
  };
 
- const queryAllBy = (matcher: M) => {
+ const queryAllBy = (matcher: M, options?: QueryOptions) => {
  try {
- return getAllBy(matcher);
+ return getAllBy(matcher, options);
  } catch (error) {
  return [];
  }
  };
 
- const findBy = (matcher: M, waitForOptions?: WaitForOptions) => {
- return waitFor(() => getBy(matcher), waitForOptions);
+ const findBy = (
+ matcher: M,
+ queryOptions?: QueryOptions & WaitForOptions,
+ waitForOptions?: WaitForOptions
+ ) => {
+ const deprecatedWaitForOptions = warnDeprectedWaitForOptionsUsage(
+ queryOptions
+ );
+
+ return waitFor(() => getBy(matcher, queryOptions), {
+ ...deprecatedWaitForOptions,
+ ...waitForOptions,
+ });
  };
 
- const findAllBy = (matcher: M, waitForOptions?: WaitForOptions) => {
- return waitFor(() => getAllBy(matcher), waitForOptions);
+ const findAllBy = (
+ matcher: M,
+ queryOptions?: QueryOptions & WaitForOptions,
+ waitForOptions?: WaitForOptions
+ ) => {
+ const deprecatedWaitForOptions = warnDeprectedWaitForOptionsUsage(
+ queryOptions
+ );
+
+ return waitFor(() => getAllBy(matcher, queryOptions), {
+ ...deprecatedWaitForOptions,
+ ...waitForOptions,
+ });
  };
 
  return {