testeiya 0.2.1 → 0.3.10

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

@@ -1,6 +1,6 @@
 ---
 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/**/*.cy.{js,ts}`, `cypress/support/{commands,e2e}.{js,ts}`, `cypress/fixtures/`, `cypress/plugins/`, `cypress/component/`), `cypress` in `devDependencies`, or test code that calls `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(...)`. Walks the port end-to-end: inventory shared logic (custom commands, ad-hoc page-object modules, shared selectors, fixtures, hooks), install CodeceptJS with the Playwright helper alongside Cypress, port the config, split `Cypress.Commands.add` into two custom helpers — `WebExtra` for browser-driven commands (Playwright `page` / `browserContext`) and `ApiExtras` for HTTP commands (REST / GraphQL helper, never `browserContext.request.*`) — port page-object-style modules to real page objects without inventing wrapper or assertion methods, convert spec files (handing off to `writing-codeceptjs-tests`), replace `cy.session` with the `auth` plugin, swap `cy.fixture` / `cy.request` / `cy.task` / `cy.intercept` for ES imports / REST helper / `ApiExtras` / `I.mockRoute`, then decommission Cypress."
+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
@@ -11,7 +11,7 @@ Cypress and CodeceptJS share a goal — browser end-to-end testing — but diffe
 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 references: `node_modules/codeceptjs/docs/basics.md`, `locators.md`, `playwright.md`, `custom-helpers.md`, `pageobjects.md`.
+Authoritative reference: `node_modules/codeceptjs/docs/` (basics, locators, playwright, custom-helpers, pageobjects).
 
 ## When to trigger
 
@@ -211,32 +211,30 @@ for (const row of await I.grabWebElements('.row')) {
 }
 ```
 
-**Dry-run as you go.** After each batch of converted specs, run:
+**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.
 
-```bash
-npx codeceptjs dry-run --steps -c <config>
-```
-
-It loads every scenario, resolves every `I.*` call against the configured helpers, and prints the step list — all without launching a browser. Typos, missing imports, page objects not registered under `include`, and `I.*` verbs that don't exist on `WebExtra` / `ApiExtras` all surface here in seconds. Fix anything that fails before running a real test.
+Then run the batch: `npx codeceptjs run --steps -c <config>`.
 
-**Then run the whole batch for real.** Dry-run proves specs parse and resolve — not that they pass. As soon as a batch is dry-run clean, run it against the browser:
+- 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.
 
-```bash
-npx codeceptjs run --steps -c <config>
-```
+### 6. Locators
 
-First real runs after a migration almost always have failures — locator drift, timing the source framework hid behind its own retry, auth/session differences, data assumptions. **This is expected; fixing it is part of the migration, not a follow-up task.** When a test fails, **invoke the `debugging-codeceptjs-tests` skill and fix it on the fly** — it breakpoints the failing step, inspects the live page via MCP, finds the working locator/wait, and commits the verified fix. Do not bulk-rewrite specs blind, and do not mask failures with `retry`. Drive every failure to a real fix before starting the next batch. A batch is "done" when it runs green, not when it dry-runs clean.
+**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*.
 
-### 6. Locators
+`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:
+CodeceptJS priority — pick the highest that fits, then add the context:
 
-1. **Semantic strings** — button text, label, placeholder, link text: `I.click('Save')`, `I.fillField('Email', 'u@t.com')`.
-2. **ARIA roles** — `I.click({ role: 'button', name: 'Sign In' })`.
-3. **`locate()` builder** — `I.click(locate('button').withText('Edit').inside('tr').withText('Acme')))`.
-4. **CSS / XPath** — fallback only.
+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.
 
-Cypress users often default to `[data-cy=...]`. Keep those attributes, but enable the `customLocator` plugin so they read as `$submit` instead of `{ css: '[data-cy=submit]' }`. Full guidance in **`writing-codeceptjs-tests`** § Locators.
+Full guidance in **`writing-codeceptjs-tests`** § Locators.
 
 ### 7. Actions, assertions, grabs
 
@@ -288,19 +286,10 @@ Only after every spec is ported and CI is green: delete `cypress/`, `cypress.con
 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/`.
 
-## Pointers
-
-- `node_modules/codeceptjs/docs/basics.md` — `I.*` vocabulary, locators, assertions, the `await` rule
-- `node_modules/codeceptjs/docs/playwright.md` — recommended helper; `mockRoute` for `cy.intercept`
-- `node_modules/codeceptjs/docs/locators.md` — semantic / ARIA / `locate()`
-- `node_modules/codeceptjs/docs/custom-helpers.md` — `WebExtra` / `ApiExtras` patterns (extending `Helper`, reaching `this.helpers['Playwright']` / `this.helpers['REST']`)
-- `node_modules/codeceptjs/docs/api.md` — REST / GraphQL configuration, `setSharedCookies()`, `defaultHeaders`, `JSONResponse` assertions, Zod schemas
-- `node_modules/codeceptjs/docs/assertions.md` — built-in `see*` assertions, `ExpectHelper`, `codeceptjs/assertions` factories (use these instead of `if (cond) throw new Error(...)`)
-- `node_modules/codeceptjs/docs/pageobjects.md` — porting Cypress page-object-style modules
-- `node_modules/codeceptjs/docs/data.md` — fixtures, data factories
-- `node_modules/codeceptjs/docs/sessions.md`, `auth.md` — multi-user + login reuse
-- `node_modules/codeceptjs/docs/effects.md` — `tryTo`, `retryTo`, `within`
-- `writing-codeceptjs-tests` — per-spec rewrite playbook (drive via MCP, learn locators, commit verified steps)
-- `debugging-codeceptjs-tests` — **use on every failing test from the first full run** (breakpoint, inspect live page via MCP, fix on the fly)
-- `codeceptjs-auth` — replace `cy.session()` and programmatic login
-- `codeceptjs-fundamentals` — run **after** migration to confirm the new setup is wired correctly
+## 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)

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

@@ -1,6 +1,6 @@
 ---
 name: migrate-protractor-to-codeceptjs
-description: "Port a Protractor test suite to CodeceptJS 4. Trigger when the project contains `protractor.conf.{js,ts}`, `protractor` in `devDependencies`, `*.e2e-spec.{js,ts}` files, an `e2e/` (or `protractor/`) directory with spec files, `@types/jasmine` / `jasmine-spec-reporter` in dependencies, imports from `protractor` (`browser`, `element`, `by`, `ExpectedConditions`, `ElementFinder`, `ElementArrayFinder`), or code calling `element(by.X(...))`, `element.all(...)`, `by.addLocator(...)`, `browser.get(...)`, `browser.executeScript(...)`, `browser.wait(EC.*)`, `browser.waitForAngular(...)`, `browser.ignoreSynchronization`, `browser.params.*`, or `browser.driver.*`. Walks the port end-to-end: inventory shared logic (page objects — Protractor projects almost always have them, custom locators via `by.addLocator`, shared helpers, `onPrepare` / `onComplete` hooks, Jasmine custom matchers), install CodeceptJS with the Playwright helper alongside Protractor, port the config, split shared helpers into `WebExtra` (browser-driven via Playwright `page`) and `ApiExtras` (HTTP via REST helper, never `browserContext.request.*`), port existing page objects to CodeceptJS page objects without inventing assertion/one-liner wrappers, replace `.then(...)` promise chains with `await` only on grabs, drop `browser.waitForAngular()` / `browser.ignoreSynchronization` (CodeceptJS auto-waits), translate `element(by.X(...))` to semantic strings / ARIA / `locate()` / `{ css }`, register `by.addLocator` strategies via the `customLocator` plugin or `WebExtra`, convert specs (handing off to `writing-codeceptjs-tests`), replace `browser.params` with `process.env`, swap Jasmine `expect()` matchers for `I.see*` / `ExpectHelper` / `codeceptjs/assertions`, then decommission Protractor."
+description: "Port a Protractor test suite to CodeceptJS 4. Trigger when the project contains `protractor.conf.{js,ts}`, `protractor` in `devDependencies`, `*.e2e-spec.{js,ts}` files, an `e2e/` (or `protractor/`) directory with spec files, `@types/jasmine` / `jasmine-spec-reporter` in dependencies, imports from `protractor` (`browser`, `element`, `by`, `ExpectedConditions`), or code calling `element(by.X(...))`, `element.all(...)`, `by.addLocator(...)`, `browser.get(...)` / `browser.executeScript(...)` / `browser.wait(EC.*)` / `browser.waitForAngular(...)` / `browser.ignoreSynchronization` / `browser.params.*`."
 ---
 
 # Migrate Protractor → CodeceptJS 4
@@ -13,7 +13,7 @@ Three foundational differences to internalize:
 2. **Helpers, not `browser` / `driver`.** `I.*` dispatches to a configured helper. **Playwright recommended**; WebDriver is also available if the suite must keep running against a Selenium Grid — test code is identical either way.
 3. **Auto-wait, not Angular-wait.** Drop `browser.waitForAngular()` and `browser.ignoreSynchronization`. The Playwright and WebDriver helpers wait on DOM and element stability, which covers Angular's render cycle without a framework-specific hook.
 
-Authoritative references: `node_modules/codeceptjs/docs/basics.md`, `locators.md`, `playwright.md`, `webdriver.md`, `custom-helpers.md`, `pageobjects.md`.
+Authoritative reference: `node_modules/codeceptjs/docs/` (basics, locators, playwright, webdriver, custom-helpers, pageobjects).
 
 ## When to trigger
 
@@ -215,30 +215,26 @@ for (const row of await I.grabWebElements('.row')) {
 }
 ```
 
-**Dry-run as you go.** After each batch of converted specs, run:
+**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.
 
-```bash
-npx codeceptjs dry-run --steps -c <config>
-```
-
-It loads every scenario, resolves every `I.*` call against the configured helpers, and prints the step list — all without launching a browser. Typos, missing imports, page objects not registered under `include`, and `I.*` verbs that don't exist on `WebExtra` / `ApiExtras` all surface here in seconds. Fix anything that fails before running a real test.
+Then run the batch: `npx codeceptjs run --steps -c <config>`.
 
-**Then run the whole batch for real.** Dry-run proves specs parse and resolve — not that they pass. As soon as a batch is dry-run clean, run it against the browser:
-
-```bash
-npx codeceptjs run --steps -c <config>
-```
-
-First real runs after a migration almost always have failures — locator drift, timing the source framework hid behind its own retry, auth/session differences, data assumptions. **This is expected; fixing it is part of the migration, not a follow-up task.** When a test fails, **invoke the `debugging-codeceptjs-tests` skill and fix it on the fly** — it breakpoints the failing step, inspects the live page via MCP, finds the working locator/wait, and commits the verified fix. Do not bulk-rewrite specs blind, and do not mask failures with `retry`. Drive every failure to a real fix before starting the next batch. A batch is "done" when it runs green, not when it dry-runs clean.
+- First real runs almost always fail — locator drift, timing the ControlFlow hid behind its own queueing, 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. Locator preference
 
-CodeceptJS priority — pick the highest that fits:
+**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*.
+
+CodeceptJS priority — pick the highest that fits, then add the context:
 
-1. **Semantic strings** — button text, label, placeholder, link text: `I.click('Save')`, `I.fillField('Email', 'u@t.com')`. Covers Protractor's `by.linkText`, `by.buttonText`, `by.partialButtonText`, `by.partialLinkText` cleanly.
-2. **ARIA roles** — `I.click({ role: 'button', name: 'Sign In' })`. Strong default for Angular apps that ship Material / ARIA-correct components.
-3. **`locate()` builder** — `I.click(locate('.row').withText('Acme').inside('table'))`. Direct equivalent of `by.cssContainingText` + element traversal chains.
-4. **CSS / XPath / attribute objects** — `{ id: 'foo' }`, `{ name: 'email' }`, `{ css: '[ng-model="user.email"]' }`, `{ xpath: '//div[@id="x"]' }`. The fallback for Angular directive attributes.
+1. **Semantic strings** — button text, label, placeholder, link text: `I.click('Save', '.toolbar')`, `I.fillField('Email', 'u@t.com', '#login-form')`. Covers Protractor's `by.linkText`, `by.buttonText`, `by.partialButtonText`, `by.partialLinkText` cleanly.
+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')`. Strong default for Angular apps that ship Material / ARIA-correct components.
+3. **`$name` via the `customLocator` plugin** — when the app tags elements with `data-qa` / `data-test`; beats repeating the attribute selector at every call site.
+4. **`locate()` builder** — `I.click(locate('.row').withText('Acme').inside('table'))`. Direct equivalent of `by.cssContainingText` + element traversal chains — though `I.click('Edit', locate('tr').withText('Acme'))` is usually the better split.
+5. **CSS / XPath / attribute objects** — `{ id: 'foo' }`, `{ name: 'email' }`, `{ css: '[ng-model="user.email"]' }`, `{ xpath: '//div[@id="x"]' }`. The fallback for Angular directive attributes.
 
 | Protractor locator | CodeceptJS 4 |
 |---|---|
@@ -334,19 +330,10 @@ Only after every spec is ported and CI is green: delete `e2e/` (or whichever dir
 5. Hand off to **`codeceptjs-run-analysis`** to inspect `output/trace_*/` artifacts (requires the `aiTrace` plugin enabled).
 6. `grep -rE "\\bbrowser\\.|\\bby\\.|\\.then\\(|waitForAngular" e2e/` — empty before deleting `e2e/`.
 
-## Pointers
-
-- `node_modules/codeceptjs/docs/basics.md` — `I.*` vocabulary, locators, assertions, the `await` rule
-- `node_modules/codeceptjs/docs/playwright.md` — recommended helper; `mockRoute` for any network mocking; `evaluate` for `executeScript` ports
-- `node_modules/codeceptjs/docs/webdriver.md` — alternative helper if the suite stays on Selenium Grid
-- `node_modules/codeceptjs/docs/locators.md` — semantic / ARIA / `locate()`, `customLocator` plugin for `by.addLocator` replacements
-- `node_modules/codeceptjs/docs/custom-helpers.md` — `WebExtra` / `ApiExtras` patterns (extending `Helper`, reaching `this.helpers['Playwright']` / `this.helpers['REST']`)
-- `node_modules/codeceptjs/docs/api.md` — REST / GraphQL configuration, `setSharedCookies()`, `defaultHeaders`, `JSONResponse` assertions, Zod schemas
-- `node_modules/codeceptjs/docs/assertions.md` — built-in `see*` assertions, `ExpectHelper`, `codeceptjs/assertions` factories (use these instead of `if (cond) throw new Error(...)`)
-- `node_modules/codeceptjs/docs/pageobjects.md` — porting Protractor page objects
-- `node_modules/codeceptjs/docs/sessions.md`, `auth.md` — multi-user + login reuse
-- `node_modules/codeceptjs/docs/effects.md` — `tryTo`, `retryTo`, `within`
-- `writing-codeceptjs-tests` — per-spec rewrite playbook (drive via MCP, learn locators, commit verified steps)
-- `debugging-codeceptjs-tests` — **use on every failing test from the first full run** (breakpoint, inspect live page via MCP, fix on the fly)
-- `codeceptjs-auth` — replace UI re-login in every `beforeEach`
-- `codeceptjs-fundamentals` — run **after** migration to confirm the new setup is wired correctly
+## 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 UI re-login in every `beforeEach` / manual cookie injection
+- `codeceptjs-fundamentals` — run after migration to confirm wiring
+- Reference docs: `node_modules/codeceptjs/docs/` (basics, playwright, webdriver, locators, custom-helpers, api, assertions, pageobjects, sessions, effects)

package/skills/codeceptjs/migrate-selenium-java-to-codeceptjs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: migrate-selenium-java-to-codeceptjs
-description: "Port a Selenium WebDriver or Selenide (Java) test suite to CodeceptJS 4. Trigger when the project contains `pom.xml` declaring `<artifactId>selenium-java</artifactId>` / `<artifactId>selenide</artifactId>` / `<artifactId>webdrivermanager</artifactId>`, `build.gradle` / `build.gradle.kts` with `org.seleniumhq.selenium:selenium-java` or `com.codeborne:selenide`, a `src/test/java/` tree with `*Test.java` / `*IT.java` / `*Tests.java` / `*Steps.java`, imports from `org.openqa.selenium.*` (`WebDriver`, `WebElement`, `By`, `WebDriverWait`, `ExpectedConditions`, `Actions`, `JavascriptExecutor`, `Select`, `Keys`) or `com.codeborne.selenide.*` (`Selenide`, `SelenideElement`, `Configuration`, `Condition`, `ElementsCollection`), JUnit 5 / 4 or TestNG annotations (`@Test`, `@BeforeEach`, `@AfterEach`, `@BeforeAll`, `@BeforeMethod`, `@BeforeClass`, `@DataProvider`, `@ParameterizedTest`, `@FindBy`, `@FindAll`), `PageFactory.initElements(...)`, `WebDriverManager.*.setup()`, `new ChromeDriver(...)` / `new RemoteWebDriver(...)`, `Selenide.open(...)`, `$(...).shouldBe(...)` / `$$(...).filter(...)` chains, or Cucumber-JVM step defs (`@Given` / `@When` / `@Then` from `io.cucumber.java.en.*`). Walks the port end-to-end: inventory page objects (almost always present, often `@FindBy`-driven), shared `*Helper` / `*Manager` classes, JUnit/TestNG hooks and listeners, data providers, Cucumber step defs; install CodeceptJS in a parallel directory with the **WebDriver helper as the default** (most native target — same W3C protocol the Java suite already speaks); no driver setup is needed because WebdriverIO v9 auto-starts the matching browser driver, with **Docker Selenium (Selenoid / `selenium/standalone-chrome`) only as a fallback** for parallel/CI/Grid runs per `codeceptjs-fundamentals` and `node_modules/codeceptjs/docs/webdriver.md § \"Selenium in Docker (Selenoid)\"`; port the config (Maven/Gradle deps → `package.json`, Selenide `Configuration.*` / Selenium capabilities → `helpers.WebDriver.*`); split shared Java helpers into `WebExtra` (browser-driven — `JavascriptExecutor` bodies become `browser.execute(...)` via `this.helpers['WebDriver'].browser`) and `ApiExtras` (RestAssured / Apache HttpClient → REST helper, never via the browser helper); port `@FindBy`-driven page objects to CodeceptJS page objects without inventing assertion/one-liner wrappers; **drop explicit wait code** (`WebDriverWait`, `ExpectedConditions.*`, Selenide `.shouldBe(visible)` / `.shouldHave(text(...))` chains) — CodeceptJS auto-waits via `smartWait`; translate `By.X(...)` / `@FindBy(...)` locators to semantic strings / ARIA / `locate()` / `{ css }`; convert specs (handing off to `writing-codeceptjs-tests`), mapping JUnit 5 / JUnit 4 / TestNG annotations to `Feature` / `Scenario` / `Before` / `BeforeSuite` / `After` / `AfterSuite` and `@DataProvider` / `@ParameterizedTest` to `Data(...).Scenario(...)`; swap any custom `LoginHelper` / cookie-based session reuse for the `auth` plugin; keep WireMock as a sidecar for client-side stubs while on WebDriver (WebDriver has no native network interception); for Cucumber-JVM, keep `.feature` files and rewrite step defs in JS via CodeceptJS BDD; then decommission the Java suite. Once the WebDriver suite is green, propose the **optional Playwright swap** (faster, cross-browser from one config, native `I.mockRoute`) — mechanical config change, test code unchanged."
+description: "Port a Selenium WebDriver or Selenide (Java) test suite to CodeceptJS 4. Trigger when the project contains `pom.xml` declaring `selenium-java` / `selenide` / `webdrivermanager` / `junit-jupiter` / `testng`, a `build.gradle{,.kts}` with `org.seleniumhq.selenium` / `com.codeborne:selenide`, a `src/test/java/` tree with `*Test.java` / `*IT.java` / `*Steps.java`, imports from `org.openqa.selenium.*` (`WebDriver`, `By`, `WebDriverWait`, `ExpectedConditions`, `Actions`) or `com.codeborne.selenide.*` (`Selenide`, `SelenideElement`, `Condition`), JUnit/TestNG annotations (`@Test`, `@BeforeEach`, `@DataProvider`, `@FindBy`, `@ParameterizedTest`), `PageFactory.initElements(...)`, `new ChromeDriver(...)` / `Selenide.open(...)`, or Cucumber-JVM step defs (`@Given` / `@When` / `@Then`)."
 ---
 
 # Migrate Selenium / Selenide (Java) → CodeceptJS 4
@@ -13,7 +13,7 @@ Three foundational differences to internalize:
 2. **Helpers, not `WebDriver` / `driver`.** `I.*` dispatches to a configured helper. **Default to the WebDriver helper** — it speaks the same W3C WebDriver protocol your Java suite already speaks, so the migration is most native: same Selenium server, same browser drivers, same capabilities, same Grid if you have one. Once the suite is green on WebDriver, you can swap in the **Playwright** helper (modern, faster, less flaky, native multi-browser via one config) by changing one helper block — the test code is identical either way.
 3. **First-class abstractions.** Page objects, the `auth` plugin, multi-user `session(...)`, custom helpers, and the `customLocator` plugin are built in. Java suites already centralise these (`PageFactory`, `LoginHelper`, `DriverManager`); the migration consolidates them onto the framework's idioms instead of carrying the Java-specific glue forward.
 
-Authoritative references: `node_modules/codeceptjs/docs/basics.md`, `locators.md`, `playwright.md`, `webdriver.md`, `custom-helpers.md`, `pageobjects.md`.
+Authoritative reference: `node_modules/codeceptjs/docs/` (basics, locators, playwright, webdriver, custom-helpers, pageobjects).
 
 ## When to trigger
 
@@ -317,30 +317,26 @@ for (const sort of testSort) {
 }
 ```
 
-**Dry-run as you go.** After each batch of converted specs, run:
+**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.
 
-```bash
-npx codeceptjs dry-run --steps -c <config>
-```
-
-It loads every scenario, resolves every `I.*` call against the configured helpers, and prints the step list — all without launching a browser. Typos, missing imports, page objects not registered under `include`, and `I.*` verbs that don't exist on `WebExtra` / `ApiExtras` all surface here in seconds. Fix anything that fails before running a real test.
+Then run the batch: `npx codeceptjs run --steps -c <config>`.
 
-**Then run the whole batch for real.** Dry-run proves specs parse and resolve — not that they pass. As soon as a batch is dry-run clean, run it against the browser:
-
-```bash
-npx codeceptjs run --steps -c <config>
-```
-
-First real runs after a migration almost always have failures — locator drift, timing the explicit `WebDriverWait` code was masking, auth/session differences, data assumptions. **This is expected; fixing it is part of the migration, not a follow-up task.** When a test fails, **invoke the `debugging-codeceptjs-tests` skill and fix it on the fly** — it breakpoints the failing step, inspects the live page via MCP, finds the working locator/wait, and commits the verified fix. Do not bulk-rewrite specs blind, and do not mask failures with `retry`. Drive every failure to a real fix before starting the next batch. A batch is "done" when it runs green, not when it dry-runs clean.
+- First real runs almost always fail — locator drift, timing the explicit `WebDriverWait` code was masking, 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
 
-CodeceptJS priority — pick the highest that fits:
+**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*.
 
-1. **Semantic strings** — button text, label, placeholder, link text: `I.click('Save')`, `I.fillField('Email', 'u@t.com')`.
-2. **ARIA roles** — `I.click({ role: 'button', name: 'Sign In' })`.
-3. **`locate()` builder** — `I.click(locate('button').withText('Edit').inside('tr').withText('Acme'))`.
-4. **CSS / XPath** — fallback only.
+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')`.
+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** — when the suite leans on `data-test` / `data-qa` attributes.
+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.
 
 Java suites lean on `By.id`, `By.cssSelector`, `By.xpath`, `By.linkText`, and `@FindBy(...)` heavily. Translation:
 
@@ -454,19 +450,10 @@ Once the migration is complete and WebDriver runs are stable in CI, consider swa
 
 You gain: cross-browser coverage (Chromium / Firefox / WebKit) from one config, faster runs, native `I.mockRoute(...)` network mocking, richer ARIA snapshots via the MCP loop.
 
-## Pointers
-
-- `node_modules/codeceptjs/docs/basics.md` — `I.*` vocabulary, locators, assertions, the `await` rule
-- `node_modules/codeceptjs/docs/webdriver.md` — default helper for this migration; § "Selenium in Docker (Selenoid)" for the container setup
-- `node_modules/codeceptjs/docs/playwright.md` — target for the optional follow-up swap; `mockRoute` for WireMock client-side stubs
-- `node_modules/codeceptjs/docs/locators.md` — semantic / ARIA / `locate()`, `customLocator` plugin
-- `node_modules/codeceptjs/docs/pageobjects.md` — for ported `@FindBy` POMs
-- `node_modules/codeceptjs/docs/custom-helpers.md` — `WebExtra` / `ApiExtras` patterns (see § "WebDriver Example" for the `browser` access pattern)
-- `node_modules/codeceptjs/docs/api.md` — REST helper for RestAssured ports
-- `node_modules/codeceptjs/docs/auth.md` — replace `LoginHelper` + cookie reuse
-- `node_modules/codeceptjs/docs/bdd.md` — CodeceptJS BDD for Cucumber-JVM ports
-- `node_modules/codeceptjs/docs/effects.md` — `session`, `tryTo`, `retryTo`, `within`
-- **`codeceptjs-fundamentals`** — Docker-fallback Selenium setup convention; run **after** migration to confirm wiring
-- **`writing-codeceptjs-tests`** — per-spec rewrite playbook (drive via MCP, learn locators, commit verified steps)
-- **`debugging-codeceptjs-tests`** — **use on every failing test from the first full run** (breakpoint, inspect live page via MCP, fix on the fly)
-- **`codeceptjs-auth`** — replace `LoginHelper` / cookie-based session reuse
+## 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 `LoginHelper` / cookie-based session reuse
+- `codeceptjs-fundamentals` — Docker-fallback Selenium convention; run after migration to confirm wiring
+- Reference docs: `node_modules/codeceptjs/docs/` (basics, webdriver, playwright, locators, custom-helpers, api, auth, bdd, effects)

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

@@ -1,6 +1,6 @@
 ---
 name: migrate-testcafe-to-codeceptjs
-description: "Port a TestCafe test suite to CodeceptJS 4. Trigger when the project contains `.testcaferc.{json,js,ts,cjs}`, `testcafe` in `devDependencies`, test files that import from `testcafe` (`Selector`, `ClientFunction`, `Role`, `RequestMock`, `RequestHook`, `RequestLogger`, `t` from a test signature), top-level `fixture('X').page(...)` + `test('y', async t => { ... })` blocks, `Selector(...)` chains (`.withText`, `.withAttribute`, `.nth`, `.find`, `.filter`, `.parent`, `.child`, `.sibling`), `await t.click(...)` / `t.typeText(...)` patterns, `t.useRole(...)`, `t.addRequestHooks(...)`, `t.eval(...)`, `ClientFunction(...)`, TestCafe Studio recordings, or a `tests/` directory matching `*.test.{js,ts}` whose contents start with `fixture(...)`. Walks the port end-to-end: inventory shared logic (TestCafe page-object-style modules, `Role` definitions, `ClientFunction` factories, `RequestMock` factories, custom Test Controller actions, fixture hooks), install CodeceptJS with the Playwright helper alongside TestCafe, port the config, split shared helpers into `WebExtra` (browser-driven via Playwright `page` — `ClientFunction` / `t.eval` ports here as `page.evaluate`) and `ApiExtras` (HTTP via REST helper, never `browserContext.request.*`), port TestCafe page objects to CodeceptJS page objects without inventing assertion/one-liner wrappers, replace `Selector(...)` chains with semantic strings / ARIA / `locate()` / `{ css }`, **strip excess `await` from every action call** (CodeceptJS auto-queues — `await` is only for grabs), convert specs (handing off to `writing-codeceptjs-tests`), replace `Role` + `t.useRole` with the `auth` plugin, swap `RequestMock` for `I.mockRoute`, fold `t.expect(sel.X).Y(...)` chains into `I.see*` / `ExpectHelper` / `codeceptjs/assertions`, then decommission TestCafe."
+description: "Port a TestCafe test suite to CodeceptJS 4. Trigger when the project contains `.testcaferc.{json,js,ts,cjs}`, `testcafe` in `devDependencies`, test files importing from `testcafe` (`Selector`, `ClientFunction`, `Role`, `RequestMock`, `RequestHook`, `RequestLogger`), top-level `fixture('X').page(...)` + `test('y', async t => { ... })` blocks, `Selector(...)` chains (`.withText`, `.nth`, `.find`, `.filter`), `await t.click(...)` patterns, `t.useRole(...)`, `t.eval(...)` / `ClientFunction(...)`, or TestCafe Studio recordings."
 ---
 
 # Migrate TestCafe → CodeceptJS 4
@@ -11,7 +11,7 @@ TestCafe and CodeceptJS share a lot at the surface — both expose a single test
 2. **Helpers, not a bundled proxy.** TestCafe runs as an HTTP/HTTPS proxy that injects automation into pages; CodeceptJS dispatches `I.*` to a configured helper. **Playwright recommended** — closest feel, fastest, supports all three engines (Chromium / Firefox / WebKit) the same way TestCafe did.
 3. **First-class abstractions.** Page objects, multi-user `session(...)`, the `auth` plugin, custom helpers, and the `customLocator` plugin are built in. TestCafe projects accumulate ad-hoc versions of these (Selector-property classes, `Role` factories, `ClientFunction` factories) — the migration consolidates them onto framework idioms.
 
-Authoritative references: `node_modules/codeceptjs/docs/basics.md`, `locators.md`, `playwright.md`, `custom-helpers.md`, `pageobjects.md`.
+Authoritative reference: `node_modules/codeceptjs/docs/` (basics, locators, playwright, custom-helpers, pageobjects).
 
 ## When to trigger
 
@@ -215,30 +215,26 @@ for (const row of await I.grabWebElements('.row')) {
 }
 ```
 
-**Dry-run as you go.** After each batch of converted specs, run:
+**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.
 
-```bash
-npx codeceptjs dry-run --steps -c <config>
-```
-
-It loads every scenario, resolves every `I.*` call against the configured helpers, and prints the step list — all without launching a browser. Typos, missing imports, page objects not registered under `include`, and `I.*` verbs that don't exist on `WebExtra` / `ApiExtras` all surface here in seconds. Fix anything that fails before running a real test.
+Then run the batch: `npx codeceptjs run --steps -c <config>`.
 
-**Then run the whole batch for real.** Dry-run proves specs parse and resolve — not that they pass. As soon as a batch is dry-run clean, run it against the browser:
-
-```bash
-npx codeceptjs run --steps -c <config>
-```
-
-First real runs after a migration almost always have failures — locator drift, timing the source framework hid behind its own retry, auth/session differences, data assumptions. **This is expected; fixing it is part of the migration, not a follow-up task.** When a test fails, **invoke the `debugging-codeceptjs-tests` skill and fix it on the fly** — it breakpoints the failing step, inspects the live page via MCP, finds the working locator/wait, and commits the verified fix. Do not bulk-rewrite specs blind, and do not mask failures with `retry`. Drive every failure to a real fix before starting the next batch. A batch is "done" when it runs green, not when it dry-runs clean.
+- 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. Locator preference
 
-CodeceptJS priority — pick the highest that fits. TestCafe's lazy chainable `Selector` lines up well with CodeceptJS's `locate()` builder, but most chains shrink considerably because semantic strings cover what `.withText` was doing.
+**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*.
+
+CodeceptJS priority — pick the highest that fits, then add the context. TestCafe's lazy chainable `Selector` lines up well with CodeceptJS's `locate()` builder, but most chains shrink considerably because a semantic string plus a context covers what `.withText` + `.find` were doing — `Selector('.row').withText('Acme').find('.btn')` becomes `I.click('Edit', locate('.row').withText('Acme'))`.
 
-1. **Semantic strings** — button text, label, placeholder, link text: `I.click('Save')`, `I.fillField('Email', 'u@t.com')`. Covers `Selector('button').withText('Save')` cleanly.
-2. **ARIA roles** — `I.click({ role: 'button', name: 'Sign In' })`. Strong default for modern apps.
-3. **`locate()` builder** — `I.click(locate('.row').withText('Acme').inside('table'))`. Direct equivalent of TestCafe `Selector('.row').withText('Acme').find('.btn')` style chains.
-4. **CSS / XPath / attribute objects** — `{ id: 'foo' }`, `{ name: 'email' }`, `{ css: '[data-test=submit]' }`, `{ xpath: '//div[@id="x"]' }`. Fallback.
+1. **Semantic strings** — button text, label, placeholder, link text: `I.click('Save', '.toolbar')`, `I.fillField('Email', 'u@t.com', '#login-form')`. Covers `Selector('button').withText('Save')` cleanly.
+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')`. Strong default for modern apps.
+3. **`$name` via the `customLocator` plugin** — when the suite uses `data-test` / `data-qa` attributes.
+4. **`locate()` builder** — `I.click(locate('.row').withText('Acme').inside('table'))`. Direct equivalent of TestCafe `Selector(...)` chains that don't reduce to locator + context.
+5. **CSS / XPath / attribute objects** — `{ id: 'foo' }`, `{ name: 'email' }`, `{ css: '[data-test=submit]' }`, `{ xpath: '//div[@id="x"]' }`. Fallback.
 
 | TestCafe Selector chain | CodeceptJS 4 |
 |---|---|
@@ -333,18 +329,10 @@ Only after every spec is ported and CI is green: delete `.testcaferc.{json,js,ts
 5. Hand off to **`codeceptjs-run-analysis`** to inspect `output/trace_*/` artifacts (requires the `aiTrace` plugin enabled).
 6. `grep -rE "\\bfixture\\(|\\btest\\(|Selector\\(|ClientFunction\\(|\\bRole\\(|t\\.click\\(|t\\.typeText\\(" tests/` — empty before deleting the original TestCafe directory.
 
-## Pointers
-
-- `node_modules/codeceptjs/docs/basics.md` — `I.*` vocabulary, locators, assertions, the `await` rule (the rule TestCafe users have to *un*-learn)
-- `node_modules/codeceptjs/docs/playwright.md` — recommended helper; `mockRoute` for `RequestMock`; `evaluate` for `ClientFunction` / `t.eval` ports
-- `node_modules/codeceptjs/docs/locators.md` — semantic / ARIA / `locate()` builder (replaces TestCafe Selector chains)
-- `node_modules/codeceptjs/docs/custom-helpers.md` — `WebExtra` / `ApiExtras` patterns (extending `Helper`, reaching `this.helpers['Playwright']` / `this.helpers['REST']`)
-- `node_modules/codeceptjs/docs/api.md` — REST / GraphQL configuration, `setSharedCookies()`, `defaultHeaders`, `JSONResponse` assertions, Zod schemas
-- `node_modules/codeceptjs/docs/assertions.md` — built-in `see*` assertions, `ExpectHelper`, `codeceptjs/assertions` factories (use these instead of `if (cond) throw new Error(...)`)
-- `node_modules/codeceptjs/docs/pageobjects.md` — porting TestCafe Selector-based page objects
-- `node_modules/codeceptjs/docs/sessions.md`, `auth.md` — replaces `Role` + `t.useRole`
-- `node_modules/codeceptjs/docs/effects.md` — `tryTo`, `retryTo`, `within` (replaces `t.switchToIframe`)
-- `writing-codeceptjs-tests` — per-spec rewrite playbook (drive via MCP, learn locators, commit verified steps)
-- `debugging-codeceptjs-tests` — **use on every failing test from the first full run** (breakpoint, inspect live page via MCP, fix on the fly)
-- `codeceptjs-auth` — replace `Role` + `t.useRole`
-- `codeceptjs-fundamentals` — run **after** migration to confirm the new setup is wired correctly
+## Related skills
+
+- `writing-codeceptjs-tests` — per-spec rewrite playbook (MCP-driven, verified steps); also the path to re-author Studio recordings
+- `debugging-codeceptjs-tests` — use on every failing test from the first full run
+- `codeceptjs-auth` — replaces `Role` + `t.useRole`
+- `codeceptjs-fundamentals` — run after migration to confirm wiring; effects (`tryTo`, `within`) replace `t.switchToIframe`
+- Reference docs: `node_modules/codeceptjs/docs/` (basics, playwright, locators, custom-helpers, api, assertions, pageobjects, sessions, auth)

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

@@ -1,53 +1,42 @@
 ---
 name: refactoring-codeceptjs-tests
-description: Use when refactoring CodeceptJS 4 tests — cleaning up duplication, extracting page objects, taming long locators, moving raw JS into custom helpers. Works targeted (one test or file) or global (whole tests directory). Always proposes changes before applying. Trigger on phrases like "refactor my tests", "clean up", "extract page object", "this test is too long", "deduplicate", or when reviewing test files for quality.
+description: >
+  Use when cleaning up existing CodeceptJS 4 tests — deduplication, extracting
+  page objects, taming long locators, moving raw JS into custom helpers.
+  Targeted (one file) or global (whole tests directory); always proposes before
+  applying. Trigger on "refactor my tests", "clean up", "extract page object",
+  "this test is too long", "deduplicate", or when reviewing test files for
+  quality.
 ---
 
 # Refactoring CodeceptJS 4 Tests
 
-Test suites rot in three predictable ways: duplicate UI flows copy-pasted across files, fat locators repeated everywhere, and raw JS escaping into Scenarios. The fix for each is moving the pattern to its proper home — page object, custom helper, or the `auth` plugin — without changing test behaviour.
+Suites rot in three predictable ways: duplicated UI flows copy-pasted across files, fat locators repeated everywhere, raw JS escaping into Scenarios. The fix for each is moving the pattern to its proper home without changing behaviour.
 
-This skill works **targeted** (refactor one test or file the user named) or **global** (sweep the whole tests directory). Either way it **proposes changes first** and applies after approval, in reviewable batches.
+Works **targeted** (a file or Scenario the user named) or **global** (the whole configured `tests` glob). Either way: **propose first**, apply in reviewable batches after approval.
 
 ## Workflow
 
-### 1. Read the project (fundamentals)
-Run the **codeceptjs-fundamentals** skill. You need: registered page objects (keys under `include`), the actor file (`custom_steps.js` or similar), any custom helpers already configured, and the `auth` plugin's user list. Without this you don't know where extractions land.
-
-### 2. Pick scope
-- **Targeted** — a file or Scenario the user named. Read it once, propose, apply.
-- **Global** — the configured `tests` glob. Treat as a multi-pass cycle: inventory → propose grouped → approve → apply a batch → re-run affected Scenarios → next batch. Never one big edit.
-
-### 3. Inventory the target
-Read the test(s). Note:
-- Repeated `I.*` sequences across 2+ Scenarios.
-- Locator strings used in 2+ places, or single locators that span multiple lines / deep XPath / nested CSS.
-- `I.executeScript` blocks beyond one statement.
-- `usePlaywrightTo` / `usePuppeteerTo` / `useWebDriverTo` blocks doing business work (not inspection).
-- Hardcoded credentials, URLs, magic strings.
-- `I.wait(N)` raw-seconds calls and `await` on plain action steps — fix while you're there.
-
-### 4. Duplicate UI flows → page object methods
-Sequences like login form fill, modal-confirm, search-then-click, table-row-edit. Extract to a method named for the user's intent: `loginPage.signIn(email, pass)`, `searchBar.searchFor(term)`, `cartPage.removeItem(name)`. Add to the existing PO when one fits the area; otherwise create a new PO and register it under `include` in the config. Apply the **rule of three** — wait for the second occurrence before extracting; one-off code shouldn't be abstracted.
-
-### 5. Fat locators → `locate()` in page objects
-Multi-line XPath, deeply nested CSS, or repeated locator strings. Convert to the `locate(...)` builder, leaning on the new 4.x DSL methods (`withClass`, `withoutClass`, `and`, `andNot`, plus `withText`, `inside`, `withDescendant`). Used once → keep `locate()` inline at the call site. Used 2+ times → store as a named page-object field with `.as('description')` so failures point at a meaningful name.
-
-### 6. Raw JS → custom helper
-Big `I.executeScript(...)` blocks, `usePlaywrightTo` doing real DOM walking or business logic, hand-rolled fetches inside a Scenario. Move into a method on a custom helper. Register the helper under `helpers` in the config alongside built-ins. **Critical rule from fundamentals**: inside a custom helper, `I` does **not** exist — compose with another helper via `this.helpers['<Name>']` (e.g. `this.helpers['Playwright'].page.evaluate(...)`, `this.helpers['REST'].sendGetRequest(...)`). Tests stay in the `I.*` vocabulary; helpers expose the new capability.
-
-### 7. Special case — login duplication
-If the duplicated UI flow is login, **don't build a `loginPage.signIn` method**. Hand off to the **codeceptjs-auth** skill — that's what the `auth` plugin exists for. Page objects for login flows are a common smell when the project should be using session reuse.
-
-### 8. Cross-page flows (optional)
-Site-wide actions used across many Features — `I.acceptCookies()`, `I.goToBilling()`, `I.dismissNotification()` — belong in the actor (`custom_steps.js`), not a single page's PO. The actor is the right home when no single page owns the action.
-
-### 9. Propose, then apply
-Group proposals by destination file (`pages/loginPage.js`, `helpers/DbHelper.js`, `tests/checkout_test.js`). Show the user the list before editing. In global mode, get explicit approval and work in batches — three to five files at a time. After each batch, run the affected Scenarios:
-```bash
-npx codeceptjs run --grep '<scenario or feature>' --steps
-```
-Hand the result to **codeceptjs-run-analysis** — confirm every affected scenario still passes and no failure shifted to a new step. Refactors that don't run aren't refactors — they're guesses.
+1. **Fundamentals** — run `codeceptjs-fundamentals`. You need: page objects under `include`, the actor file, custom helpers, auth roles. Without this you don't know where extractions land.
+2. **Pick scope**:
+   - Targeted — read once, propose, apply.
+   - Global — multi-pass cycle: inventory → propose grouped → approve → apply a batch → re-run affected Scenarios → next batch. Never one big edit.
+3. **Inventory** — flag:
+   - Repeated `I.*` sequences across 2+ Scenarios
+   - Locators used in 2+ places; multi-line XPath / deeply nested CSS
+   - Unscoped locators carrying their own region (`'.sidebar nav a.settings'`), `'aria-label=X'` spellings, raw `[data-testid=...]` at call sites
+   - Multi-statement `I.executeScript`; `usePlaywrightTo`/`usePuppeteerTo`/`useWebDriverTo` doing business work
+   - Hardcoded credentials, URLs, magic strings
+   - `I.wait(N)` and stray `await` on plain actions — fix while you're there
+4. **Duplicate flows → page-object methods** named for user intent (`loginPage.signIn(email, pass)`, `cartPage.removeItem(name)`). Rule of three: extract at the second occurrence; one-off code stays put.
+5. **Fat locators** — split before reaching for the builder: structural half becomes the context argument, rest stays a semantic string.
+   - `I.click('.sidebar nav a.settings')` → `I.click('Settings', '.sidebar')`
+   - `I.click({ css: '[aria-label="Save"]' })` → `I.click('Save', '.toolbar')`
+   - `I.click({ css: '[data-qa=submit]' })` → `I.click('$submit', '.checkout')` with `customLocator`
+   Only what survives the split needs `locate()`: used once → inline at call site; used 2+ times → named PO field with `.as('description')` so failures point at a meaningful name.
+6. **Raw JS → custom helper** — `I.executeScript` blocks, `usePlaywrightTo` doing DOM walking or business logic, hand-rolled fetches inside Scenarios. Remember the fundamentals rule: **`I` does not exist inside a helper** — compose via `this.helpers['<Name>']`. Tests stay in the `I.*` vocabulary.
+7. **Login duplication** — don't build a `loginPage.signIn` method. Hand off to `codeceptjs-auth`: that's what the `auth` plugin exists for. Login POs are a smell when session reuse applies.
+8. **Site-wide actions** (`I.acceptCookies()`, `I.goToBilling()`) — actor file (`custom_steps.js`), not any single page's PO. Right home when no single page owns the action.
 
 ## Decision tree
 
@@ -56,26 +45,34 @@ Hand the result to **codeceptjs-run-analysis** — confirm every affected scenar
 | UI flow on one page | Method on that page's PO |
 | UI flow spanning pages, site-wide | Actor (`custom_steps.js`) |
 | Login | `auth` plugin (see `codeceptjs-auth`) |
+| Long locator carrying its own region | Short semantic locator + context arg |
 | Long locator used once | `locate()` inline |
-| Long locator used 2+ times | `locate()` stored as a PO field |
+| Long locator used 2+ times | `locate()` stored as PO field |
 | Raw browser API / file system / DB / mail | Custom helper |
 | Test-data setup hitting an API | REST helper + Data Object |
 
+## Propose, then apply
+
+Group proposals by destination file (`pages/loginPage.js`, `helpers/DbHelper.js`, `tests/checkout_test.js`). Show the list before editing. In global mode: explicit approval, batches of three to five files, re-run after each batch:
+
+```bash
+npx codeceptjs run --grep '<scenario or feature>' --steps
+```
+
+Hand output to `codeceptjs-run-analysis` — confirm every affected Scenario still passes and no failure shifted to a new step. Refactors that don't run aren't refactors.
+
 ## Things to avoid
 
 - Refactoring without re-running the affected Scenarios afterwards.
-- Extracting a flow that's only used once — wait for the second occurrence.
-- Renaming PO methods or fields without grepping for every caller first.
-- Moving code to a custom helper when a page object would do.
+- Extracting a flow used only once — wait for the second occurrence.
+- Renaming PO methods/fields without grepping every caller.
+- A custom helper where a page object would do.
 - Squashing distinct flows into one method (`loginPage.do(thing)` is a smell).
-- Touching Scenario names or tags — CI pipelines and `--grep` filters reference them.
-- Mass-applying changes in global mode without batching and re-running.
+- Touching Scenario names or tags — CI and `--grep` reference them.
+- Mass-applying in global mode without batching and re-running.
 
-## Pointers
+## Related skills
 
-- `node_modules/codeceptjs/docs/pageobjects.md` — class-based POs, `inject()`, lifecycle hooks
-- `node_modules/codeceptjs/docs/custom-helpers.md` — extending `Helper`, the `this.helpers[...]` rule
-- `node_modules/codeceptjs/docs/locators.md` — `locate()` builder + 4.x DSL methods
-- `node_modules/codeceptjs/docs/best.md` — broader test-organisation guidance
-- `codeceptjs-fundamentals` skill — DI, `inject()`, the `I`-unreachable-from-helpers rule
-- `codeceptjs-auth` skill — for login deduplication
+- `codeceptjs-fundamentals` — Main rule, Where things go, Architecture (`I`-unreachable rule)
+- `codeceptjs-auth` — login deduplication
+- `codeceptjs-run-analysis` — post-refactor verification