fix formatting of API docs

Author: bcarroll22

website/versioned_docs/version-3.0.0/api-act.md

@@ -0,0 +1,13 @@
+---
+id: version-3.0.0-api-act
+title: Act
+sidebar_label: Act
+original_id: api-act
+---
+
+## `act`
+
+This is a light wrapper around the
+[`react-test-renderer` `act` function](https://reactjs.org/docs/test-renderer.html).
+All it does is forward all arguments to the act function if your version of
+react supports `act`.

website/versioned_docs/version-3.0.0/api-async.md

@@ -0,0 +1,112 @@
+---
+id: version-3.0.0-api-async
+title: Async Utilities
+sidebar_label: Async Utilities
+original_id: api-async
+---
+
+Several utilities are provided for dealing with asynchronous code. These can be useful to wait for
+an element to appear or disappear in response to an action. (See the
+[guide to testing disappearance](guide-disappearance.md).)
+
+## `wait`
+
+```typescript
+function wait(
+  callback?: () => void,
+  options?: {
+    timeout?: number;
+    interval?: number;
+  },
+): Promise<void>;
+```
+
+When in need to wait for non-deterministic periods of time you can use `wait`, to wait for your
+expectations to pass. The `wait` function is a small wrapper around the
+[`wait-for-expect`](https://github.com/TheBrainFamily/wait-for-expect) module. Here's a simple
+example:
+
+```javascript
+await wait(() => getByLabelText('username'));
+getByLabelText('username').value = 'chucknorris';
+```
+
+This can be useful if you have a unit test that mocks API calls and you need to wait for your mock
+promises to all resolve.
+
+The default `callback` is a no-op function (used like `await wait()`). This can be helpful if you
+only need to wait for one tick of the event loop (in the case of mocked API calls with promises that
+resolve immediately).
+
+The default `timeout` is `4500ms` which will keep you under
+[Jest's default timeout of `5000ms`](https://facebook.github.io/jest/docs/en/jest-object.html#jestsettimeouttimeout).
+
+The default `interval` is `50ms`. However it will run your callback immediately on the next tick of
+the event loop (in a `setTimeout`) before starting the intervals.
+
+## `waitForElement`
+
+```typescript
+function waitForElement<T>(
+  callback: () => T,
+  options?: {
+    timeout?: number;
+    interval?: number;
+  },
+): Promise<T>;
+```
+
+When you need to wait for elements to appear, you can use `waitForElement`. The `waitForElement`
+function is a similar to `wait`, but is specifically intended to wait for an element to appear.
+Additionally, the result is returned for you to use.
+
+Here's a simple example:
+
+```javascript
+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(() => [
+  getByLabelText('username'),
+  getByLabelText('password'),
+]);
+```
+
+The default `timeout` is `4500ms` which will keep you under
+[Jest's default timeout of `5000ms`](https://facebook.github.io/jest/docs/en/jest-object.html#jestsettimeouttimeout).
+
+The default `interval` is `50ms`. However it will run your callback immediately on the next tick of
+the event loop (in a `setTimeout`) before starting the intervals.
+
+## `waitForElementToBeRemoved`
+
+```typescript
+function waitForElementToBeRemoved<T>(
+  callback: () => T,
+  options?: {
+    timeout?: number;
+    interval?: number;
+  },
+): Promise<T>;
+```
+
+When you need to wait for elements to be removed, or you can use `waitForElementToBeRemoved`. The
+`waitForElementToBeRemoved` function is a similar to `wait`, but is a helper specifically intended
+to wait for an element to be removed from the tree. Similarly to `waitForElement` the result of the
+callback is returned as a Promise, but in most cases you won't need it.
+
+Here's a simple example:
+
+```javascript
+await waitForElementToBeRemoved(() => queryAllByLabelText('list-item'));
+```
+
+The default `timeout` is `4500ms` which will keep you under
+[Jest's default timeout of `5000ms`](https://facebook.github.io/jest/docs/en/jest-object.html#jestsettimeouttimeout).
+
+The default `interval` is `50ms`. However it will run your callback immediately on the next tick of
+the event loop (in a `setTimeout`) before starting the intervals.

website/versioned_docs/version-3.0.0/api-events.md

@@ -0,0 +1,57 @@
+---
+id: version-3.0.0-api-events
+title: Firing Events
+sidebar_label: Firing Events
+original_id: api-events
+---
+
+## Basic example
+
+```javascript
+import { fireEvent, NativeTestEvent, render } from 'native-testing-library';
+
+const { getByText } = render(<Button title="Submit" />);
+fireEvent(getByText(container, 'Submit'), new NativeTestEvent('press'));
+```
+
+## `fireEvent[eventName]`
+
+```typescript
+fireEvent[eventName](node: FiberRoot, eventProperties: NativeTestEvent)
+```
+
+Convenience methods for firing events. Check out
+[src/events.js](https://github.com/testing-library/native-testing-library/blob/master/src/events.js)
+for a full list as well as `validTargets` for every event type.
+
+```javascript
+import { fireEvent, render } from 'native-testing-library';
+
+const { getByText } = render(<Button title="Submit" />);
+fireEvent.press(getByText('Submit'));
+```
+
+**nativeEvent**: React Native tends to put everything relevant to their built-in events on an object
+called nativeEvent. When you fire an event using this library, you will have to build a mock event
+config. You will use this particularly for events like a change event:
+
+```javascript
+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(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 NativeTestEvent('myEvent', { nativeEvent: { value: 'testing' } }),
+);
+```

website/versioned_docs/version-3.0.0/api-helpers.md

@@ -0,0 +1,155 @@
+---
+id: version-3.0.0-api-helpers
+title: Helpers
+sidebar_label: Helpers
+original_id: api-helpers
+---
+
+## Custom Queries
+
+`native-testing-library` exposes some of the helper functions that are used to implement the default
+queries. You can use the helpers to build custom queries. For example, the code below shows a way to
+query your TestInstance by a `style` prop. Note: test files would need to now import `test-utils.js`
+instead of using `native-testing-library` directly. Also note, please never actually implement this
+helper, it's just an example of what's possible.
+
+```javascript
+// test-utils.js
+import * as nativeTestingLib from 'native-testing-library';
+
+const { queryHelpers } = nativeTestingLib;
+
+export const queryByStyle = queryHelpers.queryByProp.bind(null, 'style');
+export const queryAllByStyle = queryHelpers.queryByProp.bind(null, 'style');
+
+export function getAllByStyle(container, styles, ...rest) {
+  const els = queryAllByStyle(container, styles, ...rest);
+  if (!els.length) {
+    throw getElementError(`Unable to find an element by style="${styles}"`, container);
+  }
+  return els;
+}
+
+export function getByStyle(...args) {
+  return queryHelpers.firstResultOrNull(getAllByStyle, ...args);
+}
+
+// re-export with overrides
+export {
+  ...nativeTestingLib,
+  getByStyle,
+  getAllByStyle,
+  queryByStyle,
+  queryAllByStyle,
+};
+```
+
+> **Note**
+>
+> Custom queries can be added to the `render` method by adding `queries` to the options config
+> object. See the render [options](/docs/api-render#render-options).
+
+## `getNodeText`
+
+```typescript
+getNodeText(node: React.ReactElement<any>)
+```
+
+Returns the complete text content of an element, removing any extra whitespace, and joining children
+that are an array. The intention is to treat text in nodes exactly as how it is perceived by users
+in a browser, where any extra whitespace within words in the html code is not meaningful when the
+text is rendered, and all text appears as one cohesive string regardless of the code.
+
+```javascript
+getNodeText(
+  <Text>
+    {`
+    Hello
+      World  !
+    `}
+  </Text>,
+); // "Hello World !"
+```
+
+## `within` and `getQueriesForElement` APIs
+
+`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 { getByLabelText } = render(<LoginModal />);
+const loginForm = getByLabelText('login-form');
+
+within(loginForm).getByPlaceholderText('Username');
+```
+
+## Debugging
+
+When you use any `get` calls in your test cases, the current contents of the `baseElement` get
+printed on the console. For example:
+
+```javascript
+// <Text>Hello world</Text>
+getByText('Goodbye world'); // will fail by throwing error
+```
+
+The above test case will fail, however it prints the state of your React tree being tested, so you
+will get to see:
+
+```
+Unable to find an element with the text: Goodbye world. This could be because the text is broken up by multiple elements. In this case, you can provide a function for your text matcher to make your matcher more flexible.
+Here is the state of your container:
+<Text>
+  Hello World!
+</Text>
+```
+
+Note: Since the debug size can get really large, you can set the limit of debug content to be
+printed via environment variable `DEBUG_PRINT_LIMIT`. The default value is `7000`. You will see
+`...` in the console, when the debug content is stripped off, because of the length you have set or
+due to default size limit. Here's how you might increase this limit when running tests:
+
+```
+DEBUG_PRINT_LIMIT=10000 npm test
+```
+
+This works on macOS/linux, you'll need to do something else for windows. If you'd like a solution
+that works for both, see [`cross-env`](https://www.npmjs.com/package/cross-env)
+
+### `prettyPrint`
+
+This helper function can be used to print out readable representation of the React tree of a node.
+This can be helpful for instance when debugging tests.
+
+It is defined as:
+
+```typescript
+function prettyPrint(node: React.ReactElement<any>, maxLength?: number): string;
+```
+
+It receives the root node to print out, and an optional extra argument to limit the size of the
+resulting string, for cases when it becomes too large.
+
+This function is usually used alongside `console.log` to temporarily print out React trees during
+tests for debugging purposes:
+
+```javascript
+console.log(
+  prettyPrint(
+    <View>
+      <Text>hi</Text>
+    </View>,
+  ),
+);
+// <View>
+//   <Text>
+//     Hi
+//   </Text>
+// </View>
+```
+
+This function is what also powers [the automatic debugging output described above](#debugging).