testeiya 0.2.1 → 0.3.9

package/skills/codeceptjs/ci-fix-tests/SKILL.md

@@ -1,120 +0,0 @@
----
-name: ci-fix-tests
-description: "Use on CI in non-interactive mode when a CodeceptJS run failed — automatically attempt safe fixes (locator drift, missing waits), rerun only the failing scenarios, compare against the baseline, roll back any edit that didn't help, and always write a markdown report at `output/ci-fix.md` for the CI step to consume. Conservative by design: no refactors, no config edits, no auth fixes, no flake-masking retries. Trigger on \"ci fix tests\", \"auto-fix failing tests\", \"attempt repair on CI\", or as a CI step after a failed run."
----
-
-# Auto-fix CodeceptJS Tests on CI
-
-A non-interactive auto-repair loop. Reads the failed-tests baseline from `output/` (where `aiTrace` left trace artifacts), attempts a small set of safe fixes, reruns only the failing scenarios, compares, and writes a report at `output/ci-fix.md`. Rolls back any edit that didn't help.
-
-**Conservative by design.** CI is not the place to restructure tests, change abstractions, or fix anything that needs human judgement. The goal is "pass the run". Anything riskier is escalated through the report.
-
-This skill assumes a working **git** checkout — rollback uses `git checkout -- <file>` to restore originals.
-
-## Workflow
-
-### 1. Read the baseline failures
-Use the **codeceptjs-run-analysis** skill against the existing `output/trace_*/` artifacts to enumerate every failing scenario. Record:
-
-- the **set** of failing tests (file path + scenario name)
-- the failed step in each, and the locator / wait / assertion involved
-- a cluster signature per failure (so unique vs systemic is clear)
-
-Save this as the **baseline** — `count`, `failing_set`, `clusters`.
-
-### 2. Pick safe fix candidates
-Only attempt fixes from this allowed list:
-
-- **Locator drift** — the failed locator no longer matches anything but a similar element exists. Use the **codeceptjs-exploration** skill (headless) to find candidates; pick one with high semantic stability (ARIA `{ role, name }` → visible text → `data-testid` → composed CSS). Replace the locator at the failing step only.
-- **Missing wait for a spinner / loader / modal** — the failed step's ARIA snapshot shows a spinner or skeleton present, or the target element appears later. Add a single matching `I.waitFor*` immediately before the failing step.
-- **`I.wait(N)` replacement** — when a hardcoded sleep is the only thing between a failing assertion and a passing one and the gating element is identifiable, replace the sleep with a specific `waitFor*`.
-
-**Do not attempt:**
-- Auth / credential / env-var fixes — those are CI configuration, not test code.
-- Refactoring (extracting page objects, custom helpers, splitting scenarios).
-- Renaming Scenarios or tags — CI's `--grep` and pipelines reference them.
-- Adding `retries: N` to a Scenario — masking flake is a human decision.
-- Anything outside the failing test file (no `codecept.conf.*`, no helper, no PO edits).
-
-If a failure doesn't match any allowed-fix pattern, **skip it** and record it as `unresolved` for the report.
-
-### 3. Apply edits and rerun
-Track every modification: file path, line number, before/after snippet, fix kind. Then rerun **only the failing scenarios** under the same config CI used:
-
-```bash
-npx codeceptjs run --grep '<scenario>|<scenario>|...'
-```
-
-Find the right config via `package.json` scripts or the CI workflow file. Match the worker count if `run-workers` was used originally.
-
-### 4. Compare against the baseline
-Use **codeceptjs-run-analysis** again to enumerate the failing set after the fix.
-
-| New failing-set vs baseline | Status |
-|---|---|
-| Empty (zero failures) | `SUCCESS_FULL` |
-| Strict subset of the baseline | `SUCCESS_PARTIAL` |
-| Identical set | `NO_IMPROVEMENT` |
-| Larger, or contains a test not in baseline | `REGRESSED` |
-
-### 5. Decide: keep or roll back
-
-- `SUCCESS_FULL` / `SUCCESS_PARTIAL` → **keep** the edits.
-- `NO_IMPROVEMENT` / `REGRESSED` → **roll back every edit** with `git checkout -- <files>`. The on-disk state at the end of the skill must be identical to what it was at the start.
-
-A regression is treated the same as no improvement — the attempt didn't work, the working state is what was on disk before. Don't try to "undo only the bad ones" — the whole batch goes.
-
-### 6. Write the report (always)
-Write `output/ci-fix.md` regardless of outcome — CI reads it to surface results.
-
-## Report format
-
-```markdown
-# CI Fix Report — <ISO timestamp>
-
-**Status:** SUCCESS_FULL | SUCCESS_PARTIAL | NO_IMPROVEMENT | REGRESSED
-
-## Baseline
-Failing scenarios: N
-- `tests/foo_test.js` — "user can log in"
-- `tests/bar_test.js` — "checkout flow"
-- ...
-
-## Attempted fixes
-- `tests/foo_test.js:42` — locator drift: `'Save'` → `{ role: 'button', name: 'Save' }`
-- `tests/bar_test.js:15` — added `I.waitForInvisible('.spinner')` before checkout click
-- `tests/baz_test.js:7` — replaced `I.wait(3)` with `I.waitForVisible('.confirmation-dialog', 10)`
-
-## Result
-Failing scenarios after fix: M (was N)
-- Resolved: `tests/foo_test.js` — "user can log in"
-- Still failing: `tests/bar_test.js` — "checkout flow"
-- New failures (REGRESSED only): `tests/baz_test.js` — "edit profile"
-
-## Failure clusters (NO_IMPROVEMENT / REGRESSED only)
-- **Cluster A (3 scenarios)** — `Element not found: button.btn-primary`. Likely a deploy regression or design change.
-- **Cluster B (1 scenario)** — `Navigation timeout to /checkout`. Possible backend issue.
-
-## Discarded changes (NO_IMPROVEMENT / REGRESSED only)
-- `tests/foo_test.js` — restored
-- `tests/bar_test.js` — restored
-- `tests/baz_test.js` — restored
-```
-
-The first line of `Status:` is the machine-parseable signal. The rest is for the human reading the failed CI build.
-
-## Things to avoid
-
-- Editing files outside the failing test files. Config, helpers, page objects, and CI workflows are off-limits in this mode.
-- Attempting more than one fix kind on the same scenario in one pass. Fix one thing, observe, then try another.
-- `retries: N` to mask flakiness — human decision.
-- Skipping rollback on `NO_IMPROVEMENT`. Even no-op edits can confuse the next run or the next reviewer.
-- Writing a partial or missing `output/ci-fix.md`. CI depends on it; the absence of a report is itself a failure mode.
-- Running the **whole** suite for the verification step — only the originally-failing scenarios, to keep CI time bounded.
-
-## Pointers
-
-- `codeceptjs-run-analysis` — read trace artifacts, cluster failures, build the baseline set.
-- `codeceptjs-exploration` — find replacement locators when one has drifted.
-- `codeceptjs-fundamentals` — confirm helper, config, which env the CI run used.
-- `node_modules/codeceptjs/docs/aitrace.md` — trace format.

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

@@ -1,158 +0,0 @@
----
-name: codeceptjs-auth
-description: Use when a CodeceptJS test needs login, when different user roles are involved, or when the writing-codeceptjs-tests skill identifies authorization is required. Configures the `auth` plugin for session reuse, derives the login flow from the actual login page HTML (not guesses), keeps the real flow inside `steps_file.js` so `I.login*()` is callable directly and the conf stays small, loads credentials from a `.env` file via the modern Node `process.loadEnvFile()` API (no `dotenv` dependency), and supports multiple roles. Trigger on mentions of login, sign-in, sign-up, authentication, sessions, "logged in", admin/editor/user roles, or auth-related test failures.
----
-
-# CodeceptJS Auth Plugin
-
-The `auth` plugin logs each user in once, captures cookies (or local-storage / token via overrides), and restores the session for subsequent tests. Stale sessions trigger a fresh login automatically.
-
-Source of truth: `node_modules/codeceptjs/lib/plugin/auth.js` — JSDoc lists every recipe. Reference doc: `node_modules/codeceptjs/docs/auth.md`.
-
-## When to add it
-
-Suggested if tests have repeatable authentication and session is needed to be persisted accross tests. Also optimizes start time of tests by saving previous sessision cookies in files. 
-
-Suggested as performance optimization, refactoring measure.
-
-If `auth` plugin already exists in the project (check fundamentals' output), reuse the existing `inject` name and user keys.
-
-## Decide first — ask the user
-
-Four answers shape the plugin. Don't guess any. If the project or test plan doesn't make them obvious, ASK.
-
-1. **Is a session needed at all?** Public flows (landing, signup) don't need one — skip the plugin.
-2. **One user or many?** Default to one. Add more only when more than one is actually exercised.
-3. **If many — what splits them?** Don't assume "admin / editor / viewer". Real systems split users by role, workspace / tenant, plan tier, sign-in provider (Google vs SSO vs password — same person), or per-test fixture. ASK the user; use the answer to name the `users.<key>` entries.
-4. **What's the auth type?** Form login is the default; others need a different `login()` body:
-   - **Form** — `fillField` → `click Sign in`. Canonical shape below.
-   - **OAuth / SSO** — click provider button, drive the IdP page (often a separate origin).
-   - **Magic link / passwordless** — UI flow is rarely worth automating. Prefer a backdoor — API mint, or read the link from a test mailbox.
-   - **API token** — skip the form; `I.executeScript` to write the token into `localStorage`, or `I.setCookie(...)`.
-   - **2FA / OTP** — `async login`; fetch the code from a test mailbox / backdoor before submitting.
-
-## Rules
-
-1. **Login flow must not be written in the conf.** Better to place it nto steps_file.js (if it is includded) or page object. The conf better to reference it like: `login: (I) => I.login()`.
-2. **Credentials should not be stored in configs. Use `.env` via `process.loadEnvFile()`** (modern Node, no `dotenv` package). Passwords wrapped with `secret(...)`. No literal credentials anywhere — conf, steps file, test, or git history.
-3. **`.env` is gitignored; `.env.example` is committed** with the var names and no values. `output/*_session.json` is gitignored too.
-
-## Canonical shape
-
-```js
-// codecept.conf.js — first line of the file
-process.loadEnvFile() // or dotenv.load() if this package availble 
-// ...
-
-export const config = {
-  // ...
-  include: { I: './steps_file.js' },
-  plugins: {
-    auth: {
-      enabled: true,
-      saveToFile: true,
-      users: {
-        admin: {
-          login: (I) => I.login(),
-          check: (I) => I.see('Welcome, User', '.navbar'),
-        },
-      },
-    },
-  },
-}
-```
-
-```js
-// steps_file.js
-import { secret } from 'codeceptjs'
-const { I } = inject()
-
-export default function () {
-  return actor({
-    login() {
-      I.amOnPage('/login')
-      I.fillField('Email', process.env.ADMIN_EMAIL)
-      I.fillField('Password', secret(process.env.ADMIN_PASSWORD))
-      I.click('Sign in')
-    },
-  })
-}
-```
-
-```
-# .env (gitignored)              # .env.example (committed)
-USER_EMAIL=USER@example.com     USER_EMAIL=
-USER_PASSWORD=<secret>          USER_PASSWORD=
-```
-
-## Pre-flight (before writing config)
-
-1. **Read the real login page HTML.** Don't guess locators. MCP: `run_code` to login page and inspect the ARIA snapshot. Field labels / `name` / `id` / submit control — from the actual page. It's ok to ask user about authorization if it is not clear how to makeit.
-2. **Pick a role-specific post-login marker.** Something the page renders only for *this* user (navbar username, `data-user-role`).
-3. **Confirm session storage.** Cookies (default) for server-rendered apps; `localStorage`/`sessionStorage` for SPAs — verify with `I.executeScript(() => Object.keys(localStorage))` after a manual login. Default cookie `fetch`/`restore` silently no-op for token storage.
-
-## Verify
-
-Or MCP `run_test` against a one-Scenario file that calls `login(<role>)` then asserts on the post-login marker.
-
-Enable `saveToFile: true` only after the verification round-trip succeeds — a bad saved session masks a broken `login`.
-
-## Refactor
-
-Add to before hooks (if applied to all tests in suite) or to exact tests in syute
-
-`Before(({ login }) => login())`
-
-`login` was declared in auth plugin configuration
-
-Run real, not dry:
-
-```bash
-npx codeceptjs run --grep '<scenario>' --debug
-```
-
-
-## Multi-session shape
-
-Only after question 3 is answered. Name `users.<key>` after whatever splits them in *this* system; one matching login method per key in `steps_file.js`.
-
-```js
-// keys named after the dimension (role / workspace / provider / …)
-users: {
-  admin:      { login: (I) => I.loginAsAdmin() },
-  workspaceB: { login: (I) => I.loginToWorkspaceB() },
-}
-```
-
-Don't parameterise into a single `login(key)` — the plugin keys sessions by name and explicit methods read better. Switching between sessions in one Scenario: `session('<key>')` opens a separate browser context (see `node_modules/codeceptjs/docs/sessions.md`).
-
-## Token / local-storage auth
-
-When sessions live outside cookies, override `fetch` and `restore`:
-
-```js
-admin: {
-  login: (I) => I.loginAsAdmin(),
-  check: (I) => I.see('Admin', '.navbar'),
-  fetch: (I) => I.executeScript(() => localStorage.getItem('session_id')),
-  restore: (I, session) => {
-    I.amOnPage('/')
-    I.executeScript((s) => localStorage.setItem('session_id', s), session)
-  },
-}
-```
-
-`check(I, session)` receives whatever `fetch` returned — throw inside `check` to force a fresh login (e.g., when a `/me` endpoint shows the wrong user).
-
-## Common pitfalls
-
-- **Credentials inlined in conf or test.** Always env-driven. A code review showing a literal email or password = skill failed.
-- **Forgetting to gitignore `.env` and `output/*_session.json`.** Both leak credentials.
-
-
-## Pointers
-
-- `node_modules/codeceptjs/lib/plugin/auth.js` — JSDoc recipes (cookie / multi-user / local-storage / async / session-validation)
-- `node_modules/codeceptjs/docs/auth.md` — full reference
-- `node_modules/codeceptjs/docs/sessions.md` — `session()` for multi-user Scenarios
-- `node_modules/codeceptjs/docs/secrets.md` — the `secret()` wrapper

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

@@ -1,91 +0,0 @@
----
-name: codeceptjs-exploration
-description: Use to explore a page in CodeceptJS — read its ARIA tree, inspect candidate elements, pick a stable locator. Drives the live browser through MCP `run_code`, prefers ARIA over HTML, uses `I.grabWebElement` / `I.grabWebElements` with permissive XPaths to enumerate candidates and `toSimplifiedHTML` / `toAbsoluteXPath` to disambiguate. Other skills (`writing-codeceptjs-tests`, `debugging-codeceptjs-tests`, `refactoring-codeceptjs-tests`) invoke this whenever they need to learn what's on a page.
----
-
-# CodeceptJS Page Exploration
-
-Authoring a test, debugging a failure, and refactoring a stale locator all share one task: open a page, find the right element, pick a stable locator. This skill is the playbook.
-
-## How to look at a page
-
-Drive everything through MCP. Two tools matter for exploration:
-
-- **`run_code`** — runs CodeceptJS code and returns the value the code produced, captures `console.*` output, and saves a final-state snapshot. Use when you want to *do something and look at the result* (try a locator, grab a value, navigate).
-- **`snapshot`** — captures the current state without performing any action: URL, cookies, localStorage, HTML, ARIA, screenshot, console. Use when you want to look at "what's on the page right now" between two actions, without re-running anything.
-
-Three artifact sources, in order of preference:
-
-1. **ARIA snapshot first.** Structured, free of styling noise, easy to scan for duplicates and accessibility names.
-2. **Screenshot.** Visual confirmation — catches layout breaks, missing icons, "rendered but wrong" cases that ARIA can't show.
-3. **HTML / outer markup.** Pull only when ARIA is missing crucial context: custom widgets without accessible names, attribute-driven behaviour, dynamic content with no roles.
-
-## Inspect a known element
-
-`I.grabWebElement(locator)` returns one WebElement; `I.grabWebElements(locator)` returns an array. Same cross-helper API on Playwright / Puppeteer / WebDriver, returns values back through MCP `run_code`.
-
-| You want to … | Method on WebElement |
-|---|---|
-| Confirm rendered / visible / enabled | `exists()`, `isVisible()`, `isEnabled()` |
-| Read text / value / attribute / property | `getText()`, `getValue()`, `getAttribute(n)`, `getProperty(n)` |
-| Where is it on the page | `getBoundingBox()` — flags offscreen / zero-sized |
-| The actual rendered markup | `toOuterHTML()`, `toSimplifiedHTML(300)` (truncated, MCP-friendly) |
-| Stable selector for a fix | `toAbsoluteXPath()` |
-| Look inside an iframe | `inIframe(async (body) => { ... })` |
-| Drill into children | `$(loc)`, `$$(loc)` |
-| Run a browser-side function | `evaluate(fn, ...args)` |
-
-## Discover candidates when the obvious locator misses
-
-When `Edit` matches nothing, the control might say "Change", carry `aria-label="Edit user"`, or live in a `.btn-edit` class. Cast a wide net: pass a permissive XPath to `I.grabWebElements`, then disambiguate.
-
-Build the XPath by ORing:
-- visible text — `text()` (or `.` to match descendants too)
-- relevant attributes — `@class`, `@aria-label`, `@title`, `@data-action`, `@id`
-- **synonyms** — "edit" / "change" / "modify"; "delete" / "remove" / "trash"; "submit" / "send" / "save"
-
-Wrap each match with `translate(...)` for case-insensitive `contains`:
-
-```
-//*[contains(translate(., 'EDIT', 'edit'), 'edit')
-    or contains(translate(@class, 'EDIT', 'edit'), 'edit')
-    or contains(translate(@aria-label, 'EDIT', 'edit'), 'edit')
-    or contains(translate(., 'CHANGE', 'change'), 'change')]
-```
-
-Then iterate `toSimplifiedHTML(150)` over the result, review the candidates, pick the right one, and commit a stable locator built from its discriminating attribute or text — or `toAbsoluteXPath()` if nothing else is stable.
-
-## Pick a stable locator
-
-Once the right element is identified, choose the locator with the highest semantic value that is still unique:
-
-1. ARIA — `{ role: 'button', name: 'Edit user' }`. Survives CSS refactors.
-2. Visible label / semantic text — `'Edit user'`. Easy to read.
-3. `[data-testid="edit-user"]` if the team uses test attributes.
-4. Composed CSS with a stable parent — `#user-row-42 button.edit`.
-5. `toAbsoluteXPath()` from the candidate review — last resort; flag for the team to add a `data-testid`.
-
-Don't commit a locator you didn't verify. After picking, run `I.seeElement(<locator>)` (or `grabWebElement(<locator>)`) through MCP `run_code` to confirm it matches exactly one element.
-
-## Common patterns
-
-- **Strict mode found 2 matches** — `grabWebElements('Save')`, `toSimplifiedHTML(200)` each, find a discriminator (parent class, `data-*`, surrounding text).
-- **Button rendered but doesn't act** — `grabWebElement('Submit')`, then `isEnabled()` + `getBoundingBox()` — disabled? offscreen? zero-sized?
-- **Wrong row in a list** — `grabWebElements('.user-row')`, `getText()` per row, identify, then `getAttribute('data-id')` for a stable hook.
-- **Inside an iframe** — `(await I.grabWebElement('iframe.editor')).inIframe(async (body) => body.$('button'))`.
-- **No semantic name on the element** — `toAbsoluteXPath()` for now; flag the team to add a `data-testid`.
-
-## Things to avoid
-
-- Choosing a locator without seeing the candidates first — you'll guess wrong and the test will be flaky.
-- Committing `toAbsoluteXPath()` when a semantic locator is right there.
-- Ignoring the screenshot — "element exists in HTML" doesn't mean "user can see it".
-- Reaching for `usePlaywrightTo` / `useWebDriverTo` when WebElement methods cover the case (cross-helper code is preferred).
-
-## Pointers
-
-- `node_modules/codeceptjs/docs/web-element.md` — full WebElement API
-- `node_modules/codeceptjs/docs/locators.md` — locator strategies and priorities
-- `node_modules/codeceptjs/docs/element-selection.md` — `step.opts({ elementIndex })`, strict mode
-- `node_modules/codeceptjs/docs/mcp.md` — MCP tool list
-- `codeceptjs-fundamentals` skill — locator priority and the `await` rule

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

@@ -1,158 +0,0 @@
----
-name: codeceptjs-fundamentals
-description: "Run first when working with any CodeceptJS 4 project. Compact primer on the internals you must know — configuration, the `I` actor and helpers, the DI container and `inject()`, custom helpers (and the rule that `I` is unreachable from inside one), plugins as hook listeners, and the `await` rule. Then runs a four-step discovery against this project: `codeceptjs check` to verify the setup loads, read the config, run `codeceptjs list` to enumerate available `I.*` actions, run `codeceptjs dry-run` to enumerate existing tests — and reports which helper, plugins, env switching, page objects, custom actions, and test suites are actually active. Other CodeceptJS skills depend on this output."
----
-
-# CodeceptJS Fundamentals
-
-Two jobs: teach the concepts you need to read CodeceptJS code without making things up, and report what *this* project has configured. Do both, in order.
-
----
-
-## Concepts
-
-### Module system
-CodeceptJS 4 is **ESM and TypeScript only**. Tests, configs, page objects, and helpers use `import`/`export`; `package.json` **must** have `"type": "module"` — if it isn't there yet, add it before doing anything else (without it, every `.js` file is parsed as CommonJS and imports fail). **TypeScript** is first-class: name the config `codecept.conf.ts`, add a loader entry like `require: ['tsx/cjs']` (or `ts-node/register`), and write tests as `.ts` files.
-
-If the project is on **CodeceptJS 3.x or still uses CommonJS** (`require()` / `module.exports`, no `"type": "module"`, removed helpers/plugins like `autoLogin` or `Nightmare`), stop here and run the **`migrate-codeceptjs-4`** skill — it walks the full upgrade path (Node bump, ESM conversion, helper/plugin replacements, AI/Zod/effects API changes, `noGlobals`, dependency bumps, verify). Don't try to half-fix individual files; the migration is a whole-project change.
-
-### Configuration
-`codecept.conf.{js,ts,mjs,cjs}` at the repo root. Top-level keys: `helpers`, `plugins`, `include`, `ai`, `bootstrap`/`teardown`, `tests`, `output`, `timeout`. TypeScript configs declare a loader in `require: [...]` (`tsx/cjs`, `ts-node/register`, `ts-node/esm`). Multiple env-specific files (`codecept.ci.conf.js`, …) are selected via `--config <file>`. The `@codeceptjs/configure` package mutates the resolved config at load time (`setHeadlessWhen`, `setBrowser`, `setCommonPlugins`, `setWindowSize`) — static fields can lie until you grep for that import.
-
-### `I` and helpers
-`I` is the actor. Every `I.<method>(...)` is dispatched to whichever active helper provides that method. Built-in helpers contribute different surfaces: web (Playwright, Puppeteer, WebDriver — overlapping core actions plus helper-specific extras), API (REST, GraphQL), AI, mobile (Appium), utility (FileSystem). The active helpers are exactly the keys under `helpers` in config.
-
-### `inject()` and the DI container
-Everything testable lives in a global container — the actor, every helper, every page object listed in `include`, every custom step module, every support object. Inside a Scenario you destructure from the test signature: `Scenario('...', ({ I, loginPage }) => { ... })`. Inside a *file* (page object class, data factory, custom helper module) call `const { I } = inject()` once at the top to pull what you need from the container. The names available are exactly the keys in `include`.
-
-### Custom helpers
-Custom helpers extend `Helper` (from `codeceptjs`) and contribute new `I.<method>` calls. They register under `helpers` in config alongside built-ins. **You cannot call `I.*` from inside a custom helper — `I` does not exist in helper scope.** To compose with another helper, reach for it via `this.helpers['<Name>']` (e.g. `this.helpers['Playwright'].page` or `this.helpers['REST'].sendGetRequest(...)`). Helpers exist to expose new low-level capabilities; tests stay in the `I.*` vocabulary.
-
-### Plugins and hooks
-Plugins are event listeners. CodeceptJS emits lifecycle events on a global dispatcher; any plugin can subscribe. Events include `suite.before`/`after`, `test.before`/`started`/`passed`/`failed`/`after`, `step.before`/`started`/`passed`/`failed`/`after`, `hook.passed`/`failed`, `multiple.before`/`after`. Plugins react — taking screenshots, retrying, healing, writing artifacts, pausing. Built-ins live under `node_modules/codeceptjs/lib/plugin/`; the full event list is in `node_modules/codeceptjs/lib/event.js`. A plugin is registered under `plugins` with `enabled: true`. `setCommonPlugins()` from `@codeceptjs/configure` enables a recommended bundle silently.
-
-### Plugins worth knowing
-- `retryFailedStep` — re-runs a transient action failure
-- `screenshot` — saves a screenshot when a step matches the trigger (default `on: 'fail'`); set `slides: true` to also produce a `output/records.html` slideshow (replaces the old `stepByStepReport`)
-- `pageInfo` — dumps URL, HTML, console output on failure
-- `auth` — session reuse for login (see the `codeceptjs-auth` skill)
-- `aiTrace` — per-step screenshots/HTML/ARIA/console for AI debugging (default `on: 'step'`; set `on: 'fail'` to capture only failures)
-- `pause` — interactive pause (replaces `pauseOn` / `pauseOnFail`; default `on: 'fail'`)
-- `heal` — AI-suggested fixes for broken action steps (disabled in `--debug` mode)
-- `screencast` — records a video / animated frames of the run (replaces `subtitles`)
-- `browser` — CLI-only override of browser helper config; see the next section
-
-### Running plugins from the CLI
-Plugins are normally enabled in `codecept.conf.{js,ts}`, but any plugin can be turned on or reconfigured for a single run via `-p <plugin>` on the runner. Args chain with `:` (or `;` inside one arg):
-
-```bash
-npx codeceptjs run -p aiTrace                      # enable aiTrace for this run
-npx codeceptjs run -p screenshot:on=step           # screenshot every step
-npx codeceptjs run -p pause:on=file:path=tests/login_test.js;line=43
-npx codeceptjs run -p browser:hide:browser=firefox:windowSize=1280x800
-```
-
-`screenshot`, `pause`, `aiTrace`, and `heal` share a unified **`on=` parameter** that picks when they fire:
-
-| `on=` value | Fires when | Extra args |
-|---|---|---|
-| `fail` | a step fails (default for screenshot / pause / heal) | — |
-| `step` | every step (default for aiTrace) | — |
-| `test` | after each test | — |
-| `file` | execution reaches a file/line | `path=<file>[;line=<N>]` |
-| `url` | browser URL matches a pattern | `pattern=<glob>` (`*` wildcards) |
-
-The **`browser` plugin** is CLI-only and overrides the active browser helper without touching the config file — useful for one-off env variants and CI matrix legs:
-
-```bash
-npx codeceptjs run -p browser:show                              # force visible
-npx codeceptjs run -p browser:hide                              # force headless
-npx codeceptjs run -p browser:browser=firefox                   # switch browser
-npx codeceptjs run -p browser:windowSize=1024x768
-npx codeceptjs run -p browser:hide:browser=webkit:windowSize=800x600
-```
-
-Requires `@codeceptjs/configure` installed. It translates `browser=` per helper (Puppeteer's `product`, Playwright's `browser`) and injects `--headless` into WebDriver capability args when toggling `hide`.
-
-### Test file structure
-One `Feature(...)` per file with one or more `Scenario(...)` blocks inside it. CodeceptJS does **not** allow nested suites or multiple Features in the same file. Hooks: `Before`, `After`, `BeforeSuite`, `AfterSuite`, plus `Fail((test, err) => { ... })` for failure-only cleanup. Page objects can expose `_before`, `_after`, `_afterSuite` lifecycle methods so per-page setup lives next to the page.
-
-### Locators
-Most actions accept a locator as a plain string (semantic — visible text, label, placeholder, `name`) or an object (`{ css }`, `{ xpath }`, `{ role, name }`, `{ id }`, `{ aria }`). Prefer ARIA `{ role, name }` for resilience to markup changes; semantic strings for prototyping; CSS / XPath as fallback. The `locate(...)` builder composes complex queries (`.withClass`, `.withText`, `.inside`, `.and`, `.andNot`). Almost every action method takes an optional context arg that narrows the search to a subtree: `I.click('Save', '.modal')`.
-
-### Auto-waiting
-Action methods (`click`, `fillField`, `selectOption`, …) automatically wait for the element to exist and become interactable before acting. Explicit `I.waitFor*` calls are needed only when the next condition isn't tied to an interaction — a modal appearing after a network call, a spinner disappearing, a value updating. Avoid `I.wait(N)` (raw seconds) unless nothing else fits.
-
-### Assertions
-CodeceptJS ships built-in browser assertions: `I.see`, `I.dontSee`, `I.seeElement`, `I.dontSeeElement`, `I.seeInCurrentUrl`, `I.seeInTitle`, `I.seeInField`, `I.seeNumberOfElements`, `I.seeCookie`, `I.seeCheckboxIsChecked`, etc. Use these instead of an external `expect()` library — they produce clear failure messages and integrate with the recorder. For non-DOM assertions, use `grab*` plus any assertion library: `const title = await I.grabTitle(); expect(title).toEqual('My App')`.
-
-### `await` inside tests
-CodeceptJS queues steps onto an internal recorder; the framework chains them, you do not. **Use `await` only when you need a return value** — `await I.grabTextFrom(...)`, `await I.grabCookie(...)`, or when calling a user-defined `async` function. Plain action steps (`I.click`, `I.fillField`, `I.see`) do not need `await`. Same rule inside `within(...)` and `pause()` callbacks. Sprinkling unnecessary `await` doesn't break anything, but signals you don't trust the recorder.
-
-### `secret()` for sensitive values
-Wrap passwords, tokens, API keys so they're masked in logs, step output, and trace artifacts: `I.fillField('Password', secret(process.env.PASSWORD))`. Imported from `codeceptjs`. Use anywhere a value would otherwise leak through verbose output, trace files, or AI prompts.
-
-### Sessions and `within`
-- `session(name, fn)` runs `fn` in a parallel browser context — for multi-user Scenarios (chat, multi-tenant). Combined with the `auth` plugin, each session can log in as a different role.
-- `within(locator, fn)` scopes locator resolution inside `fn` to the subtree under `locator`. `within({ frame: '#editor' }, fn)` switches into an iframe for the callback. Both can return values (`await within(..., () => I.grabTextFrom(...))`).
-
-### Parallel runs
-`npx codeceptjs run-workers <N>` splits Scenarios across N Node worker threads; results aggregate in the main process. The config can also describe **profiles** (different browsers, viewports, environments) via the `multiple` block; launch with `npx codeceptjs run-multiple <profile>`.
-
----
-
-## Discover this project
-
-Four steps, in order. Don't skip — guesses about helpers, custom actions, or what tests exist will be wrong as often as they're right.
-
-### 1. Verify the setup loads
-
-```sh
-npx codeceptjs check -c <config>          # validates config, container, helpers, plugins, page objects, hooks, tests, defs
-```
-
-Each item prints a pass/fail line, so the output doubles as a quick inventory of what the project has wired up. If anything fails here, fix it before running `list` or `dry-run` — a broken helper or unresolved page object will distort their output. Skipping this step also means you won't notice a missing dependency, an `auth` plugin pointed at a non-existent login route, or a custom helper that throws at construction.
-
-### 2. Read the active config
-
-Open `codecept.conf.{js,ts,mjs,cjs}` (resolve via `package.json` scripts and CI workflows if multiple files exist — note the path; you'll pass it to `-c` in steps 3 and 4). Extract: which helper(s) and any non-default behaviour (browser, strict, navigation, base URL, viewport, env-driven values); which plugins (incl. anything `setCommonPlugins()` injects); AI provider + the env var its key requires; how environments are selected (`--config` vs `process.env.*` branching, plus any `setHeadlessWhen`-style mutations); page object names from `include`; any custom helpers (entries pointing at local files).
-
-### 3. List available actions
-
-```sh
-npx codeceptjs list -c <config>          # every I.<method>, grouped by helper, with signature
-npx codeceptjs list --docs -c <config>   # adds JSDoc + docs/webapi/* prose under each action
-npx codeceptjs list --action <name> -c <config>   # single action; I. prefix optional; implies --docs
-```
-
-Run `list` against the discovered config before suggesting any method — especially in projects with custom helpers, where the available `I.*` surface differs from the built-in catalog. The CodeceptJS MCP server's `list_actions` tool returns the same data programmatically.
-
-### 4. List existing tests
-
-```sh
-npx codeceptjs dry-run -c <config>            # suite + test names that the config would load
-npx codeceptjs dry-run --steps -c <config>    # also prints queued I.* steps inside each test
-npx codeceptjs dry-run --grep "@smoke" -c <config>   # filter by name; --features / --tests narrow file kind
-npx codeceptjs dry-run --debug --grep '<test>' --numbers --no-ansi -c <config>   # numbered steps, no ANSI
-```
-
-`dry-run` walks the test files the active config picks up and prints them without executing — confirming both **which tests exist** and (with `--steps`) **what each Scenario would do** before any browser spins up.
-
-`--numbers` (paired with `--debug`, `--steps`, or `--verbose`) prefixes each leaf step with a per-test 1-based index. The numbering matches the `pauseAt: N` parameter on the MCP `run_test` tool — so this is the canonical way to discover step indices for programmatic breakpoints. `--no-ansi` strips colors / ANSI escapes so the output is clean for LLM consumption or piping to other tools.
-
-For Gherkin step definitions specifically, `npx codeceptjs gherkin:steps -c <config>` lists registered step patterns.
-
-## Report
-
-Short prose summary covering the items above. Flag env-driven values explicitly — don't claim a fixed value when it's `process.env.BROWSER || 'chromium'`. Flag conflicts (static `show: true` overridden by `setHeadlessWhen(CI)`; `auth` configured but the credential env vars are missing from the current shell or `.env.example`). If no config exists at the repo root and no `--config` is referenced anywhere, recommend `npx codeceptjs init .` and stop. **If the project is on CodeceptJS 3.x or CommonJS, recommend the `migrate-codeceptjs-4` skill and stop** — discovery output for a pre-4 project will misrepresent the available APIs.
-
-## Pointers
-
-- `node_modules/codeceptjs/docs/configuration.md` — config reference
-- `node_modules/codeceptjs/docs/typescript.md` — TS loader options
-- `node_modules/codeceptjs/docs/helpers.md` — helper concepts and method catalogs
-- `node_modules/codeceptjs/docs/custom-helpers.md` — writing your own
-- `node_modules/codeceptjs/docs/plugins.md` — plugin authoring + built-ins
-- `node_modules/codeceptjs/docs/hooks.md` — suite/test/step hook semantics
-- `node_modules/codeceptjs/lib/event.js` — every event the dispatcher emits
-- `@codeceptjs/configure` (npm) — the mutator API surface

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

@@ -1,90 +0,0 @@
----
-name: codeceptjs-run-analysis
-description: Use after running CodeceptJS tests with the `aiTrace` plugin enabled — analyse the trace artifacts (trace.md, per-step HTML/ARIA/screenshots, console logs) via bash tools. Toolkit, not a workflow — use cases include verifying a fix, clustering errors across a CI fail-storm, diagnosing flakiness across reruns, or investigating a single failure. Other skills (`writing-codeceptjs-tests`, `debugging-codeceptjs-tests`, `refactoring-codeceptjs-tests`) invoke this whenever a run has happened and needs to be reviewed. Trigger on phrases like "what failed", "analyse the run", "cluster these errors", "is it flaky", "did the fix hold".
----
-
-# CodeceptJS Run Analysis
-
-After `npx codeceptjs run`, the trace artifacts land in `output/`. This skill is the playbook for reading them efficiently — pulling out the right step, the right file, and the right slice of a giant HTML snapshot using bash tools rather than re-running the test through MCP.
-
-There's no single end goal — pick the use case that matches the situation. The foundations (where artifacts live, how to read them, what tools to reach for) apply to all of them.
-
-## Foundations
-
-### Ensure aiTrace is on
-The whole skill leans on `output/trace_<TestName>_<hash>/trace.md` and its sibling artifacts. Confirm `plugins: { aiTrace: { enabled: true } }` in the active config (run `codeceptjs-fundamentals` if you don't already know). Without aiTrace there are screenshots and `pageInfo` dumps at most — useful but partial; suggest enabling and re-running before deep analysis.
-
-The MCP `run_step_by_step` tool is now interactive (pauses after every step; agent advances via `continue`) and no longer auto-writes a per-run artifact bundle. `aiTrace` is the only source of per-step trace files now — for ad-hoc `run_code` and `snapshot` calls you still get a single-shot artifact set under `output/trace_run_code_*` / `output/snapshot_*`.
-
-### Locate traces
-Trace directories are `output/trace_<TestName>_<short-hash>/`; reruns produce a new dir per run. **When the right trace isn't obvious, sort by modification time and take the most recent** (`ls -dt`) — almost always the run you just kicked off.
-
-### Read trace.md first
-trace.md is the index — each step block links to its screenshot/HTML/ARIA/console. **Focus on the step marked failed; if no failure is explicitly marked, jump to the last step in the trace** — execution usually stops where the failure happened. When more than one step shows failed, the **first** is usually the cause; the rest are cascading side effects.
-
-### Open artifacts in the right order
-For the focus step `NNNN_<step>`:
-
-| Artifact | When |
-|---|---|
-| `NNNN_*_aria.txt` | First read — leaner than HTML, structured, easy to scan for duplicates |
-| `NNNN_*_screenshot.png` | Visual confirmation — layout, animation, "rendered but wrong" |
-| `NNNN_*_page.html` | Only when ARIA is missing context. **Use `grep`, not `cat`** |
-| `NNNN_*_console.json` | JS errors, 4xx/5xx, deprecation warnings explaining "vanished" elements |
-| `NNNN_*_storage.json` | Cookies + localStorage at this step. First place to look when auth is the suspected culprit. |
-
-### Never read big files whole
-HTML snapshots can be megabytes; `console.json` arrays can be long.
-
-- Use `grep` to search HTML for expected elements / attributes / locator variants (text, class, aria-label, `data-*`). Line numbers and context flags make the match readable.
-- Use `jq` to filter `console.json` for errors or specific event types instead of reading every entry.
-- When scanning many files, `grep -l` returns filenames-only.
-
-## Use cases
-
-### Verify a fix held
-After editing a test (e.g. via MCP) and re-running it via CLI: locate the latest trace, read trace.md, confirm no FAILED markers. Glance at `console.json` for warnings worth fixing while you're there.
-
-### Cluster errors across a CI batch
-When many tests failed in one run: extract the failing-step lines from every `trace.md` in the batch, group by signature (`grep` + `sort` + `uniq -c`), rank by frequency.
-
-- **Same error in many tests = systemic.** Env var missing, auth broken, base URL wrong, deploy regression. Fix the root cause once and rerun the batch.
-- **Different errors per test = local issues.** Triage one at a time.
-
-Pick the most-frequent root cause first; rerun to see how many tests came back along with it.
-
-### Diagnose flakiness across reruns
-Run the same test 5–10 times. Extract which step failed in each trace and look at how the answer varies. If the failing step is the *same* but the surrounding state differs, `diff` the ARIA snapshots at that step between two runs to spot what changed.
-
-- **Different step each run** → timing, environment, external service.
-- **Same step, different reason** → likely a missing or wrong wait (see Waiting in writing/debug skills).
-- **`console.json` differs between runs** → transient backend / network errors.
-- **Bounding box differs** → layout reflow or late-loading content shifting things.
-
-### Investigate a single failure
-Locate the trace, jump to the failed-or-last step, open ARIA + screenshot first, console.json second, HTML last (and only via `grep`). Form a hypothesis. If the trace alone isn't enough — the failure resists static analysis or the page state needs live poking — hand off to **debugging-codeceptjs-tests** for the MCP-driven loop.
-
-## After the analysis
-
-- **Systemic cause across many tests** — fix the root once (env, auth, deploy, base URL). Not per test.
-- **Locator drift** — invoke **codeceptjs-exploration** to pick a new stable locator.
-- **Timing / wait issue** — apply the Waiting guidance from the writing/debugging skills, replacing `I.wait(N)` with a specific `waitFor*`.
-- **Failure resists static analysis** — invoke **debugging-codeceptjs-tests** for the live MCP loop.
-- **Test passed cleanly** — done. Still glance at `console.json` for warnings worth fixing now.
-
-## Things to avoid
-
-- Reading large HTML or `console.json` files whole — search them with `grep` / `jq` instead.
-- When more than one step is marked failed, stopping at the last one — the **first** failure is usually the cause and the rest are cascading.
-- Triaging individual failures before clustering — fixing 12 symptoms of one bug is wasted effort.
-- Drawing flakiness conclusions from a single run — needs 5+ reruns.
-- Deleting `output/` mid-investigation; the artifacts are the only record of the run.
-
-## Pointers
-
-- `node_modules/codeceptjs/docs/aitrace.md` — trace format and config knobs
-- `node_modules/codeceptjs/docs/debugging.md` — verbose flags, `pause` plugin's `on=` modes
-- `node_modules/codeceptjs/docs/reports.md` — alternative reporters
-- `codeceptjs-fundamentals` — what's actually configured
-- `codeceptjs-exploration` — when locator drift is the cause
-- `debugging-codeceptjs-tests` — when post-mortem isn't enough