testeiya 0.3.9 → 0.3.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testeiya",
-  "version": "0.3.9",
+  "version": "0.3.14",
   "description": "AI testing agent — QA-focused coding agent for manual and automated tests",
   "type": "module",
   "license": "MIT",
@@ -28,10 +28,12 @@
   },
   "scripts": {
     "start": "npm run build && node dist/src/cli.js",
+    "dev": "./testeiya",
     "build": "tsc -p tsconfig.json && npm run build:vendor",
     "build:vendor": "esbuild scripts/vendor-entry.ts --bundle --format=esm --platform=node --packages=external --outfile=dist/vendor/mcp.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node --test test/*.test.js"
   },
   "keywords": [
     "testing",
@@ -54,6 +56,8 @@
   "devDependencies": {
     "@types/node": "^22.19.19",
     "esbuild": "^0.28.1",
-    "typescript": "^5.9.3"
+    "tsx": "^4.23.12",
+    "typescript": "^5.9.3",
+    "yaml": "^2.9.0"
   }
 }

package/prompt/index.ts

@@ -6,7 +6,7 @@ import {
   projectSettings,
   type TmsAccess,
 } from "./testomatio.js";
-import { nonInteractive, reportOutput } from "./print.js";
+import { briefAnswer, nonInteractive, reportOutput } from "./print.js";
 import {
   contextPromptSection,
   type ContextEntry,
@@ -28,6 +28,8 @@ export function buildSystemPrompt(options?: SystemPromptOptions): string {
       interactive,
       toolBullets: options?.toolBullets,
       rules: options?.rules,
+      connectedClis: options?.connectedClis,
+      connectedMcps: options?.connectedMcps,
     }),
   ];
 
@@ -62,7 +64,8 @@ export function buildSystemPrompt(options?: SystemPromptOptions): string {
     parts.push(testomatioNotConnected());
   }
 
-  // The report contract goes last so it is the final instruction the model reads.
+  // The answer contract goes last so it is the final instruction the model reads.
+  if (options?.brief) parts.push(briefAnswer);
   if (options?.outputFile) parts.push(reportOutput(options.outputFile));
 
   return parts.join("\n\n");
@@ -85,9 +88,15 @@ export interface SystemPromptOptions {
   tms?: TmsAccess;
   /** Absolute path the agent must write its final report to (`--output`). */
   outputFile?: string;
+  /** Answer a question instead of doing a task and reporting (`testeiya ask`). */
+  brief?: boolean;
   projectInfo?: TestomatioProjectInfo | null;
   /** User-added context (linked folders, cloned repos, uploaded docs). */
   contextEntries?: ContextEntry[];
   /** Non-empty predefined `.testeiya` context folders (manual-tests, code, …). */
   contextFolders?: ContextFolder[];
+  /** CLI tools the user has connected and signed in (e.g. `gh`, `acli`). */
+  connectedClis?: string[];
+  /** MCP servers connected for this session (the enabled `mcp.json` set). */
+  connectedMcps?: string[];
 }

package/prompt/print.ts

@@ -21,3 +21,12 @@ export function reportOutput(path: string): string {
 </final-report>
 `;
 }
+
+export const briefAnswer = dedent`
+<answer>
+  * You were asked a question, not given a task. Answer it.
+  * Lead with the answer in one line, then the evidence you checked.
+  * A few sentences. No report file, no headings, no plan.
+  * Say plainly when what you found does not settle the question.
+</answer>
+`;

package/prompt/system-prompt.ts

@@ -9,6 +9,8 @@ export function getSystemPrompt(cwd?: string, options?: PromptSurface): string {
   if (!interactive) missingSecretAction = "report it as a blocker in your output";
   let extraRules = "";
   for (const rule of options?.rules ?? []) extraRules += `    * ${rule}\n`;
+  const cliList = (options?.connectedClis ?? []).join(", ") || "none connected yet";
+  const mcpList = (options?.connectedMcps ?? []).join(", ") || "none connected yet";
   return dedent`
   <role>
     You are Testeiya, an AI agent that helps with QA tasks.
@@ -87,6 +89,16 @@ export function getSystemPrompt(cwd?: string, options?: PromptSurface): string {
 
   ${tools({ extra: options?.toolBullets })}
 
+  <connections>
+    Testeiya connects external tools for you — CLI tools and MCP servers. This session has:
+
+    * **Connected CLIs:** ${cliList}
+    * **Connected MCP servers:** ${mcpList}
+
+    * **Missing Connection — Ask, Never Improvise:** When a task needs a tool that is not in the lists above, STOP and ask the user to connect it in Testeiya (Settings → Connections). Never reach the service sideways: no raw REST/GraphQL calls against its API, no scraping credentials from dotfiles or env dumps, no installing binaries on your own.
+    * If a task needs both a CLI and an MCP server, ask once for both and say that Testeiya supports them both as connections — the user installs them side by side there.
+  </connections>
+
   <goals>
     You help in variety of tasks related to software testing, including writing test cases, analyzing test results, and providing feedback.
     You have skills to perform QA tasks on user demand.
@@ -98,10 +110,8 @@ export function getSystemPrompt(cwd?: string, options?: PromptSurface): string {
     * Assisting with manual test execution
     * Manage tests with TMS Testomat.io
     * Setting up CI pipelines for continuous testing
-    * Analyzing requirements
-    * Automating manual test cases
-    * Launching automated exploratory tests via explorbot
-    * Analyzing test results and providing feedback
+    * Analyzing requirements and issues
+    * Analyzing test results
 
     This is what you can do.
   </goals>
@@ -148,6 +158,10 @@ export interface PromptSurface {
   toolBullets?: string[];
   /** Extra `<rules>` bullets, for rules that only hold in this harness. */
   rules?: string[];
+  /** CLI tools the user has connected and signed in (e.g. `gh`, `acli`). */
+  connectedClis?: string[];
+  /** MCP servers connected for this session (the enabled `mcp.json` set). */
+  connectedMcps?: string[];
 }
 
 /*

package/prompt/testomatio.ts

@@ -35,7 +35,7 @@ const tmsViaDirectTools = dedent`
   | Runs, testruns, plans, labels, issues, analytics | MCP \`testomatio-*\` tools |
   | Creating/updating tests or suites | edit the markdown file, then \`npx check-tests push\` |
   | Creating/updating runs, linking issues | MCP create/update tools |
-  | Launching automated or mixed Run remotely on CI | Use npx @testomatio/reporter run --remote <profile>, raise error if no CI profiles configured
+  | Launching automated or mixed Run remotely on CI | Use npx -y @testomatio/reporter@latest run --remote <profile>, raise error if no CI profiles configured
   | Running automated Run | Use local test runner with testomatio reporter attached to report to current project
 
   ---
@@ -73,7 +73,7 @@ const tmsViaProxy = dedent`
   | Runs, testruns, plans, labels, issues, analytics | \`mcp({ search: … })\`, then \`mcp({ tool: … })\` |
   | Creating/updating tests or suites | edit the markdown file, then \`npx check-tests push\` |
   | Creating/updating runs, linking issues | the matching \`mcp\` create/update operation |
-  | Launching automated or mixed Run remotely on CI | Use npx @testomatio/reporter run --remote <profile>, raise error if no CI profiles configured |
+  | Launching automated or mixed Run remotely on CI | Use npx -y @testomatio/reporter@latest run --remote <profile>, raise error if no CI profiles configured |
   | Running automated Run | Use local test runner with testomatio reporter attached to report to current project |
 
   ---
@@ -106,7 +106,7 @@ const tmsViaCli = dedent`
   | Suite hierarchy / structure / which files exist | \`ls\` / \`find\` |
   | Runs, testruns, plans, labels, issues, analytics | \`curl\` against \`/api/v2\` |
   | Creating/updating tests or suites | edit the markdown file, then \`npx check-tests push\` |
-  | Launching automated or mixed Run remotely on CI | Use npx @testomatio/reporter run --remote <profile>, raise error if no CI profiles configured |
+  | Launching automated or mixed Run remotely on CI | Use npx -y @testomatio/reporter@latest run --remote <profile>, raise error if no CI profiles configured |
   | Running automated Run | Use local test runner with testomatio reporter attached to report to current project |
 
   ---

package/prompt/tools.ts

@@ -11,11 +11,19 @@ import dedent from 'dedent';
  */
 export function tools(options?: { extra?: string[] }): string {
   const extra = (options?.extra ?? []).join('');
-  let github = '    - GitHub: issues and projects through MCP.';
-  if (hasGh()) {
-    github +=
+  let routing = '    - GitHub: issues and projects through MCP.';
+  if (onPath('gh')) {
+    routing +=
       '\n    - Pull requests and repositories: `gh` in `bash`. When a PR question needs issue detail, query the issue through MCP — never infer it from a PR title.';
   }
+  if (onPath('acli')) {
+    routing +=
+      '\n    - Jira in bulk (many issues at once), boards, sprints and filters: `acli` in `bash`, per the `atlassian` skill. Confluence and attachments have no `acli` command and stay on MCP.';
+  }
+  if (onPath('glab')) {
+    routing +=
+      '\n    - GitLab releases, labels, milestones, snippets, CI artifacts, and any endpoint with no MCP tool: `glab` in `bash`. Issues, merge requests, pipelines and code search stay on MCP, which covers them well.';
+  }
   return dedent`
 <available-tools>
   You have these tools available:
@@ -27,7 +35,7 @@ ${extra}  * **Internal Skills:** For QA-related tasks, check available skills fi
   * **External Integrations:** Use MCP tools when they provide superior data or specialized integrations.
     - Primary MCP (Testomat.io): Use Testomat.io MCP tools to extend functionality.
     - Secondary MCP (Jira, GitHub, etc.): Invoke only when user explicitly asks or when remote context exploration is required.
-${github}
+${routing}
 
   <tool-governance>
     * **Prioritize Specificity:** Use \`read\` instead of \`cat\`, and \`edit\` instead of \`sed\`. Dedicated tools provide better error tracking and safety.
@@ -39,11 +47,26 @@ ${github}
 `;
 }
 
-/** Is the `gh` CLI on PATH? Never tell the agent to use a binary this machine lacks. */
-function hasGh(): boolean {
+/** Is this CLI on PATH? Never tell the agent to use a binary this machine lacks. */
+function onPath(bin: string): boolean {
   for (const dir of (process.env.PATH ?? '').split(delimiter)) {
     if (!dir) continue;
-    if (existsSync(join(dir, 'gh')) || existsSync(join(dir, 'gh.exe'))) return true;
+    if (existsSync(join(dir, bin)) || existsSync(join(dir, `${bin}.exe`))) return true;
   }
   return false;
 }
+
+/**
+ * CLIs Testeiya knows how to connect, probed on PATH — the same trio routed in
+ * `<available-tools>` above. Shared with the prompt's connections section so
+ * the two can never disagree about whether `gh` etc. exist.
+ */
+export const KNOWN_CLIS: { bin: string; label: string }[] = [
+  { bin: 'gh', label: 'gh (GitHub CLI)' },
+  { bin: 'acli', label: 'acli (Atlassian CLI)' },
+  { bin: 'glab', label: 'glab (GitLab CLI)' },
+];
+
+export function pathClis(): string[] {
+  return KNOWN_CLIS.filter((c) => onPath(c.bin)).map((c) => c.label);
+}

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

@@ -0,0 +1,119 @@
+---
+name: ci-fix-tests
+description: "Use on CI in non-interactive mode after a failed CodeceptJS run — attempts safe fixes only (locator drift, missing waits), reruns failing scenarios, rolls back edits that didn't help, reports at `output/ci-fix.md`. No refactors, no config edits, no flake-masking. 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 a short locator scoped to a stable region — `I.click('Save', '.toolbar')` — in this order: visible text / accessible name → ARIA `{ role, name }` → `$name` (`customLocator`) → 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: `I.click('Save')` → `I.click('Save', '.toolbar')`
+- `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.
+
+## Related skills
+
+- `codeceptjs-run-analysis` — baseline, clustering, post-fix comparison
+- `codeceptjs-exploration` — replacement locators for drift
+- `codeceptjs-fundamentals` — config, helper, CI environment

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

@@ -0,0 +1,141 @@
+---
+name: codeceptjs-auth
+description: >
+  Use when a CodeceptJS test needs login, user roles, or session reuse — or
+  when another CodeceptJS skill identifies authorization is required. Also on
+  auth-related test failures. Trigger on login, sign-in, sign-up,
+  authentication, sessions, "logged in", admin/editor/user roles.
+---
+
+# CodeceptJS Auth Plugin
+
+The `auth` plugin logs each user in once, captures cookies (or localStorage/token via overrides), and restores the session for subsequent tests. Stale sessions trigger a fresh login automatically.
+
+If the project already has `auth` configured (fundamentals' discovery output), **reuse** its existing inject name and user keys — don't reconfigure.
+
+## Decide first — ask the user
+
+Four answers shape the plugin. Don't guess any.
+
+1. **Is a session needed at all?** Public flows (landing, signup) → skip the plugin.
+2. **One user or many?** Default one; add more only when actually exercised.
+3. **If many — what splits them?** Role, workspace/tenant, plan tier, sign-in provider, per-test fixture — real systems vary. Ask; use the answer to name `users.<key>` entries.
+4. **What's the auth type?**
+   - **Form** — default; canonical shape below
+   - **OAuth / SSO** — click provider button, drive the IdP page (often separate origin)
+   - **Magic link / passwordless** — UI flow rarely worth automating; prefer an API mint or reading the link from a test mailbox
+   - **API token** — skip the form; write the token into `localStorage` via `executeScript`, or `I.setCookie(...)`
+   - **2FA / OTP** — async `login`; fetch the code from a test mailbox / backdoor before submitting
+
+## Rules
+
+1. **Login flow never lives in the conf.** Put it in `steps_file.js` (if included) or a page object; conf only references it: `login: (I) => I.login()`.
+2. **Credentials from env only** — `.env` loaded via `process.loadEnvFile()` (no dotenv dependency). Passwords wrapped with `secret(...)`. No literals anywhere — conf, steps file, test, git history.
+3. **`.env` is gitignored; `.env.example` is committed** with names, no values. Gitignore `output/*_session.json` too.
+
+## Canonical shape
+
+```js
+// codecept.conf.js — first line of the file
+process.loadEnvFile()
+
+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')
+    },
+  })
+}
+```
+
+```sh
+# .env (gitignored)        # .env.example (committed)
+USER_EMAIL=...             USER_EMAIL=
+USER_PASSWORD=<secret>     USER_PASSWORD=
+```
+
+## Pre-flight (before writing config)
+
+1. **Read the real login page** — MCP `run_code` to `/login`, inspect the ARIA snapshot (`codeceptjs-exploration`). Field labels / `name` / `id` / submit control from the actual page, not guesses. Unclear authorization mechanism → ask the user.
+2. **Pick a role-specific post-login marker** — something rendered only for *this* user (navbar username, `data-user-role`).
+3. **Confirm session storage** — cookies (default) for server-rendered apps; localStorage/sessionStorage for SPAs. Verify after a manual login with `I.executeScript(() => Object.keys(localStorage))`. Cookie fetch/restore silently no-op against token storage.
+
+## Verify
+
+Run a one-Scenario file that calls `login(<role>)` then asserts on the post-login marker:
+
+```bash
+npx codeceptjs run --grep '<scenario>' --debug    # real run, not dry — dry-run doesn't init plugins
+```
+
+Enable `saveToFile: true` only after this round-trip succeeds — a bad saved session masks a broken `login`.
+
+Then wire into hooks/tests: `Before(({ login }) => login())` for suite-wide, or per-test as needed.
+
+## Multi-role shape
+
+Only after question 3 is answered. Keys named after whatever splits users *in this system*; one matching actor method per key:
+
+```js
+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, explicit methods read better. Switch mid-Scenario: `session('<key>')` opens a parallel browser context (fundamentals § Writing tests).
+
+## Token / localStorage auth
+
+Override `fetch` / `restore` when sessions live outside cookies:
+
+```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 fresh login (e.g. `/me` endpoint shows wrong user).
+
+## Pitfalls
+
+- Credentials inlined in conf/test — always env-driven + `secret()`.
+- Forgetting to gitignore `.env` and `output/*_session.json` — both leak credentials.
+
+## Related skills
+
+- `codeceptjs-fundamentals` — secrets rule, sessions, config mutation trap
+- `codeceptjs-exploration` — reading the live login page
+- `writing-codeceptjs-tests` / `refactoring-codeceptjs-tests` — invoke this skill when auth is identified
+- `debugging-codeceptjs-tests` — auth-related failure patterns

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

@@ -0,0 +1,100 @@
+---
+name: codeceptjs-exploration
+description: >
+  Use when an agent needs to learn what's on a page in CodeceptJS — read the
+  ARIA tree, inspect candidate elements, pick or disambiguate a stable locator.
+  Drives the live browser via MCP `run_code` / `snapshot`. Invoked by
+  writing-codeceptjs-tests, debugging-codeceptjs-tests, and
+  refactoring-codeceptjs-tests whenever page inspection is needed.
+---
+
+# CodeceptJS Page Exploration
+
+Authoring a test, debugging a failure, and refactoring a stale locator share one task: open a page, find the right element, pick a stable locator. This is that playbook.
+
+## Tools
+
+- **`run_code`** — runs CodeceptJS code, returns produced values, captures `console.*`, saves a final-state snapshot. For *do something and look at the result*.
+- **`snapshot`** — captures state without acting (URL, cookies, localStorage, HTML, ARIA, screenshot, console). For "what's on the page right now".
+
+Artifact sources, in preference order:
+
+1. **ARIA snapshot** — structured, no styling noise, easy duplicate/accessibility-name scanning
+2. **Screenshot** — visual confirmation; catches layout breaks ARIA can't show
+3. **HTML** — only when ARIA lacks context (custom widgets without accessible names, attribute-driven behaviour)
+
+## Inspect an element
+
+`I.grabWebElement(locator)` → one WebElement; `I.grabWebElements(locator)` → array. Same cross-helper API on Playwright / Puppeteer / WebDriver.
+
+| You want to … | Method |
+|---|---|
+| Confirm rendered / visible / enabled | `exists()`, `isVisible()`, `isEnabled()` |
+| Read text / value / attribute / property | `getText()`, `getValue()`, `getAttribute(n)`, `getProperty(n)` |
+| Position on page | `getBoundingBox()` — flags offscreen / zero-sized |
+| Rendered markup | `toOuterHTML()`, `toSimplifiedHTML(300)` (truncated, MCP-friendly) |
+| Stable selector for a fix | `toAbsoluteXPath()` |
+| Inside an iframe | `inIframe(async (body) => { ... })` |
+| Drill into children | `$(loc)`, `$$(loc)` |
+| Browser-side function | `evaluate(fn, ...args)` |
+
+## Discover candidates when the obvious locator misses
+
+When `Edit` matches nothing, the control may say "Change", carry `aria-label="Edit user"`, or live in `.btn-edit`. Cast a wide net with a permissive XPath via `I.grabWebElements`, then disambiguate.
+
+OR together in the XPath:
+
+- visible text — `text()` (or `.` for descendants)
+- attributes — `@class`, `@aria-label`, `@title`, `@data-action`, `@id`
+- **synonyms** — edit/change/modify; delete/remove/trash; submit/send/save
+
+Case-insensitive via `translate(...)`:
+
+```
+//*[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 results, pick the right candidate, commit a stable locator from its discriminating attribute or text.
+
+## Pick a stable locator
+
+Two decisions in order: **which region scopes the lookup** (context), **what identifies the element inside it**. Region first keeps the identifier short and semantic — the discriminator found during disambiguation belongs in the context argument:
+
+```js
+I.click('Edit user', '.user-row')      // ✅ region + what the user sees
+I.click('#user-row-42 button.edit')    // ❌ same element, brittle, unreadable
+```
+
+Stable regions: landmarks (`nav`, `main`, `{ role: 'dialog' }`), app-shell containers (`.sidebar`, `.toolbar`, `.modal`), rows/cards identified by data via `locate(...)`. Identifier priority (full rationale: `codeceptjs-fundamentals` § Locators):
+
+1. Visible label / accessible name — plain string already matches `aria-label`; don't expand to `{ css: '[aria-label="..."]' }`
+2. ARIA role when ambiguous within context or role is part of the check
+3. `$name` via `customLocator` when team test attributes exist
+4. Composed CSS, still scoped: `I.click('button.edit', '#user-row-42')`
+5. `toAbsoluteXPath()` — last resort; flag the team to add a `data-testid`
+
+**Never commit an unverified locator** — confirm via `run_code` (`I.seeElement(loc, context)` or `grabWebElement(loc)`) that it matches exactly one element.
+
+## Common patterns
+
+- Strict mode 2+ matches → `grabWebElements('Save')` + `toSimplifiedHTML(200)` each, find discriminator, pass as context: `I.click('Save', '.modal')`
+- Button rendered but doesn't act → `grabWebElement('Submit')` + `isEnabled()` + `getBoundingBox()` — disabled? offscreen? zero-sized?
+- Wrong row in a list → `grabWebElements('.user-row')`, `getText()` per row to identify, `getAttribute('data-id')` for stable hook
+- Inside iframe → `(await I.grabWebElement('iframe.editor')).inIframe(async (body) => body.$('button'))`
+
+## Things to avoid
+
+- Choosing a locator without seeing candidates first.
+- Committing `toAbsoluteXPath()` when a semantic locator is available.
+- Committing unscoped locators where a context keeps them short.
+- Ignoring the screenshot — "exists in HTML" ≠ "user can see it".
+- `usePlaywrightTo` / `useWebDriverTo` when WebElement methods cover it.
+
+## Related skills
+
+- `codeceptjs-fundamentals` — locator priority, await rule
+- `writing-codeceptjs-tests` — invokes this during Mode B exploration
+- `debugging-codeceptjs-tests` — invokes this for live inspection; offline variant via `codeceptq`