testeiya 0.3.9 → 0.3.14

package/skills/codeceptjs/codeceptjs-fundamentals/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: codeceptjs-fundamentals
+description: >
+  Run first when working with any CodeceptJS 4 project — before writing,
+  debugging, refactoring, or migrating tests. Teaches the framework's
+  non-obvious rules and runs four-step discovery (`check` → read config →
+  `list` → `dry-run`) reporting which helpers, plugins, page objects, custom
+  actions, and tests are active. Other CodeceptJS skills depend on this output.
+---
+
+# CodeceptJS Fundamentals
+
+Two jobs, in order: learn the rules below, then discover what *this* project has configured.
+
+## Gate
+
+- CodeceptJS 4 is **ESM/TypeScript only**; tests, configs, page objects, helpers use `import`/`export`.
+- No `"type": "module"` in package.json → add it before anything else.
+- TypeScript: config `codecept.conf.ts`, TS loader entry in `require: [...]`.
+- Project on 3.x or CommonJS (`require()`, removed plugins like `autoLogin`, helper `Nightmare`) → stop, recommend `migrate-codeceptjs-4`. Don't patch files piecemeal — migration is whole-project.
+
+## Main rule
+
+- Tests are written from the user's perspective: a linear scenario of actions, readable as prose.
+  - Good: `I.click('Login')`, `I.fillField('Email', ...)`, `I.see('Welcome')`
+- **Tests are declarative, helpers imperative — recommended layering:**
+  - Scenario shows *what* the user does via `I.*`; implementation details live below
+  - Low-level access (`this.helpers['Playwright'].page`, fetch, filesystem) works fine inside a Scenario, but it's recommended to push it into a helper and expose one `I.*` action instead
+- Keep tests short: repeated sequences → actor method, page object, or step object.
+- Prefer semantic locators over selectors so tests survive markup churn.
+
+## Where things go (recommended placement)
+
+- Site-wide actions (`login`, dropdowns, rich text editors) → **actor file** (custom steps)
+- Page/screen actions + locators → **page object**; SPA screen = one page object
+- Site-wide widgets (nav, modals, datepickers) → **page fragments / component objects**
+- Low-level driver access (DB connections, email, filesystem, complex mouse) → **helper**
+- Data creation/cleanup via API → **data objects** (REST/GraphQL helper + `_after()` cleanup), or `ApiDataFactory` (`I.have(...)`)
+- Don't overengineer: no page object until an abstraction is reused across tests.
+
+## Shortcuts
+
+- Login needed → `autoLogin` plugin or actor method, not inline steps per test
+- Test data → create via API before the test, not through the UI
+- Long test → break into several; long tests are fragile and hard to follow
+- Optional UI element / conditional flow → `await tryTo(...)` instead of `if (await I.grab...)` — keeps scenarios linear
+
+## Architecture
+
+- **Config**: `codecept.conf.{js,ts,mjs,cjs}` at repo root; multiple files selected via `--config <file>`.
+- **Helpers execute; `I` delegates.** Every `I.<method>` is routed to whichever active helper implements it (Playwright, WebDriver, Puppeteer, Appium share one API surface). Active helpers = keys under `helpers`. Tests call the actor, never the engine — backends stay swappable.
+- **DI container** — why it exists:
+  - Everything shared (actor, helpers, page objects, support objects) registers under one container; `include` maps names → modules
+  - Classes are auto-instantiated by the container — no `new`, no manual wiring
+  - **`inject()` returns lazy proxies**: destructuring at module top resolves at call time, so circular page-object references work where plain `import` would give `undefined`
+  - Access: destructure in Scenario signature (`Scenario('...', ({ I, loginPage }) => ...)`) or `const { I } = inject()` once per file
+- **Custom helpers** extend `Helper`, register under `helpers`, add new `I.*` methods.
+  - **`I` does not exist inside a helper.** Compose via `this.helpers['<HelperName>']` (e.g. `this.helpers['Playwright'].page`, `this.helpers['REST'].sendGetRequest(...)`).
+- **Plugins** are event listeners on lifecycle events (`suite.*`, `test.*`, `step.*`, `hook.*`, `multiple.*`). Full list: `node_modules/codeceptjs/lib/event.js`. Register under `plugins` with `enabled: true`.
+
+## Config mutation trap
+
+- `@codeceptjs/configure` mutates resolved config at load time (`setHeadlessWhen`, `setBrowser`, ...). Static values can lie — grep for its import before trusting `show:` / `browser:` fields.
+- `setCommonPlugins()`: **enables** `retryFailedStep` + `screenshot`; **registers** (off until `-p`) `pause`, `browser`, `aiTrace`, `heal`.
+
+## Plugins worth knowing
+
+- `retryFailedStep` — retries transient step failures
+- `screenshot` — screenshots on failure; `slides: true` → `output/records.html` slideshow
+- `pageInfo` — dumps URL/HTML/console on failure
+- `auth` — session reuse for login (see `codeceptjs-auth` skill)
+- `aiTrace` — per-step screenshots/HTML/ARIA/console for AI debugging
+- `pause` — interactive pause
+- `heal` — AI-suggested fixes for broken steps (off in `--debug`)
+- `screencast` — video of the run
+- `customLocator` — maps `$name` prefix to team's test attribute (`data-testid`, `data-qa`)
+- `browser` — CLI-only override of browser helper config (see below)
+
+Note: `tryTo`, `retryTo`, `eachElement` are not plugins in 4.x — import them from `codeceptjs/effects`.
+
+## Plugins from CLI
+
+Any plugin can be enabled/reconfigured per-run with `-p <plugin>`, args chained with `:`:
+
+```sh
+npx codeceptjs run -p aiTrace                    # enable for this run
+npx codeceptjs run -p screenshot:on=step         # reconfigure inline
+npx codeceptjs run -p pause:on=file:path=tests/login_test.js;line=43
+```
+
+- `screenshot`, `pause`, `aiTrace`, `heal` share an `on=` trigger: `fail` (default except aiTrace) | `step` | `test` | `file:path=...;line=N` | `url:pattern=<glob>`
+- `browser` plugin overrides without touching config — CI matrix legs, one-off env variants:
+  - `-p browser:hide` / `-p browser:show` / `-p browser:browser=firefox` / `-p browser:windowSize=1280x800`
+  - Requires `@codeceptjs/configure`
+
+## Effects (`codeceptjs/effects`)
+
+Flow-control functions imported from `codeceptjs/effects`. In 4.x these are no longer plugins/globals.
+
+- **`tryTo(() => ...)`** — runs steps that may fail without stopping the test; returns `boolean`.
+  - **Prefer `tryTo` over `if`:** scenarios should stay linear — instead of branching on a grabbed value to decide whether a UI state exists, attempt the optional steps and branch on the boolean result:
+    ```js
+    const banner = await tryTo(() => { I.see('Cookie banner'); I.click('Accept cookies') })
+    if (!banner) I.say('No cookie banner')
+    ```
+  - Auto-retries are disabled inside `tryTo` blocks.
+- **`retryTo(() => ..., maxTries, pollInterval = 200)`** — retries a step block until it succeeds (flaky elements, animations); callback receives the current attempt count.
+- **`hopeThat(() => ...)`** — soft assertions (see Assertions); end with `hopeThat.noErrors()`.
+- **`within(locator | { frame }, fn)`** — scopes resolution to subtree or iframe; can return values (`await`). Prefer the context parameter of individual actions (`I.click('Save', '.toolbar')`) when possible — reserve `within` for genuinely scoped blocks.
+
+All effects return Promises — `await` them.
+
+## Element-based API (`codeceptjs/els`)
+
+Hybrid style: mix `I.*` with direct element access. Import `{ element, eachElement, expectElement, expectAnyElement, expectAllElements } from 'codeceptjs/els'`.
+
+- `element(locator, async el => { ... })` — scoped access to one element; chain `el.$(locator)` into children without re-querying
+- `eachElement(locator, async (el, index) => ...)` — iterate collections
+- `expectElement` / `expectAnyElement` / `expectAllElements(locator, fn)` — custom conditions
+- Elements are `WebElement` wrappers — same API on all helpers: `getText()`, `getAttribute()`, `isVisible()`, `isEnabled()`, `getBoundingBox()`, `exists()`, `$$()`
+- Optional purpose string improves debug logs: `element('verify discount applied', '.price', ...)`
+- Use when built-ins don't cover it: collections, layout checks (`getBoundingBox`), per-element loops, chaining ops on one element. Prefer `I.*` for readability otherwise.
+
+## Writing tests
+
+- Structure: one `Feature(...)` per file, one or more `Scenario(...)` inside. No nested suites, no multiple Features per file.
+- Hooks: `Before`, `After`, `BeforeSuite`, `AfterSuite`, `Fail(...)`.
+- Page object lifecycle hooks: `_before()` (lazy, once per test, on first use), `_after()` (skipped if unused), `_beforeSuite()`, `_afterSuite()`.
+- **`await` required for**: `grab*` methods, imported functions, page-object methods containing async ops (elsewhere: unhandled rejections). Never for plain action steps — the recorder chains them.
+- Secrets: `I.fillField('Password', secret(process.env.PASSWORD))` — masks logs, traces, AI prompts. Import from `codeceptjs`.
+- Sessions: `session(name, fn)` — parallel browser context for multi-user Scenarios (chat, multi-tenant).
+
+## Locators
+
+- **ARIA locators are strongest** — resilient to CSS refactors, describe what the user sees:
+  - `I.click({ role: 'button', name: 'Save' })`
+- Actions accept plain strings (visible text, label, placeholder, `name`, `aria-label`) or objects (`{ css }`, `{ xpath }`, `{ id }`).
+- Plain string already matches `aria-label` — no `'aria-label=...'` prefix needed.
+- **Pass context as last argument** — scoped semantic locator beats long unscoped one:
+  - `I.click('Save', '.toolbar')` not `I.click('#toolbar .btn-save')`
+- Avoid style-based class names (`.bg-green`); prefer semantic ones (`.btn-save`).
+- `data-testid`/`data-qa` apps → enable `customLocator`, write `$name`.
+- No semantic name fits → `locate(...)` builder (`.withClass`, `.withText`, `.inside`, `.and`): `locate('.button').withText('Click me')`.
+
+## Waiting
+
+- Action steps auto-wait for existence + interactability. Add explicit `waitFor*` only when the condition isn't tied to an interaction (modal after network call, spinner hiding).
+- Avoid `I.wait(N)` — last resort.
+
+## Assertions
+
+Built-in browser assertions come first: `I.see`, `I.seeTextEquals`, `I.seeElement`, `I.seeInField`, `I.seeNumberOfElements`, `I.seeInCurrentUrl` (+ `dontSee*` counterparts). Clear failures, recorder-integrated. `see` matches *visible* text; hidden DOM content needs `seeInSource` / `seeElementInDOM`.
+
+For what built-ins don't cover, in order of preference:
+
+1. **Reusable custom assertion** in a helper — `I.seeTableIsOrdered('Price', 'desc')`; name positives `see*`, negatives `dontSee*`; use `codeceptjs/assertions` inside, never raw `throw new Error()`
+2. **ExpectHelper** (`@codeceptjs/expect-helper`) — chai matchers on `I`: `I.expectEqual`, `I.expectDeepEqualExcluding`, `I.expectMatchesPattern`, `I.expectJsonSchema`; appears in step log like other steps
+3. **`codeceptjs/assertions`** directly — dependency-free factories: `equals(subject).assert(actual, expected)` / `.negate(...)`; failure messages match `I.see` formatting
+4. **Any library** on grabbed data (`grab*` always needs `await`) — chai/jest/`node:assert`; fails the test but won't show as a step
+
+Soft assertions: `hopeThat(() => I.see(...))` from `codeceptjs/effects` — logs each failure and continues; end with `hopeThat.noErrors()` to fail if any were recorded.
+
+## Parallel runs
+
+- `run-workers <N>` — splits Scenarios across worker threads
+- `run-multiple <profile>` — profiles via `multiple` block in config (browsers, viewports)
+
+## Config organization (recommended)
+
+- Multiple config files per environment (`codecept.conf.js`, `codecept.ci.conf.js`, ...); share parts via modules in a `config/` dir
+- `.env` files + `dotenv` for secrets/env-specific values
+- Bulk-register page objects/components by spreading exported maps into `include`
+- Pass data from config/bootstrap into tests via `codeceptjs.container.append({ testUser })` — injectable by name
+
+## Discover this project
+
+In order; skipping steps produces wrong guesses:
+
+1. **Verify setup loads**: `npx codeceptjs check -c <config>` — validates everything; output doubles as inventory. Fix failures before continuing.
+2. **Read the active config**: helpers (+ browser/baseURL/viewport/env-driven values), plugins (incl. anything `setCommonPlugins()` injects), AI provider + required env var, env selection mechanism, page objects from `include`, custom helpers.
+3. **List actions**: `npx codeceptjs list -c <config>` (`--docs` adds JSDoc; `--action <name>` for one). The actual `I.*` surface differs from built-ins when custom helpers exist — always check before suggesting a method.
+4. **List tests**: `npx codeceptjs dry-run -c <config>` — `--steps` shows queued actions, `--grep` filters, `--numbers` gives per-test step indices matching MCP `pauseAt`.
+   - ⚠ `dry-run --grep` and `run --grep` do **not** select the same set (4.1.0): `run --grep` matches `Feature` + `Scenario`, `dry-run --grep` matches the Scenario title only. `dry-run --grep 'Dialogs'` lists 0 tests where `run --grep 'Dialogs'` executes all 11. Never size a run from a dry-run's grep, and target a whole Feature by file path (`run tests/foo_test.ts`) when the selection must be exact.
+
+Gherkin projects: `npx codeceptjs gherkin:steps -c <config>`.
+
+Reference docs live under `node_modules/codeceptjs/docs/` — read them instead of guessing APIs.
+
+## Report
+
+Short prose summary. Must include:
+
+- Env-driven values flagged as env-driven (`process.env.BROWSER || 'chromium'`, not just `'chromium'`)
+- Conflicts flagged (static `show: true` vs `setHeadlessWhen(CI)`; `auth` configured but credential env vars missing)
+- No config at root and no `--config` referenced → recommend `npx codeceptjs init .`, stop
+- 3.x/CommonJS detected → recommend `migrate-codeceptjs-4`, stop

package/skills/codeceptjs/codeceptjs-run-analysis/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: codeceptjs-run-analysis
+description: >
+  Use after running CodeceptJS tests with the `aiTrace` plugin enabled and the
+  results need review — verify a fix held, investigate a single failure, cluster
+  errors across a CI fail-storm, diagnose flakiness across reruns. Invoked by
+  other CodeceptJS skills whenever a run has happened. Trigger on "what failed",
+  "analyse the run", "cluster these errors", "is it flaky", "did the fix hold".
+---
+
+# CodeceptJS Run Analysis
+
+After `npx codeceptjs run`, trace artifacts land in `output/`. This skill reads them efficiently — right step, right file, right slice of a giant HTML snapshot — via bash tools rather than re-running through MCP.
+
+No single end goal: pick the use case matching the situation. The foundations apply to all of them.
+
+## Foundations
+
+- **aiTrace must be on.** Everything leans on `output/trace_<TestName>_<hash>/trace.md`. Confirm in the active config (run `codeceptjs-fundamentals` if unknown). Without it there are only screenshots and `pageInfo` dumps — suggest enabling and re-running before deep analysis.
+- `run_step_by_step` is interactive only; `aiTrace` is the sole source of per-step files. Ad-hoc `run_code` / `snapshot` still produce single-shot bundles under `output/trace_run_code_*` / `output/snapshot_*`.
+- **Locate traces**: reruns create new dirs — when unclear, most recent wins (`ls -dt output/trace_*`).
+- **Read trace.md first** — it's the index linking each step to its artifacts.
+  - Focus on the failed step; none marked → last step in the trace.
+  - Multiple failures marked → the **first** is usually the cause; the rest cascade.
+
+### Artifact order for the focus step (`NNNN_<step>`)
+
+| Artifact | When |
+|---|---|
+| `NNNN_*_aria.txt` | First read — lean, structured, easy to scan for duplicates |
+| `NNNN_*_screenshot.png` | Visual confirmation — layout, animation, "rendered but wrong" |
+| `NNNN_*_console.json` | JS errors, 4xx/5xx, deprecation warnings explaining vanished elements |
+| `NNNN_*_storage.json` | Cookies + localStorage at this step — first stop when auth suspected |
+| `NNNN_*_page.html` | Last resort, and only via `grep` |
+
+### Never read big files whole
+
+- HTML snapshots: search with `grep` (text, class, aria-label, `data-*`) — line numbers + context flags keep matches readable.
+- `console.json`: filter with `jq`, don't read every entry.
+- Scanning many files: `grep -l` for filenames only.
+
+## Use cases
+
+### Verify a fix held
+Locate latest trace → read trace.md → confirm no FAILED markers. Glance at `console.json` for warnings worth fixing while you're there.
+
+### Cluster errors across a CI batch
+Extract failing-step lines from every `trace.md`, group by signature (`grep` + `sort` + `uniq -c`), rank by frequency.
+- Same error in many tests = **systemic** (env var, auth, base URL, deploy regression) — fix root cause once, rerun the batch.
+- Different errors per test = local — triage one at a time.
+Start with the most frequent root cause; rerun to see how many tests came back with it.
+
+### Diagnose flakiness
+Rerun the same test 5–10 times; compare which step failed in each trace.
+- Different step each run → timing, environment, external service
+- Same step, different state → missing/wrong wait — `diff` the ARIA snapshots of that step between runs
+- `console.json` differs between runs → transient backend/network errors
+- Bounding box differs → layout reflow or late-loading content
+
+### Investigate a single failure
+Failed-or-last step → ARIA + screenshot first, console second, HTML last (grep only). Form a hypothesis. Trace not enough / page needs live poking → hand off to `debugging-codeceptjs-tests`.
+
+## After analysis
+
+- Systemic cause → fix root once (env, auth, deploy), not per test
+- Locator drift → `codeceptjs-exploration`
+- Timing/wait issue → Waiting guidance from fundamentals/writing skills; replace `I.wait(N)` with specific `waitFor*`
+- Resists static analysis → `debugging-codeceptjs-tests` (live MCP loop)
+- Clean pass → done, but glance at `console.json` anyway
+
+## Things to avoid
+
+- Reading large HTML or `console.json` whole — `grep` / `jq`.
+- Stopping at the last marked failure instead of the first.
+- Triaging individual failures before clustering.
+- Flakiness conclusions from a single run — needs 5+ reruns.
+- Deleting `output/` mid-investigation.
+
+## Related skills
+
+- `codeceptjs-fundamentals` — what's configured, aiTrace `-p` overrides
+- `codeceptjs-exploration` — locator drift fixes
+- `debugging-codeceptjs-tests` — live loop + offline locator resolution via `codeceptq`

package/skills/codeceptjs/debugging-codeceptjs-tests/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: debugging-codeceptjs-tests
+description: >
+  Use when a CodeceptJS 4 test fails, flakes, or behaves unexpectedly. Trigger
+  on run errors and stack traces from `npx codeceptjs run`, intermittent
+  failures, locator drift, timing issues, "works locally fails in CI", "why
+  does this fail", trace/screenshot/console mentions, and breakpoint /
+  step-through / "pause at step N" requests.
+---
+
+# Debugging CodeceptJS 4 Tests
+
+Failures lie — the error usually points at a step that's a side effect of something earlier (auth expired, frame switch missed, network call pending). Reproduce, capture state, read it, then fix.
+
+## Paths
+
+- **MCP-first (AI agents)**: `run_test` / in-test `pause()` yield control to the agent on the same `I` / browser the test uses. Inspect via `run_code` / `snapshot`; step through via `run_step_by_step` + `continue`.
+- **CLI fallback (humans / CI / framework internals)**: `--debug` → `--verbose` → `DEBUG="codeceptjs:*"`. The DEBUG escape hatch is only for framework-internal suspicion: recorder hangs, plugin races, event leaks, "step never ran". Namespaces: `codeceptjs:recorder`, `codeceptjs:pause`, `codeceptjs:ai`, `codeceptjs:plugin:<name>`.
+
+`pause()` adapts to who's driving: TTY → readline REPL; MCP → yields control to the agent; non-TTY non-MCP subprocess → prints a notice and resolves (no CI deadlock).
+
+## Workflow
+
+1. **Fundamentals** — run `codeceptjs-fundamentals`: helper, plugins (`aiTrace`, `screenshot`, `pageInfo`, `retryFailedStep`, `pause`, `auth`), env vars, MCP availability. If `aiTrace` isn't declared, add it once: `plugins: { aiTrace: { enabled: true } }` — most of this skill leans on its output.
+   - **Declare once; never edit config to change its trigger.** Override per-run with `-p aiTrace:on=step|fail|test|file|url` (fundamentals § Plugins from CLI). `on=fail` for lean CI repros, `on=step` while diagnosing. Flipping `on:` in config churns the repo and leaks into other runs.
+2. **Reproduce minimally**: `npx codeceptjs run --grep '<scenario>' --steps`. Add `-c codecept.ci.conf.js` if CI-specific. Confirm reproduction before instrumenting.
+3. **Pick tools**:
+   - MCP `run_test <test>` — runs in-process; returns reporter result or `{ status: 'paused', pausedAfter, page, suggestions }`
+   - MCP `run_step_by_step` + `continue` — pause after every step; for watching the whole flow
+   - MCP `run_code` — arbitrary code in the live session; works fresh *and* paused; returns produced values + console output + final-state snapshot
+   - MCP `snapshot` — current browser state without acting (URL, cookies, storage, HTML, ARIA, screenshot, console)
+   - MCP `list_actions` — sanity-check an `I.*` method exists
+   - CLI `npx codeceptjs run --grep '<scenario>' --debug` — first move without MCP; `--verbose` adds promise-queue/retry/timeout logs
+4. **Breakpoint**:
+   - In-test `pause()` — best when already editing or breaking inside `within`/loop/hook
+   - `pauseAt: N` on `run_test` — no test edit; pauses after the Nth leaf step
+   - Find N: `npx codeceptjs dry-run --debug --grep '<scenario>' --numbers --no-ansi` (1-based, per-test; number of the line to stop *after*)
+   - While paused: inspect with `run_code`, capture clean state with `snapshot`, walk prior steps in `output/trace_<TestName>_<hash>/trace.md`, release with `continue`
+5. **Read the trace** — hand off to `codeceptjs-run-analysis`; focus on the **first** failed step — late failures are usually side effects of an earlier silent miss. It also covers grepping large HTML, clustering errors across traces, comparing reruns.
+6. **Form a hypothesis**:
+
+   | Symptom | Likely cause |
+   |---|---|
+   | Element missing, page is `/login` | Auth: stale session cache, missing env var |
+   | Element in HTML but `display: none` | `waitForVisible`, not `waitForElement` |
+   | Locator matches 2+ (strict mode) | Scope it: context arg, then ARIA role, then `step.opts({ elementIndex })` |
+   | Element present in screenshot N+1, missing in N | Animation / lazy load → `waitForVisible(loc, t)` |
+   | 401/403 in console.json | API token expired or env var missing |
+   | Steps pass, next `I.see` fails | Frame switch missed → `within({ frame })` |
+   | Different result CI vs local | `setHeadlessWhen(CI)`, viewport, timing, env vars |
+   | Recorder hangs, step never fires | `DEBUG="codeceptjs:recorder"` |
+   | Plugin misbehaves | `DEBUG="codeceptjs:plugin:<name>"` |
+
+7. **Verify the fix on the live page** — try the candidate replacement step via `run_code` (works while paused, same `I`) **before editing the file**. Humans at a TTY get the same via in-test `pause()`.
+8. **Apply and re-run**: edit, then `npx codeceptjs run --grep '<scenario>' --steps`; confirm via `codeceptjs-run-analysis` that the failure didn't shift steps. Leave a one-line `Why:` comment when the fix introduces `waitFor*` or `step.opts` — those comments are worth keeping.
+
+## Query trace HTML with `codeceptq`
+
+`aiTrace` writes per-step `<NNNN>_<step>_page.html` snapshots (one element per line — line numbers map 1:1 to elements). `codeceptq` resolves any CodeceptJS locator against a saved snapshot.
+
+- **Never load page HTML into context manually** — snapshots are thousands of lines; `codeceptq` returns only matched elements with their line numbers.
+- Test candidate locators offline before applying via `run_code` — a hit is a green light to try live, not a guarantee (visibility, re-renders).
+- Multiple matches → don't write a brittler XPath; disambiguate with `step.opts({ elementIndex })` following the order `codeceptq` prints.
+
+```bash
+npx codeceptq '#submit-btn' --file output/trace_*/0007_*_page.html     # CSS
+npx codeceptq 'Email' --field --file output/trace_*/0003_*_page.html   # semantic field
+npx codeceptq 'Save' '.modal' --click --file output/trace_*/0005_*_page.html  # scoped clickable
+npx codeceptq 'Username' --field --json --file ...                     # machine-readable
+```
+
+Key flags: `--field/--click/--checkable/--select` force semantic strategies; `--xpath`/`--css` override auto-detection (a bare tag name like `select.foo` is treated as fuzzy text); exit codes `0` match / `1` none / `2` invalid input.
+
+> ⚠ **The `[context]` second positional does not scope** (CodeceptJS 4.1.0). It prints `N matches within '<ctx>'` but returns page-wide results — `lib/command/query.js` evaluates an absolute XPath (`//…`) against the context node, and `//foo` re-roots at the document. It will report a match inside a container that does not hold the element. To check a scoped locator offline, pass one composed selector (`codeceptq '.modal button[aria-label="Save"]'`) and compare its count against the unscoped form; a context-dependent locator is only truly verified by running the step.
+
+## Inspect deeper
+
+Hand off to `codeceptjs-exploration` when the trace says *what* failed but you need more page-state detail ("is this button actually disabled?", "are there really two Save buttons?"). Debug-specific reaches:
+
+- Button rendered but click had no effect → `grabWebElement('Submit')` + `isEnabled()` + `getBoundingBox()` (disabled? offscreen?)
+- Strict-mode multi-match → exploration's broad-XPath iterate-and-disambiguate pattern
+- Iframe content → wrap failing steps in `within({ frame })`
+
+Prefer this over `usePlaywrightTo`/`useWebDriverTo` for inspection — same code across helpers, less boilerplate.
+
+## Native helper escape hatch
+
+Only when the `I.*` surface truly doesn't cover it (network interception, storage manipulation, helper-only APIs):
+
+- Playwright: `I.usePlaywrightTo('label', async ({ browser, browserContext, page }) => { ... })`
+- Puppeteer: `I.usePuppeteerTo('label', async ({ page }) => { ... })`
+- WebDriver: `I.useWebDriverTo('label', async ({ browser }) => { ... })`
+
+The label shows up in step output and traces. Works inside MCP `run_code` too. These couple tests to a specific helper — last resort.
+
+## Helper gotchas
+
+- Playwright: `strict: true` throws on multi-match; prefer `'load'`/`'domcontentloaded'` over `'networkidle'`; `trace: 'on'` → `output/trace.zip` (`npx playwright show-trace`)
+- Puppeteer: `'networkidle0'` hangs on long-polling pages — use `'networkidle2'` or `'domcontentloaded'`
+- WebDriver: `smartWait` covers actions only, not assertions; `executeScript` args must be JSON-serializable
+
+## Auth-related failures
+
+Redirect to `/login` mid-test or 401/403 in console → fix **auth**, not the failing step: check the plugin's `check`, credential env vars, and stale cached session under `output/<role>_session.json` (delete to force re-login). Full pattern in `codeceptjs-auth`.
+
+## Flakiness and waits
+
+Most "intermittent" failures are missed waits. Use trace HTML/ARIA to find the actual gating element instead of adding generic delay (fundamentals § Waiting has the mapping). `I.wait(N)` confirms a timing hypothesis while debugging — replace with the specific `waitFor*` before committing.
+
+## Things to avoid
+
+- Fixing from the error message without reading the trace.
+- Editing the test before verifying the fix via `run_code`.
+- Committing `pause()` calls — debugging tool only.
+- Blind `waitFor*` instead of identifying the real gating element.
+- Leaving `I.wait(N)` in committed tests.
+- Editing `aiTrace`'s `on:` in config between runs — declare once, override per-run.
+- Skipping the config check — `setHeadlessWhen(CI)` / env-driven URLs explain many "works locally fails in CI".
+- Hiding failures with `retries` instead of fixing the cause.
+
+## Related skills
+
+- `codeceptjs-fundamentals` — effects, plugins-from-CLI, waiting rules
+- `codeceptjs-exploration` — WebElement inspection, broad-XPath disambiguation
+- `codeceptjs-run-analysis` — trace.md walking, error clustering, rerun comparison
+- `codeceptjs-auth` — auth failure patterns

package/skills/codeceptjs/migrate-codeceptjs-4/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: migrate-codeceptjs-4
+description: "Migrate a CodeceptJS 3.x project to 4.x. Trigger when `package.json` pins `codeceptjs` at 3.x or is missing `\"type\": \"module\"`, when test files still use CommonJS (`require()` / `module.exports`) against CodeceptJS APIs, when config references removed helpers (`Nightmare`, `Protractor`, `TestCafe`, `AI`, `SoftExpectHelper`, `Mochawesome`) or removed plugins (`autoLogin`, `tryTo`, `retryTo`, `eachElement`, `commentStep`, `fakerTransform`, `enhancedRetryFailedStep`, `allure`, `htmlReporter`, `wdio`, `selenoid`, `screenshotOnFail`, `pauseOnFail`, `stepByStepReport`), or when 3.x APIs are in use (`ai.request` function, Joi schemas in `seeResponseMatchesJsonSchema`, `restart: 'browser'`, `I.retry()`, `I.limitTime()`, Playwright `customLocators`)."
+---
+
+# Migrate CodeceptJS 3.x → 4.x
+
+CodeceptJS 4 is **ESM-only and TypeScript-first**. There is no compatibility shim for CommonJS — every helper, page object, custom step, and config file must be ESM. This skill drives a project through the upgrade end-to-end.
+
+The authoritative reference is `node_modules/codeceptjs/docs/migration-4.md` (after `npm install codeceptjs@4`). Read it once; this skill orchestrates the work and surfaces the parts agents miss.
+
+## When to trigger
+
+Detect *before* acting. Look for any of:
+
+- `package.json` lists `"codeceptjs": "^3"` / `"3.x"`, or has no `"type": "module"`.
+- Tests, page objects, helpers, or config use `require()` / `module.exports` against CodeceptJS.
+- Config still references removed helpers (`Nightmare`, `Protractor`, `TestCafe`, `AI`, `SoftExpectHelper`, `Mochawesome`) or removed plugins (`autoLogin`, `tryTo`, `retryTo`, `eachElement`, `commentStep`, `fakerTransform`, `enhancedRetryFailedStep`, `allure`, `htmlReporter`, `wdio`, `selenoid`, `screenshotOnFail`, `pauseOnFail`, `stepByStepReport`).
+- 3.x APIs: `ai.request`, Joi schemas in `seeResponseMatchesJsonSchema`, `restart: 'browser'`, `I.retry()`, `I.limitTime()`, Playwright `customLocators`, `I.softExpect*` / `I.flushSoftAssertions`.
+- `--reporter mochawesome` in scripts/CI, or `mochawesome` in `package.json` / `mocha.reporterOptions`.
+
+If none of these hint at 3.x, the project is likely on 4.x already — hand back to `codeceptjs-fundamentals`.
+
+## Workflow
+
+Phases run in order. Commit at each boundary so any regression is bisectable.
+
+### 1. Bump Node and CodeceptJS
+
+- Confirm Node ≥ 16 (recommended 20+); update `engines.node` and CI runners.
+- `npm install codeceptjs@4`.
+- TypeScript projects: `npm install --save-dev tsx`. Replaces `ts-node/esm`, which now warns.
+
+### 2. Convert the project to ESM
+
+- Add `"type": "module"` to `package.json`. **Without this, every `.js` file parses as CommonJS and ESM imports throw at load time.**
+- Convert config, page objects, custom helpers, custom steps, programmatic usage:
+  - `const Helper = require('@codeceptjs/helper')` → `import Helper from '@codeceptjs/helper'`
+  - `module.exports = X` → `export default X` (or named exports)
+  - `const { codecept, container, event } = require('codeceptjs')` → `import codeceptjs, { container, event } from 'codeceptjs'`
+- `Container.create()` and `Config.load()` are now async — `await` them.
+- Files that genuinely need CJS (rare; usually third-party shims): rename to `.cjs`.
+
+### 3. Remove or replace deleted helpers and plugins
+
+| Old | Replacement |
+|---|---|
+| Helper `Nightmare` / `Protractor` / `TestCafe` | `Playwright`, `Puppeteer`, or `WebDriver`. |
+| Helper `AI` | Top-level `ai:` config + `aiTrace` plugin. |
+| Helper `SoftExpectHelper` | `import { hopeThat } from 'codeceptjs/effects'`; call `hopeThat.noErrors()` at end of scenario. |
+| Helper `Mochawesome` | **Stop and ask the user** — see "Mochawesome decision" below. Do not silently delete it. |
+| Plugin `autoLogin` | `auth` plugin (see the `codeceptjs-auth` skill). |
+| Plugin `tryTo` / `retryTo` | `import { tryTo, retryTo } from 'codeceptjs/effects'` |
+| Plugin `eachElement` | `import { eachElement } from 'codeceptjs/els'` |
+| Plugin `commentStep` | `import step from 'codeceptjs/steps'` → `step.section('name')` / `step.endSection()` |
+| Plugin `fakerTransform` | `import { faker } from '@faker-js/faker'` directly in tests. |
+| Plugin `enhancedRetryFailedStep` | Renamed to `retryFailedStep`. |
+| Plugin `allure` / `htmlReporter` | `@testomatio/reporter` (HTML pipe). For JUnit XML, the `junitReporter` plugin. |
+| Plugin `wdio` / `selenoid` | Configure via `helpers.WebDriver`, or run externally. |
+| Plugin `screenshotOnFail` / `pauseOnFail` / `stepByStepReport` | Renamed `screenshot` / `pause` / `screenshot` with `slides: true`. Old names still resolve but emit a deprecation warning. |
+
+#### Mochawesome decision
+
+The bundled `Mochawesome` **helper** is removed in 4.x (the helper class, the `mochawesome` dependency, and the worker report-dir wiring). The `mochawesome` **reporter** itself still works — it is a stock Mocha reporter and never needed CodeceptJS to bundle it.
+
+This is a **user choice — do not pick for them**. When you detect Mochawesome (the helper in `helpers:`, `--reporter mochawesome`, or `mochawesome` in `package.json`/`mocha.reporterOptions`), stop and ask which path they want:
+
+1. **Switch to `@testomatio/reporter` (recommended).** Richer HTML report (steps, screenshots, videos, traces), worker-safe, no helper or internal coupling. `npm install --save-dev @testomatio/reporter`, enable the `testomatio` plugin, run with `TESTOMATIO_DISABLE_UPLOAD=1`. For JUnit XML add the `junitReporter` plugin. This is the path to recommend.
+2. **Keep Mochawesome — report only.** Remove the `Mochawesome` helper from `helpers:`, keep `npm i -D mochawesome` and `--reporter mochawesome --reporter-options reportDir=output`. Loses the auto-embedded failure screenshots the helper provided.
+3. **Keep Mochawesome — with embedded screenshots.** Remove the helper from `helpers:` and re-create it as a **project-local custom helper** that wraps `mochawesome/addContext` (a faithful port is in the migration guide, section "Keeping Mochawesome"). Flag the two caveats: it imports non-semver-stable `codeceptjs/lib/*` internals (pin the version), and the screenshot-plugin filename sync is no longer automatic (set `uniqueScreenshotNames` identically on the helper and the `screenshot` plugin).
+
+In all cases also: remove `mochawesome` report-dir handling from any custom worker scripts, and replace any reliance on `I.addMochawesomeContext()` (only option 3 keeps it).
+
+Present options 1–3 explicitly and let the user decide before changing anything. Default the recommendation to option 1. The full reference (before/after configs + the custom-helper port) is in `node_modules/codeceptjs/docs/migration-4.md` → "Mochawesome → Testomat.io Reporter".
+
+### 4. Update changed APIs
+
+- **AI config** — delete the `request` function. Install Vercel AI SDK + provider (`npm install ai @ai-sdk/openai`) and set `ai: { model: openai('gpt-5') }`. Same shape for `@ai-sdk/anthropic`, `@ai-sdk/google`, etc.
+- **JSON schemas** — `I.seeResponseMatchesJsonSchema()` now uses Zod, not Joi. Rewrite (`Joi.object().keys({...})` → `z.object({...})`, `Joi.string().required()` → `z.string()`, etc.) and `npm uninstall joi`.
+- **Playwright** — replace `restart: 'browser'` with `'session'` (default), `'context'`, or `'keep'`. Drop `customLocators` config; use the `customLocator` plugin or ARIA locators (`{ role: 'button', name: 'Submit' }`).
+- **`I.retry()` / `I.limitTime()`** — **removed** (not just deprecated). Replace with the step options API: `import step from 'codeceptjs/steps'`, then pass the config as the **last argument** of the step. `I.retry(3).click('Submit')` → `I.click('Submit', step.retry(3))`; `I.limitTime(10).fillField('Email', x)` → `I.fillField('Email', x, step.timeout(10))`. Also `step.opts({ elementIndex: 2 })`. Behavior is unchanged except the option no longer leaks onto the following step. `recorder.retry()` is unaffected (custom helpers only).
+- **`within` and `session`** — no longer global. `import { within, session } from 'codeceptjs'` (or `within` from `codeceptjs/effects`). Both return Promises — `await` when you need the return value.
+- **Subpath imports** — `codeceptjs/effects`, `codeceptjs/els`, `codeceptjs/steps`, `codeceptjs/store`, `codeceptjs/assertions`. See the migration guide for the full list.
+- **`tryTo` / `hopeThat`** — return `Promise<boolean>` (the 3.x `Promise<T | false>` shape is gone).
+
+### 5. Adopt `noGlobals: true`
+
+3.x leaked `Helper`, `actor`, `inject`, `share`, `secret`, `locate`, `dataTable`, `within`, `session`, `codecept_dir`, `output_dir` as globals. 4.x defaults `noGlobals: true` in new configs and warns for projects without it. Add it to config and replace globals with explicit imports from `codeceptjs` / `@codeceptjs/helper`. Test-runner globals (`Feature`, `Scenario`, `Before`, `After`, `BeforeSuite`, `AfterSuite`, `pause`, `inject`, `share`) and BDD step-definition globals (`Given`, `When`, `Then`, `And`) **stay** — they're scope-injected by the runner.
+
+### 6. Bump dependent packages
+
+If your project depends directly on these, verify nothing breaks: `chai` (4 → 6, ESM-only), `chai-as-promised` (7 → 8), `commander` (11 → 14), `@faker-js/faker` (9 → 10), `chokidar` (4 → 5), `@cucumber/gherkin` (35 → 38), `webdriverio` (9.12 → 9.23). `joi` and `testcafe` are removed. See migration guide §7 for the full table.
+
+### 7. Verify
+
+Run, in order:
+
+1. `npx codeceptjs check -c <config>` — surfaces config / helper / plugin / page object issues without spinning up a browser.
+2. `npx codeceptjs run --debug` on a small smoke scenario. Confirm steps execute and the report is sane.
+3. `npx codeceptjs run-workers 2` — confirms the worker event dispatcher fires per-test events the same way it does in single-process mode (4.x change).
+4. TypeScript users: confirm error stack traces point at `.ts` source lines (proves `tsx` is loaded, not `ts-node/esm`).
+5. Grep the repo for `tryTo(`, `retryTo(`, `eachElement(`, `commentStep(`, `softExpect`, `I.softExpect`, `Joi.`, `restart: 'browser'`, `I.retry(`, `I.limitTime(`, and (unless the user chose to keep it) `Mochawesome` / `--reporter mochawesome` — none should remain. `step.retry(` / `step.timeout(` passed as a step argument is the expected replacement, not a leftover.
+6. If the project used `autoLogin`: confirm the `auth` plugin restores sessions and roles.
+
+## Related skills
+
+- `codeceptjs-auth` — replacement for the removed `autoLogin` plugin
+- `codeceptjs-fundamentals` — run **after** migration to confirm wiring
+- Full reference: `node_modules/codeceptjs/docs/migration-4.md`