fix(getBy*): throw an error if more than one element is found

README.md

@@ -166,8 +166,8 @@ that library with this one somehow.
 
 ## Other Solutions
 
-* [`react-native-testing-library`](https://github.com/callstack/react-native-testing-library)
-* [`enzyme`](https://airbnb.io/enzyme/docs/guides/react-native.html)
+- [`react-native-testing-library`](https://github.com/callstack/react-native-testing-library)
+- [`enzyme`](https://airbnb.io/enzyme/docs/guides/react-native.html)
 
 ## Guiding Principles
 

src/__tests__/get-by-errors.js

@@ -0,0 +1,187 @@
+import React from 'react';
+import { Text, TextInput, View } from 'react-native';
+import cases from 'jest-in-case';
+
+import { render } from '../';
+
+cases(
+  'getBy* queries throw an error when there are multiple elements returned',
+  ({ name, query, tree }) => {
+    const utils = render(tree);
+    expect(() => utils[name](query)).toThrow(/multiple elements/i);
+  },
+  {
+    getByA11yHint: {
+      query: /his/,
+      tree: (
+        <View>
+          <View accessibilityHint="his" />
+          <View accessibilityHint="history" />
+        </View>
+      ),
+    },
+    getByA11yLabel: {
+      query: /his/,
+      tree: (
+        <View>
+          <View accessibilityLabel="his" />
+          <View accessibilityLabel="history" />
+        </View>
+      ),
+    },
+    getByA11yRole: {
+      query: 'button',
+      tree: (
+        <View>
+          <View accessibilityRole="button" />
+          <View accessibilityRole="button" />
+        </View>
+      ),
+    },
+    getByA11yStates: {
+      query: ['selected'],
+      tree: (
+        <View>
+          <View accessibilityStates={['selected']} />
+          <View accessibilityStates={['selected']} />
+        </View>
+      ),
+    },
+    getByA11yTraits: {
+      query: ['button'],
+      tree: (
+        <View>
+          <View accessibilityTraits={['button']} />
+          <View accessibilityTraits={['button']} />
+        </View>
+      ),
+    },
+    getByPlaceholder: {
+      query: /his/,
+      tree: (
+        <View>
+          <TextInput placeholder="his" />
+          <TextInput placeholder="history" />
+        </View>
+      ),
+    },
+    getByTestId: {
+      query: /his/,
+      tree: (
+        <View>
+          <Text testID="his">text</Text>
+          <Text testID="history">other</Text>
+        </View>
+      ),
+    },
+    getByText: {
+      query: /his/,
+      tree: (
+        <View>
+          <Text>his</Text>
+          <Text>history</Text>
+        </View>
+      ),
+    },
+    getByValue: {
+      query: /his/,
+      tree: (
+        <View>
+          <TextInput value="his" />
+          <TextInput value="history" />
+        </View>
+      ),
+    },
+  },
+);
+
+cases(
+  'queryBy* queries throw an error when there are multiple elements returned',
+  ({ name, query, tree }) => {
+    const utils = render(tree);
+    expect(() => utils[name](query)).toThrow(/multiple elements/i);
+  },
+  {
+    queryByA11yHint: {
+      query: /his/,
+      tree: (
+        <View>
+          <View accessibilityHint="his" />
+          <View accessibilityHint="history" />
+        </View>
+      ),
+    },
+    queryByA11yLabel: {
+      query: /his/,
+      tree: (
+        <View>
+          <View accessibilityLabel="his" />
+          <View accessibilityLabel="history" />
+        </View>
+      ),
+    },
+    queryByA11yRole: {
+      query: 'button',
+      tree: (
+        <View>
+          <View accessibilityRole="button" />
+          <View accessibilityRole="button" />
+        </View>
+      ),
+    },
+    queryByA11yStates: {
+      query: ['selected'],
+      tree: (
+        <View>
+          <View accessibilityStates={['selected']} />
+          <View accessibilityStates={['selected']} />
+        </View>
+      ),
+    },
+    queryByA11yTraits: {
+      query: ['button'],
+      tree: (
+        <View>
+          <View accessibilityTraits={['button']} />
+          <View accessibilityTraits={['button']} />
+        </View>
+      ),
+    },
+    queryByPlaceholder: {
+      query: /his/,
+      tree: (
+        <View>
+          <TextInput placeholder="his" />
+          <TextInput placeholder="history" />
+        </View>
+      ),
+    },
+    queryByTestId: {
+      query: /his/,
+      tree: (
+        <View>
+          <Text testID="his">text</Text>
+          <Text testID="history">other</Text>
+        </View>
+      ),
+    },
+    queryByText: {
+      query: /his/,
+      tree: (
+        <View>
+          <Text>his</Text>
+          <Text>history</Text>
+        </View>
+      ),
+    },
+    queryByValue: {
+      query: /his/,
+      tree: (
+        <View>
+          <TextInput value="his" />
+          <TextInput value="history" />
+        </View>
+      ),
+    },
+  },
+);

src/__tests__/misc.js

@@ -0,0 +1,20 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import { render } from '../';
+import { queryByProp } from '../';
+
+// we used to use queryByProp internally, but we don't anymore. Some people
+// use it as an undocumented part of the API, so we'll keep it around.
+test('queryByProp', () => {
+  const { container } = render(
+    <View>
+      <View importantForAccessibility="no" />
+      <View importantForAccessibility="no-hide-descendants" />
+    </View>,
+  );
+
+  expect(queryByProp('importantForAccessibility', container, 'no')).not.toBeNull();
+  expect(queryByProp('importantForAccessibility', container, 'auto')).toBeNull();
+  expect(() => queryByProp('importantForAccessibility', container, /no/)).toThrow(/multiple/);
+});

src/__tests__/text-matchers.js

@@ -141,6 +141,11 @@ cases(
       query: `Dwayne 'The Rock' Johnson`,
       queryFn: `queryAllByPlaceholder`,
     },
+    queryAllByValue: {
+      tree: <TextInput value="Dwayne 'The Rock' Johnson" />,
+      query: `Dwayne 'The Rock' Johnson`,
+      queryFn: `queryAllByValue`,
+    },
     queryAllByAccessibilityLabel: {
       tree: <Image accessibilityLabel="Finding Nemo poster " src="/finding-nemo.png" />,
       query: `Finding Nemo poster`,

src/index.d.ts

@@ -227,7 +227,6 @@ export interface Queries {
 export declare function defaultFilter(node: NativeTestInstance): boolean
 export declare function getBaseElement(container: ReactTestRenderer | ReactTestInstance): ReactTestInstance
 export declare function getElementError(message: string, container: ReactTestRenderer): Error
-export declare function firstResultOrNull<T extends any[], U>(query: (...args: T) => U[], ...args: T): U | null
 export declare function filterNodeByType(node: NativeTestInstance, type: string): boolean
 export declare function queryAllByProp(
   attribute: string,