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>

src/__tests__/within.test.js

@@ -0,0 +1,71 @@
+// @flow
+import React from 'react';
+import { View, Text, TextInput } from 'react-native';
+import { render, within } from '..';
+
+test('within() exposes basic queries', () => {
+  const rootQueries = render(
+    <View>
+      <View accessibilityHint="first">
+        <Text>Same Text</Text>
+        <TextInput value="Same Value" placeholder="Same Placeholder" />
+      </View>
+      <View accessibilityHint="second">
+        <Text>Same Text</Text>
+        <TextInput value="Same Value" placeholder="Same Placeholder" />
+      </View>
+    </View>
+  );
+
+  expect(rootQueries.getAllByText('Same Text')).toHaveLength(2);
+  expect(rootQueries.getAllByDisplayValue('Same Value')).toHaveLength(2);
+  expect(rootQueries.getAllByPlaceholder('Same Placeholder')).toHaveLength(2);
+
+  const firstQueries = within(rootQueries.getByA11yHint('first'));
+  expect(firstQueries.getAllByText('Same Text')).toHaveLength(1);
+  expect(firstQueries.getByText('Same Text')).toBeTruthy();
+  expect(firstQueries.queryAllByText('Same Text')).toHaveLength(1);
+  expect(firstQueries.queryByText('Same Text')).toBeTruthy();
+  expect(firstQueries.getByDisplayValue('Same Value')).toBeTruthy();
+  expect(firstQueries.getByPlaceholder('Same Placeholder')).toBeTruthy();
+
+  const secondQueries = within(rootQueries.getByA11yHint('second'));
+  expect(secondQueries.getAllByText('Same Text')).toHaveLength(1);
+  expect(secondQueries.getByText('Same Text')).toBeTruthy();
+  expect(secondQueries.queryAllByText('Same Text')).toHaveLength(1);
+  expect(secondQueries.queryByText('Same Text')).toBeTruthy();
+  expect(secondQueries.getByDisplayValue('Same Value')).toBeTruthy();
+  expect(secondQueries.getByPlaceholder('Same Placeholder')).toBeTruthy();
+});
+
+test('within() exposes a11y queries', () => {
+  const rootQueries = render(
+    <View>
+      <View accessibilityHint="first">
+        <TextInput
+          value="Same Value"
+          accessibilityLabel="Same Label"
+          accessibilityHint="Same Hint"
+        />
+      </View>
+      <View accessibilityHint="second">
+        <TextInput
+          value="Same Value"
+          accessibilityLabel="Same Label"
+          accessibilityHint="Same Hint"
+        />
+      </View>
+    </View>
+  );
+
+  expect(rootQueries.getAllByA11yLabel('Same Label')).toHaveLength(2);
+  expect(rootQueries.getAllByA11yHint('Same Hint')).toHaveLength(2);
+
+  const firstQueries = within(rootQueries.getByA11yHint('first'));
+  expect(firstQueries.getByA11yLabel('Same Label')).toBeTruthy();
+  expect(firstQueries.getByA11yHint('Same Hint')).toBeTruthy();
+
+  const secondQueries = within(rootQueries.getByA11yHint('second'));
+  expect(secondQueries.getAllByA11yLabel('Same Label')).toHaveLength(1);
+  expect(secondQueries.getAllByA11yHint('Same Hint')).toHaveLength(1);
+});

src/index.js

@@ -7,6 +7,7 @@ import flushMicrotasksQueue from './flushMicrotasksQueue';
 import render from './render';
 import shallow from './shallow';
 import waitForElement from './waitForElement';
+import within from './within';
 
 export { act };
 export { cleanup };
@@ -16,3 +17,4 @@ export { flushMicrotasksQueue };
 export { render };
 export { shallow };
 export { waitForElement };
+export { within };

src/within.js

@@ -0,0 +1,12 @@
+// @flow
+import { getByAPI } from './helpers/getByAPI';
+import { queryByAPI } from './helpers/queryByAPI';
+import a11yAPI from './helpers/a11yAPI';
+
+export default function within(instance: ReactTestInstance) {
+  return {
+    ...getByAPI(instance),
+    ...queryByAPI(instance),
+    ...a11yAPI(instance),
+  };
+}