Skip to content
This repository was archived by the owner on Jul 30, 2020. It is now read-only.

Commit a5b0e05

Browse files
bcarroll22bcarroll22
committed
docs(readme): update readme to include more [ci skip]
1 parent 65bee96 commit a5b0e05

File tree

2 files changed

+174
-3
lines changed

2 files changed

+174
-3
lines changed

‎README.md‎

Lines changed: 130 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
<div align="center">
2-
<h1>native-testing-library (react native)</h1>
2+
<h1>(React) Native Testing Library</h1>
3+
<img
4+
height="80"
5+
width="80"
6+
alt="goat"
7+
src="https://raw.githubusercontent.com/brandonvcarroll/native-testing-library/master/other/mascot.png"
8+
/>
9+
310
<p>Simple and complete React Native testing utilities that encourage good testing practices.</p>
411

512
[**Read The Docs**](https://native-testing-library.com/docs/intro) |
@@ -10,10 +17,130 @@
1017

1118
[![Build Status](https://travis-ci.org/bcarroll22/native-testing-library.svg?branch=master)](https://travis-ci.org/bcarroll22/native-testing-library)
1219
[![Code Coverage](https://img.shields.io/codecov/c/github/bcarroll22/native-testing-library.svg?style=flat-square)](https://codecov.io/github/bcarroll22/native-testing-library)
13-
[![version](https://img.shields.io/npm/v/native-testing-library.svg?style=flat-square)](https://www.npmjs.com/package/native-testing-library)
20+
[![version](https://img.shields.io/npm/v/native-testing-library.svg?style=flat-square)](https://www.npmjs.com/package/native-testing-library)
1421
[![downloads](https://img.shields.io/npm/dm/native-testing-library.svg?style=flat-square)](http://www.npmtrends.com/native-testing-library)
1522
[![MIT License](https://img.shields.io/npm/l/native-testing-library.svg?style=flat-square)](https://github.com/bcarroll22/native-testing-library/blob/master/LICENSE)
16-
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
23+
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
1724

1825
[![Watch on GitHub](https://img.shields.io/github/watchers/bcarroll22/native-testing-library.svg?style=social)](https://github.com/bcarroll22/native-testing-library/watchers)
1926
[![Star on GitHub](https://img.shields.io/github/stars/bcarroll22/native-testing-library.svg?style=social)](https://github.com/bcarroll22/native-testing-library/stargazers)
27+
28+
## The problem
29+
30+
You want to write maintainable tests for your React Native application. You love Kent Dodds' testing
31+
library, and you want to be able to write maintainable tests for your React Native application. You
32+
don't want to use a library that renders components to a fake DOM, and you've had a hard time
33+
finding what you need to write tests using that philosophy in React Native.
34+
35+
## This solution
36+
37+
`native-testing-library` is an implementation of the well-known testing-library API that works for
38+
React Native. The primary goal is to mimic the testing library API as closely as possible while
39+
still accounting for the differences in the platforms.
40+
41+
## Example
42+
43+
```javascript
44+
import React from 'react';
45+
import { Button, Text, TextInput, View } from 'react-native';
46+
import { act, fireEvent, render, wait } from 'native-testing-library';
47+
48+
function Example() {
49+
const [name, setUser] = React.useState('');
50+
const [show, setShow] = React.useState(false);
51+
52+
return (
53+
<View>
54+
<TextInput value={name} onChangeText={setUser} testID="input" />
55+
<Button
56+
title="Print Username"
57+
onPress={() => {
58+
// let's pretend this is making a server request, so it's async
59+
// (you'd want to mock this imaginary request in your unit tests)...
60+
setTimeout(() => {
61+
setShow(!show);
62+
}, Math.floor(Math.random() * 200));
63+
}}
64+
/>
65+
{show && <Text testID="printed-username">{name}</Text>}
66+
</View>
67+
);
68+
}
69+
70+
test('examples of some things', async () => {
71+
const { getByTestId, getByText, queryByTestId, rootInstance } = render(<Example />);
72+
const famousWomanInHistory = 'Ada Lovelace';
73+
74+
const input = getByTestId('input');
75+
fireEvent.changeText(input, famousWomanInHistory);
76+
77+
const button = getByText('Print Username');
78+
fireEvent.press(button);
79+
80+
await wait(() => expect(queryByTestId('printed-username')).toBeTruthy());
81+
82+
expect(getByTestId('printed-username').props.children).toBe(famousWomanInHistory);
83+
expect(rootInstance).toMatchSnapshot();
84+
});
85+
```
86+
87+
> [The more your tests resemble the way your software is used, the more confidence they can give you.](https://twitter.com/kentcdodds/status/977018512689455106)
88+
89+
We try to only expose methods and utilities that encourage you to write tests that closely resemble
90+
how your apps are used.
91+
92+
Utilities are included in this project based on the following guiding principles:
93+
94+
1. Rendering React Native components ultimately creates native views, and those views should be
95+
what you test rather than the React component instances you rendered to make them.
96+
2. In general, test the way your users use your app. There are instances where you'll need to write
97+
unit tests, but try your best to write with this first -- the more your tests resemble the way
98+
your app works, the more confident you'll be with your app.
99+
3. Be responsible, and remember that testing exists to serve you, not the other way around. If the
100+
library isn't working for you, contribute to make it work or do something more intuitive. Make
101+
your tests work for you and your team!
102+
103+
In summary, we believe in the principles of `dom-testing-library` and its companion libraries, and
104+
try to adhere to them as closely as possible. Changes to this library should always consider how
105+
they relate to what's happening in the other libraries in this family of tools.
106+
107+
## Installation
108+
109+
This module should be install as in your project's `devDependencies`:
110+
111+
```
112+
npm install --save-dev native-testing-library
113+
```
114+
115+
You will need `react` and `react-native` installed as _dependencies_ in order to run this project.
116+
117+
## Hooks
118+
119+
You can test hooks out of the box with this package as follows:
120+
121+
```javascript
122+
import { renderHook } from 'native-testing-library';
123+
```
124+
125+
Reads more about hooks on the [docs site](https://native-testing-library.com/docs/api-render-hook).
126+
127+
## Prior art
128+
129+
Huge thanks to Kent C. Dodds for evangelizing this approach to testing. We could have never come up
130+
with this library without him 🙏. Check out his awesome work and learn more about testing with
131+
confidence at [testinghavascript.com](https://testingjavascript.com/) (you won't regret purchasing
132+
it), and of course, use this library's big brother, `react-testing-library` for your DOM
133+
applications as well!
134+
135+
Another huge source of inspiration was the original
136+
[`react-native-testing-library`](https://github.com/callstack/react-native-testing-library) made by
137+
the awesome engineers at [Callstack](https://callstack.com/). Seeing their implementation and how
138+
they solved some of the big gotchas with testing React Native using this philosphy was extremely
139+
helpful. (And if you know anyone looking for some React Native development, be sure to send them
140+
their way 😉.)
141+
142+
Last but not least, the hook testing ability of this library is quite literally the same as
143+
[react-hooks-testing-library](https://github.com/mpeyper/react-hooks-testing-library). The only
144+
reason it was included in this package is because we need you to import render from us, not the
145+
`dom-testing-library`, and that's an important blocker. Some day, maybe we'll try to allow use of
146+
that library with this one somehow.

‎examples/__tests__/docs.js‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
import React from 'react';
2+
import { Button, Text, TextInput, View } from 'react-native';
3+
import { act, fireEvent, render, wait } from '../../src';
4+
5+
function Example() {
6+
const [name, setUser] = React.useState('');
7+
const [show, setShow] = React.useState(false);
8+
9+
return (
10+
<View>
11+
<TextInput value={name} onChangeText={setUser} testID="input" />
12+
<Button
13+
title="Print Username"
14+
onPress={() => {
15+
// let's pretend this is making a server request, so it's async
16+
// (you'd want to mock this imaginary request in your unit tests)...
17+
setTimeout(() => {
18+
setShow(!show);
19+
}, Math.floor(Math.random() * 200));
20+
}}
21+
/>
22+
{show && <Text testID="printed-username">{name}</Text>}
23+
</View>
24+
);
25+
}
26+
27+
test('examples of some things', async () => {
28+
const { getByTestId, getByText, queryByTestId, testInstance } = render(<Example />);
29+
const famousWomanInHistory = 'Ada Lovelace';
30+
31+
// Get form elements by their label text.
32+
// An error will be thrown if one cannot be found (accessibility FTW!)
33+
const input = getByTestId('input');
34+
fireEvent.changeText(input, famousWomanInHistory);
35+
36+
// Get elements by their text, just like a real user does.
37+
const button = getByText('Print Username');
38+
fireEvent.press(button);
39+
40+
await wait(() => expect(queryByTestId('printed-username')).toBeTruthy());
41+
42+
expect(getByTestId('printed-username').props.children).toBe(famousWomanInHistory);
43+
expect(testInstance).toMatchSnapshot();
44+
});

0 commit comments

Comments
 (0)