codeceptjs 3.5.12-beta.3 → 3.5.12-beta.5

package/docs/helpers/Detox.md

@@ -0,0 +1,586 @@
+---
+permalink: /helpers/Detox
+sidebar: auto
+title: Detox
+---
+
+# Detox
+
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## Detox
+
+**Extends Helper**
+
+This is a wrapper on top of [Detox][1] library, aimied to unify testing experience for CodeceptJS framework.
+Detox provides a grey box testing for mobile applications, playing especially good for React Native apps.
+
+Detox plays quite differently from Appium. To establish detox testing you need to build a mobile application in a special way to inject Detox code.
+This why **Detox is grey box testing** solution, so you need an access to application source code, and a way to build and execute it on emulator.
+
+Comparing to Appium, Detox runs faster and more stable but requires an additional setup for build.
+
+### Setup
+
+1.  [Install and configure Detox for iOS][2] and [Android][3]
+2.  [Build an application][4] using `detox build` command.
+3.  Install [CodeceptJS][5] and detox-helper: 
+
+
+    npm i @codeceptjs/detox-helper --save
+
+Detox configuration is required in `package.json` under `detox` section.
+
+If you completed step 1 and step 2 you should have a configuration similar this:
+
+```js
+ "detox": {
+   "configurations": {
+     "ios.sim.debug": {
+       "binaryPath": "ios/build/Build/Products/Debug-iphonesimulator/example.app",
+       "build": "xcodebuild -project ios/example.xcodeproj -scheme example -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build",
+       "type": "ios.simulator",
+       "name": "iPhone 7"
+     }
+   }
+ }
+```
+
+### Configuration
+
+Besides Detox configuration, CodeceptJS should also be configured to use Detox.
+
+In `codecept.conf.js` enable Detox helper:
+
+```js
+helpers: {
+   Detox: {
+     require: '@codeceptjs/detox-helper',
+     configuration: '<detox-configuration-name>', 
+   }   
+}
+```
+
+It's important to specify a package name under `require` section and current detox configuration taken from `package.json`.
+
+Options:
+
+-   `configuration` - a detox configuration name. Required.
+-   `reloadReactNative` - should be enabled for React Native applications.
+-   `reuse` - reuse application for tests. By default, Detox reinstalls and relaunches app.
+-   `registerGlobals` - (default: true) Register Detox helper functions `by`, `element`, `expect`, `waitFor` globally.
+
+### Parameters
+
+-   `config`  
+
+### appendField
+
+Appends text into the field.
+A field can be located by text, accessibility id, id.
+
+```js
+I.appendField('name', 'davert');
+```
+
+#### Parameters
+
+-   `field` **([string][6] \| [object][7])** 
+-   `value` **[string][6]** 
+
+### clearField
+
+Clears a text field.
+A field can be located by text, accessibility id, id.
+
+```js
+I.clearField('~name');
+```
+
+#### Parameters
+
+-   `field` **([string][6] \| [object][7])** an input element to clear
+
+### click
+
+Clicks on an element. 
+Element can be located by its text or id or accessibility id
+
+The second parameter is a context (id | type | accessibility id) to narrow the search.
+
+Same as [tap][8]
+
+```js
+I.click('Login'); // locate by text
+I.click('~nav-1'); // locate by accessibility label
+I.click('#user'); // locate by id
+I.click('Login', '#nav'); // locate by text inside #nav
+I.click({ ios: 'Save', android: 'SAVE' }, '#main'); // different texts on iOS and Android
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** 
+-   `context` **([string][6] \| [object][7] | null)**  (optional, default `null`)
+
+### clickAtPoint
+
+Performs click on element with horizontal and vertical offset.
+An element is located by text, id, accessibility id.
+
+```js
+I.clickAtPoint('Save', 10, 10);
+I.clickAtPoint('~save', 10, 10); // locate by accessibility id
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** 
+-   `x` **[number][9]** horizontal offset (optional, default `0`)
+-   `y` **[number][9]** vertical offset (optional, default `0`)
+
+### dontSee
+
+Checks text not to be visible.
+Use second parameter to narrow down the search.
+
+```js
+I.dontSee('Record created');
+I.dontSee('Record updated', '#message');
+I.dontSee('Record deleted', '~message');
+```
+
+#### Parameters
+
+-   `text` **[string][6]** to check invisibility
+-   `context` **([string][6] \| [object][7] | null)** element in which to search for text (optional, default `null`)
+
+### dontSeeElement
+
+Checks that element is not visible.
+Use second parameter to narrow down the search.
+
+```js
+I.dontSeeElement('~edit'); // located by accessibility id
+I.dontSeeElement('~edit', '#menu'); // element inside #menu
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** element to locate
+-   `context` **([string][6] \| [object][7] | null)** context element (optional, default `null`)
+
+### dontSeeElementExists
+
+Checks that element not exists.
+Use second parameter to narrow down the search.
+
+```js
+I.dontSeeElementExist('~edit'); // located by accessibility id
+I.dontSeeElementExist('~edit', '#menu'); // element inside #menu
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** element to locate
+-   `context` **([string][6] \| [object][7])** context element (optional, default `null`)
+
+### fillField
+
+Fills in text field in an app.
+A field can be located by text, accessibility id, id.
+
+```js
+I.fillField('Username', 'davert');
+I.fillField('~name', 'davert');
+I.fillField({ android: 'NAME', ios: 'name' }, 'davert');
+```
+
+#### Parameters
+
+-   `field` **([string][6] \| [object][7])** an input element to fill in
+-   `value` **[string][6]** value to fill
+
+### goBack
+
+Goes back on Android
+
+```js
+I.goBack(); // on Android only
+```
+
+### installApp
+
+Installs a configured application.
+Application is installed by default.
+
+```js
+I.installApp();
+```
+
+### launchApp
+
+Launches an application. If application instance already exists, use [relaunchApp][10].
+
+```js
+I.launchApp();
+```
+
+### longPress
+
+Taps an element and holds for a requested time.
+
+```js
+I.longPress('Login', 2); // locate by text, hold for 2 seconds
+I.longPress('~nav', 1); // locate by accessibility label, hold for second
+I.longPress('Update', 2, '#menu'); // locate by text inside #menu, hold for 2 seconds
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** element to locate
+-   `sec` **[number][9]** number of seconds to hold tap
+-   `context` **([string][6] \| [object][7] | null)** context element (optional, default `null`)
+
+### multiTap
+
+Multi taps on an element.
+Element can be located by its text or id or accessibility id.
+
+Set the number of taps in second argument.
+Optionally define the context element by third argument.
+
+```js
+I.multiTap('Login', 2); // locate by text
+I.multiTap('~nav', 2); // locate by accessibility label
+I.multiTap('#user', 2); // locate by id
+I.multiTap('Update', 2, '#menu'); // locate by id
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** element to locate
+-   `num` **[number][9]** number of taps
+-   `context` **([string][6] \| [object][7] | null)** context element (optional, default `null`)
+
+### relaunchApp
+
+Relaunches an application.
+
+```js
+I.relaunchApp();
+```
+
+### runOnAndroid
+
+Execute code only on Android
+
+```js
+I.runOnAndroid(() => {
+   I.click('Button');
+   I.see('Hi, Android');
+});
+```
+
+#### Parameters
+
+-   `fn` **[Function][11]** a function which will be executed on android
+
+### runOnIOS
+
+Execute code only on iOS
+
+```js
+I.runOnIOS(() => {
+   I.click('Button');
+   I.see('Hi, IOS');
+});
+```
+
+#### Parameters
+
+-   `fn` **[Function][11]** a function which will be executed on iOS
+
+### saveScreenshot
+
+Saves a screenshot to the output dir
+
+```js
+I.saveScreenshot('main-window.png');
+```
+
+#### Parameters
+
+-   `name` **[string][6]** 
+
+### scrollDown
+
+Scrolls to the bottom of an element.
+
+```js
+I.scrollDown('#container');
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** 
+
+### scrollLeft
+
+Scrolls to the left of an element.
+
+```js
+I.scrollLeft('#container');
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** 
+
+### scrollRight
+
+Scrolls to the right of an element.
+
+```js
+I.scrollRight('#container');
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** 
+
+### scrollUp
+
+Scrolls to the top of an element.
+
+```js
+I.scrollUp('#container');
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** 
+
+### see
+
+Checks text to be visible.
+Use second parameter to narrow down the search.
+
+```js
+I.see('Record created');
+I.see('Record updated', '#message');
+I.see('Record deleted', '~message');
+```
+
+#### Parameters
+
+-   `text` **[string][6]** to check visibility
+-   `context` **([string][6] \| [object][7] | null)** element inside which to search for text (optional, default `null`)
+
+### seeElement
+
+Checks for visibility of an element.
+Use second parameter to narrow down the search.
+
+```js
+I.seeElement('~edit'); // located by accessibility id
+I.seeElement('~edit', '#menu'); // element inside #menu
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** element to locate
+-   `context` **([string][6] \| [object][7] | null)** context element (optional, default `null`)
+
+### seeElementExists
+
+Checks for existence of an element. An element can be visible or not.
+Use second parameter to narrow down the search.
+
+```js
+I.seeElementExists('~edit'); // located by accessibility id
+I.seeElementExists('~edit', '#menu'); // element inside #menu
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** element to locate
+-   `context` **([string][6] \| [object][7])** context element (optional, default `null`)
+
+### setLandscapeOrientation
+
+Switches device to landscape orientation
+
+```js
+I.setLandscapeOrientation();
+```
+
+### setPortraitOrientation
+
+Switches device to portrait orientation
+
+```js
+I.setPortraitOrientation();
+```
+
+### shakeDevice
+
+Shakes the device.
+
+```js
+I.shakeDevice();
+```
+
+### swipeDown
+
+Performs a swipe up inside an element.
+Can be `slow` or `fast` swipe.
+
+```js
+I.swipeUp('#container');
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** an element on which to perform swipe
+-   `speed` **[string][6]** a speed to perform: `slow` or `fast`. (optional, default `'slow'`)
+
+### swipeLeft
+
+Performs a swipe up inside an element.
+Can be `slow` or `fast` swipe.
+
+```js
+I.swipeUp('#container');
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** an element on which to perform swipe
+-   `speed` **[string][6]** a speed to perform: `slow` or `fast`. (optional, default `'slow'`)
+
+### swipeRight
+
+Performs a swipe up inside an element.
+Can be `slow` or `fast` swipe.
+
+```js
+I.swipeUp('#container');
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** an element on which to perform swipe
+-   `speed` **[string][6]** a speed to perform: `slow` or `fast`. (optional, default `'slow'`)
+
+### swipeUp
+
+Performs a swipe up inside an element.
+Can be `slow` or `fast` swipe.
+
+```js
+I.swipeUp('#container');
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** an element on which to perform swipe
+-   `speed` **[string][6]** a speed to perform: `slow` or `fast`. (optional, default `'slow'`)
+
+### tap
+
+Taps on an element. 
+Element can be located by its text or id or accessibility id.
+
+The second parameter is a context element to narrow the search.
+
+Same as [click][12]
+
+```js
+I.tap('Login'); // locate by text
+I.tap('~nav-1'); // locate by accessibility label
+I.tap('#user'); // locate by id
+I.tap('Login', '#nav'); // locate by text inside #nav
+I.tap({ ios: 'Save', android: 'SAVE' }, '#main'); // different texts on iOS and Android
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** 
+-   `context` **([string][6] \| [object][7] | null)**  (optional, default `null`)
+
+### wait
+
+Waits for number of seconds
+
+```js
+I.wait(2); // waits for 2 seconds
+```
+
+#### Parameters
+
+-   `sec` **[number][9]** number of seconds to wait
+
+### waitForElement
+
+Waits for an element to exist on page.
+
+```js
+I.waitForElement('#message', 1); // wait for 1 second
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** an element to wait for
+-   `sec` **[number][9]** number of seconds to wait, 5 by default (optional, default `5`)
+
+### waitForElementVisible
+
+Waits for an element to be visible on page.
+
+```js
+I.waitForElementVisible('#message', 1); // wait for 1 second
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** an element to wait for
+-   `sec` **[number][9]** number of seconds to wait (optional, default `5`)
+
+### waitToHide
+
+Waits an elment to become not visible.
+
+```js
+I.waitToHide('#message', 2); // wait for 2 seconds
+```
+
+#### Parameters
+
+-   `locator` **([string][6] \| [object][7])** an element to wait for
+-   `sec` **[number][9]** number of seconds to wait (optional, default `5`)
+
+[1]: https://github.com/wix/Detox
+
+[2]: https://github.com/wix/Detox/blob/master/docs/Introduction.GettingStarted.md
+
+[3]: https://github.com/wix/Detox/blob/master/docs/Introduction.Android.md
+
+[4]: https://github.com/wix/Detox/blob/master/docs/Introduction.GettingStarted.md#step-4-build-your-app-and-run-detox-tests
+
+[5]: https://codecept.io
+
+[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[8]: #tap
+
+[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+
+[10]: #relaunchApp
+
+[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+
+[12]: #click