Skip to content

Commit 7579f75

Browse files
janoshrubosjanoshrubos
committed
docs: detox
1 parent 3096f06 commit 7579f75

File tree

3 files changed

+237
-0
lines changed

3 files changed

+237
-0
lines changed

‎.vitepress/config.js

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,6 +158,10 @@ function getPluginsSidebar() {
158158
text: 'DateTimePicker',
159159
link: '/plugins/datetimepicker',
160160
},
161+
{
162+
text: 'Detox',
163+
link: '/plugins/detox',
164+
},
161165
{ text: 'Email', link: '/plugins/email' },
162166
{
163167
text: 'Fingerprint-Auth',

‎plugins/detox.md

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
---
2+
title: Detox
3+
---
4+
5+
# NativeScript Detox
6+
7+
Easily add [Detox](https://github.com/wix/Detox) end-to-end testing to your NativeScript apps!
8+
9+
| <img src="https://i.imgur.com/apdbINz.gif" /> | <img src="https://i.imgur.com/mWBBF26.gif" /> |
10+
| --------------------------------------------- | --------------------------------------------- |
11+
| iOS Demo | Android Demo |
12+
13+
---
14+
15+
## Table of Contents
16+
17+
1. [Installation](#installation)
18+
2. [Global Setup](#global-setup)
19+
3. [Project Setup](#project-setup)
20+
4. [Usage](#usage)
21+
5. [Running Tests](#running-tests)
22+
6. [Troubleshooting](#troubleshooting)
23+
24+
## Installation
25+
26+
```bash
27+
ns plugin add @nativescript/detox
28+
```
29+
30+
## Global Setup
31+
32+
The full setup requirements can be found [here](https://github.com/wix/Detox/blob/master/docs/Introduction.GettingStarted.md) but the minimal setup steps are as follows:
33+
34+
### Install Detox command line tools (`detox-cli`)
35+
36+
```bash
37+
npm install -g detox-cli
38+
```
39+
40+
### Install [applesimutils](https://github.com/wix/AppleSimulatorUtils) (iOS)
41+
42+
```bash
43+
brew tap wix/brew
44+
brew install applesimutils
45+
```
46+
47+
## Project Setup
48+
49+
### Install the Detox package to your NativeScript project
50+
51+
```bash
52+
npm install detox --save-dev
53+
```
54+
55+
### Install Jest
56+
57+
```bash
58+
npm install jest jest-cli jest-circus --save-dev --no-package-lock
59+
```
60+
61+
### Initialize Detox
62+
63+
```bash
64+
detox init -r jest
65+
```
66+
67+
If things go well, you should to have this set up:
68+
69+
- An `e2e/` folder in your project root
70+
- An `e2e/config.json` file; [example](https://github.com/wix/Detox/blob/master/examples/demo-react-native-jest/e2e/config.json)
71+
- An `e2e/environment.js` file; [example](https://github.com/wix/Detox/blob/master/examples/demo-react-native-jest/e2e/environment.js)
72+
- An `e2e/firstTest.e2e.js` file with content similar to [this](https://github.com/wix/Detox/blob/master/examples/demo-react-native-jest/e2e/app-hello.e2e.js).
73+
74+
There should also be a file called `.detoxrc.json` in your project root.
75+
76+
### Configure Detox
77+
78+
Detox must be configued to know the ___location of the iOS and Android app binary as well as what emulator/simulator to use.
79+
80+
Open `.detoxrc.json` and make the following modifications under `configurations` for iOS and Android.
81+
82+
- `binaryPath`: Specify the ___location of the app binary (probably something like below).
83+
84+
- iOS: `platforms/ios/build/Debug-iphonesimulator/[APP_NAME].app`
85+
- Android: `platforms/android/app/build/outputs/apk/debug/app-debug.apk`
86+
87+
- `build`: Specify the build command for iOS and Android.
88+
89+
- iOS: `ns build ios`
90+
- Android: `ns build android --detox`
91+
92+
- `device`:
93+
- iOS: `"type": "iPhone 11"`
94+
- Android: `"avdName": "Pixel_3a_API_30_1"` (use `emulator -list-avds` to list Android emulators)
95+
96+
Here is a full example of a Detox configuration:
97+
98+
```json
99+
{
100+
"testRunner": "jest",
101+
"runnerConfig": "e2e/config.json",
102+
"configurations": {
103+
"ios": {
104+
"binaryPath": "platforms/ios/build/Debug-iphonesimulator/[APP_NAME].app",
105+
"build": "ns build ios",
106+
"type": "ios.simulator",
107+
"device": {
108+
"type": "iPhone 11"
109+
}
110+
},
111+
"android": {
112+
"binaryPath": "platforms/android/app/build/outputs/apk/debug/app-debug.apk",
113+
"build": "ns build android --detox",
114+
"type": "android.emulator",
115+
"device": {
116+
"avdName": "Pixel_3a_API_30_1"
117+
}
118+
}
119+
}
120+
}
121+
```
122+
123+
**NOTE:** A default NativeScript Android project uses 17 as the minimum SDK, but Detox requires >=18. Remove or modify the `minSdkVersion` in your `App_Resources/Android/app.gradle`.
124+
125+
## Usage
126+
127+
Read through [this tutorial](https://github.com/wix/Detox/blob/master/docs/Introduction.WritingFirstTest.md) written by Detox about writing your first test. Nearly all of the things specified towards React Native apps also apply to NativeScript apps.
128+
129+
Get started by opening the default test scenario in `e2e/firstTest.e2e.js`.
130+
131+
```javascript
132+
describe('Example', () => {
133+
beforeEach(async () => {
134+
await device.reloadReactNative()
135+
})
136+
137+
it('should have welcome screen', async () => {
138+
await expect(element(by.text('Sergio'))).toBeVisible()
139+
})
140+
})
141+
```
142+
143+
This example creates a testing scenario called `Example` and has a single test inside of it called `should have welcome screen`.
144+
145+
### Matchers
146+
147+
Detox uses [matchers](https://github.com/wix/Detox/blob/master/docs/APIRef.Matchers.md) to find elements in your UI to interact with such as `by.label()` or `by.text()`.
148+
149+
You can use the `automationText` property to find your UI elements by a unique label in NativeScript.
150+
151+
Example `by.label()`:
152+
153+
```xml
154+
<Button text="Tap Me!" automationText="testButton" />
155+
```
156+
157+
```javascript
158+
await element(by.label('testButton')).tap()
159+
```
160+
161+
### Actions
162+
163+
Once you find your UI element you can use an [action](https://github.com/wix/Detox/blob/master/docs/APIRef.ActionsOnElement.md) on it such as `tap()` to simulate user interaction.
164+
165+
You should now be able to write tests to simulate user behavior and test for expected results.
166+
167+
## Running Tests
168+
169+
### Building
170+
171+
Build your app for testing using the following command:
172+
173+
```bash
174+
detox build -c ios|android
175+
```
176+
177+
### Testing
178+
179+
Run your tests with the folling command:
180+
181+
```bash
182+
detox test -c ios|android
183+
```
184+
185+
**NOTE:** If using an Android emulator, Detox will disable animations when the tests are ran. Animations will remain disabled after they are finished. This can be very annoying when you are actively developing. You can re-enable animations by running this helper script from your project's directory `./node_modules/.bin/enable-animations`.
186+
187+
To make this even easier I would suggest adding these scripts to your `package.json`.
188+
189+
```json
190+
{
191+
"scripts": {
192+
"e2e:android:build": "detox build -c android",
193+
"e2e:android:test": "detox test -c android && ./node_modules/.bin/enable-animations",
194+
"e2e:ios:build": "detox build -c ios",
195+
"e2e:ios:test": "detox test -c ios"
196+
}
197+
}
198+
```
199+
200+
Now to build and run tests you would run:
201+
202+
Android:
203+
204+
```bash
205+
npm run e2e:android:build
206+
npm run e2e:android:test
207+
```
208+
209+
iOS:
210+
211+
```bash
212+
npm run e2e:ios:build
213+
npm run e2e:ios:test
214+
```
215+
216+
## Troubleshooting
217+
218+
Detox requires a minimum SDK version of 18, so if you get the following error, change the `minSdkVersion` to 18 in `App_Resources/Android/app.gradle`.
219+
220+
```bash
221+
Execution failed for task ':app:processDebugAndroidTestManifest'.
222+
Manifest merger failed : uses-sdk:minSdkVersion 17 cannot be smaller than version 18 declared in library [com.wix:detox:17.6.1] /Users/user/.gradle/caches/transforms-2/files-2.1/91a3acd87d710d1913b266ac114d7001/jetified-detox-17.6.1/AndroidManifest.xml as the library might be using APIs not available in 17
223+
Suggestion: use a compatible library with a minSdk of at most 17,
224+
or increase this project's minSdk version to at least 18,
225+
or use tools:overrideLibrary="com.wix.detox" to force usage (may lead to runtime failures)
226+
227+
Command ./gradlew failed with exit code 1
228+
```
229+
230+
## License
231+
232+
Apache License Version 2.0

‎plugins/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ title: Plugins
88
- [@nativescript/brightness](brightness)
99
- [@nativescript/camera](camera)
1010
- [@nativescript/datetimepicker](datetimepicker)
11+
- [@nativescript/detox](detox)
1112
- [@nativescript/email](email)
1213
- [@nativescript/fingerprint-auth](fingerprint-auth)
1314
- [@nativescript/geolocation](geolocation)

0 commit comments

Comments
 (0)