feat: add getQueriesForElement alias to within (#461)

* feat: getQueriesForElement alias implementation & test

* feat: added typescript types and tests

* feat: updated docs

Author: mdjastrzebski

src/__tests__/within.test.js

@@ -1,7 +1,7 @@
 // @flow
 import React from 'react';
 import { View, Text, TextInput } from 'react-native';
-import { render, within } from '..';
+import { render, within, getQueriesForElement } from '..';
 
 test('within() exposes basic queries', async () => {
   const rootQueries = render(
@@ -91,3 +91,7 @@ test('within() exposes a11y queries', async () => {
     secondQueries.findAllByA11yHint('Same Hint')
   ).resolves.toHaveLength(1);
 });
+
+test('getQueriesForElement is alias to within', () => {
+  expect(getQueriesForElement).toBe(within);
+});

src/pure.js

@@ -7,7 +7,7 @@ import render from './render';
 import shallow from './shallow';
 import waitFor, { waitForElement } from './waitFor';
 import waitForElementToBeRemoved from './waitForElementToBeRemoved';
-import within from './within';
+import { within, getQueriesForElement } from './within';
 
 export { act };
 export { cleanup };
@@ -17,4 +17,4 @@ export { render };
 export { shallow };
 export { waitFor, waitForElement };
 export { waitForElementToBeRemoved };
-export { within };
+export { within, getQueriesForElement };

src/within.js

@@ -4,11 +4,13 @@ import { queryByAPI } from './helpers/queryByAPI';
 import { findByAPI } from './helpers/findByAPI';
 import a11yAPI from './helpers/a11yAPI';
 
-export default function within(instance: ReactTestInstance) {
+export function within(instance: ReactTestInstance) {
   return {
     ...getByAPI(instance),
     ...queryByAPI(instance),
     ...findByAPI(instance),
     ...a11yAPI(instance),
   };
 }
+
+export const getQueriesForElement = within;

typings/__tests__/index.test.tsx

@@ -9,6 +9,7 @@ import {
   waitForElementToBeRemoved,
   act,
   within,
+  getQueriesForElement,
 } from '../..';
 
 interface HasRequiredProp {
@@ -306,6 +307,18 @@ const withinGet: Array<ReactTestInstance> = [
   within(instance).getByRole('button'),
   within(instance).getByA11yState({ busy: true }),
   within(instance).getByA11yValue({ min: 10 }),
+  getQueriesForElement(instance).getByText('Test'),
+  getQueriesForElement(instance).getByDisplayValue('Test'),
+  getQueriesForElement(instance).getByPlaceholderText('Test'),
+  getQueriesForElement(instance).getByTestId('Test'),
+  getQueriesForElement(instance).getByA11yLabel('Test'),
+  getQueriesForElement(instance).getByLabelText('Test'),
+  getQueriesForElement(instance).getByA11yHint('Test'),
+  getQueriesForElement(instance).getByHintText('Test'),
+  getQueriesForElement(instance).getByA11yRole('button'),
+  getQueriesForElement(instance).getByRole('button'),
+  getQueriesForElement(instance).getByA11yState({ busy: true }),
+  getQueriesForElement(instance).getByA11yValue({ min: 10 }),
 ];
 
 const withinGetAll: Array<ReactTestInstance[]> = [
@@ -321,6 +334,18 @@ const withinGetAll: Array<ReactTestInstance[]> = [
   within(instance).getAllByRole('button'),
   within(instance).getAllByA11yState({ busy: true }),
   within(instance).getAllByA11yValue({ min: 10 }),
+  getQueriesForElement(instance).getAllByText('Test'),
+  getQueriesForElement(instance).getAllByDisplayValue('Test'),
+  getQueriesForElement(instance).getAllByPlaceholderText('Test'),
+  getQueriesForElement(instance).getAllByTestId('Test'),
+  getQueriesForElement(instance).getAllByA11yLabel('Test'),
+  getQueriesForElement(instance).getAllByLabelText('button'),
+  getQueriesForElement(instance).getAllByA11yHint('Test'),
+  getQueriesForElement(instance).getAllByHintText('button'),
+  getQueriesForElement(instance).getAllByA11yRole('button'),
+  getQueriesForElement(instance).getAllByRole('button'),
+  getQueriesForElement(instance).getAllByA11yState({ busy: true }),
+  getQueriesForElement(instance).getAllByA11yValue({ min: 10 }),
 ];
 
 const withinQuery: Array<ReactTestInstance | null> = [
@@ -336,6 +361,18 @@ const withinQuery: Array<ReactTestInstance | null> = [
   within(instance).queryByRole('button'),
   within(instance).queryByA11yState({ busy: true }),
   within(instance).queryByA11yValue({ min: 10 }),
+  getQueriesForElement(instance).queryByText('Test'),
+  getQueriesForElement(instance).queryByDisplayValue('Test'),
+  getQueriesForElement(instance).queryByPlaceholderText('Test'),
+  getQueriesForElement(instance).queryByTestId('Test'),
+  getQueriesForElement(instance).queryByA11yLabel('Test'),
+  getQueriesForElement(instance).queryByLabelText('button'),
+  getQueriesForElement(instance).queryByA11yHint('Test'),
+  getQueriesForElement(instance).queryByHintText('button'),
+  getQueriesForElement(instance).queryByA11yRole('button'),
+  getQueriesForElement(instance).queryByRole('button'),
+  getQueriesForElement(instance).queryByA11yState({ busy: true }),
+  getQueriesForElement(instance).queryByA11yValue({ min: 10 }),
 ];
 
 const withinQueryAll: Array<ReactTestInstance[]> = [
@@ -351,6 +388,18 @@ const withinQueryAll: Array<ReactTestInstance[]> = [
   within(instance).queryAllByRole('button'),
   within(instance).queryAllByA11yState({ busy: true }),
   within(instance).queryAllByA11yValue({ min: 10 }),
+  getQueriesForElement(instance).queryAllByText('Test'),
+  getQueriesForElement(instance).queryAllByDisplayValue('Test'),
+  getQueriesForElement(instance).queryAllByPlaceholderText('Test'),
+  getQueriesForElement(instance).queryAllByTestId('Test'),
+  getQueriesForElement(instance).queryAllByA11yLabel('Test'),
+  getQueriesForElement(instance).queryAllByLabelText('Test'),
+  getQueriesForElement(instance).queryAllByA11yHint('Test'),
+  getQueriesForElement(instance).queryAllByHintText('Test'),
+  getQueriesForElement(instance).queryAllByA11yRole('button'),
+  getQueriesForElement(instance).queryAllByRole('button'),
+  getQueriesForElement(instance).queryAllByA11yState({ busy: true }),
+  getQueriesForElement(instance).queryAllByA11yValue({ min: 10 }),
 ];
 
 const withinFind: Promise<ReactTestInstance>[] = [
@@ -366,6 +415,18 @@ const withinFind: Promise<ReactTestInstance>[] = [
   within(instance).findByRole('button'),
   within(instance).findByA11yState({ busy: true }),
   within(instance).findByA11yValue({ min: 10 }),
+  getQueriesForElement(instance).findByText('Test'),
+  getQueriesForElement(instance).findByDisplayValue('Test'),
+  getQueriesForElement(instance).findByPlaceholderText('Test'),
+  getQueriesForElement(instance).findByTestId('Test'),
+  getQueriesForElement(instance).findByA11yLabel('Test'),
+  getQueriesForElement(instance).findByLabelText('Test'),
+  getQueriesForElement(instance).findByA11yHint('Test'),
+  getQueriesForElement(instance).findByHintText('Test'),
+  getQueriesForElement(instance).findByA11yRole('button'),
+  getQueriesForElement(instance).findByRole('button'),
+  getQueriesForElement(instance).findByA11yState({ busy: true }),
+  getQueriesForElement(instance).findByA11yValue({ min: 10 }),
 ];
 
 const withinFindAll: Promise<ReactTestInstance[]>[] = [
@@ -381,4 +442,16 @@ const withinFindAll: Promise<ReactTestInstance[]>[] = [
   within(instance).findAllByRole('button'),
   within(instance).findAllByA11yState({ busy: true }),
   within(instance).findAllByA11yValue({ min: 10 }),
+  getQueriesForElement(instance).findAllByText('Test'),
+  getQueriesForElement(instance).findAllByDisplayValue('Test'),
+  getQueriesForElement(instance).findAllByPlaceholderText('Test'),
+  getQueriesForElement(instance).findAllByTestId('Test'),
+  getQueriesForElement(instance).findAllByA11yLabel('Test'),
+  getQueriesForElement(instance).findAllByLabelText('Test'),
+  getQueriesForElement(instance).findAllByA11yHint('Test'),
+  getQueriesForElement(instance).findAllByHintText('Test'),
+  getQueriesForElement(instance).findAllByA11yRole('button'),
+  getQueriesForElement(instance).findAllByRole('button'),
+  getQueriesForElement(instance).findAllByA11yState({ busy: true }),
+  getQueriesForElement(instance).findAllByA11yValue({ min: 10 }),
 ];

typings/index.d.ts

@@ -346,6 +346,9 @@ export declare const waitForElementToBeRemoved: WaitForElementToBeRemovedFunctio
 
 export declare const act: (callback: () => void) => Thenable;
 export declare const within: (instance: ReactTestInstance) => Queries;
+export declare const getQueriesForElement: (
+  instance: ReactTestInstance
+) => Queries;
 
 /**
  * @deprecated This function has been removed. Please use `waitFor` function.

website/docs/API.md

@@ -368,7 +368,10 @@ function waitForElementToBeRemoved<T>(
 Waits for non-deterministic periods of time until queried element is removed or times out. `waitForElementToBeRemoved` periodically calls `expectation` every `interval` milliseconds to determine whether the element has been removed or not.
 
 ```jsx
-import { render, waitForElementToBeRemoved } from 'react-native-testing-library';
+import {
+  render,
+  waitForElementToBeRemoved,
+} from 'react-native-testing-library';
 
 test('waiting for an Banana to be removed', async () => {
   const { getByText } = render(<Banana />);
@@ -387,17 +390,18 @@ In order to properly use `waitForElementToBeRemoved` you need at least React >=1
 
 If you're using Jest's [Timer Mocks](https://jestjs.io/docs/en/timer-mocks#docsNav), remember not to use `async/await` syntax as it will stall your tests.
 
-## `within`
+## `within`, `getQueriesForElement`
 
 - [`Example code`](https://github.com/callstack/react-native-testing-library/blob/master/src/__tests__/within.test.js)
 
 Defined as:
 
 ```jsx
 function within(instance: ReactTestInstance): Queries
+function getQueriesForElement(instance: ReactTestInstance): Queries
 ```
 
-Perform [queries](./Queries.md) scoped to given element.
+`within` (also available as `getQueriesForElement` alias) performs [queries](./Queries.md) scoped to given element.
 
 :::note
 Please note that additional `render` specific operations like `update`, `unmount`, `debug`, `toJSON` are _not_ included.

website/docs/MigrationV7.md

@@ -50,7 +50,6 @@ This guide describes steps necessary to migrate from `@testing-library/react-nat
 
 ## Changed helpers
 
-- `getQueriesForElement` is removed, rename it to `within`
 - `wait` and `waitForElement` is removed, rename these to `waitFor`
 
 ## Missing queries