codeceptjs 4.0.0-rc.20 → 4.0.0-rc.22
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/bin/mcp-server.js +7 -5
- package/docs/advanced.md +1 -1
- package/docs/agents.md +32 -10
- package/docs/architecture.md +219 -0
- package/docs/configuration.md +82 -127
- package/docs/continuous-integration.md +113 -151
- package/docs/custom-helpers.md +1 -1
- package/docs/environment-variables.md +131 -0
- package/docs/hooks.md +76 -277
- package/docs/installation.md +95 -40
- package/docs/parallel.md +98 -496
- package/docs/plugins.md +43 -0
- package/docs/reports.md +102 -401
- package/docs/retry.md +44 -37
- package/docs/typescript.md +54 -269
- package/lib/codecept.js +1 -1
- package/lib/command/run-workers.js +0 -14
- package/lib/command/run.js +2 -16
- package/lib/command/utils.js +14 -0
- package/lib/command/workers/runTests.js +1 -5
- package/lib/heal.js +2 -0
- package/lib/helper/Playwright.js +15 -4
- package/lib/plugin/aiTrace.js +16 -13
- package/lib/plugin/analyze.js +5 -4
- package/lib/plugin/heal.js +3 -2
- package/lib/plugin/junitReporter.js +303 -0
- package/lib/plugin/pageInfo.js +5 -7
- package/lib/plugin/retryFailedStep.js +4 -3
- package/lib/plugin/screencast.js +6 -4
- package/lib/workers.js +11 -3
- package/package.json +1 -1
- package/docs/internal-api.md +0 -265
package/docs/configuration.md
CHANGED
|
@@ -5,167 +5,129 @@ title: Configuration
|
|
|
5
5
|
|
|
6
6
|
# Configuration
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
After running `codeceptjs init` it should be saved in test root.
|
|
11
|
-
|
|
12
|
-
| Name | Type | Description |
|
|
13
|
-
| :------------------- | :----------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
14
|
-
| `bootstrap?` | (() => `Promise`<`void`\>) \| `boolean` \| `string` | [Execute code before](https://codecept.io/bootstrap/) tests are run. Can be either JS module file or async function: `bootstrap: async () => server.launch(), ` or `bootstrap: 'bootstrap.js', ` |
|
|
15
|
-
| `bootstrapAll?` | (() => `Promise`<`void`\>) \| `boolean` \| `string` | [Execute code before launching tests in parallel mode](https://codecept.io/bootstrap/#bootstrapall-teardownall) |
|
|
16
|
-
| `gherkin?` | { `features`: `string` \| `string`[] ; `steps`: `string`[] } | Enable [BDD features](https://codecept.io/bdd/#configuration). Sample configuration: `gherkin: { features: "./features/*.feature", steps: ["./step_definitions/steps.js"] } ` |
|
|
17
|
-
| `gherkin.features` | `string` \| `string`[] | load feature files by pattern. Multiple patterns can be specified as array |
|
|
18
|
-
| `gherkin.steps` | `string`[] | load step definitions from JS files |
|
|
19
|
-
| `grep?` | `string` | Pattern to filter tests by name. This option is useful if you plan to use multiple configs for different environments. To execute only tests with @firefox tag use `grep: '@firefox' ` |
|
|
20
|
-
| `helpers?` | {} | Enable and configure helpers: `helpers: { Playwright: { url: 'https://mysite.com', browser: 'firefox' } } ` |
|
|
21
|
-
| `include?` | `any` | Include page objects to access them via dependency injection `I: "./custom_steps.js", loginPage: "./pages/Login.js", User: "./pages/User.js", ` Configured modules can be injected by name in a Scenario: `Scenario('test', { I, loginPage, User }) ` |
|
|
22
|
-
| `mocha?` | `any` | [Mocha test runner options](https://mochajs.org/#configuring-mocha-nodejs), additional [reporters](https://codecept.io/reports/#xml) can be configured here. Example: `mocha: { "mocha-junit-reporter": { stdout: "./output/console.log", options: { mochaFile: "./output/result.xml", attachments: true //add screenshot for a failed test } } } ` |
|
|
23
|
-
| `noGlobals?` | `boolean` | Disable registering global functions (Before, Scenario, etc). Not recommended |
|
|
24
|
-
| `output` | `string` | Where to store failure screenshots, artifacts, etc `output: './output' ` |
|
|
25
|
-
| `plugins?` | `any` | Enable CodeceptJS plugins. Example: `plugins: { autoDelay: { enabled: true } } ` |
|
|
26
|
-
| `require?` | `string`[] | [Require additional JS modules](https://codecept.io/configuration/#require) Example: `require: ["should"]` |
|
|
27
|
-
| `teardown?` | (() => `Promise`<`void`\>) \| `boolean` \| `string` | [Execute code after tests](https://codecept.io/bootstrap/) finished. Can be either JS module file or async function: `teardown: async () => server.stop(), ` or `teardown: 'teardown.js', ` |
|
|
28
|
-
| `teardownAll?` | (() => `Promise`<`void`\>) \| `boolean` \| `string` | [Execute JS code after finishing tests in parallel mode](https://codecept.io/bootstrap/#bootstrapall-teardownall) |
|
|
29
|
-
| `tests` | `string` | Pattern to locate CodeceptJS tests. Allows to enter glob pattern or an Array<string> of patterns to match tests / test file names. For tests in JavaScript: `tests: 'tests/**.test.js' ` For tests in TypeScript: `tests: 'tests/**.test.ts' ` |
|
|
30
|
-
| `timeout?` | `number` | Set default tests timeout in seconds. Tests will be killed on no response after timeout. `timeout: 20, ` |
|
|
31
|
-
| `translation?` | `string` | Enable [localized test commands](https://codecept.io/translation/) |
|
|
32
|
-
| `maskSensitiveData?` | `boolean` | Enable to mask Sensitive Data in console. |
|
|
8
|
+
`codeceptjs init` creates a `codecept.conf.js` (or `codecept.conf.ts`) in your test root. It exports a `config` object:
|
|
33
9
|
|
|
34
|
-
|
|
10
|
+
```js
|
|
11
|
+
export const config = {
|
|
12
|
+
tests: './**/*_test.js',
|
|
13
|
+
output: './output',
|
|
14
|
+
helpers: {
|
|
15
|
+
Playwright: { url: 'http://localhost', browser: 'chromium' },
|
|
16
|
+
},
|
|
17
|
+
include: {
|
|
18
|
+
I: './steps_file.js',
|
|
19
|
+
},
|
|
20
|
+
}
|
|
21
|
+
```
|
|
35
22
|
|
|
36
|
-
|
|
37
|
-
- **Assertion libraries:** e.g., `'should'` instead of manually requiring it in each test
|
|
38
|
-
- **TypeScript loaders:** Enable TypeScript test files in ESM or CommonJS projects
|
|
39
|
-
- **Setup modules:** Initialize testing environment
|
|
40
|
-
- **Custom modules:** With relative paths like `"require": ["./lib/setup"]`
|
|
23
|
+
## Options
|
|
41
24
|
|
|
42
|
-
|
|
25
|
+
**Tests and files**
|
|
43
26
|
|
|
44
|
-
|
|
27
|
+
- `tests` — glob pattern (or array of patterns) locating your test files, e.g. `'tests/**/*_test.js'` (or `*_test.ts` for TypeScript).
|
|
28
|
+
- `output` — directory for failure screenshots, artifacts, and temporary files. Default `./output`.
|
|
29
|
+
- `include` — page objects and support objects exposed via dependency injection: `{ I: './steps_file.js', loginPage: './pages/Login.js' }`. They can then be injected by name — `Scenario('test', ({ I, loginPage }) => …)`.
|
|
30
|
+
- `require` — extra modules to load before tests run: assertion libraries, TypeScript loaders, setup files. See [Require](#require).
|
|
31
|
+
- `grep` — run only tests whose name matches this pattern, e.g. `grep: '@firefox'`. Handy when you keep separate configs per environment.
|
|
45
32
|
|
|
46
|
-
|
|
33
|
+
**Helpers and plugins**
|
|
47
34
|
|
|
48
|
-
|
|
35
|
+
- `helpers` — enable and configure [helpers](/helpers): `{ Playwright: { url: 'https://mysite.com', browser: 'firefox' } }`.
|
|
36
|
+
- `plugins` — enable [plugins](/plugins): `{ autoDelay: { enabled: true } }`.
|
|
49
37
|
|
|
50
|
-
|
|
51
|
-
// codecept.conf.ts
|
|
52
|
-
export const config = {
|
|
53
|
-
tests: './**/*_test.ts',
|
|
54
|
-
require: ['tsx/cjs'], // ← Modern TypeScript loader
|
|
55
|
-
helpers: {},
|
|
56
|
-
include: {},
|
|
57
|
-
}
|
|
58
|
-
```
|
|
38
|
+
**Hooks**
|
|
59
39
|
|
|
60
|
-
|
|
40
|
+
- `bootstrap` / `teardown` — run code before / after the whole run; an async function or a path to a JS module. See [Bootstrap](/bootstrap).
|
|
41
|
+
- `bootstrapAll` / `teardownAll` — run once around a parallel run (before any worker starts / after all finish). See [bootstrapAll / teardownAll](/bootstrap#bootstrapall-teardownall).
|
|
61
42
|
|
|
62
|
-
|
|
63
|
-
// codecept.conf.ts
|
|
64
|
-
export const config = {
|
|
65
|
-
tests: './**/*_test.ts',
|
|
66
|
-
require: ['ts-node/esm'], // ← Established TypeScript loader
|
|
67
|
-
helpers: {},
|
|
68
|
-
include: {},
|
|
69
|
-
}
|
|
70
|
-
```
|
|
43
|
+
**Test runner**
|
|
71
44
|
|
|
72
|
-
|
|
45
|
+
- `timeout` — default per-test timeout in seconds; a test is killed if it stops responding.
|
|
46
|
+
- `mocha` — [Mocha options](https://mochajs.org/#configuring-mocha-nodejs), including extra reporters. See [Reporters](/reports).
|
|
73
47
|
|
|
74
|
-
|
|
48
|
+
**BDD**
|
|
75
49
|
|
|
76
|
-
|
|
50
|
+
- `gherkin` — enable [BDD features](/bdd#configuration): `{ features: './features/*.feature', steps: ['./step_definitions/steps.js'] }`.
|
|
51
|
+
- `gherkin.features` — feature file glob, or an array of globs.
|
|
52
|
+
- `gherkin.steps` — JS files with step definitions.
|
|
77
53
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
helpers: {},
|
|
84
|
-
include: {},
|
|
85
|
-
}
|
|
86
|
-
```
|
|
54
|
+
**TypeScript**
|
|
55
|
+
|
|
56
|
+
- `fullPromiseBased` — generate typings where `I.*` methods return promises, so you can `await` each command. See [TypeScript](/typescript#promise-based-typings).
|
|
57
|
+
|
|
58
|
+
**Other**
|
|
87
59
|
|
|
88
|
-
|
|
60
|
+
- `translation` — enable [localized commands](/translation).
|
|
61
|
+
- `maskSensitiveData` — mask secrets in console output.
|
|
62
|
+
- `noGlobals` — don't register the global functions (`Feature`, `Scenario`, `Before`, …). Not recommended.
|
|
89
63
|
|
|
90
|
-
|
|
64
|
+
## Require
|
|
65
|
+
|
|
66
|
+
`require` loads modules before tests run — assertion libraries (`'should'`), setup files (`'./lib/setup'`), and TypeScript loaders. Modules load in the order listed.
|
|
67
|
+
|
|
68
|
+
For TypeScript test files in CodeceptJS 4.x, use the [`tsx`](https://tsx.is) loader:
|
|
91
69
|
|
|
92
|
-
```
|
|
70
|
+
```ts
|
|
93
71
|
// codecept.conf.ts
|
|
94
72
|
export const config = {
|
|
95
|
-
tests:
|
|
96
|
-
require: [
|
|
97
|
-
'tsx/cjs', // TypeScript loader
|
|
98
|
-
'should', // Assertion library
|
|
99
|
-
'./lib/testSetup' // Custom setup
|
|
100
|
-
],
|
|
73
|
+
tests: './**/*_test.ts',
|
|
74
|
+
require: ['tsx/cjs'],
|
|
101
75
|
helpers: {},
|
|
102
76
|
include: {},
|
|
103
77
|
}
|
|
104
78
|
```
|
|
105
79
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
## Dynamic Configuration
|
|
109
|
-
|
|
110
|
-
By default `codecept.json` is used for configuration. You can override its values in runtime by using `--override` or `-o` option in command line, passing valid JSON as a value:
|
|
80
|
+
Combine several modules:
|
|
111
81
|
|
|
112
|
-
```
|
|
113
|
-
|
|
82
|
+
```ts
|
|
83
|
+
require: ['tsx/cjs', 'should', './lib/testSetup']
|
|
114
84
|
```
|
|
115
85
|
|
|
116
|
-
|
|
117
|
-
|
|
86
|
+
The config file itself (`codecept.conf.ts`) and helpers are transpiled automatically — only test files need the loader. See [TypeScript](/typescript) for the full setup.
|
|
87
|
+
|
|
88
|
+
## Dynamic configuration
|
|
118
89
|
|
|
119
|
-
|
|
90
|
+
A JS/TS config file is plain code, so you can read environment variables and build the config at runtime:
|
|
120
91
|
|
|
121
92
|
```js
|
|
122
93
|
export const config = {
|
|
123
94
|
helpers: {
|
|
124
95
|
WebDriver: {
|
|
125
|
-
// load variables from the environment and provide defaults
|
|
126
96
|
url: process.env.CODECEPT_URL || 'http://localhost:3000',
|
|
127
|
-
|
|
128
97
|
user: process.env.CLOUDSERVICE_USER,
|
|
129
98
|
key: process.env.CLOUDSERVICE_KEY,
|
|
130
|
-
|
|
131
|
-
coloredLogs: true,
|
|
132
99
|
waitForTimeout: 10000,
|
|
133
100
|
},
|
|
134
101
|
},
|
|
135
|
-
|
|
136
|
-
// don't build monolithic configs
|
|
137
|
-
mocha: require('./mocha.conf.js') || {},
|
|
138
102
|
include: {
|
|
139
103
|
I: './src/steps_file.js',
|
|
140
|
-
loginPage: './src/pages/login_page',
|
|
141
|
-
dashboardPage: new DashboardPage(),
|
|
104
|
+
loginPage: './src/pages/login_page.js',
|
|
142
105
|
},
|
|
143
|
-
|
|
144
|
-
// here goes config as it was in codecept.conf.ts
|
|
145
|
-
// ....
|
|
146
106
|
}
|
|
147
107
|
```
|
|
148
108
|
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
If you prefer to store your configuration files in a different location, or with a different name, you can do that with `--config` or `-c:
|
|
109
|
+
Override config values at runtime with `--override` / `-o`, passing JSON:
|
|
152
110
|
|
|
153
111
|
```sh
|
|
154
|
-
codeceptjs run
|
|
112
|
+
npx codeceptjs run -o '{ "helpers": { "WebDriver": { "browser": "firefox" } } }'
|
|
155
113
|
```
|
|
156
114
|
|
|
157
|
-
|
|
115
|
+
Point at a non-default config file with `--config` / `-c`:
|
|
158
116
|
|
|
159
|
-
|
|
117
|
+
```sh
|
|
118
|
+
npx codeceptjs run --config ./path/to/config.js
|
|
119
|
+
```
|
|
160
120
|
|
|
161
|
-
|
|
121
|
+
## Common configuration patterns
|
|
162
122
|
|
|
163
|
-
|
|
123
|
+
[`@codeceptjs/configure`](https://github.com/codeceptjs/configure) ships with CodeceptJS as a dependency. It holds shared recipes for config that's independent of the active helper.
|
|
124
|
+
|
|
125
|
+
Toggle headless mode, set window size, and so on:
|
|
164
126
|
|
|
165
127
|
```js
|
|
166
128
|
import { setHeadlessWhen, setWindowSize } from '@codeceptjs/configure'
|
|
167
129
|
|
|
168
|
-
setHeadlessWhen(process.env.CI)
|
|
130
|
+
setHeadlessWhen(process.env.HEADLESS || process.env.CI)
|
|
169
131
|
setWindowSize(1600, 1200)
|
|
170
132
|
|
|
171
133
|
export const config = {
|
|
@@ -173,20 +135,20 @@ export const config = {
|
|
|
173
135
|
}
|
|
174
136
|
```
|
|
175
137
|
|
|
176
|
-
For one-shot bundles use `setBrowserConfig` — pass any subset of `{ browser, show, windowSize, url
|
|
138
|
+
For one-shot bundles use `setBrowserConfig` — pass any subset of `{ browser, show, windowSize, url }` and the right per-helper translation happens automatically (Puppeteer gets `product`, WebDriver gets `--headless` injected, …). Keys whose value is `undefined` are skipped, so an unset env var won't clobber existing config:
|
|
177
139
|
|
|
178
140
|
```js
|
|
179
141
|
import { setBrowserConfig } from '@codeceptjs/configure'
|
|
180
142
|
|
|
181
143
|
setBrowserConfig({
|
|
182
|
-
browser: process.env.BROWSER,
|
|
183
|
-
show: !process.env.HEADLESS,
|
|
144
|
+
browser: process.env.BROWSER, // optional engine override
|
|
145
|
+
show: !process.env.HEADLESS, // headed unless HEADLESS is set
|
|
184
146
|
windowSize: '1280x720',
|
|
185
|
-
url: process.env.URL,
|
|
147
|
+
url: process.env.URL, // overrides helper.url when set
|
|
186
148
|
})
|
|
187
149
|
```
|
|
188
150
|
|
|
189
|
-
`setCommonPlugins()` enables a curated set of plugins and registers a few more as discoverable
|
|
151
|
+
`setCommonPlugins()` enables a curated set of plugins and registers a few more as discoverable, so they can be switched on ad-hoc with [`-p` plugin arguments](/commands#plugin-arguments) without editing the config:
|
|
190
152
|
|
|
191
153
|
```js
|
|
192
154
|
import { setCommonPlugins } from '@codeceptjs/configure'
|
|
@@ -194,27 +156,21 @@ import { setCommonPlugins } from '@codeceptjs/configure'
|
|
|
194
156
|
setCommonPlugins()
|
|
195
157
|
```
|
|
196
158
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
| `aiTrace` | registered | Capture AI traces — `-p aiTrace`, narrow with `on=fail|test|step|file|url` |
|
|
204
|
-
| `heal` | registered | Self-heal failing steps — `-p heal`, narrow with `on=file|url` |
|
|
159
|
+
- `retryFailedStep` — *enabled*. Retries steps that fail with transient errors.
|
|
160
|
+
- `screenshot` — *enabled*. Screenshot on `fail` (default), or `test` / `step` / `file` / `url`.
|
|
161
|
+
- `pause` — *registered*. Pause on failure / step / file / URL: `-p pause:on=fail`, `-p pause:on=step`, `-p pause:on=file:path=tests/login_test.js`, `-p pause:on=url:pattern=/checkout/*`.
|
|
162
|
+
- `browser` — *registered*. CLI overrides for browser helpers: `-p browser:show`, `-p browser:browser=firefox`. See [browser control](/commands#browser-control).
|
|
163
|
+
- `aiTrace` — *registered*. Capture AI traces: `-p aiTrace`, narrow with `on=fail|test|step|file|url`.
|
|
164
|
+
- `heal` — *registered*. Self-heal failing steps: `-p heal`, narrow with `on=file|url`.
|
|
205
165
|
|
|
206
166
|
> `eachElement`, `tryTo`, and `retryTo` are no longer plugins in 4.x — import them from `codeceptjs/effects`.
|
|
207
167
|
|
|
208
168
|
## Profile
|
|
209
169
|
|
|
210
|
-
|
|
211
|
-
It provides value of `--profile` option passed to runner.
|
|
212
|
-
Use its value to change config value on the fly.
|
|
213
|
-
|
|
214
|
-
For instance, with the config above we can change browser value using `profile` option
|
|
170
|
+
`process.env.profile` carries the value of the `--profile` CLI option, so you can branch the config on it:
|
|
215
171
|
|
|
216
172
|
```sh
|
|
217
|
-
codeceptjs run --profile firefox
|
|
173
|
+
npx codeceptjs run --profile firefox
|
|
218
174
|
```
|
|
219
175
|
|
|
220
176
|
```js
|
|
@@ -222,8 +178,7 @@ export const config = {
|
|
|
222
178
|
helpers: {
|
|
223
179
|
WebDriver: {
|
|
224
180
|
url: 'http://localhost:3000',
|
|
225
|
-
|
|
226
|
-
browser: process.env.profile || 'firefox',
|
|
181
|
+
browser: process.env.profile || 'chrome',
|
|
227
182
|
},
|
|
228
183
|
},
|
|
229
184
|
}
|