qa-engineer 0.10.0 → 0.12.0

package/skills/qa-run/references/playwright-execution.md

@@ -20,10 +20,23 @@ Start from the package-manager invocation (`pnpm exec playwright test`, `npx pla
 | Scope — project or browser | `--project=<name>` |
 | Display | `--headed` only on explicit request; headless is the default (no flag) |
 | Evidence — trace | `--trace=on-first-retry` by default, `on` when the strategy asks |
-| Evidence — video / screenshot | `--video` and `--screenshot` at the strategy's level |
+| Evidence — screenshot | `--screenshot=only-on-failure` always, `on` when the strategy asks |
+| Evidence — video | `--video=retain-on-failure` always, `on` when the strategy asks |
 
 The full command is recorded verbatim. Secrets are never interpolated; environment variables are referenced by name and resolved at run time (see the environment-detection module).
 
+### The failure floor in Playwright flags
+
+The last three rows are the shared failure evidence floor (see the command-builder module) expressed in Playwright's own flags, and they are written on every command — including a one-spec run and a smoke run:
+
+```text
+--screenshot=only-on-failure --video=retain-on-failure --trace=on-first-retry
+```
+
+- **`--screenshot=off`, `--video=off`, and `--trace=off` are never built.** Playwright's own defaults are `off`, and a project config may set `off` explicitly; the flags are passed anyway because a CLI flag overrides `use.screenshot` / `use.video` / `use.trace` in the config, which is exactly the point.
+- **Retries interact with the floor.** `--trace=on-first-retry` produces a trace only when a retry happens, so a run with `--retries=0` fails without one. When a diagnosis needs the trace of a first, un-retried failure, the strategy raises tracing to `--trace=retain-on-failure` rather than lowering the floor.
+- **The cost is paid only by failures.** `only-on-failure` and `retain-on-failure` write nothing for a passing test — a green run produces the same artifacts it always did, which is why the floor does not need a fast-mode exemption.
+
 ## Launch and run
 
 The agent runs the built command through its shell, under the run's wall-clock timeout, following the browser lifecycle: headless by default, bounded test-level retries via `--retries` to observe flakiness, cleanup on every exit path, and honest handling of a hang or crash as `errored` rather than as a test failure.

package/skills/qa-run/scripts/qa-tool.mjs

@@ -29,6 +29,7 @@
 // `node qa-tool.mjs …`, which needs none.
 
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -38,7 +39,7 @@ const here = path.dirname(fileURLToPath(import.meta.url));
 const USAGE = `usage: node qa-tool.mjs <tool> <subcommand> [args]
 
   analysis     parse artifacts, classify errors, validate contracts, diff-guard,
-               read .qa/context.md, render an HTML report, print the footer
+              read .qa/context.md, render an HTML report, print the footer
   diagnostics  root cause, timeline, priority, repair plans, release readiness
   playwright   normalize a Playwright report or summarize a trace
 
@@ -53,15 +54,26 @@ examples:
 /**
  * Where the engine is, and how we found it.
  *
- * Ordered by cost: a bundled copy needs no resolution and no network, a
- * node_modules copy needs no network, and npx needs both on first use. Reporting
- * *which* one answered matters when a skill degrades — "the engine is missing" and
- * "the engine is being fetched" are different problems.
+ * Ordered by cost: a bundled copy needs no resolution and no network, a shared copy
+ * needs one stat per ancestor, a node_modules copy needs no network, and npx needs both
+ * on first use. Reporting *which* one answered matters when a skill degrades — "the
+ * engine is missing" and "the engine is being fetched" are different problems.
+ *
+ * The shared lookup is what lets one skill directory serve a project, a workspace, and a
+ * machine-wide install without knowing which installed it. Walking up for
+ * `.qa-engineer/engine` finds a workspace install from a skill inside the repository,
+ * and finds a global install from a skill linked into an agent's user-level directory —
+ * `~/.claude/skills/qa-explore` walks up to `~`, where `~/.qa-engineer/engine` is.
  */
 function resolveEngine() {
   const bundled = path.join(here, 'lib', 'bin', 'qa-engine.mjs');
   if (fs.existsSync(bundled)) return { kind: 'bundled', command: [process.execPath, bundled] };
 
+  for (const root of candidateSharedRoots()) {
+    const shared = path.join(root, 'bin', 'qa-engine.mjs');
+    if (fs.existsSync(shared)) return { kind: 'shared', command: [process.execPath, shared] };
+  }
+
   for (const base of candidateModuleRoots()) {
     const installed = path.join(base, 'qa-engineer', 'packages', 'engine', 'bin', 'qa-engine.mjs');
     if (fs.existsSync(installed)) {
@@ -75,6 +87,30 @@ function resolveEngine() {
   };
 }
 
+/** Shared engine directories worth checking, most specific first. */
+function candidateSharedRoots() {
+  const roots = [];
+
+  // An explicit home wins over anything discovered, so a user who moved the install can
+  // rely on it rather than on whatever the walk happens to find first.
+  const override = process.env.QA_ENGINEER_HOME;
+  if (override && override.trim()) roots.push(path.join(path.resolve(override.trim()), 'engine'));
+
+  let dir = here;
+  for (let depth = 0; depth < 12; depth += 1) {
+    roots.push(path.join(dir, '.qa-engineer', 'engine'));
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // The default machine home, for the case where the skill lives outside it entirely.
+  const home = os.homedir();
+  if (home) roots.push(path.join(home, '.qa-engineer', 'engine'));
+
+  return roots;
+}
+
 /** node_modules directories worth checking, nearest first. */
 function candidateModuleRoots() {
   const roots = [];