codeceptjs 4.2.1 → 4.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -3
- package/docs/ai.md +1 -1
- package/docs/alternative-browsers.md +59 -4
- package/docs/api.md +13 -13
- package/docs/assertions.md +6 -6
- package/docs/best.md +1 -1
- package/docs/bootstrap.md +1 -1
- package/docs/data.md +8 -8
- package/docs/helpers/ApiDataFactory.md +2 -2
- package/docs/helpers/Appium.md +2 -2
- package/docs/helpers/Decision.md +1 -1
- package/docs/helpers/Detox.md +1 -1
- package/docs/helpers/ExpectHelper.md +1 -1
- package/docs/helpers/FileSystem.md +1 -1
- package/docs/helpers/GraphQL.md +1 -1
- package/docs/helpers/GraphQLDataFactory.md +2 -2
- package/docs/helpers/JSONResponse.md +1 -1
- package/docs/helpers/Kitesurf.md +1 -1
- package/docs/helpers/Lightpanda.md +1837 -9
- package/docs/helpers/MockRequest.md +1 -1
- package/docs/helpers/Moli.md +1956 -0
- package/docs/helpers/Obscura.md +1 -1
- package/docs/helpers/Playwright.md +2 -2
- package/docs/helpers/Puppeteer.md +3 -3
- package/docs/helpers/REST.md +1 -1
- package/docs/helpers/WebDriver.md +1 -1
- package/docs/installation.md +19 -1
- package/docs/lint.md +111 -0
- package/docs/mobile.md +3 -2
- package/docs/mobilewright.md +166 -0
- package/docs/parallel.md +1 -1
- package/docs/playwright.md +5 -5
- package/docs/plugins/aiTrace.md +1 -1
- package/docs/plugins/autoDelay.md +1 -1
- package/docs/plugins/customLocator.md +1 -1
- package/docs/plugins/customReporter.md +1 -1
- package/docs/plugins/junitReporter.md +2 -2
- package/docs/plugins/pageInfo.md +1 -1
- package/docs/plugins/pauseOnFail.md +1 -1
- package/docs/plugins/retryFailedStep.md +1 -1
- package/docs/plugins/screenshotOnFail.md +1 -1
- package/docs/plugins/stepTimeout.md +1 -1
- package/docs/plugins.md +10 -10
- package/docs/puppeteer.md +4 -4
- package/docs/timeouts.md +5 -5
- package/docs/webdriver.md +8 -8
- package/lib/aria.js +1 -0
- package/lib/codecept.js +1 -1
- package/lib/command/run-multiple.js +7 -2
- package/lib/container.js +1 -1
- package/lib/helper/ApiDataFactory.js +1 -1
- package/lib/helper/Appium.js +1 -1
- package/lib/helper/Decision.js +1 -1
- package/lib/helper/GraphQLDataFactory.js +1 -1
- package/lib/helper/Moli.js +125 -0
- package/lib/helper/Playwright.js +1 -1
- package/lib/helper/Puppeteer.js +3 -3
- package/lib/helper/WebDriver.js +3 -6
- package/lib/mocha/asyncWrapper.js +14 -3
- package/lib/mocha/cli.js +2 -2
- package/lib/mocha/index.js +1 -2
- package/lib/mocha/suite.js +1 -1
- package/lib/mocha/test.js +2 -2
- package/lib/mocha/ui.js +3 -3
- package/lib/plugin/auth.js +3 -0
- package/lib/plugin/junitReporter.js +21 -12
- package/lib/plugin/pause.js +1 -1
- package/lib/recorder.js +20 -2
- package/lib/step/func.js +1 -1
- package/lib/step/helper.js +1 -1
- package/lib/workers.js +15 -0
- package/package.json +31 -34
- package/typings/promiseBasedTypes.d.ts +112 -6
- package/typings/types.d.ts +112 -6
package/docs/helpers/Obscura.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
permalink: /helpers/
|
|
2
|
+
permalink: /helpers/playwright
|
|
3
3
|
editLink: false
|
|
4
4
|
sidebar: auto
|
|
5
5
|
title: Playwright
|
|
@@ -2992,7 +2992,7 @@ Set current page
|
|
|
2992
2992
|
|
|
2993
2993
|
[27]: https://playwright.dev/docs/api/class-locator#locator-is-disabled
|
|
2994
2994
|
|
|
2995
|
-
[28]: https://codecept.io/helpers/
|
|
2995
|
+
[28]: https://codecept.io/helpers/file-system
|
|
2996
2996
|
|
|
2997
2997
|
[29]: https://playwright.dev/docs/api/class-apirequestcontext#api-request-context-get
|
|
2998
2998
|
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
permalink: /helpers/
|
|
2
|
+
permalink: /helpers/puppeteer
|
|
3
3
|
editLink: false
|
|
4
4
|
sidebar: auto
|
|
5
5
|
title: Puppeteer
|
|
@@ -2606,7 +2606,7 @@ Set current page
|
|
|
2606
2606
|
|
|
2607
2607
|
[1]: https://github.com/puppeteer/puppeteer
|
|
2608
2608
|
|
|
2609
|
-
[2]: https://codecept.io/helpers/
|
|
2609
|
+
[2]: https://codecept.io/helpers/puppeteer-firefox
|
|
2610
2610
|
|
|
2611
2611
|
[3]: https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target
|
|
2612
2612
|
|
|
@@ -2642,7 +2642,7 @@ Set current page
|
|
|
2642
2642
|
|
|
2643
2643
|
[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined
|
|
2644
2644
|
|
|
2645
|
-
[20]: https://codecept.io/helpers/
|
|
2645
|
+
[20]: https://codecept.io/helpers/file-system
|
|
2646
2646
|
|
|
2647
2647
|
[21]: https://pptr.dev/guides/network-interception
|
|
2648
2648
|
|
package/docs/helpers/REST.md
CHANGED
package/docs/installation.md
CHANGED
|
@@ -97,7 +97,7 @@ export const config = {
|
|
|
97
97
|
}
|
|
98
98
|
```
|
|
99
99
|
|
|
100
|
-
See [Alternative Browser Engines](/alternative-browsers) for connection modes and limitations, and the [Obscura helper reference](/helpers/
|
|
100
|
+
See [Alternative Browser Engines](/alternative-browsers) for connection modes and limitations, and the [Obscura helper reference](/helpers/obscura) for every option.
|
|
101
101
|
|
|
102
102
|
## Lightpanda (experimental)
|
|
103
103
|
|
|
@@ -115,6 +115,22 @@ export const config = {
|
|
|
115
115
|
|
|
116
116
|
See [Alternative Browser Engines](/alternative-browsers) for running an existing Playwright suite on Lightpanda.
|
|
117
117
|
|
|
118
|
+
## Moli (experimental)
|
|
119
|
+
|
|
120
|
+
Moli is a headless browser for automation that runs your app's JavaScript in V8 and skips layout and painting. Install it following the [official instructions](https://github.com/lexmount/moli#direct-installation), then enable the helper:
|
|
121
|
+
|
|
122
|
+
```js
|
|
123
|
+
export const config = {
|
|
124
|
+
helpers: {
|
|
125
|
+
Moli: {
|
|
126
|
+
url: 'http://localhost:3000',
|
|
127
|
+
},
|
|
128
|
+
},
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
See [Alternative Browser Engines](/alternative-browsers) for running an existing Playwright suite on Moli.
|
|
133
|
+
|
|
118
134
|
## Appium (mobile)
|
|
119
135
|
|
|
120
136
|
Native iOS and Android testing. Appium speaks the WebDriver protocol, so CodeceptJS drives it through `webdriverio`:
|
|
@@ -134,6 +150,8 @@ appium
|
|
|
134
150
|
|
|
135
151
|
You'll also need the Android SDK and an emulator or device, or Xcode and a simulator or device (or a device-cloud account). Set `platformName`, `deviceName`, and `app` in the helper config — see [Mobile Testing](/mobile).
|
|
136
152
|
|
|
153
|
+
For mobile tests without an Appium server, see the experimental [Mobilewright helper](/mobilewright): it drives devices directly via adb/mobilecli and reads the accessibility tree.
|
|
154
|
+
|
|
137
155
|
## API testing
|
|
138
156
|
|
|
139
157
|
REST and GraphQL tests need no browser — the helpers are built in (they use `axios`, already a dependency):
|
package/docs/lint.md
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
---
|
|
2
|
+
permalink: /lint
|
|
3
|
+
title: Linting
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Linting
|
|
7
|
+
|
|
8
|
+
CodeceptJS tests have well-known smell patterns: fixed sleeps instead of waits, `if` branches that make tests non-deterministic, raw `fetch()` calls that bypass test steps and reports, plain-text passwords printed into logs, missing `await` on grabbers, and leftover `pause()` or `.only` from debugging sessions.
|
|
9
|
+
|
|
10
|
+
[`@codeceptjs/lint`](https://github.com/codeceptjs/lint) catches all of them statically. It reads tests, page objects and helpers as an AST — CodeceptJS itself doesn't need to be installed and no browser is started.
|
|
11
|
+
|
|
12
|
+
## Usage
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npx @codeceptjs/lint # files from codecept.conf.js in the current directory
|
|
16
|
+
npx @codeceptjs/lint tests/ pages/login.js # explicit paths
|
|
17
|
+
npx @codeceptjs/lint -r no-pause -r no-only # only these rules (or --rules no-pause,no-only)
|
|
18
|
+
npx @codeceptjs/lint rules # list all rules
|
|
19
|
+
npx @codeceptjs/lint --json # findings as JSON
|
|
20
|
+
npx @codeceptjs/lint -c e2e/codecept.conf.js # config in another directory
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Each finding is printed on one line:
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
checkout_test.js:4:3 error no-fixed-wait I.wait() sleeps unconditionally. Wait for a condition: I.waitForElement / I.waitForText / I.see
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Exit codes: `0` — no errors (warnings allowed), `1` — errors found, `2` — bad input or a file that can't be parsed.
|
|
30
|
+
|
|
31
|
+
Without paths, the linter reads `codecept.conf.js` (or `.ts`, `.cjs`, `.mjs`) and lints files matched by `tests`, local files from `include` (page objects, steps file) and helpers loaded with `require`.
|
|
32
|
+
|
|
33
|
+
## Rules
|
|
34
|
+
|
|
35
|
+
| Rule | Default | Detects |
|
|
36
|
+
| --- | --- | --- |
|
|
37
|
+
| `no-fixed-wait` | error | `I.wait(5)` with a number. Use `I.waitForElement`, `I.waitForText`, `I.see` |
|
|
38
|
+
| `no-sleep` | error | `setTimeout`, including `window.setTimeout`, `await new Promise(r => setTimeout(r, ms))` and `timers/promises`, outside helpers |
|
|
39
|
+
| `no-if-in-test` | error | `if` inside a Scenario or hook. Use `tryTo()` from `codeceptjs/effects` |
|
|
40
|
+
| `no-fetch` | error | `fetch()` outside helpers. Use the REST helper: `I.sendGetRequest`, `I.sendPostRequest` |
|
|
41
|
+
| `no-console` | warn | `console.*` outside helpers. Use `I.say()` |
|
|
42
|
+
| `no-only` | error on CI, warn locally | `Scenario.only`, `Feature.only`, `Data(...).only` |
|
|
43
|
+
| `no-pause` | error on CI, warn locally | `pause()` |
|
|
44
|
+
| `no-skip` | warn | `Scenario.skip`, `Feature.skip`, `xScenario`, `xFeature` |
|
|
45
|
+
| `secret-credentials` | error | `I.fillField` on a password, token, secret or API key field, or such a `process.env.*` passed to `I.*`, without `secret()` |
|
|
46
|
+
| `await-grab` | error | `I.grab*()` assigned or used without `await` |
|
|
47
|
+
| `no-actor-in-helper` | error | `I` inside a class extending `Helper`. Use `this.helpers[...]` |
|
|
48
|
+
| `raw-browser-in-test` | warn | `I.use*To`, `I.executeScript` in a Scenario. Move it into a helper or page object |
|
|
49
|
+
|
|
50
|
+
"On CI" means the `CI` environment variable is set, which every CI provider does. Locally `pause()` and `.only` stay warnings, so debugging stubs don't fail the lint.
|
|
51
|
+
|
|
52
|
+
## Configuration
|
|
53
|
+
|
|
54
|
+
Set rule levels in a `lint` section of `codecept.conf.js`:
|
|
55
|
+
|
|
56
|
+
```js
|
|
57
|
+
export const config = {
|
|
58
|
+
tests: './*_test.js',
|
|
59
|
+
lint: {
|
|
60
|
+
rules: { 'no-if-in-test': 'warn', 'raw-browser-in-test': 'off' },
|
|
61
|
+
},
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Levels are `error`, `warn` or `off`.
|
|
66
|
+
|
|
67
|
+
To allow a single case, suppress it inline — the rule id is required:
|
|
68
|
+
|
|
69
|
+
```js
|
|
70
|
+
I.wait(1) // codeceptjs-lint-disable-line no-fixed-wait
|
|
71
|
+
|
|
72
|
+
// codeceptjs-lint-disable-next-line no-fixed-wait
|
|
73
|
+
I.wait(1)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
TypeScript is read with Node's type stripping (Node 22.13+). Files that use `enum` or `namespace` are reported as parse errors. A TypeScript config that imports `.js` paths of `.ts` files (the tsx/esbuild convention) can't be loaded by plain Node; if the project has `tsx` installed, the linter registers its loader automatically, otherwise pass paths explicitly.
|
|
77
|
+
|
|
78
|
+
## CI
|
|
79
|
+
|
|
80
|
+
```yaml
|
|
81
|
+
- run: npx @codeceptjs/lint
|
|
82
|
+
- run: npx codeceptjs run
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
## Blocking Bad Edits by an AI Agent
|
|
86
|
+
|
|
87
|
+
The linter can check an agent's edit before it lands. Add a `PreToolUse` hook to `.claude/settings.json`:
|
|
88
|
+
|
|
89
|
+
```json
|
|
90
|
+
{
|
|
91
|
+
"hooks": {
|
|
92
|
+
"PreToolUse": [
|
|
93
|
+
{
|
|
94
|
+
"matcher": "Write|Edit|MultiEdit",
|
|
95
|
+
"hooks": [{ "type": "command", "command": "npx @codeceptjs/lint --hook claude" }]
|
|
96
|
+
}
|
|
97
|
+
]
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
The hook checks only files the config lints. It builds the file as it would look after the edit, and blocks the edit only when it adds a new error. Errors already in the file and warnings never block, so an agent can still add a `pause()` stub or touch a legacy test. If the hook fails, the edit is allowed. See [Agentic Testing](/agents/) for the full agent toolkit.
|
|
103
|
+
|
|
104
|
+
## API
|
|
105
|
+
|
|
106
|
+
```js
|
|
107
|
+
import Linter from '@codeceptjs/lint'
|
|
108
|
+
|
|
109
|
+
const linter = await Linter.load('codecept.conf.js')
|
|
110
|
+
for (const file of linter.files()) console.log(linter.lintFile(file))
|
|
111
|
+
```
|
package/docs/mobile.md
CHANGED
|
@@ -114,7 +114,7 @@ Initialize CodeceptJS with `init` command:
|
|
|
114
114
|
npx codeceptjs init
|
|
115
115
|
```
|
|
116
116
|
|
|
117
|
-
Select [Appium helper](https://codecept.io/helpers/
|
|
117
|
+
Select [Appium helper](https://codecept.io/helpers/appium/) when asked.
|
|
118
118
|
|
|
119
119
|
```sh
|
|
120
120
|
? What helpers do you want to use?
|
|
@@ -207,7 +207,7 @@ There are mobile-only methods like:
|
|
|
207
207
|
* `hideDeviceKeyboard`,
|
|
208
208
|
* `seeAppIsInstalled`, `installApp`, `removeApp`, `seeAppIsNotInstalled` - Android only
|
|
209
209
|
|
|
210
|
-
and [others](https://codecept.io/helpers/
|
|
210
|
+
and [others](https://codecept.io/helpers/appium/).
|
|
211
211
|
|
|
212
212
|
## Locating Elements
|
|
213
213
|
|
|
@@ -231,6 +231,7 @@ Accessibility id is recommended to use for locating element, as it rarely change
|
|
|
231
231
|
* For [React Native for Android see our special guide](mobile-react-native-locators.md).
|
|
232
232
|
|
|
233
233
|
> If you test React Native application, consider using [Detox helper](/detox) for faster tests.
|
|
234
|
+
> If you want mobile tests without an Appium server at all, consider the experimental [Mobilewright helper](/mobilewright).
|
|
234
235
|
|
|
235
236
|
Add `~` prefix to search for element by its accessibility id:
|
|
236
237
|
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
---
|
|
2
|
+
permalink: /mobilewright
|
|
3
|
+
title: Mobile Testing with Mobilewright
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
> Warning! Mobilewright support in CodeceptJS is experimental. Please try it and help us to test it and improve it. [See Mobilewright helper repository](https://github.com/codeceptjs/mobilewright-helper).
|
|
7
|
+
|
|
8
|
+
[Appium](/mobile) is the default choice for mobile testing with CodeceptJS, but it requires a running Appium server and slow UI-dump based automation. [Mobilewright](https://mobilewright.dev) takes a different approach: it talks to simulators, emulators and real devices directly via adb (Android) and mobilecli (iOS), and reads the accessibility tree instead of taking UI snapshots.
|
|
9
|
+
|
|
10
|
+
**Pros** (vs Appium):
|
|
11
|
+
|
|
12
|
+
* no Appium server, no WebDriver — a device and `adb` is all you need
|
|
13
|
+
* fast startup: a full suite of 4 scenarios runs in about a minute, ~7-10s per test including app installation
|
|
14
|
+
* Playwright-like locators: `{ role: 'button', name: 'Sign In' }`, test ids, accessibility labels, and human-style "label next to the field" matching
|
|
15
|
+
* same locator conventions as the Appium helper, so most tests move between the two helpers unchanged
|
|
16
|
+
* interactive [pause](/basics#pause), auto-retries and other CodeceptJS features work out of the box
|
|
17
|
+
|
|
18
|
+
**Cons**:
|
|
19
|
+
|
|
20
|
+
* experimental (v0.1.x), the API may change
|
|
21
|
+
* no XPath or CSS locators — only accessibility-based ones
|
|
22
|
+
* text on screen ≠ text in the accessibility tree: some visible messages can't be asserted by text (common for React Native error labels)
|
|
23
|
+
* iOS + React Native: taps may not reach RN controls (known mobilecli issue); Android works
|
|
24
|
+
|
|
25
|
+
CodeceptJS allows you to try different options and choose the one which works best for you. If Mobilewright covers your app, tests run dramatically faster than with Appium.
|
|
26
|
+
|
|
27
|
+
## Installation
|
|
28
|
+
|
|
29
|
+
Requirements: Node.js 22.12+, CodeceptJS 4, a booted simulator or emulator, or a connected device.
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
npm i @codeceptjs/mobilewright --save-dev
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Check your environment with one command:
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
npx mobilewright doctor
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
It reports Node.js, mobilecli versions, connected devices and common misconfigurations. List available devices:
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
npx mobilewright devices
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Configuration
|
|
48
|
+
|
|
49
|
+
```js
|
|
50
|
+
exports.config = {
|
|
51
|
+
tests: './*_test.js',
|
|
52
|
+
output: './output',
|
|
53
|
+
helpers: {
|
|
54
|
+
Mobilewright: {
|
|
55
|
+
require: '@codeceptjs/mobilewright',
|
|
56
|
+
platform: 'android', // or 'ios'
|
|
57
|
+
app: 'com.saucelabs.mydemoapp.rn', // package name (Android) or bundle id (iOS)
|
|
58
|
+
installApps: './MyDemoApp.apk', // installed before tests
|
|
59
|
+
actionTimeout: 10000,
|
|
60
|
+
waitForTimeout: 10000,
|
|
61
|
+
animations: 'off', // disables system animations on device
|
|
62
|
+
},
|
|
63
|
+
},
|
|
64
|
+
plugins: {
|
|
65
|
+
screenshot: { enabled: true },
|
|
66
|
+
retryFailedStep: { enabled: true },
|
|
67
|
+
},
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
| Option | Default | Description |
|
|
72
|
+
| --- | --- | --- |
|
|
73
|
+
| `platform` | required | `ios` or `android` |
|
|
74
|
+
| `app` | — | bundle id (iOS) or package name (Android) of the app under test |
|
|
75
|
+
| `installApps` | — | path or list of paths to `.apk`, `.app` or `.ipa` files installed before tests |
|
|
76
|
+
| `deviceId` | first booted device | UDID or serial of the device |
|
|
77
|
+
| `deviceName` | — | string or RegExp matched against device names |
|
|
78
|
+
| `url` | — | URL of a running mobilecli server; when set, the helper does not start one |
|
|
79
|
+
| `restart` | `'app'` | `'app'` relaunches the app before every test, `'session'` launches it once, `false` never launches it |
|
|
80
|
+
| `animations` | unchanged | `'off'` disables system animations |
|
|
81
|
+
|
|
82
|
+
The helper starts and stops a mobilecli server automatically; with `restart: 'app'` (default) the app is relaunched before every test, so no `Before()` hook is needed.
|
|
83
|
+
|
|
84
|
+
## Locators
|
|
85
|
+
|
|
86
|
+
Mobilewright reads the accessibility tree. Locators follow the [Appium helper](/mobile) conventions:
|
|
87
|
+
|
|
88
|
+
| Locator | Finds |
|
|
89
|
+
| --- | --- |
|
|
90
|
+
| `'~login'` | test id, then accessibility label |
|
|
91
|
+
| `'#login'` | test id; on Android also matches `com.app:id/login` |
|
|
92
|
+
| `{ role: 'button', name: 'Sign In' }` | element by role and accessible name |
|
|
93
|
+
| `{ label }`, `{ text }`, `{ placeholder }`, `{ testId }` | the matching attribute; `text` accepts a RegExp |
|
|
94
|
+
| `{ android: '#a', ios: '~b' }` | a different locator per platform |
|
|
95
|
+
|
|
96
|
+
For `fillField` a plain name matches a text field by its accessibility label, its placeholder, or **the text label displayed next to the field** — the way a human reads a form. XPath and CSS are not supported and fail with an error suggesting a supported locator.
|
|
97
|
+
|
|
98
|
+
## A Test
|
|
99
|
+
|
|
100
|
+
A test against the [Sauce Labs My Demo App](https://github.com/saucelabs/my-demo-app-rn) (React Native):
|
|
101
|
+
|
|
102
|
+
```js
|
|
103
|
+
import { secret } from 'codeceptjs'
|
|
104
|
+
|
|
105
|
+
Feature('Sauce Labs Store')
|
|
106
|
+
|
|
107
|
+
Scenario('Open a product and add it to cart', ({ I }) => {
|
|
108
|
+
I.waitForText('Products', 30)
|
|
109
|
+
I.click('Sauce Labs Backpack') // click by visible text
|
|
110
|
+
I.waitForElement('~Add To Cart button', 15)
|
|
111
|
+
I.click('~Add To Cart button') // ~ = accessibility id / label
|
|
112
|
+
I.see('1', '~cart badge')
|
|
113
|
+
I.saveElementScreenshot('~cart badge', 'cart-badge.png') // element screenshot
|
|
114
|
+
})
|
|
115
|
+
|
|
116
|
+
Scenario('Deep link and fill fields by label', ({ I }) => {
|
|
117
|
+
I.waitForText('Products', 30)
|
|
118
|
+
I.amOnPage('mydemoapprn://login') // deep link
|
|
119
|
+
I.fillField('Username', 'bob@example.com') // found by the label next to the field
|
|
120
|
+
I.fillField('Password', secret('10203040')) // secret() keeps the password out of logs
|
|
121
|
+
I.click('~Login button')
|
|
122
|
+
I.waitForText('Products', 15)
|
|
123
|
+
})
|
|
124
|
+
|
|
125
|
+
Scenario('Rotate the screen', ({ I }) => {
|
|
126
|
+
I.setOrientation('LANDSCAPE')
|
|
127
|
+
I.seeOrientationIs('LANDSCAPE')
|
|
128
|
+
I.setOrientation('PORTRAIT')
|
|
129
|
+
})
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Run tests as usual:
|
|
133
|
+
|
|
134
|
+
```
|
|
135
|
+
npx codeceptjs run --steps
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## Debugging
|
|
139
|
+
|
|
140
|
+
* [Interactive pause](/basics#pause) works: drop `pause()` into a test and try steps and locators by hand.
|
|
141
|
+
* `DEBUG='mw:*' npx codeceptjs run` prints the whole device dialogue over WebSocket.
|
|
142
|
+
* `await I.grabSource()` returns the accessibility tree as JSON — the main tool for debugging locators: it shows every label, testId and element type on the current screen.
|
|
143
|
+
* `npx mobilewright screenshot -o screen.png` takes a device screenshot without any test.
|
|
144
|
+
* `npx mobilewright codegen` records taps on the device and generates a test; `npx mobilewright inspect` opens a live element inspector in the browser.
|
|
145
|
+
|
|
146
|
+
## Appium vs Mobilewright
|
|
147
|
+
|
|
148
|
+
| | Appium | Mobilewright |
|
|
149
|
+
| --- | --- | --- |
|
|
150
|
+
| Server | Appium server + WebDriver required | none (adb / mobilecli direct) |
|
|
151
|
+
| Automation basis | UI dumps | accessibility tree |
|
|
152
|
+
| Speed | slow startup, minutes per suite | ~7-10s per test incl. app install |
|
|
153
|
+
| Locators | XPath, CSS, accessibility ids | accessibility ids, roles, labels, text |
|
|
154
|
+
| App instrumentation | none needed | none needed |
|
|
155
|
+
| Maturity | industry standard, huge ecosystem | experimental (v0.1.x) |
|
|
156
|
+
| Cloud (SauceLabs, BrowserStack) | yes | not yet |
|
|
157
|
+
|
|
158
|
+
Both helpers share locator conventions, so most tests move between them with little change — start with Mobilewright for fast local runs and keep an Appium job for cloud testing and XPath-heavy suites.
|
|
159
|
+
|
|
160
|
+
## Known Pitfalls
|
|
161
|
+
|
|
162
|
+
1. **Text on screen ≠ text in the accessibility tree.** Error messages may be visible on a screenshot but missing from the tree — text assertions on such elements fail. Check with `I.grabSource()` before asserting by text.
|
|
163
|
+
2. **`clearField` on React Native fields is unstable**; the helper falls back to backspaces, but masked values (passwords) report the wrong length. Filling a password field twice is a flakiness candidate.
|
|
164
|
+
3. **React Native components may not expose testIds** — on such apps `#id` locators don't match; `~` locators fall back to labels and usually work.
|
|
165
|
+
4. **App state persists between tests**: `restart` relaunches the app but does not clear its data.
|
|
166
|
+
5. **iOS + React Native**: taps may not reach RN controls (known mobilecli issue); Android works.
|
package/docs/parallel.md
CHANGED
|
@@ -225,7 +225,7 @@ share({ tmpFile: '/tmp/run-1' }, { local: true })
|
|
|
225
225
|
## Scaling beyond one machine
|
|
226
226
|
|
|
227
227
|
Worker threads split the suite, but every Playwright worker still runs a full local browser.
|
|
228
|
-
With the [Kitesurf helper](/helpers/
|
|
228
|
+
With the [Kitesurf helper](/helpers/kitesurf) each worker drives a cloud browser on Cloudflare
|
|
229
229
|
instead — `run-workers 16` means sixteen browsers spawned in about a second, none of them
|
|
230
230
|
competing for your runner's CPU. See [Alternative Browser Engines](/alternative-browsers) for
|
|
231
231
|
the full setup.
|
package/docs/playwright.md
CHANGED
|
@@ -104,7 +104,7 @@ When to consider navigation succeeded, defaults to `load`. Given an array of eve
|
|
|
104
104
|
When a test runs faster than application it is recommended to increase `waitForAction` config value.
|
|
105
105
|
It will wait for a small amount of time (100ms) by default after each user action is taken.
|
|
106
106
|
|
|
107
|
-
> ▶ More options are listed in [helper reference](https://codecept.io/helpers/
|
|
107
|
+
> ▶ More options are listed in [helper reference](https://codecept.io/helpers/playwright/).
|
|
108
108
|
|
|
109
109
|
## Writing Tests
|
|
110
110
|
|
|
@@ -129,7 +129,7 @@ Tests consist with a scenario of user's action taken on a page. The most widely
|
|
|
129
129
|
- `see`, `dontSee` - to check for a text on a page
|
|
130
130
|
- `seeElement`, `dontSeeElement` - to check for elements on a page
|
|
131
131
|
|
|
132
|
-
> ℹ All actions are listed in [Playwright helper reference](https://codecept.io/helpers/
|
|
132
|
+
> ℹ All actions are listed in [Playwright helper reference](https://codecept.io/helpers/playwright/).\*
|
|
133
133
|
|
|
134
134
|
All actions which interact with elements can use **[CSS or XPath locators](https://codecept.io/locators/#css-and-xpath)**. Actions like `click` or `fillField` can locate elements by their name or value on a page:
|
|
135
135
|
|
|
@@ -377,15 +377,15 @@ Scenario('website looks nice on iPhone', () => {
|
|
|
377
377
|
|
|
378
378
|
## API Requests
|
|
379
379
|
|
|
380
|
-
CodeceptJS has [REST](/helpers/
|
|
380
|
+
CodeceptJS has [REST](/helpers/rest) and [GraphQL](/helpers/graph-ql) helpers to perform requests to external APIs. This may be helpful to implement [data management](https://codecept.io/data/) strategy.
|
|
381
381
|
|
|
382
|
-
However, Playwright since 1.18 has its own [API for making request](https://playwright.dev/docs/api/class-apirequestcontext#api-request-context-get). It uses cookies from browser session to authenticate requests. So you can use it via [`makeApiRequest`](/helpers/
|
|
382
|
+
However, Playwright since 1.18 has its own [API for making request](https://playwright.dev/docs/api/class-apirequestcontext#api-request-context-get). It uses cookies from browser session to authenticate requests. So you can use it via [`makeApiRequest`](/helpers/playwright#makeapirequest) method:
|
|
383
383
|
|
|
384
384
|
```js
|
|
385
385
|
I.makeApiRequest('GET', '/users')
|
|
386
386
|
```
|
|
387
387
|
|
|
388
|
-
It is also possible to test JSON responses by adding [`JSONResponse`](/helpers/
|
|
388
|
+
It is also possible to test JSON responses by adding [`JSONResponse`](/helpers/json-response) and connecting it to Playwright:
|
|
389
389
|
|
|
390
390
|
```js
|
|
391
391
|
// inside codecept.conf.js
|
package/docs/plugins/aiTrace.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
permalink: /plugins/
|
|
2
|
+
permalink: /plugins/junit-reporter
|
|
3
3
|
editLink: false
|
|
4
4
|
sidebar: auto
|
|
5
5
|
title: junitReporter
|
|
@@ -33,7 +33,7 @@ The produced file is consumable by Jenkins, GitLab CI, CircleCI, GitHub Actions
|
|
|
33
33
|
Possible config options:
|
|
34
34
|
|
|
35
35
|
* `outputName`: file name for the report. Default: `report.xml`.
|
|
36
|
-
* `output`: directory where the report is stored, relative to the project root. Default: the `output` directory.
|
|
36
|
+
* `output`: directory where the report is stored, relative to the project root. Default: the `output` directory. With `run-workers` and `multiple` runs, each run writes its own report into its run folder (e.g. `output/dev_chromium1`) and this option is ignored.
|
|
37
37
|
* `testGroupName`: value of the `name` attribute on the root `<testsuites>` element. Default: `CodeceptJS`.
|
|
38
38
|
* `attachMeta`: add the test's meta information (`meta` keys, `tags`, `retries`) as `<properties>`. Default: true.
|
|
39
39
|
* `attachSteps`: add the step/substep log as `<system-out>`. Default: true.
|
package/docs/plugins/pageInfo.md
CHANGED
package/docs/plugins.md
CHANGED
|
@@ -9,7 +9,7 @@ title: Plugins
|
|
|
9
9
|
|
|
10
10
|
CodeceptJS bundles the following plugins. Each plugin has its own page with full configuration reference.
|
|
11
11
|
|
|
12
|
-
## [aiTrace](/plugins/
|
|
12
|
+
## [aiTrace](/plugins/ai-trace)
|
|
13
13
|
|
|
14
14
|
Generates AI-friendly trace files for debugging with AI agents. This plugin creates a markdown file with test execution logs and links to all artifacts (screenshots, HTML, ARIA snapshots, browser logs, HTTP requests) for each step.
|
|
15
15
|
|
|
@@ -21,7 +21,7 @@ Uses AI to analyze test failures and provide insights
|
|
|
21
21
|
|
|
22
22
|
Logs user in for the first test and reuses session for next tests. Works by saving cookies into memory or file. If a session expires automatically logs in again.
|
|
23
23
|
|
|
24
|
-
## [autoDelay](/plugins/
|
|
24
|
+
## [autoDelay](/plugins/auto-delay)
|
|
25
25
|
|
|
26
26
|
Sometimes it takes some time for a page to respond to user's actions. Depending on app's performance this can be either slow or fast.
|
|
27
27
|
|
|
@@ -33,11 +33,11 @@ Overrides browser helper config from the command line. Works for all browser hel
|
|
|
33
33
|
|
|
34
34
|
Dumps code coverage from Playwright/Puppeteer after every test.
|
|
35
35
|
|
|
36
|
-
## [customLocator](/plugins/
|
|
36
|
+
## [customLocator](/plugins/custom-locator)
|
|
37
37
|
|
|
38
38
|
Creates a [custom locator][1] by using special attributes in HTML.
|
|
39
39
|
|
|
40
|
-
## [customReporter](/plugins/
|
|
40
|
+
## [customReporter](/plugins/custom-reporter)
|
|
41
41
|
|
|
42
42
|
Sample custom reporter for CodeceptJS.
|
|
43
43
|
|
|
@@ -49,11 +49,11 @@ Exposes properties from helper instances as injectable test arguments. Use it to
|
|
|
49
49
|
|
|
50
50
|
Self-healing tests with AI.
|
|
51
51
|
|
|
52
|
-
## [junitReporter](/plugins/
|
|
52
|
+
## [junitReporter](/plugins/junit-reporter)
|
|
53
53
|
|
|
54
54
|
Generates a JUnit-compatible XML report after a test run.
|
|
55
55
|
|
|
56
|
-
## [pageInfo](/plugins/
|
|
56
|
+
## [pageInfo](/plugins/page-info)
|
|
57
57
|
|
|
58
58
|
Collects information from web page after each failed test and adds it to the test as an artifact. It is suggested to enable this plugin if you run tests on CI and you need to debug failed tests. This plugin can be paired with `analyze` plugin to provide more context.
|
|
59
59
|
|
|
@@ -61,11 +61,11 @@ Collects information from web page after each failed test and adds it to the tes
|
|
|
61
61
|
|
|
62
62
|
Pauses test execution interactively. Replaces the legacy `pauseOnFail` plugin. The default `on=fail` matches the old `pauseOnFail` behavior.
|
|
63
63
|
|
|
64
|
-
## [pauseOnFail](/plugins/
|
|
64
|
+
## [pauseOnFail](/plugins/pause-on-fail)
|
|
65
65
|
|
|
66
66
|
Starts an interactive pause when a test fails.
|
|
67
67
|
|
|
68
|
-
## [retryFailedStep](/plugins/
|
|
68
|
+
## [retryFailedStep](/plugins/retry-failed-step)
|
|
69
69
|
|
|
70
70
|
Retries each failed step in a test.
|
|
71
71
|
|
|
@@ -77,7 +77,7 @@ Records a video of tests. Uses Playwright's `page.screencast` API (WebM) when th
|
|
|
77
77
|
|
|
78
78
|
Saves screenshots from the browser at points triggered by `on=`.
|
|
79
79
|
|
|
80
|
-
## [screenshotOnFail](/plugins/
|
|
80
|
+
## [screenshotOnFail](/plugins/screenshot-on-fail)
|
|
81
81
|
|
|
82
82
|
Saves a screenshot when a test fails.
|
|
83
83
|
|
|
@@ -85,7 +85,7 @@ Saves a screenshot when a test fails.
|
|
|
85
85
|
|
|
86
86
|
Collects all pages visited while tests are running and saves them as a [sitemap][1] XML file.
|
|
87
87
|
|
|
88
|
-
## [stepTimeout](/plugins/
|
|
88
|
+
## [stepTimeout](/plugins/step-timeout)
|
|
89
89
|
|
|
90
90
|
Set timeout for test steps globally.
|
|
91
91
|
|
package/docs/puppeteer.md
CHANGED
|
@@ -43,7 +43,7 @@ npx codeceptjs init
|
|
|
43
43
|
|
|
44
44
|
You will be asked for a Helper to use, you should select Puppeteer and provide url of a website you are testing.
|
|
45
45
|
|
|
46
|
-
> Puppeteer can also work with Firefox. [Learn how to set it up](/helpers/
|
|
46
|
+
> Puppeteer can also work with Firefox. [Learn how to set it up](/helpers/puppeteer-firefox)
|
|
47
47
|
|
|
48
48
|
## Configuring
|
|
49
49
|
|
|
@@ -80,7 +80,7 @@ By default it is set to `domcontentloaded` which waits for `DOMContentLoaded` ev
|
|
|
80
80
|
When a test runs faster than application it is recommended to increase `waitForAction` config value.
|
|
81
81
|
It will wait for a small amount of time (100ms) by default after each user action is taken.
|
|
82
82
|
|
|
83
|
-
> ▶ More options are listed in [helper reference](https://codecept.io/helpers/
|
|
83
|
+
> ▶ More options are listed in [helper reference](https://codecept.io/helpers/puppeteer/).
|
|
84
84
|
|
|
85
85
|
## Writing Tests
|
|
86
86
|
|
|
@@ -105,7 +105,7 @@ Tests consist with a scenario of user's action taken on a page. The most widely
|
|
|
105
105
|
- `see`, `dontSee` - to check for a text on a page
|
|
106
106
|
- `seeElement`, `dontSeeElement` - to check for elements on a page
|
|
107
107
|
|
|
108
|
-
> ℹ All actions are listed in [Puppeteer helper reference](https://codecept.io/helpers/
|
|
108
|
+
> ℹ All actions are listed in [Puppeteer helper reference](https://codecept.io/helpers/puppeteer/).\*
|
|
109
109
|
|
|
110
110
|
All actions which interact with elements **support CSS and XPath locators**. Actions like `click` or `fillField` by locate elements by their name or value on a page:
|
|
111
111
|
|
|
@@ -241,7 +241,7 @@ To master request intercepting [use `HTTPRequest` object](https://pptr.dev/next/
|
|
|
241
241
|
|
|
242
242
|
## Accessing Puppeteer API
|
|
243
243
|
|
|
244
|
-
To get Puppeteer API inside a test use [`I.usePupepteerTo`](/helpers/
|
|
244
|
+
To get Puppeteer API inside a test use [`I.usePupepteerTo`](/helpers/puppeteer/#usepuppeteerto) method with a callback.
|
|
245
245
|
To keep test readable provide a description of a callback inside the first parameter.
|
|
246
246
|
|
|
247
247
|
```js
|