version 3.0.0

Author: bcarroll22

docs/api-async.md

@@ -62,16 +62,16 @@ Additionally, the result is returned for you to use.
 Here's a simple example:
 
 ```javascript
-const usernameElement = await waitForElement(() => getByA11yLabel('username'));
+const usernameElement = await waitForElement(() => getByLabelText('username'));
 expect(usernameElement).toHaveTextContent('chucknorris');
 ```
 
 You can also wait for multiple elements at once:
 
 ```javascript
 const [usernameElement, passwordElement] = await waitForElement(() => [
-  getByA11yLabel('username'),
-  getByA11yLabel('password'),
+  getByLabelText('username'),
+  getByLabelText('password'),
 ]);
 ```
 
@@ -101,17 +101,7 @@ callback is returned as a Promise, but in most cases you won't need it.
 Here's a simple example:
 
 ```javascript
-const listItems = await waitForElementToBeRemoved(() => queryAllByA11yLabel('list-item'));
-expect(listItems).toHaveLength(0);
-```
-
-You can also wait for multiple elements to be removed at once:
-
-```javascript
-const [usernameElement, passwordElement] = await waitForElementToBeRemoved(() => [
-  queryByA11yLabel('username'),
-  queryByA11yLabel('password'),
-]);
+await waitForElementToBeRemoved(() => queryAllByLabelText('list-item'));
 ```
 
 The default `timeout` is `4500ms` which will keep you under

docs/api-events.md

@@ -7,16 +7,16 @@ sidebar_label: Firing Events
 ## Basic example
 
 ```javascript
-import { fireEvent, NativeEvent, render } from 'native-testing-library';
+import { fireEvent, NativeTestEvent, render } from 'native-testing-library';
 
 const { getByText } = render(<Button title="Submit" />);
-fireEvent(getByText(container, 'Submit'), new NativeEvent('press'));
+fireEvent(getByText(container, 'Submit'), new NativeTestEvent('press'));
 ```
 
 ## `fireEvent[eventName]`
 
 ```typescript
-fireEvent[eventName](node: FiberRoot, eventProperties: NativeEvent)
+fireEvent[eventName](node: FiberRoot, eventProperties: NativeTestEvent)
 ```
 
 Convenience methods for firing events. Check out
@@ -35,19 +35,22 @@ called nativeEvent. When you fire an event using this library, you will have to
 config. You will use this particularly for events like a change event:
 
 ```javascript
-fireEvent.change(getByA11yLabel(/username/i), { nativeEvent: { text: 'a' } });
+fireEvent.change(getByLabelText(/username/i), { nativeEvent: { text: 'a' } });
 ```
 
 **changeText**: `Text` has a method for value updating called `onChangeText`. Since this is such a
 commonly used method, there is a special case in the library for this method.
 
 ```javascript
-fireEvent.changeText(getByA11yLabel(/username/i), 'a');
+fireEvent.changeText(getByLabelText(/username/i), 'a');
 ```
 
 **customEvent**: You may be using a library that has custom event listeners that you want to be able
 to fire. This is how you would fire one of these events:
 
 ```javascript
-fireEvent(getByTestId('swiper'), new NativeEvent('myEvent', { nativeEvent: { value: 'testing' } }));
+fireEvent(
+  getByTestId('swiper'),
+  new NativeTestEvent('myEvent', { nativeEvent: { value: 'testing' } }),
+);
 ```

docs/api-helpers.md

@@ -60,45 +60,30 @@ in a browser, where any extra whitespace within words in the html code is not me
 text is rendered, and all text appears as one cohesive string regardless of the code.
 
 ```javascript
-const inputNode = <TextInput value="words" />;
-const textNode = (
+getNodeText(
   <Text>
     {`
-  Hello
-    World  !
-  `}
-  </Text>
-);
-
-getNodeText(node); // "Hello World !"
-```
-
-This function is also used internally when querying nodes by their text content. This enables
-functions like `getByText` and `queryByText` to work as expected, finding elements in the tree
-similarly to how users would do.
-
-The function works for for input elements as well:
-
-```javascript
-const inputNode = <TextInput value="words" />;
-
-getNodeText(inputNode); // "words"
+    Hello
+      World  !
+    `}
+  </Text>,
+); // "Hello World !"
 ```
 
 ## `within` and `getQueriesForElement` APIs
 
-`within` (an alias to `getQueriesForElement`) takes a `ReactTestRendererInstance` and binds it to
-the raw query functions, allowing them to be used without manually specifying a container.
+`within` (an alias to `getQueriesForElement`) takes a `NativeTestInstance` and binds it to the raw
+query functions, allowing them to be used without manually specifying a container.
 
 Example: To get the username input of a login form within a `<LoginModal />`, you could do:
 
 ```js
 import { render, within } from 'native-testing-library';
 
-const { getByA11yLabel } = render(<LoginModal />);
-const loginForm = getByA11yLabel('login-form');
+const { getByLabelText } = render(<LoginModal />);
+const loginForm = getByLabelText('login-form');
 
-within(loginForm).getByPlaceholder('Username');
+within(loginForm).getByPlaceholderText('Username');
 ```
 
 ## Debugging

docs/api-queries.md

@@ -62,7 +62,7 @@ See [TextMatch](#textmatch) for documentation on what can be passed to a query.
 
 ```typescript
 getByHintText(
-  container: ReactTestRenderer | NativeTestInstance,
+  container: NativeTestInstance,
   match: TextMatch,
   options?: {
     exact?: boolean = true,
@@ -91,7 +91,7 @@ getByHintText('summary'); // returns the View node
 
 ```typescript
 getByLabelText(
-  container: ReactTestRenderer | NativeTestInstance,
+  container: NativeTestInstance,
   match: TextMatch,
   options?: {
     exact?: boolean = true,
@@ -130,7 +130,7 @@ getByLabelText('username'); // returns the TextInput node
 
 ```typescript
 getByRole(
-  container: ReactTestRenderer | NativeTestInstance,
+  container: NativeTestInstance,
   match: TextMatch,
   options?: {
     selector?: SelectorFn,
@@ -158,7 +158,7 @@ getByRole('summary'); // returns the View node
 
 ```typescript
 getByPlaceholderText(
-  container: ReactTestRenderer | NativeTestInstance,
+  container: NativeTestInstance,
   match: TextMatch,
   options?: {
     exact?: boolean = true,
@@ -186,7 +186,7 @@ getByPlaceholderText('Username'); // returns the TextInput node
 
 ```typescript
 getByText(
-  container: ReactTestRenderer | NativeTestInstance,
+  container: NativeTestInstance,
   match: TextMatch,
   options?: {
     exact?: boolean = true,
@@ -198,8 +198,7 @@ getByText(
 ```
 
 This will search for all elements of type `Text` with `props.children` matching the given. It will
-also search `TextInput` elements by their value and `Button` elements by their `title`
-[`TextMatch`](#textmatch).
+also search for `Button` elements by their `title` [`TextMatch`](#textmatch).
 
 ```js
 import { render } from 'native-testing-library';
@@ -215,7 +214,7 @@ getByText(/about/i); // returns the Text node
 
 ```typescript
 getByTitle(
-  container: ReactTestRenderer | NativeTestInstance,
+  container: NativeTestInstance,
   match: TextMatch,
   options?: {
     exact?: boolean = true,
@@ -237,13 +236,14 @@ const { getByTitle } = render(<Button title="About" />);
 getByTitle(/about/i); // returns the Button node
 ```
 
-### `ByValue`
+### `ByDisplayValue`
 
-> getByValue, queryByValue, getAllByValue, queryAllByValue, findByValue, findAllByValue
+> getByDisplayValue, queryByDisplayValue, getAllByDisplayValue, queryAllByDisplayValue,
+> findByDisplayValue, findAllByDisplayValue
 
 ```typescript
-getByValue(
-  container: ReactTestRenderer | NativeTestInstance,
+getByDisplayValue(
+  container: NativeTestInstance,
   match: TextMatch,
   options?: {
     exact?: boolean = true,
@@ -254,15 +254,15 @@ getByValue(
   }): NormalizerOptions
 ```
 
-This will search for all `TextInput` elements with a `value` prop or `Picker` elements with a
-`selectedValue` prop and find ones that matches the given [`TextMatch`](#textmatch).
+This will search for all `TextInput` elements with a `value` prop and `Picker` or `Switch` elements
+with a `selectedValue` prop and find ones that matches the given [`TextMatch`](#textmatch).
 
 ```js
 import { render } from 'native-testing-library';
 
-const { getByValue } = render(<Input value="About ℹ" onChangeText={() => ({})} />);
+const { getByDisplayValue } = render(<Input value="About ℹ" onChangeText={() => ({})} />);
 
-getByValue(/about/i); // returns the Input node
+getByDisplayValue(/about/i); // returns the Input node
 ```
 
 ### `ByTestId`
@@ -271,7 +271,7 @@ getByValue(/about/i); // returns the Input node
 
 ```typescript
 getByTestId(
-  container: ReactTestRenderer | NativeTestInstance,
+  container: NativeTestInstance,
   match: TextMatch,
   options?: {
     trim?: boolean = true,

docs/api-test-instance.md

@@ -0,0 +1,105 @@
+---
+id: api-test-instance
+title: NativeTestInstance
+sidebar_label: NativeTestInstance
+---
+
+`NativeTestInstance` is a proxied react-test-renderer TestInstance. Not all properties are
+available, so you should only rely on the ones listed in this documentation.
+
+Properties are excluded or overridden in an effort to make it easier to follow the guiding
+principles of testing-library. If there are other assertions you'd like to make, that aren't
+supported by this library there should be no problem running other react-test-renderer tests in the
+same codebase.
+
+> Before assuming you need access to something not exposed, try to ask yourself what you would do if
+> you were using dom testing library.
+>
+> We believe all of the utilities provided by this package allow you to write tests the way you
+> would using that library, so if you're struggling to write a test, try to take a step back and
+> evaluate if you're trying to test implementation details or making an assertion that doesn't map
+> to something your users could do.
+
+## `getProp`
+
+This is simply a helper that allows you to get the value of a native node prop. It is meant to
+mirror the `getAttribute` API in the DOM. You should rarely need to use this method in your tests.
+
+```javascript
+const nativeNode = getByValue('hello world');
+const value = nativeNode.getProp('value');
+
+expect(value).toBe('hello world');
+```
+
+## `findAll`
+
+This method will return you all children nodes that are valid native nodes. **This will not find
+custom components, it will only return core components defined in the preset.** It is meant to be
+similar to `document.querySelectorAll`.
+
+```javascript
+const { container } = render(<MyComponent />);
+const textNodes = container.findAll(node => node.getProp('accessibilityLabel') === 'hello world');
+
+expect(textNodes).toHaveLength(2);
+```
+
+## `type`
+
+This will be the type of the native node. For all queries you can make in this library, this value
+will be a string.
+
+```javascript
+const { findByText } = render(<Text>hello world</Text>);
+
+expect(findByText(/hello world/i).type).toBe('hello world');
+```
+
+## `props`
+
+The props of the element you've queried for. These are meant to be the equivalent of a DOM
+"attribute". You should rarely need to make assertions on these values, so try not to rely heavily
+on using them directly.
+
+```javascript
+const { findByText } = render(<Text style={{}}>hello world</Text>);
+
+console.log(findByText(/hello world/i).props);
+```
+
+## `parentNode`
+
+This will return only valid native node parents. This differs from the react-test-renderer's
+`parent` property in that way. You will not be able to get your implementation components by
+traversing the parents of your tree.
+
+```javascript
+const { findByText } = render(
+  <View>
+    <CustomComponent>
+      <Text>hello world</Text>
+    </CustomComponent>
+  </View>,
+);
+
+expect(findByText(/hello world/i).parentNode.type).toBe('View'); // NOT CustomComponent
+```
+
+## `children`
+
+This will return only valid native node children. This differs from the react-test-renderer's
+children property in that way. You will not be able to get your implementation components by
+traversing the children of your tree.
+
+```javascript
+const { findByTestID } = render(
+  <View testID="my-wrapper">
+    <CustomComponent>
+      <Text>hello world</Text>
+    </CustomComponent>
+  </View>,
+);
+
+expect(findByTestID('my-wrapper').children[0].type).toBe('Text'); // NOT CustomComponent
+```