Detox Helper for CodeceptJS
Testing Mobile Apps on iOS and Android can look like this:
I.setLandscapeOrientation();
I.fillField('#text', 'a new text');
I.see('a new text', '#textValue');
I.dontSeeElement('#createdAndVisibleText');
I.click({ ios: '#GoButton', android: 'Button' });
I.waitForElement('#createdAndVisibleText', 20);
I.seeElement('#createdAndVisibleText');
I.runOnAndroid(() => {
I.click('Save');
I.see('Text Saved', '#message');
});
I.runOnIOS(() => {
I.click('SAVE');
I.see('SAVED!');
});
Example output:
CodeceptJS v3.5.12 #StandWithUkraine
Using test root "/Users/t/Desktop/projects/detox-helper/test"
Helpers: Detox
Plugins: screenshotOnFail
Starter --
[1] Starting recording promises
Timeouts:
12:08:18.693 detox[70751] i org.reactjs.native.example.MyTestApp launched. To watch simulator logs, run:
/usr/bin/xcrun simctl spawn 2A7CB01D-1AAF-4AB6-8236-163E1701D21A log stream --level debug --style compact --predicate 'process == "MyTestApp"'
12:08:20.542 detox[70751] i App started
12:08:20.908 detox[70751] i I see "Welcome to
React Native"
12:08:20.919 detox[70751] i ✔ OK in 17ms
12:08:20.919 detox[70751] i
12:08:20.922 detox[70751] i Get plaform
12:08:21.274 detox[70751] i I grab platform
12:08:21.274 detox[70751] i ios
12:08:21.274 detox[70751] i ✔ OK in 4ms
12:08:21.275 detox[70751] i
12:08:21.310 detox[70751] i
12:08:21.312 detox[70751] i OK | 2 passed // 14s
CodeceptJS provides next features over standard Detox:
- Unified API. The same test can be executed in Appium or Detox. Unified API helps different teams to use the same syntax and easy port tests from one engine to another.
- Interactive pause. When starting/stopping an application takes a long time, debugging and writing tests can be hard. CodeceptJS solves this by pausing an execution and letting you try different commands and locators. With this feature a test can be writtern during one running session.
- One Test For Android and IOS. When application differs on Android and IOS you can provide corresponding system-related locators for both systems. When needed a different code can be executed for Android and IOS keeping it inside the same test.
-
Detox
- Setup
- Configuration
- Parameters
- saveScreenshot
- relaunchApp
- launchApp
- installApp
- shakeDevice
- goBack
- setLandscapeOrientation
- setPortraitOrientation
- grabPlatform
- runOnIOS
- runOnAndroid
- tap
- multiTap
- longPress
- click
- tapByLabel
- clickAtPoint
- see
- dontSee
- seeElement
- checkIfElementExists
- dontSeeElement
- seeElementExists
- dontSeeElementExists
- fillField
- tapReturnKey
- clearField
- appendField
- scrollUp
- scrollDown
- scrollLeft
- scrollRight
- swipeUp
- swipeDown
- swipeLeft
- swipeRight
- wait
- waitForElement
- waitForElementVisible
- waitToHide
- scrollToElement
Extends Helper
This is a wrapper on top of Detox 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 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.
-
Build an application using
detox build
command. -
Install CodeceptJS 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:
"detox": {
"configurations": {
"ios.sim.debug": {
"device": "simulator",
"app": "ios.debug"
}
},
"apps": {
"ios.debug": {
"type": "ios.app",
"binaryPath": "../test/ios/build/Build/Products/Debug-iphonesimulator/MyTestApp.app",
"build": "xcodebuild -workspace ../test/ios/MyTestApp.xcworkspace -scheme MyTestApp -configuration Debug -sdk iphonesimulator -derivedDataPath ../test/ios/build"
}
},
"devices": {
"simulator": {
"type": "ios.simulator",
"device": {
"type": "iPhone 15"
}
}
}
}
Besides Detox configuration, CodeceptJS should also be configured to use Detox.
In codecept.conf.js
enable Detox helper:
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 functionsby
,element
,expect
,waitFor
globally.
config
Saves a screenshot to the output dir
I.saveScreenshot('main-window.png');
-
name
string
Relaunches an application.
I.relaunchApp();
Launches an application. If application instance already exists, use relaunchApp.
I.launchApp();
Installs a configured application. Application is installed by default.
I.installApp();
Shakes the device.
I.shakeDevice();
Goes back on Android
I.goBack(); // on Android only
Switches device to landscape orientation
I.setLandscapeOrientation();
Switches device to portrait orientation
I.setPortraitOrientation();
Grab the device platform
const platform = await I.grabPlatform();
Execute code only on iOS
I.runOnIOS(() => {
I.click('Button');
I.see('Hi, IOS');
});
-
fn
Function a function which will be executed on iOS
Execute code only on Android
I.runOnAndroid(() => {
I.click('Button');
I.see('Hi, Android');
});
-
fn
Function a function which will be executed on android
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
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
-
locator
CodeceptJS.LocatorOrString -
context
(CodeceptJS.LocatorOrString | null) (optional, defaultnull
)
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.
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
-
locator
CodeceptJS.LocatorOrString element to locate -
num
number number of taps -
context
(CodeceptJS.LocatorOrString | null) context element (optional, defaultnull
)
Taps an element and holds for a requested time.
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
-
locator
CodeceptJS.LocatorOrString element to locate -
sec
number number of seconds to hold tap -
context
(CodeceptJS.LocatorOrString | null) context element (optional, defaultnull
)
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
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
-
locator
CodeceptJS.LocatorOrString -
context
(CodeceptJS.LocatorOrString | null) (optional, defaultnull
)
Clicks on an element. Element can be located by its label
The second parameter is a context (id | type | accessibility id) to narrow the search.
I.tapByLabel('Login'); // locate by text
I.tapByLabel('Login', '#nav'); // locate by text inside #nav
-
locator
CodeceptJS.LocatorOrString -
context
(CodeceptJS.LocatorOrString | null) (optional, defaultnull
)
Performs click on element with horizontal and vertical offset. An element is located by text, id, accessibility id.
I.clickAtPoint('Save', 10, 10);
I.clickAtPoint('~save', 10, 10); // locate by accessibility id
-
locator
CodeceptJS.LocatorOrString -
x
number horizontal offset (optional, default0
) -
y
number vertical offset (optional, default0
)
Checks text to be visible. Use second parameter to narrow down the search.
I.see('Record created');
I.see('Record updated', '#message');
I.see('Record deleted', '~message');
-
text
string to check visibility -
context
(CodeceptJS.LocatorOrString | null) element inside which to search for text (optional, defaultnull
)
Checks text not to be visible. Use second parameter to narrow down the search.
I.dontSee('Record created');
I.dontSee('Record updated', '#message');
I.dontSee('Record deleted', '~message');
-
text
string to check invisibility -
context
(CodeceptJS.LocatorOrString | null) element in which to search for text (optional, defaultnull
)
Checks for visibility of an element. Use second parameter to narrow down the search.
I.seeElement('~edit'); // located by accessibility id
I.seeElement('~edit', '#menu'); // element inside #menu
-
locator
CodeceptJS.LocatorOrString element to locate -
context
(CodeceptJS.LocatorOrString | null) context element (optional, defaultnull
)
Checks if an element exists.
I.checkIfElementExists('~edit'); // located by accessibility id
I.checkIfElementExists('~edit', '#menu'); // element inside #menu
-
locator
CodeceptJS.LocatorOrString element to locate -
context
(CodeceptJS.LocatorOrString | null) context element (optional, defaultnull
)
Checks that element is not visible. Use second parameter to narrow down the search.
I.dontSeeElement('~edit'); // located by accessibility id
I.dontSeeElement('~edit', '#menu'); // element inside #menu
-
locator
CodeceptJS.LocatorOrString element to locate -
context
(CodeceptJS.LocatorOrString | null) context element (optional, defaultnull
)
Checks for existence of an element. An element can be visible or not. Use second parameter to narrow down the search.
I.seeElementExists('~edit'); // located by accessibility id
I.seeElementExists('~edit', '#menu'); // element inside #menu
-
locator
CodeceptJS.LocatorOrString element to locate -
context
CodeceptJS.LocatorOrString context element (optional, defaultnull
)
Checks that element not exists. Use second parameter to narrow down the search.
I.dontSeeElementExist('~edit'); // located by accessibility id
I.dontSeeElementExist('~edit', '#menu'); // element inside #menu
-
locator
CodeceptJS.LocatorOrString element to locate -
context
CodeceptJS.LocatorOrString context element (optional, defaultnull
)
Fills in text field in an app. A field can be located by text, accessibility id, id.
I.fillField('Username', 'davert');
I.fillField('~name', 'davert');
I.fillField({ android: 'NAME', ios: 'name' }, 'davert');
-
field
CodeceptJS.LocatorOrString an input element to fill in -
value
string value to fill
Taps return key. A field can be located by text, accessibility id, id.
I.tapReturnKey('Username');
I.tapReturnKey('~name');
I.tapReturnKey({ android: 'NAME', ios: 'name' });
-
field
CodeceptJS.LocatorOrString an input element to fill in
Clears a text field. A field can be located by text, accessibility id, id.
I.clearField('~name');
-
field
CodeceptJS.LocatorOrString an input element to clear
Appends text into the field. A field can be located by text, accessibility id, id.
I.appendField('name', 'davert');
-
field
CodeceptJS.LocatorOrString -
value
string
Scrolls to the top of an element.
I.scrollUp('#container');
-
locator
CodeceptJS.LocatorOrString
Scrolls to the bottom of an element.
I.scrollDown('#container');
-
locator
CodeceptJS.LocatorOrString
Scrolls to the left of an element.
I.scrollLeft('#container');
-
locator
CodeceptJS.LocatorOrString
Scrolls to the right of an element.
I.scrollRight('#container');
-
locator
CodeceptJS.LocatorOrString
Performs a swipe up inside an element.
Can be slow
or fast
swipe.
I.swipeUp('#container');
-
locator
CodeceptJS.LocatorOrString an element on which to perform swipe -
speed
string a speed to perform:slow
orfast
. (optional, default'slow'
)
Performs a swipe up inside an element.
Can be slow
or fast
swipe.
I.swipeUp('#container');
-
locator
CodeceptJS.LocatorOrString an element on which to perform swipe -
speed
string a speed to perform:slow
orfast
. (optional, default'slow'
)
Performs a swipe up inside an element.
Can be slow
or fast
swipe.
I.swipeUp('#container');
-
locator
CodeceptJS.LocatorOrString an element on which to perform swipe -
speed
string a speed to perform:slow
orfast
. (optional, default'slow'
)
Performs a swipe up inside an element.
Can be slow
or fast
swipe.
I.swipeUp('#container');
-
locator
CodeceptJS.LocatorOrString an element on which to perform swipe -
speed
string a speed to perform:slow
orfast
. (optional, default'slow'
)
Waits for number of seconds
I.wait(2); // waits for 2 seconds
-
sec
number number of seconds to wait
Waits for an element to exist on page.
I.waitForElement('#message', 1); // wait for 1 second
-
locator
CodeceptJS.LocatorOrString an element to wait for -
sec
number number of seconds to wait, 5 by default (optional, default5
)
Waits for an element to be visible on page.
I.waitForElementVisible('#message', 1); // wait for 1 second
-
locator
CodeceptJS.LocatorOrString an element to wait for -
sec
number number of seconds to wait (optional, default5
)
Waits an elmenet to become not visible.
I.waitToHide('#message', 2); // wait for 2 seconds
-
locator
CodeceptJS.LocatorOrString an element to wait for -
sec
number number of seconds to wait (optional, default5
)
Scrolls within a scrollable container to an element.
-
targetLocator
CodeceptJS.LocatorOrString Locator of the element to scroll to -
containerLocator
CodeceptJS.LocatorOrString Locator of the scrollable container -
direction
string 'up' or 'down' (optional, default'down'
) -
offset
number Offset for scroll, can be adjusted based on need (optional, default100
)