@delt/tester-mcp 0.1.0

package/dist/secrets/resolveSecrets.d.ts

@@ -0,0 +1,5 @@
+export interface ResolveOpts {
+    secrets?: Record<string, unknown>;
+    env?: Record<string, string | undefined>;
+}
+export declare function resolveSecrets(value: string, opts?: ResolveOpts): string;

package/dist/secrets/resolveSecrets.js

@@ -0,0 +1,16 @@
+// ${secrets.a.b} → secrets file (nested) first, else env SECRET_A_B; throw if missing.
+export function resolveSecrets(value, opts = {}) {
+    const env = opts.env ?? process.env;
+    return value.replace(/\$\{secrets\.([\w.]+)\}/g, (_m, path) => {
+        const fromFile = path
+            .split(".")
+            .reduce((o, k) => (o == null ? undefined : o[k]), opts.secrets);
+        if (typeof fromFile === "string")
+            return fromFile;
+        const key = "SECRET_" + path.replace(/\./g, "_").toUpperCase();
+        const v = env[key];
+        if (v === undefined)
+            throw new Error(`시크릿 누락: ${path} (tester-mcp.secrets.yaml 의 ${path} 또는 env ${key})`);
+        return String(v);
+    });
+}

package/dist/util/runId.d.ts

@@ -0,0 +1 @@
+export declare function makeRunId(now?: Date): string;

package/dist/util/runId.js

@@ -0,0 +1,3 @@
+export function makeRunId(now = new Date()) {
+    return now.toISOString().replace(/\..+$/, "").replace(/:/g, "-");
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@delt/tester-mcp",
+  "version": "0.1.0",
+  "description": "Opus(planner) + Haiku(executor) + Chrome 통합 테스트 오케스트레이터",
+  "type": "module",
+  "bin": { "tester-mcp": "bin/tester-mcp.js" },
+  "files": ["dist", "bin", "skills"],
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run"
+  },
+  "engines": { "node": ">=20" },
+  "dependencies": { "commander": "^12.1.0", "yaml": "^2.5.0" },
+  "devDependencies": {
+    "typescript": "^5.5.0", "tsx": "^4.16.0", "vitest": "^2.0.0", "@types/node": "^20.14.0"
+  }
+}

package/skills/tester-mcp/SKILL.md

@@ -0,0 +1,29 @@
+---
+description: Run browser screen E2E tests. Use when the user asks to test a web screen or flow, verify a login or form, or check a UI after a change. Writes a scenario YAML, runs the tester-mcp CLI to drive a claude-in-chrome executor, and reports PASS / PARTIAL / FAIL / NOT_TESTED.
+allowed-tools: Bash(tester-mcp *) Read Write Edit Glob Grep
+---
+
+# tester-mcp — Screen E2E testing
+
+Current CLI usage (always up to date):
+
+!`tester-mcp --help`
+
+> Prerequisites and the full scenario DSL (single source of truth): run `tester-mcp document-guide`.
+
+## Workflow (document first)
+
+1. **Write the scenario** — `scenarios/<area>/<id>.yaml`. **Resolve a stable `css` or `role` selector from the Vue/PrimeVue source and put it in the `target`** — don't rely on the executor to find elements by natural language (it tries once, then bails NOT_TESTED). `description`/`text` are last-resort fallbacks. Pin the language with `locale:`, reference secrets as `${secrets...}`. Full schema: `tester-mcp document-guide`.
+2. **Run** — `tester-mcp run <scenarios...> -c <config>`. The CLI spawns the executor(s) and waits. Pass multiple scenarios (files or a directory) to run them in parallel; `--concurrency <1-10>` caps how many run at once (default `min(count, 10)`). Each executor creates its OWN browser tab (via tabs_create), so they run truly in parallel (~2-3× at 4-way). They still share one Chrome, so heavy scenarios contend somewhat — keep concurrency modest for heavy flows.
+3. **Branch on the result label**:
+   - PASS / PARTIAL → report the evidence and screenshots.
+   - FAIL → present the contradicting evidence, screenshots, and `handoff_notes`, then move into a fix.
+   - NOT_TESTED → give the reason plus `pattern_inference` (assumed_ok/unknown); state the missing precondition, or hand off to a human after repeated failure. Read the result's executor_log (full tool trail) to diagnose, then fix the scenario's selectors.
+
+## Secrets
+
+The test account lives in the gitignored `tester-mcp.secrets.yaml` (or env `SECRET_*` in CI); reference it as `${secrets.tester.username}`. If it is missing, tell the user to fill it in. Details: `tester-mcp document-guide`.
+
+## Discipline
+
+Grep for references to any changed symbol and check runtime dependencies (storage, store, API params). Separate proof from inference — report "verified X, inferred Y by the same pattern", never absolute claims.

package/skills/tester-mcp/document-guide.md

@@ -0,0 +1,146 @@
+# tester-mcp — Authoring Guide
+
+This guide is printed by `tester-mcp document-guide`. It is the single source of
+truth for prerequisites and the scenario DSL. Read it before writing scenarios.
+
+## Prerequisites
+
+- Node.js >= 20.
+- The `claude` CLI must be installed and **logged in** (the executor runs
+  `claude -p --chrome`).
+- The claude-in-chrome browser extension must be installed and connected. The
+  executor drives a **real, visible Chrome window** — it is NOT headless and it
+  keeps cookies/session. Chrome/Edge only.
+- On **Windows**, the `--chrome` flag is required for claude-in-chrome to work in
+  PowerShell. **WSL is not supported.**
+- Run `tester-mcp init` once per project to install the skill and scaffold
+  `tester-mcp.config.yaml` plus a secrets example.
+
+## Running
+
+```
+tester-mcp run scenarios/<area>/<id>.yaml -c tester-mcp.config.yaml
+```
+
+The CLI spawns the executor, waits, and writes a result to `runs/<runId>/`.
+A hard timeout (default 5 min, `runner.timeout_ms` or `--timeout`) kills a stuck
+executor and reports NOT_TESTED.
+
+### Running multiple scenarios in parallel
+
+Pass several scenario files (or a directory) to run them concurrently — each
+scenario gets its own executor process and creates its OWN browser tab (via
+tabs_create) inside the shared Chrome tab group, so they run in parallel
+(~2-3× at 4-way; one Chrome still serializes part of the work, so expect some
+contention and varied finish times, not a clean N×):
+
+```
+tester-mcp run scenarios/a.yaml scenarios/b.yaml --concurrency 3 -c tester-mcp.config.yaml
+tester-mcp run scenarios/auth/ --concurrency 5 -c tester-mcp.config.yaml
+```
+
+- `--concurrency <1-10>`: how many run at once (default `min(count, 10)`, hard cap 10).
+- Each scenario writes its own `runs/<runId>/<id>.json` + `.log`.
+- Logins are per-tab isolated (auth in sessionStorage), so concurrent logins are safe.
+- But `localStorage` (e.g. `languageType`) is shared across tabs — keep parallel scenarios on the **same locale**, or run different locales serially.
+- Slow scenarios under contention may exceed the timeout — raise `--timeout` (e.g. 240000–300000) for parallel batches.
+- Each scenario `id` must be unique across the batch (results/logs are keyed by `id`).
+
+## Scenario file
+
+A scenario is one YAML file. Fields:
+
+- `id` (string, required) — stable identifier, used in the result filename.
+- `title` (string, required) — human-readable summary.
+- `steps` (list, required) — ordered actions (see below).
+- `locale` (string, optional) — pins UI language: `kg` (Kyrgyz), `ru` (Russian),
+  `kr` (Korean). The executor switches the app to this language first.
+- `login_as` (string, optional) — named login to perform before the steps.
+- `on_failure` (string, optional) — `stop` (default) or `continue`.
+- `optional` (bool, optional) — if true, a FAIL is downgraded to a soft signal.
+- `defaults` (map, optional) — default values reused across steps.
+- `precondition` (string, optional) — human note on required data/state.
+
+## Actions (each item in `steps`)
+
+- `navigate` — `{ action: navigate, url: "/path" }` (relative to `targets.frontend`).
+- `fill` — `{ action: fill, target: <target>, value: "..." }`.
+- `click` — `{ action: click, target: <target> }`.
+- `wait_for` — `{ action: wait_for, target: <target> }`.
+- `assert_visible` — `{ action: assert_visible, target: <target> }`.
+- `screenshot` — `{ action: screenshot, name: "after-login" }`.
+
+## Target (how to locate an element)
+
+`target` is a multi-strategy object. Provide one or more; the executor tries them
+in order of specificity. There is no testid in this project, so prefer stable
+attributes and visible text.
+
+- `css` — CSS selector.
+- `placeholder` — input placeholder text.
+- `label` — associated label text.
+- `text` — visible text content.
+- `role` — ARIA role (e.g. `button`).
+- `description` — natural-language fallback ("the blue Login button").
+
+Example:
+```yaml
+target:
+  placeholder: "Username"
+  description: "the username input on the login form"
+```
+
+**Authoring rule (selector-first).** Resolve a stable `css` or `role`+name from the
+component source (Vue/PrimeVue) and put it in the target. `description`/`text` are
+last-resort fallbacks, not the primary strategy. The executor tries the target's
+strategies **once** and does NOT grope the page — on a first-attempt miss it bails
+with NOT_TESTED and reports what it actually saw. A precise selector is what drives
+pass rate and speed. For multi-step UI (filters, dropdowns, modals), script the
+open→select sequence as explicit steps with `wait_for` between them.
+
+## Secrets
+
+Never inline credentials. Reference them as `${secrets.a.b}`:
+```yaml
+- { action: fill, target: { placeholder: "Username" }, value: "${secrets.tester.username}" }
+- { action: fill, target: { placeholder: "Password" }, value: "${secrets.tester.password}" }
+```
+Resolution order: the file `tester-mcp.secrets.yaml` (gitignored) first, then the
+environment variable `SECRET_A_B` (uppercased, dot → underscore). Secret values
+are redacted to `***` in stored results.
+
+## Ephemeral UI (toasts, snackbars)
+
+Short-lived elements (e.g. PrimeVue toast, `life:3000`) vanish faster than tool
+round-trips. To verify them reliably:
+- Set `ephemeral: true` on the scenario.
+- Assert immediately after the trigger with ONE fast text/DOM check — do NOT chain
+  fallbacks (JS → find → read_page); the element disappears mid-chain.
+- Do NOT add a `screenshot` step for an ephemeral element — the assertion IS the
+  proof, and a screenshot of a vanished element causes retry loops.
+- (Optional) In a test build, raise the toast `life` so it stays long enough.
+
+## Result labels
+
+- `PASS` — every assertion verified at runtime.
+- `PARTIAL` — some verified, some not (each item carries proof or reason).
+- `FAIL` — an assertion was contradicted at runtime.
+- `NOT_TESTED` — could not run (timeout, missing data, blocked prerequisite).
+
+On NOT_TESTED, read the run's `executor_log` (path is in the result JSON) to see the
+tool sequence and errors — that's how the Planner diagnoses and fixes the scenario.
+
+## Minimal example
+
+```yaml
+id: login-success
+title: Login with valid credentials reaches the dashboard
+locale: ru
+steps:
+  - { action: navigate, url: "/" }
+  - { action: fill, target: { placeholder: "Username" }, value: "${secrets.tester.username}" }
+  - { action: fill, target: { placeholder: "Password" }, value: "${secrets.tester.password}" }
+  - { action: click, target: { text: "Login", role: "button" } }
+  - { action: assert_visible, target: { description: "the main dashboard after login" } }
+  - { action: screenshot, name: "dashboard" }
+```