testeiya 0.3.9 → 0.3.10

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`

package/skills/codeceptjs/migrate-cypress-to-codeceptjs/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: migrate-cypress-to-codeceptjs
+description: "Port a Cypress test suite to CodeceptJS 4. Trigger when the project contains `cypress.config.{js,ts,mjs}`, a `cypress/` directory (`cypress/e2e/`, `cypress/support/{commands,e2e}.*`, `cypress/fixtures/`), `cypress` in `devDependencies`, or test code calling `cy.*` (`cy.visit`, `cy.get`, `cy.contains`, `cy.session`, `cy.intercept`, `cy.request`, `cy.task`, `cy.fixture`, `cy.origin`, `cy.mount`), `Cypress.Commands.add(...)`, or `Cypress.env(...)`."
+---
+
+# Migrate Cypress → CodeceptJS 4
+
+Cypress and CodeceptJS share a goal — browser end-to-end testing — but differ in three foundational ways:
+
+1. **Step queueing vs command chains.** CodeceptJS auto-queues every `I.*` call onto an internal recorder; tests look synchronous and `await` is only needed for grabs (`await I.grabTextFrom(...)`). There is no `.then()` chain to thread state through.
+2. **Helpers, not a bundled browser.** `I.*` dispatches to a configured helper. Cypress is single-browser by design; CodeceptJS lets you pick **Playwright** (recommended for Cypress migrators — Chromium parity plus cross-browser), Puppeteer, or WebDriver, and the test code stays the same.
+3. **First-class abstractions.** Page objects, multi-user `session(...)`, the `auth` plugin, and custom helpers are built in. Cypress projects accumulate ad-hoc versions of these; the migration consolidates them onto the framework's idioms.
+
+Authoritative reference: `node_modules/codeceptjs/docs/` (basics, locators, playwright, custom-helpers, pageobjects).
+
+## When to trigger
+
+Any of:
+
+- `cypress.config.{js,ts,mjs}` at the repo root.
+- A `cypress/` directory with `e2e/`, `support/`, `fixtures/`, `plugins/`, or `component/` subdirs.
+- `cypress` listed in `devDependencies`.
+- Test code calls `cy.*` (`cy.visit`, `cy.get`, `cy.contains`, `cy.session`, `cy.intercept`, `cy.request`, `cy.task`, `cy.fixture`, `cy.origin`, `cy.mount`), uses `Cypress.Commands.add(...)`, or reads `Cypress.env(...)`.
+- The user says "migrate / port / convert from Cypress".
+
+## What does not migrate
+
+Be honest up-front:
+
+- **Component tests** (`cy.mount`, `cypress/component/`) — CodeceptJS is E2E only. Keep Cypress for components, or move them to Playwright Component Testing / Vitest + Testing Library.
+- **`cy.intercept('POST', '/api').as('save')` → `cy.wait('@save')`** — the closest equivalent is Playwright's `I.mockRoute()` (no alias, no `cy.wait('@x')`). Anchor waits on UI outcomes (`I.waitForText('Saved')`) instead of network events.
+- **Cypress Cloud / time-travel debugger** — replaced by the `aiTrace` plugin's per-step artifacts and `@testomatio/reporter` for dashboards.
+- **`cy.origin()` multi-origin flows** — limited support; document the gap and plan around it.
+
+## Workflow
+
+Run phases in order. Commit at each boundary so any regression is bisectable.
+
+### 1. Inventory the Cypress project
+
+Before touching anything, build a picture. Two passes.
+
+**Shape of the project** — grep / `wc -l` for cost predictors:
+
+- `cypress.config.{js,ts,mjs}` — which keys are in use
+- `cypress/e2e/**/*.cy.{js,ts}` — spec count
+- `cypress/fixtures/` — count + filenames
+- `cypress/support/{e2e,commands}.{js,ts}` — these always exist; **read in full**
+- `cypress/plugins/` — legacy preprocessor / task wiring
+- `cypress/component/` + `cy.mount(` — flag for the user (out of scope)
+- count occurrences of `cy.intercept(`, `cy.task(`, `cy.session(`, `cy.origin(`, `Cypress.Commands.add(`, `cy.fixture(` — each maps to a known replacement pattern
+
+**Shared logic and shared locators** — Cypress has no built-in page objects, but suites accumulate shared abstractions anyway. Find them before touching test files:
+
+- **Custom commands** — every `Cypress.Commands.add('<name>', fn)` in `cypress/support/commands.{js,ts}`. List name → arguments → body. Almost every suite has them (`cy.login`, `cy.seedData`, `cy.dragRowTo`, …).
+- **Page-object-style modules** — look in `cypress/support/`, `cypress/pages/`, `cypress/page-objects/`, `cypress/helpers/`, `cypress/objects/`, `cypress/po/`, and any `pages/` / `pageObjects/` outside the cypress directory. Recognise: modules exporting selector bundles (`{ usernameField: '#user', submitBtn: '[data-cy=submit]' }`), modules exporting methods that call `cy.*` (`login(user, pwd)`, `goToProfile()`), classes with selectors as fields.
+- **Shared selector constants** — files named `selectors.{js,ts}` / `locators.{js,ts}`, or modules exporting only strings. Grep specs for repeated `cy.get('[data-cy=...]')` strings — duplicates are abstraction candidates.
+- **Utility helpers** — date formatters, URL builders, API wrappers (`api.js`, `helpers.js`, `utils.js`).
+- **Global hooks** — `cypress/support/e2e.{js,ts}` `beforeEach` blocks, `Cypress.on('uncaught:exception', ...)`, etc.
+
+Produce a short inventory: every shared abstraction with its current Cypress location and planned CodeceptJS destination (see phase 4's destination table). The user reviews before any code is written.
+
+### 2. Install CodeceptJS alongside Cypress
+
+`npx codeceptjs init` and pick the **Playwright** helper. Do not remove Cypress yet — both run in parallel through the migration, so a half-converted suite still has green coverage.
+
+### 3. Port the config
+
+Map `cypress.config.{js,ts}` keys → `codecept.conf.{js,ts}`:
+
+| Cypress | CodeceptJS 4 (`Playwright` helper) |
+|---|---|
+| `e2e.baseUrl` | `helpers.Playwright.url` |
+| `viewportWidth` / `viewportHeight` | `helpers.Playwright.windowSize: '1280x720'` |
+| `defaultCommandTimeout` | `helpers.Playwright.waitForTimeout` |
+| `video` | `helpers.Playwright.video: true` |
+| `screenshotOnRunFailure` | plugin `screenshot` with `on: 'fail'` |
+| `retries` | top-level `retry: N` |
+| `env.*` / `Cypress.env('X')` | `process.env.X` |
+| `setupNodeEvents` / `cy.task` | custom helper or `bootstrap` / `teardown` |
+
+### 4. Port shared abstractions
+
+This is the bedrock. Do it before any spec rewrite — every spec rewrite shrinks because the verbs it needs (`I.doSmth(...)`) already exist.
+
+**Hard rule for Cypress custom commands.** Every `Cypress.Commands.add('<name>', fn)` becomes a method on a custom helper. **Split commands across two helpers by the kind of operation** — they have different access patterns and different correct APIs:
+
+- **`WebExtra`** (`lib/helpers/WebExtra.js`) for **browser-driven** commands — anything that needs the open page, DOM, `evaluate`, init scripts, storage, network-response waits. Reaches `this.helpers['Playwright'].page` / `.browserContext`.
+- **`ApiExtras`** (`lib/helpers/ApiExtras.js`) for **pure HTTP** commands — programmatic login, seed/teardown data, CRUD against an API. Reaches `this.helpers['REST']` (or `GraphQL`). See `node_modules/codeceptjs/docs/api.md` for REST helper configuration.
+
+One async method per Cypress command, named identically, so `cy.doSmth(arg)` → `I.doSmth(arg)`. Register both helpers under `helpers` in `codecept.conf.{js,ts}`.
+
+**Never call `this.helpers['Playwright'].browserContext.request.*` for API work.** That bypasses the REST + `JSONResponse` stack — no step logging, no `I.seeResponseCodeIsSuccessful` assertions, no shared headers, and the same verb ends up split between helpers. If the API needs the same auth as the browser, share cookies once at the top of the config:
+
+```js
+import { setSharedCookies } from '@codeceptjs/configure'
+setSharedCookies()
+```
+
+…or set `defaultHeaders` on the REST helper for token-based auth, or use `I.amBearerAuthenticated(secret(token))` per test. All three patterns are covered in `api.md`.
+
+**WebExtra example** — browser-driven commands (here `login` drives the UI form; the API-driven variant goes to `ApiExtras` below):
+
+```js
+import Helper from '@codeceptjs/helper'
+import fs from 'node:fs/promises'
+
+export default class WebExtra extends Helper {
+  async login(user, password) {
+    const { page } = this.helpers['Playwright']
+    await page.goto('/login')
+    await page.getByLabel('Email').fill(user)
+    await page.getByLabel('Password').fill(password)
+    await page.getByRole('button', { name: 'Sign In' }).click()
+    await page.waitForURL(/\/dashboard/)
+  }
+
+  async setLocalStorage(key, value) {
+    const { page } = this.helpers['Playwright']
+    await page.evaluate(([k, v]) => localStorage.setItem(k, v), [key, value])
+  }
+
+  async stubWindowOpen() {
+    const { page } = this.helpers['Playwright']
+    await page.addInitScript(() => {
+      window.__lastOpenUrl = null
+      const orig = window.open
+      window.open = (url, ...rest) => {
+        window.__lastOpenUrl = url
+        return orig ? orig.call(window, 'about:blank', ...rest) : null
+      }
+    })
+  }
+
+  async writeJsonFile(filePath, data) {
+    await fs.writeFile(filePath, JSON.stringify(data, null, 2))
+  }
+}
+```
+
+**ApiExtras example** — pure HTTP commands routed through the REST helper:
+
+```js
+import Helper from '@codeceptjs/helper'
+
+export default class ApiExtras extends Helper {
+  async loginViaApi(email, password) {
+    const REST = this.helpers['REST']
+    await REST.sendPostRequest('/login_ajax', { email, password, remember: false })
+  }
+
+  async seedCourse(courseData) {
+    const REST = this.helpers['REST']
+    const { data } = await REST.sendPostRequest('/course', courseData)
+    return data
+  }
+}
+```
+
+**Helper code style** — applies to both:
+
+- All `import` statements at the **top of the file**. Never `const fs = await import('node:fs/promises')` inside a method.
+- Use built-in assertions (`I.seeResponseCodeIsSuccessful` for API, `I.seeElement` for browser), `ExpectHelper`, or factories from `codeceptjs/assertions` — **never** `if (cond) throw new Error('...')`. Failures must render as proper assertion errors. See `node_modules/codeceptjs/docs/assertions.md`.
+- If your `WebExtra` is growing a session-cache map keyed by user name, you are reimplementing the `auth` plugin — stop and let the `auth` plugin (phase 8) handle session reuse. The helper should expose `loginViaApi` / `login`; the plugin handles caching.
+
+Cypress code that called `cy.window().then(...)`, `cy.wrap(...)`, or imperative DOM tricks translates cleanly into `page.evaluate(...)` inside `WebExtra`. Cypress code that called `cy.request(...)` translates to `REST.sendXxxRequest(...)` inside `ApiExtras`.
+
+**Other destinations** from the phase 1 inventory:
+
+- **Cypress page-object-style module** → CodeceptJS **page object class** under `pages/`. **Port conservatively** — keep only the methods the original module had; do not invent new wrappers during migration. Selector bundles become `this.fields = { ... }`; methods rewrite with `const { I } = inject()` at the top, calling `I.fillField`, `I.click`, and any `I.*` verb the `WebExtra` / `ApiExtras` helpers now contribute. Register under `include` in `codecept.conf.{js,ts}` so the page object auto-injects into Scenarios.
+
+  Page-object anti-patterns to avoid (unless the original Cypress code already had them):
+  - **Assertion methods** (`checkTitle() { I.seeElement(...) }`) — page objects are action verbs (`fillForm`, `submitOrder`); let assertions live in the test.
+  - **One-liner wrappers** around a single `I.click` / `I.see*` / `I.grabTextFrom` — the wrapper buys nothing over calling `I.*` from the test.
+  - **Methods used by only one test** — leave the steps in the test. Page objects exist for reuse.
+  - **`if (cond) throw new Error(...)`** in any method — use `I.see*`, `I.seeNumberOfElements`, `ExpectHelper`, or `codeceptjs/assertions` factories instead.
+
+- **Shared selector constants** → fields on the relevant page object. No free-floating `selectors.js`.
+- **Pure utility modules** that don't touch the browser → plain ES modules, imported where needed.
+- **Global hooks** → CodeceptJS `Before` / `BeforeSuite` in tests, or `bootstrap` / `teardown` in config for one-off setup.
+
+Sanity-check before moving on: `npx codeceptjs check -c <config>` must pass, and `npx codeceptjs list -c <config>` must show every Cypress command name as an `I.*` action contributed by `WebExtra` or `ApiExtras` — whichever owns it.
+
+### 5. Convert spec files
+
+One file at a time, leaning on the abstractions from phase 4. Hand off the per-spec work to the **`writing-codeceptjs-tests`** skill — it drives the live browser via MCP and verifies each step before committing.
+
+| Cypress | CodeceptJS 4 |
+|---|---|
+| File `*.cy.{js,ts}` | `*_test.{js,ts}` |
+| `describe('X', () => { ... })` | `Feature('X')` at top, one Feature per file |
+| `it('Y', () => { ... })` | `Scenario('Y', ({ I }) => { ... })` |
+| `beforeEach(() => { ... })` | `Before(({ I }) => { ... })` |
+| `afterEach(() => { ... })` | `After(({ I }) => { ... })` |
+| `before(...)` / `after(...)` | `BeforeSuite(...)` / `AfterSuite(...)` |
+| `cy.visit('/x')` | `I.amOnPage('/x')` |
+| `cy.login(u, p)` (custom command) | `I.login(u, p)` (from `WebExtra`) |
+
+**Iteration** — in tests, page objects, and helpers, use **`for...of`** for any loop containing `I.*` calls. Never `Array.prototype.forEach`. `.forEach` swallows the iteration callback's return — an `await` inside it does not block the outer function, and the CodeceptJS recorder may queue steps out of order or finish the Scenario before the loop is done. `for...of` keeps the loop sequential and lets you add `await` later without rewriting:
+
+```js
+for (const sort of testSort) {
+  I.click(locate(this.filterFormLabel).withText(sort))
+}
+```
+
+```js
+for (const row of await I.grabWebElements('.row')) {
+  const text = await row.getText()
+  I.expectNotEmpty(text)
+}
+```
+
+**Per batch**: `npx codeceptjs dry-run --steps -c <config>` — loads every Scenario, resolves every `I.*` call, no browser. Surfaces typos, missing imports, page objects not under `include`, and nonexistent verbs in seconds. Fix before anything real.
+
+Then run the batch: `npx codeceptjs run --steps -c <config>`.
+
+- First real runs almost always fail — locator drift, timing the source framework hid behind its own retry, auth/session differences, data assumptions. **Expected; fixing it is part of the migration.**
+- Every failure → invoke `debugging-codeceptjs-tests` and fix on the fly (breakpoint, live-page inspection, verified fix). No blind rewrites, no `retry` masking.
+- A batch is done when it runs green, not when it dry-runs clean.
+
+### 6. Locators
+
+**Scope every locator with a context.** The last argument of every action narrows the lookup to a region — `I.click('Save', '.toolbar')`, `I.fillField('Email', 'u@t.com', '#login-form')`, `I.click({ role: 'button', name: 'Delete' }, '.modal')`. A short semantic or ARIA locator plus a context beats one long unscoped locator: it reads like the page, disambiguates duplicate labels without growing, and survives markup churn. Apply this to every row of the tables below — the source framework's chain usually splits cleanly into *region* + *what the user sees*.
+
+`cy.get(sel).within(() => ...)` and `cy.get(parent).find(child)` both collapse onto the context argument — that is where a Cypress chain's parent selector belongs.
+
+CodeceptJS priority — pick the highest that fits, then add the context:
+
+1. **Semantic strings** — button text, label, placeholder, link text: `I.click('Save', '.toolbar')`, `I.fillField('Email', 'u@t.com', '#login-form')`. Replaces most `cy.contains(...)` calls.
+A plain string already matches `aria-label`, so an icon-only control with `aria-label="Save"` is `I.click('Save', <context>)` — never `'aria-label=Save'` or `{ css: '[aria-label="Save"]' }`.
+2. **ARIA roles** — `I.click({ role: 'button', name: 'Sign In' }, '#login-form')`.
+3. **`$name` via the `customLocator` plugin** — Cypress users often default to `[data-cy=...]`. Keep those attributes, but enable the plugin so they read as `I.click('$submit', '.checkout')` instead of `{ css: '[data-cy=submit]' }`.
+4. **`locate()` builder** — `I.click(locate('button').withText('Edit').inside('tr').withText('Acme'))`; often better split as `I.click('Edit', locate('tr').withText('Acme'))`.
+5. **CSS / XPath** — fallback only.
+
+Full guidance in **`writing-codeceptjs-tests`** § Locators.
+
+### 7. Actions, assertions, grabs
+
+| Cypress | CodeceptJS 4 |
+|---|---|
+| `cy.get(sel).click()` | `I.click(sel)` |
+| `cy.get(sel).type('x')` | `I.fillField(sel, 'x')` |
+| `cy.get(sel).clear()` | `I.clearField(sel)` |
+| `cy.get(sel).check()` / `.uncheck()` | `I.checkOption(sel)` / `I.uncheckOption(sel)` |
+| `cy.get(sel).select('A')` | `I.selectOption(sel, 'A')` |
+| `cy.get(sel).should('be.visible')` | `I.seeElement(sel)` |
+| `cy.get(sel).should('have.text', 'X')` | `I.see('X', sel)` |
+| `cy.get(sel).should('have.value', 'X')` | `I.seeInField(sel, 'X')` |
+| `cy.get(sel).should('have.length', 5)` | `I.seeNumberOfElements(sel, 5)` |
+| `cy.url().should('include', '/x')` | `I.seeInCurrentUrl('/x')` |
+| `cy.get(sel).invoke('text').then(t => ...)` | `const t = await I.grabTextFrom(sel)` |
+| `cy.getCookie('s')` | `const c = await I.grabCookie('s')` |
+
+`await` only on grabs. Plain actions queue automatically.
+
+### 8. Sessions and auth
+
+`cy.session(id, setup, { validate })` and `cy.request`-based programmatic login → the **`auth` plugin**. Hand off to **`codeceptjs-auth`** for the setup walk-through. If phase 4 already ported `cy.login` into `WebExtra` as `I.login(...)`, the `auth` plugin's role definition just calls `I.login(...)`. For multi-user scenarios (Cypress has no native equivalent) use `session(...)` from `codeceptjs/effects`.
+
+### 9. Fixtures, requests, tasks
+
+| Cypress | CodeceptJS 4 |
+|---|---|
+| `cy.fixture('users.json')` | `import users from './fixtures/users.json' with { type: 'json' }` |
+| `cy.request('POST', '/api/x', body)` | `await I.sendPostRequest('/api/x', body)` via the **REST helper**; for reusable flows wrap in the `ApiExtras` helper from phase 4 |
+| `cy.task('seedDB')` | method on `ApiExtras` (if HTTP), a dedicated helper, or `bootstrap` / `teardown` |
+
+REST helper auth: `setSharedCookies()` from `@codeceptjs/configure` shares the browser session with REST so the same user is logged in on both sides; alternatively set `defaultHeaders` for static tokens or `I.amBearerAuthenticated(secret(token))` per test. See `node_modules/codeceptjs/docs/api.md` for the full configuration surface, including `JSONResponse` assertions (`I.seeResponseCodeIsSuccessful`, `I.seeResponseContainsKeys`, `I.seeResponseMatchesJsonSchema` with Zod).
+
+### 10. Network mocking
+
+`cy.intercept(url, handler)` → `I.mockRoute(url, route => route.fulfill({ ... }))` (Playwright). Disable with `I.stopMockingRoute(url)`. There is no `cy.wait('@alias')` equivalent — anchor waits on UI outcomes (`I.waitForText`, `I.seeElement`) instead of network events.
+
+### 11. Decommission Cypress
+
+Only after every spec is ported and CI is green: delete `cypress/`, `cypress.config.*`, drop `cypress` from `devDependencies`, remove the Cypress CI jobs.
+
+## Verify
+
+1. `npx codeceptjs check -c <config>` — config + helper + plugin sanity.
+2. `npx codeceptjs list -c <config>` — every ported Cypress command appears as an `I.*` action from `WebExtra` or `ApiExtras`; every page object's methods appear.
+3. `npx codeceptjs dry-run --steps -c <config>` — every Scenario loads.
+4. Full run: `npx codeceptjs run --steps -c <config>`. Failures are expected on first runs — drive each to a fix via the **`debugging-codeceptjs-tests`** skill (not `retry`, not blind rewrites). The migration is complete only when the whole converted suite is green.
+5. Hand off to **`codeceptjs-run-analysis`** to inspect `output/trace_*/` artifacts (requires the `aiTrace` plugin enabled).
+6. `grep -r "cy\." cypress/` — empty before deleting `cypress/`.
+
+## Related skills
+
+- `writing-codeceptjs-tests` — per-spec rewrite playbook (MCP-driven, verified steps)
+- `debugging-codeceptjs-tests` — use on every failing test from the first full run
+- `codeceptjs-auth` — replaces `cy.session()` and programmatic login
+- `codeceptjs-fundamentals` — run after migration to confirm wiring
+- Reference docs: `node_modules/codeceptjs/docs/` (basics, playwright, locators, custom-helpers, api, assertions, pageobjects, data, sessions, effects)