testeiya 0.10.1 → 0.10.2

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

@@ -1,126 +0,0 @@
----
-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/lint-codeceptjs-tests/SKILL.md

@@ -1,104 +0,0 @@
----
-name: lint-codeceptjs-tests
-description: >
-  Use when a CodeceptJS 4 suite needs a static quality gate — before committing
-  tests, reviewing a PR that touches tests, hardening CI, or on direct asks:
-  "lint the tests", "find I.wait / setTimeout sleeps", "leftover .only or
-  pause()", "missing await on grab", "passwords printed in logs", "why are
-  tests slow/flaky". Runs `@codeceptjs/lint` — an AST-based linter that needs
-  no CodeceptJS install and no browser.
----
-
-# Lint CodeceptJS 4 Tests
-
-`@codeceptjs/lint` reads tests, page objects and helpers as an AST and reports the smells that make suites slow, flaky or leaky — fixed sleeps, `if` branching, raw `fetch`, missing `await` on grabbers, plain-text credentials, leftover `.only`/`pause()`. One finding per line; exit codes `0` / `1` (errors found) / `2` (bad input, unparsable file) drop straight into CI.
-
-## Commands
-
-```bash
-npx @codeceptjs/lint                          # files from codecept.conf.js in cwd
-npx @codeceptjs/lint tests/ pages/login.js    # explicit paths (no config needed)
-npx @codeceptjs/lint -r no-pause -r no-only   # only these rules (or --rules a,b)
-npx @codeceptjs/lint rules                    # list rules + defaults
-npx @codeceptjs/lint --json                   # file, line, column, rule, level, message, source
-npx @codeceptjs/lint -c e2e/codecept.conf.js  # config in another directory
-```
-
-Without paths it reads `codecept.conf.js|ts|cjs|mjs` and lints everything matched by `tests`, local `include` files (page objects, steps file) and helpers loaded via `require`. TypeScript is parsed with Node's type stripping (Node 22.13+); `enum`/`namespace` report as parse errors. A TS config importing `./x.js` for an `x.ts` file (tsx convention) loads when the project has `tsx` installed.
-
-## Rules and the fix for each
-
-| Rule | Default | Detects → fix |
-|---|---|---|
-| `no-fixed-wait` | error | `I.wait(5)` → `I.waitForElement` / `I.waitForText` / `I.see` |
-| `no-sleep` | error | bare and `window.`/`globalThis.` `setTimeout`, incl. `await new Promise(r => setTimeout(r, ms))` and `timers/promises`, outside helpers → condition wait |
-| `no-if-in-test` | error | `if` inside a Scenario/hook → `tryTo()` from `codeceptjs/effects` |
-| `no-fetch` | error | `fetch()` (incl. `window.fetch`, `globalThis.fetch`) outside helpers → REST helper `I.sendGetRequest` / `I.sendPostRequest` |
-| `no-console` | warn | `console.*` outside helpers → `I.say()` (lands in the report) |
-| `no-only` | error on CI, warn locally | `Scenario.only`, `Feature.only`, `Data(...).only` → remove before commit |
-| `no-pause` | error on CI, warn locally | `pause()`, `this.pause()` → remove before commit |
-| `no-skip` | warn | `Scenario.skip`, `Feature.skip`, `xScenario`, `xFeature` → intentional? suppress with a comment explaining why |
-| `secret-credentials` | error | credential-ish `process.env.X` / `process.env['X']` or a password/token/secret/api-key locator passed to `I.*` → wrap with `secret()` |
-| `await-grab` | error | `I.grab*()` assigned, destructured or passed without `await` (`await Promise.all([...])` and `.then()` chains are fine) → add `await` |
-| `no-actor-in-helper` | error | `I` inside a class extending `Helper` → `this.helpers['Name']` |
-| `raw-browser-in-test` | warn | `I.use*To`, `I.executeScript` in a Scenario → move into a helper or page object |
-
-"On CI" = the `CI` env var is set — local debugging stubs (`pause()`, `.only`) stay warnings so they don't fail the lint while investigating.
-
-## Configuring per project
-
-Levels live in the config, next to the tests they govern:
-
-```js
-export const config = {
-  tests: './*_test.js',
-  lint: {
-    rules: { 'no-if-in-test': 'warn', 'raw-browser-in-test': 'off' },
-  },
-}
-```
-
-Levels: `error`, `warn`, `off`. For a single deliberate case, suppress inline — rule id required, never disable a rule project-wide for one line:
-
-```js
-I.wait(1) // codeceptjs-lint-disable-line no-fixed-wait
-```
-
-## Workflow
-
-1. Run `npx @codeceptjs/lint` at the project root; if no config loads (secrets, tsx-less TS config), pass paths explicitly.
-2. Fix errors first (they fail CI), warnings by judgment. Triage by cost: sleeps and missing `await` are the flakiness drivers; `secret()` fixes are one-line.
-3. For bulk cleanup, feed `--json` output to drive file-by-file edits — the `source` field holds the offending line (truncated to 120 chars).
-4. Add the gate so it stays clean:
-
-```yaml
-# CI, before codeceptjs run
-- run: npx @codeceptjs/lint
-```
-
-For agent-driven work, a Claude Code `PreToolUse` hook blocks edits that *add* a new error (pre-existing errors and warnings never block; a failing hook allows the edit):
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      { "matcher": "Write|Edit|MultiEdit", "hooks": [{ "type": "command", "command": "npx @codeceptjs/lint --hook claude" }] }
-    ]
-  }
-}
-```
-
-## Things to avoid
-
-- "Fixing" `await-grab` by deleting the `await` usage — the grab result is a promise, the fix is `await`, not removal.
-- Replacing `I.wait` with a longer `I.wait`.
-- Suppressing `no-if-in-test` when the branch is load-bearing — that's `tryTo()` or a helper's job.
-- Adding the CI step before triaging existing findings — the suite goes red on day one.
-- Skipping the hook's config scope check — it only lints files the config covers.
-
-## Related skills
-
-- `debugging-codeceptjs-tests` — `I.wait(N)` as a timing probe is fine mid-debug, lint-clean it before committing
-- `refactoring-codeceptjs-tests` — bulk cleanup of a lint-red suite (extract helpers, tame locators)
-- `writing-codeceptjs-tests` — write clean tests from the start
-- `ci-fix-tests` — run the lint gate first so CI fixes don't reintroduce smells

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

@@ -1,109 +0,0 @@
----
-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`