feat: add within operator for returned instance-bound queries (#306)

* Basic within implementation and tests

* Added typescript types & tests

* Removed duplicated import in index.d.ts

* Reversed prettier run on typings

* Fixed package level exports for `within` operator

* Replaced getByTestId queries with getByA11yHint queries in unit tests for `within`

* Added `within` section to API.md

* Updated README.md regarding `within` operator

* Update website/docs/API.md

Co-authored-by: Michał Pierzchała <thymikee@gmail.com>

typings/__tests__/index.test.tsx

@@ -9,6 +9,7 @@ import {
   debug,
   waitForElement,
   act,
+  within,
 } from '../..';
 
 interface HasRequiredProp {
@@ -217,3 +218,115 @@ const waitByAll: Promise<Array<ReactTestInstance>> = waitForElement<
 act(() => {
   render(<TestComponent />);
 });
+
+// within API
+const instance: ReactTestInstance = tree.getByText('<View />');
+const withinGetByText: ReactTestInstance = within(instance).getByText('Test');
+const withinGetAllByText: ReactTestInstance[] = within(instance).getAllByText(
+  'Test'
+);
+const withinGetByDisplayValue: ReactTestInstance = within(
+  instance
+).getByDisplayValue('Test');
+const withinGetAllByDisplayValue: ReactTestInstance[] = within(
+  instance
+).getAllByDisplayValue('Test');
+const withinGetByPlaceholder: ReactTestInstance = within(
+  instance
+).getByPlaceholder('Test');
+const withinGetAllByPlaceholder: ReactTestInstance[] = within(
+  instance
+).getAllByPlaceholder('Test');
+const withinGetByTestId: ReactTestInstance = within(instance).getByTestId(
+  'Test'
+);
+const withinGetAllByTestId: ReactTestInstance[] = within(
+  instance
+).getAllByTestId('Test');
+
+const withinQueryByText: ReactTestInstance | null = within(
+  instance
+).queryByText('Test');
+const withinQueryAllByText: ReactTestInstance[] = within(
+  instance
+).queryAllByText('Test');
+const withinQueryByDisplayValue: ReactTestInstance | null = within(
+  instance
+).queryByDisplayValue('Test');
+const withinQueryAllByDisplayValue: ReactTestInstance[] = within(
+  instance
+).queryAllByDisplayValue('Test');
+const withinQueryByPlaceholder: ReactTestInstance | null = within(
+  instance
+).queryByPlaceholder('Test');
+const withinQueryAllByPlaceholder: ReactTestInstance[] = within(
+  instance
+).queryAllByPlaceholder('Test');
+const withinQueryByTestId: ReactTestInstance | null = within(
+  instance
+).queryByTestId('Test');
+const withinQueryAllByTestId: ReactTestInstance[] = within(
+  instance
+).queryAllByTestId('Test');
+
+const withinGetByA11yLabel: ReactTestInstance = within(instance).getByA11yLabel(
+  'Test'
+);
+const withinGetAllByA11yLabel: ReactTestInstance[] = within(
+  instance
+).getAllByA11yLabel('Test');
+const withinGetByA11yHint: ReactTestInstance = within(instance).getByA11yHint(
+  'Test'
+);
+const withinGetAllByA11yHint: ReactTestInstance[] = within(
+  instance
+).getAllByA11yHint('Test');
+const withinGetByA11yRole: ReactTestInstance = within(instance).getByA11yRole(
+  'button'
+);
+const withinGetAllByA11yRole: ReactTestInstance[] = within(
+  instance
+).getAllByA11yRole('button');
+const withinGetByA11yState: ReactTestInstance = within(
+  instance
+).getByA11yState({ busy: true });
+const withinGetAllByA11yState: ReactTestInstance[] = within(
+  instance
+).getAllByA11yState({ busy: true });
+const withinGetByA11yValue: ReactTestInstance = within(
+  instance
+).getByA11yValue({ min: 10 });
+const withinGetAllByA11yValue: ReactTestInstance[] = within(
+  instance
+).getAllByA11yValue({ min: 10 });
+
+const withinQueryByA11yLabel: ReactTestInstance | null = within(
+  instance
+).queryByA11yLabel('Test');
+const withinQueryAllByA11yLabel: ReactTestInstance[] = within(
+  instance
+).queryAllByA11yLabel('Test');
+const withinQueryByA11yHint: ReactTestInstance | null = within(
+  instance
+).queryByA11yHint('Test');
+const withinQueryAllByA11yHint: ReactTestInstance[] = within(
+  instance
+).queryAllByA11yHint('Test');
+const withinQueryByA11yRole: ReactTestInstance | null = within(
+  instance
+).queryByA11yRole('button');
+const withinQueryAllByA11yRole: ReactTestInstance[] = within(
+  instance
+).queryAllByA11yRole('button');
+const withinQueryByA11yState: ReactTestInstance | null = within(
+  instance
+).queryByA11yState({ busy: true });
+const withinQueryAllByA11yState: ReactTestInstance[] = within(
+  instance
+).queryAllByA11yState({ busy: true });
+const withinQueryByA11yValue: ReactTestInstance | null = within(
+  instance
+).queryByA11yValue({ min: 10 });
+const withinQueryAllByA11yValue: ReactTestInstance[] = within(
+  instance
+).queryAllByA11yValue({ min: 10 });

typings/index.d.ts

@@ -123,7 +123,9 @@ export interface RenderOptions {
   createNodeMock?: (element: React.ReactElement<any>) => any;
 }
 
-export interface RenderAPI extends GetByAPI, QueryByAPI, A11yAPI {
+type Queries = GetByAPI & QueryByAPI & A11yAPI;
+
+export interface RenderAPI extends Queries {
   update(nextElement: React.ReactElement<any>): void;
   rerender(nextElement: React.ReactElement<any>): void;
   unmount(nextElement?: React.ReactElement<any>): void;
@@ -175,3 +177,4 @@ export declare const debug: DebugAPI;
 export declare const fireEvent: FireEventAPI;
 export declare const waitForElement: WaitForElementFunction;
 export declare const act: (callback: () => void) => Thenable;
+export declare const within: (instance: ReactTestInstance) => Queries;