Skip to content

Commit 8a1f081

Browse files
author
DavertMik
committed
Updated docs
1 parent fb28db2 commit 8a1f081

2 files changed

Lines changed: 143 additions & 10 deletions

File tree

‎docs/agents.md‎

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,18 @@ Agents get full control over test and browser execution:
2323

2424
CodeceptJS is token-efficient: it stores HTML, ARIA, logs, and HTTP request data as files instead of streaming them through MCP. Agents read these files with their native shell tools—no extra API calls, no redundant context.
2525

26+
## The loop
27+
28+
Whether the agent is writing a new test or fixing an old one, it follows the same cycle.
29+
30+
1. **Open the page.** Run a stub test (new work) or set a breakpoint at the failing step (fix). The browser lands at the right starting point and yields control to the agent.
31+
2. **Read the page.** MCP saves HTML, ARIA, and screenshot of the page to files (and the agent can call the `snapshot` tool to refresh them). The agent reads those files before deciding what to try next, controlling its token usage.
32+
3. **Run a CodeceptJS command.** The agent tries `I.*` commands like `I.click('Add to cart')`, `I.fillField('Email', secret(process.env.EMAIL))`, `I.see('Confirmed')`. On success, that line goes into the test — same syntax.
33+
4. **Check the result.** The response after each command shows the new page state. If the URL changed and the modal opened, the line goes into the verified sequence. If not, the agent reads the page again and tries a different locator or a wait.
34+
5. **Move forward.** The agent looks at the new state and chooses the next command. Steps 2–4 repeat until the scenario is whole.
35+
6. **Commit to the file.** The agent edits the test — replaces `pause()` (new tests) or the broken line (fixes) with the verified sequence — then reruns end-to-end and reads the trace to confirm.
36+
37+
2638
## How It Works
2739

2840
CodeceptJS ships an **MCP server and a skillset** that lets an AI agent (Claude Code, Cursor, Codex, others) write and fix tests by driving the real browser. The agent runs the same `I.*` commands the test does, reads how the page responds, and only commits the lines that succeeded.
@@ -50,16 +62,6 @@ This lets the agent get a test working in one iteration. The agent can live-writ
5062

5163
The MCP server is the agent-facing equivalent of the `pause()` REPL — same access, driven by tool calls instead of keystrokes. Full tool reference at [/mcp](/mcp).
5264

53-
## The loop
54-
55-
Whether the agent is writing a new test or fixing an old one, it follows the same cycle.
56-
57-
1. **Open the page.** Run a stub test (new work) or set a breakpoint at the failing step (fix). The browser lands at the right starting point and yields control to the agent.
58-
2. **Read the page.** MCP saves HTML, ARIA, and screenshot of the page to files (and the agent can call the `snapshot` tool to refresh them). The agent reads those files before deciding what to try next, controlling its token usage.
59-
3. **Run a CodeceptJS command.** The agent tries `I.*` commands like `I.click('Add to cart')`, `I.fillField('Email', secret(process.env.EMAIL))`, `I.see('Confirmed')`. On success, that line goes into the test — same syntax.
60-
4. **Check the result.** The response after each command shows the new page state. If the URL changed and the modal opened, the line goes into the verified sequence. If not, the agent reads the page again and tries a different locator or a wait.
61-
5. **Move forward.** The agent looks at the new state and chooses the next command. Steps 2–4 repeat until the scenario is whole.
62-
6. **Commit to the file.** The agent edits the test — replaces `pause()` (new tests) or the broken line (fixes) with the verified sequence — then reruns end-to-end and reads the trace to confirm.
6365

6466
## How the agent reads the page
6567

‎docs/environment-variables.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
permalink: /environment-variables
3+
title: Environment Variables
4+
---
5+
6+
# Environment Variables
7+
8+
CodeceptJS reads several environment variables that change runtime behavior. They are useful for tuning CI runs, enabling extra logging, configuring the MCP server, or wiring values into the generated `codecept.conf.js`.
9+
10+
This page is a reference for every `process.env.*` switch CodeceptJS reads or sets internally.
11+
12+
## Quick Reference
13+
14+
| Variable | Category | Default | Purpose |
15+
| :--- | :--- | :--- | :--- |
16+
| `profile` | Test execution | _unset_ | Profile name forwarded from `--profile`; readable from config and helpers. |
17+
| `CI` | Test execution | _unset_ | Auto-set by every CI provider; enables CI-aware behavior. |
18+
| `DONT_FAIL_ON_EMPTY_RUN` | Test execution | _unset_ | When set, do not fail CI if zero tests were executed. |
19+
| `RUNS_WITH_WORKERS` | Workers | _unset_ | Set to `true` while running in workers; read by helpers/plugins to branch behavior. |
20+
| `CODECEPT_WORKER_TIMEOUT` | Workers | `5m` | Hung-worker watchdog timeout. Accepts [ms](https://github.com/vercel/ms) strings (`30s`, `2m`, `1h`). |
21+
| `CODECEPT_AUTO_EXIT_TIMEOUT` | Workers | `2000` | Time in ms allowed for helper cleanup before forced `process.exit`. Set to `0` to disable. |
22+
| `DEBUG` | Debug | _unset_ | `debug` package namespace filter, e.g. `codeceptjs:*`, `codeceptjs:heal`. |
23+
| `HEADLESS` | Init template | _unset_ | Read by `setHeadlessWhen()` in the generated config to toggle headless mode. |
24+
| `BASE_URL` | Init template | `http://localhost` | Default URL written into the generated Playwright config. |
25+
26+
## Test Execution
27+
28+
### `profile`
29+
30+
Set automatically when you pass `--profile <name>` to `run`, `run-workers`, `run-rerun`, `run-multiple`, or `interactive`. The value is available inside `codecept.conf.js`, helpers, and plugins via `process.env.profile`, which is the standard way to switch configuration based on environment:
31+
32+
```js
33+
exports.config = {
34+
helpers: {
35+
Playwright: {
36+
url: process.env.profile === 'staging' ? 'https://staging.example.com' : 'http://localhost:3000',
37+
},
38+
},
39+
}
40+
```
41+
42+
### `CI`
43+
44+
A de-facto standard variable exported by every major CI provider (GitHub Actions, GitLab CI, CircleCI, Jenkins, Travis, etc.). CodeceptJS uses it for two CI-aware behaviors:
45+
46+
- Extends the polling timeout for `submittedData()` to 60s (vs 2s locally).
47+
- Fails the run with exit code `1` if no tests were executed (see `DONT_FAIL_ON_EMPTY_RUN`).
48+
49+
You should not need to set this manually.
50+
51+
### `DONT_FAIL_ON_EMPTY_RUN`
52+
53+
By default, when `CI` is set and no tests are executed (e.g. an over-restrictive `--grep`), CodeceptJS fails the run to surface false-positive green builds. Set `DONT_FAIL_ON_EMPTY_RUN=true` to keep the run green even when nothing ran.
54+
55+
```yaml
56+
# .github/workflows/tests.yml
57+
env:
58+
DONT_FAIL_ON_EMPTY_RUN: 'true'
59+
```
60+
61+
## Workers
62+
63+
### `RUNS_WITH_WORKERS`
64+
65+
Automatically set to `'true'` while a `run-workers` invocation is active and reset to `'false'` when it finishes. Read it from helpers or plugins when you need to behave differently in worker mode — for example, to disable an interactive feature or change reporter output:
66+
67+
```js
68+
if (process.env.RUNS_WITH_WORKERS === 'true') {
69+
// running in a worker thread
70+
}
71+
```
72+
73+
Do not set this manually.
74+
75+
### `CODECEPT_WORKER_TIMEOUT`
76+
77+
Per-worker hung-process watchdog. If a worker produces no output for this duration, it is auto-terminated and reported as failed. Accepts any string parsed by the [`ms`](https://github.com/vercel/ms) package: `30s`, `2m`, `5m`, `1h`. Defaults to `5m`.
78+
79+
```sh
80+
CODECEPT_WORKER_TIMEOUT=10m npx codeceptjs run-workers 4
81+
```
82+
83+
### `CODECEPT_AUTO_EXIT_TIMEOUT`
84+
85+
Time in **milliseconds** that CodeceptJS waits for helper `_cleanup()` hooks to complete before calling `process.exit()`. Defaults to `2000`. Set to `0` to disable the auto-exit and let the Node event loop drain naturally — useful when long-running async work (e.g. report uploads) must complete after the test run.
86+
87+
```sh
88+
CODECEPT_AUTO_EXIT_TIMEOUT=0 npx codeceptjs run
89+
```
90+
91+
## Debug
92+
93+
### `DEBUG`
94+
95+
Standard [`debug`](https://www.npmjs.com/package/debug) package selector. CodeceptJS emits debug output under the `codeceptjs:*` namespace. Useful namespaces:
96+
97+
| Namespace | Source |
98+
| :--- | :--- |
99+
| `codeceptjs:*` | All internal logs |
100+
| `codeceptjs:recorder` | Recorder/promise queue |
101+
| `codeceptjs:event` | Event dispatcher |
102+
| `codeceptjs:container` | DI container |
103+
| `codeceptjs:steps` | Step lifecycle |
104+
| `codeceptjs:exit` | Exit listener |
105+
| `codeceptjs:timeout` | Global timeout listener |
106+
| `codeceptjs:pause` | Interactive pause |
107+
| `codeceptjs:ai` | AI features |
108+
| `codeceptjs:heal` | Heal plugin |
109+
| `codeceptjs:analyze` | Analyze plugin |
110+
| `codeceptjs:retryFailedStep` | retryFailedStep plugin |
111+
| `codeceptjs:bdd` | Gherkin/BDD |
112+
113+
```sh
114+
DEBUG="codeceptjs:*" npx codeceptjs run --verbose
115+
DEBUG="codeceptjs:heal" npx codeceptjs run
116+
DEBUG="codeceptjs:retryFailedStep" npx codeceptjs run
117+
```
118+
119+
When `DEBUG` includes a `codeceptjs:` selector, the `heal` plugin keeps healing enabled in `--debug` mode (which otherwise disables it).
120+
121+
## Init Template
122+
123+
These variables are read by the configuration scaffolded by `codeceptjs init`. They have no effect unless your project's generated `codecept.conf.js` references them.
124+
125+
### `HEADLESS`
126+
127+
Read by [`setHeadlessWhen()`](https://www.npmjs.com/package/@codeceptjs/configure) in the generated config. When truthy, the browser starts headless. The init template wires this in so you can run `HEADLESS=true npx codeceptjs run` on CI without changing the config.
128+
129+
### `BASE_URL`
130+
131+
The init template uses `BASE_URL` (falling back to `http://localhost`) as the Playwright `url` value. After scaffolding, edit the generated config to change this default.

0 commit comments

Comments
 (0)