@selfcure/runner 0.1.0

package/README.md

@@ -0,0 +1,17 @@
+# @selfcure/runner
+
+> Playwright execution layer for **selfcure** — runs tests programmatically and captures traces on failure.
+
+Part of selfcure's **legacy BYOK pipeline**. Wraps the `@playwright/test` programmatic API to execute generated specs and capture traces/errors for the self-healing loop.
+
+Internal library powering `selfcure run`. The headline, preventive flow is `selfcure lint` — see [`@selfcure/cli`](https://www.npmjs.com/package/@selfcure/cli).
+
+## Install
+
+```bash
+npm install @selfcure/runner
+```
+
+## Docs
+
+Full documentation: https://github.com/ricardofrancocustodio/selfcure#readme

package/dist/index.d.ts

@@ -0,0 +1,133 @@
+import { WcagLevel, AccessibilityFinding, A11ySeverity } from '@selfcure/analyzer';
+
+interface DynamicScanRoute {
+    /** Relative route path, e.g. "/" or "/checkout/summary" */
+    path: string;
+    /** Optional: Playwright storage-state JSON path for pre-authenticated sessions */
+    storageState?: string;
+    /** Wait condition after navigation — default: 'networkidle' */
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
+}
+interface DynamicScanOptions {
+    /** Base URL of the running app, e.g. "http://localhost:3000" */
+    baseURL: string;
+    /** Routes to scan — defaults to [{path: '/'}] */
+    routes?: DynamicScanRoute[] | string[];
+    /** WCAG level to check — default 'AA' */
+    level?: WcagLevel;
+    /** Page navigation timeout ms — default 30000 */
+    timeout?: number;
+    /** Run browser without UI — default true */
+    headless?: boolean;
+    /**
+     * URL or local path to axe-core script.
+     * Defaults to the axe-core CDN. For offline use, point to
+     * node_modules/axe-core/axe.min.js or a local copy.
+     */
+    axeSource?: string;
+}
+interface DynamicScanResult {
+    findings: AccessibilityFinding[];
+    scannedRoutes: number;
+    errors: Array<{
+        route: string;
+        error: string;
+    }>;
+}
+/** Extract WCAG criterion numbers like "4.1.2" from axe tags like "wcag412". */
+declare function wcagRefsFromTags(tags: string[]): string[];
+/** Map axe impact string to our A11ySeverity. */
+declare function impactToSeverity(impact: string | null): A11ySeverity;
+/** Derive the highest applicable WCAG level from axe tags. */
+declare function levelFromTags(tags: string[]): WcagLevel;
+/**
+ * Launch a Playwright browser, navigate to each configured route, inject
+ * axe-core, run WCAG checks, and return findings mapped to AccessibilityFinding[].
+ *
+ * Requires Playwright browsers to be installed (`npx playwright install`).
+ * Requires the target app to be running and accessible at baseURL.
+ */
+declare function runDynamicScan(opts: DynamicScanOptions): Promise<DynamicScanResult>;
+
+interface RuntimeElement {
+    tag: string;
+    role?: string;
+    /** Accessible name — aria-label or visible text */
+    name?: string;
+    /** Best selector available */
+    selector: string;
+    testId?: string;
+    /** Testability score 0–100 */
+    score: number;
+}
+interface RuntimeRouteEvidence {
+    url: string;
+    route: string;
+    status: 'reachable' | 'error' | 'timeout' | 'auth-required';
+    title?: string;
+    domSnapshotPath?: string;
+    accessibilityTreePath?: string;
+    screenshotPath?: string;
+    interactiveElements: RuntimeElement[];
+    consoleErrors: string[];
+    loadTimeMs: number;
+}
+interface RuntimeDiscoveryOptions {
+    baseURL: string;
+    routes: string[];
+    outDir: string;
+    timeout?: number;
+    headless?: boolean;
+    storageState?: string;
+    screenshots?: boolean;
+}
+interface RuntimeDiscoveryResult {
+    routes: RuntimeRouteEvidence[];
+    scannedRoutes: number;
+    reachable: number;
+    errored: number;
+}
+/** Compute a testability score for a single element from its attributes. */
+declare function scoreElement(opts: {
+    testId?: string;
+    id?: string;
+    name?: string;
+    type?: string;
+    tag: string;
+}): number;
+/** Build the best CSS selector for an element from its attributes. */
+declare function buildRuntimeSelector(opts: {
+    testId?: string;
+    id?: string;
+    name?: string;
+    tag: string;
+}): string;
+/**
+ * Launch Playwright, visit each route, and capture runtime evidence.
+ * Requires the app to be running at `baseURL`.
+ */
+declare function runRuntimeDiscovery(opts: RuntimeDiscoveryOptions): Promise<RuntimeDiscoveryResult>;
+
+interface RunOptions {
+    /** Absolute path to playwright.config.ts */
+    playwrightConfig: string;
+    /** Subset of test files to run; omit to run all */
+    testFiles?: string[];
+    /** Base URL forwarded to Playwright via env */
+    baseURL?: string;
+}
+interface TestResult {
+    filePath: string;
+    passed: boolean;
+    error?: string;
+    /** Absolute path to the .zip trace if Playwright captured one */
+    tracePath?: string;
+    durationMs: number;
+}
+/**
+ * Execute Playwright tests via the CLI and parse the JSON reporter output.
+ * Always enables `--trace on-first-retry` so healer has trace data on failure.
+ */
+declare function run(options: RunOptions): Promise<TestResult[]>;
+
+export { type DynamicScanOptions, type DynamicScanResult, type DynamicScanRoute, type RunOptions, type RuntimeDiscoveryOptions, type RuntimeDiscoveryResult, type RuntimeElement, type RuntimeRouteEvidence, type TestResult, buildRuntimeSelector, run as default, impactToSeverity, levelFromTags, run, runDynamicScan, runRuntimeDiscovery, scoreElement, wcagRefsFromTags };

package/dist/index.js

@@ -0,0 +1,367 @@
+// src/index.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+import path3 from "path";
+
+// src/a11y/dynamic.ts
+import { chromium } from "@playwright/test";
+import { readFile } from "fs/promises";
+import path from "path";
+var DEFAULT_AXE_CDN = "https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.10.2/axe.min.js";
+var WCAG_TAGS = {
+  A: ["wcag2a"],
+  AA: ["wcag2a", "wcag2aa"],
+  AAA: ["wcag2a", "wcag2aa", "wcag2aaa"]
+};
+var IMPACT_SEVERITY = {
+  critical: "critical",
+  serious: "major",
+  moderate: "minor",
+  minor: "info"
+};
+var _seq = 0;
+function makeFindingId() {
+  _seq++;
+  return `a11y_dyn_${Date.now().toString(36)}${_seq.toString(36).padStart(3, "0")}`;
+}
+function wcagRefsFromTags(tags) {
+  const refs = [];
+  for (const tag of tags) {
+    if (!/^wcag\d+$/.test(tag)) continue;
+    const d = tag.slice(4);
+    if (d.length === 3) refs.push(`${d[0]}.${d[1]}.${d[2]}`);
+    else if (d.length === 2) refs.push(`${d[0]}.${d[1]}`);
+    else refs.push(d);
+  }
+  return refs;
+}
+function impactToSeverity(impact) {
+  return IMPACT_SEVERITY[impact ?? ""] ?? "minor";
+}
+function levelFromTags(tags) {
+  if (tags.includes("wcag2aaa")) return "AAA";
+  if (tags.includes("wcag2aa")) return "AA";
+  return "A";
+}
+async function injectAxe(page, source) {
+  if (/^https?:\/\//.test(source)) {
+    await page.addScriptTag({ url: source });
+  } else {
+    const abs = path.resolve(source);
+    const content = await readFile(abs, "utf-8");
+    await page.addScriptTag({ content });
+  }
+}
+function mapViolations(violations, pageUrl, now) {
+  const findings = [];
+  for (const v of violations) {
+    const severity = impactToSeverity(v.impact);
+    const level = levelFromTags(v.tags);
+    const wcag = wcagRefsFromTags(v.tags);
+    const ruleId = `a11y-dynamic.${v.id}`;
+    for (let nodeIdx = 0; nodeIdx < v.nodes.length; nodeIdx++) {
+      const node = v.nodes[nodeIdx];
+      const selector = node.target.join(", ");
+      findings.push({
+        id: makeFindingId(),
+        ruleId,
+        wcag,
+        level,
+        severity,
+        status: "open",
+        sourceFile: pageUrl,
+        line: 0,
+        column: nodeIdx,
+        // used as finding-key differentiator per node
+        selector,
+        message: v.help,
+        remediation: node.failureSummary || v.description,
+        firstSeenAt: now,
+        lastSeenAt: now
+      });
+    }
+  }
+  return findings;
+}
+async function scanPage(page, url, level, source, timeout, waitUntil) {
+  await page.goto(url, { timeout, waitUntil });
+  await injectAxe(page, source);
+  const results = await page.evaluate((tags) => {
+    const g = globalThis;
+    return g.axe.run(g.document, { runOnly: { type: "tag", values: tags } });
+  }, WCAG_TAGS[level]);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return mapViolations(results.violations, url, now);
+}
+async function runDynamicScan(opts) {
+  const {
+    baseURL,
+    level = "AA",
+    timeout = 3e4,
+    headless = true,
+    axeSource = DEFAULT_AXE_CDN
+  } = opts;
+  const rawRoutes = opts.routes ?? ["/"];
+  const routes = rawRoutes.map(
+    (r) => typeof r === "string" ? { path: r } : r
+  );
+  const allFindings = [];
+  const errors = [];
+  const browser = await chromium.launch({ headless });
+  try {
+    for (const route of routes) {
+      const url = new URL(route.path, baseURL).toString();
+      const ctx = await browser.newContext(
+        route.storageState ? { storageState: route.storageState } : {}
+      );
+      const page = await ctx.newPage();
+      try {
+        const findings = await scanPage(
+          page,
+          url,
+          level,
+          axeSource,
+          timeout,
+          route.waitUntil ?? "networkidle"
+        );
+        allFindings.push(...findings);
+      } catch (err) {
+        errors.push({
+          route: url,
+          error: err instanceof Error ? err.message : String(err)
+        });
+      } finally {
+        await ctx.close();
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+  return { findings: allFindings, scannedRoutes: routes.length, errors };
+}
+
+// src/discovery/runtime.ts
+import { chromium as chromium2 } from "@playwright/test";
+import { writeFile, mkdir } from "fs/promises";
+import path2 from "path";
+function scoreElement(opts) {
+  if (opts.testId) return 100;
+  if (opts.id) return 85;
+  if (opts.name) return 75;
+  if (opts.type) return 50;
+  return opts.tag === "button" || opts.tag === "a" ? 30 : 20;
+}
+function buildRuntimeSelector(opts) {
+  if (opts.testId) return `[data-testid="${opts.testId}"]`;
+  if (opts.id) return `#${opts.id}`;
+  if (opts.name) return `[aria-label="${opts.name}"]`;
+  return opts.tag;
+}
+var DOM_SCAN_SELECTORS = [
+  "button",
+  "input:not([type=hidden])",
+  "select",
+  "textarea",
+  "a[href]",
+  "[role=button]",
+  "[role=link]",
+  "[role=textbox]",
+  "[role=checkbox]",
+  "[role=radio]",
+  "[role=combobox]"
+];
+async function extractElements(page) {
+  const raw = await page.evaluate((selectors) => {
+    const g = globalThis;
+    const doc = g.document;
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    for (const sel of selectors) {
+      for (const el of doc.querySelectorAll(sel)) {
+        if (seen.has(el)) continue;
+        seen.add(el);
+        const tag = el.tagName.toLowerCase();
+        const testId = el.getAttribute("data-testid") || void 0;
+        const id = el.id || void 0;
+        const aLabel = el.getAttribute("aria-label") || void 0;
+        const text = el.textContent?.trim().slice(0, 60) || void 0;
+        const type = el.getAttribute("type") || void 0;
+        const role = el.getAttribute("role") || void 0;
+        out.push({ tag, role, testId, id, name: aLabel || text, type });
+      }
+    }
+    return out;
+  }, DOM_SCAN_SELECTORS);
+  return raw.map((r) => {
+    const score = scoreElement(r);
+    const selector = buildRuntimeSelector(r);
+    const el = { tag: r.tag, selector, score };
+    if (r.role) el.role = r.role;
+    if (r.name) el.name = r.name;
+    if (r.testId) el.testId = r.testId;
+    return el;
+  });
+}
+function safeName(route) {
+  return route.replace(/^\//, "").replace(/[^a-z0-9]/gi, "-").replace(/-+/g, "-").slice(0, 48) || "root";
+}
+async function renderRoute(page, url, route, outDir, timeout, screenshots) {
+  const consoleErrors = [];
+  const onConsole = (msg) => {
+    if (msg.type() === "error") consoleErrors.push(msg.text());
+  };
+  page.on("console", onConsole);
+  const t0 = Date.now();
+  let status = "reachable";
+  let title;
+  try {
+    const response = await page.goto(url, { timeout, waitUntil: "networkidle" });
+    const httpStatus = response?.status() ?? 200;
+    if (httpStatus === 401 || httpStatus === 403) status = "auth-required";
+    title = await page.title().catch(() => void 0);
+  } catch (err) {
+    status = String(err).toLowerCase().includes("timeout") ? "timeout" : "error";
+  }
+  const loadTimeMs = Date.now() - t0;
+  let domSnapshotPath;
+  let accessibilityTreePath;
+  let screenshotPath;
+  let interactiveElements = [];
+  if (status === "reachable") {
+    const base = safeName(route);
+    const domDir = path2.join(outDir, "dom-snapshots");
+    await mkdir(domDir, { recursive: true });
+    const domFile = path2.join(domDir, `${base}.html`);
+    await writeFile(domFile, await page.content(), "utf-8");
+    domSnapshotPath = domFile;
+    const a11ySnapshot = await page.locator("body").ariaSnapshot().catch(() => null);
+    if (a11ySnapshot) {
+      const treeDir = path2.join(outDir, "accessibility-trees");
+      await mkdir(treeDir, { recursive: true });
+      const treeFile = path2.join(treeDir, `${base}.aria.txt`);
+      await writeFile(treeFile, a11ySnapshot, "utf-8");
+      accessibilityTreePath = treeFile;
+    }
+    if (screenshots) {
+      const ssDir = path2.join(outDir, "screenshots");
+      await mkdir(ssDir, { recursive: true });
+      const ssFile = path2.join(ssDir, `${base}.png`);
+      await page.screenshot({ path: ssFile, fullPage: true }).catch(() => {
+      });
+      screenshotPath = ssFile;
+    }
+    interactiveElements = await extractElements(page).catch(() => []);
+  }
+  page.off("console", onConsole);
+  return {
+    url,
+    route,
+    status,
+    title,
+    domSnapshotPath,
+    accessibilityTreePath,
+    screenshotPath,
+    interactiveElements,
+    consoleErrors,
+    loadTimeMs
+  };
+}
+async function runRuntimeDiscovery(opts) {
+  const {
+    baseURL,
+    routes,
+    outDir,
+    timeout = 3e4,
+    headless = true,
+    storageState,
+    screenshots = false
+  } = opts;
+  const browser = await chromium2.launch({ headless });
+  const results = [];
+  try {
+    for (const route of routes) {
+      const url = new URL(route, baseURL).toString();
+      const ctx = await browser.newContext(storageState ? { storageState } : {});
+      const pg = await ctx.newPage();
+      try {
+        const evidence = await renderRoute(pg, url, route, outDir, timeout, screenshots);
+        results.push(evidence);
+      } catch (err) {
+        results.push({
+          url,
+          route,
+          status: "error",
+          interactiveElements: [],
+          consoleErrors: [String(err)],
+          loadTimeMs: 0
+        });
+      } finally {
+        await ctx.close();
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+  return {
+    routes: results,
+    scannedRoutes: routes.length,
+    reachable: results.filter((r) => r.status === "reachable").length,
+    errored: results.filter((r) => r.status !== "reachable").length
+  };
+}
+
+// src/index.ts
+var execFileAsync = promisify(execFile);
+async function run(options) {
+  const args = [
+    "playwright",
+    "test",
+    "--reporter=json",
+    "--trace=on-first-retry",
+    `--config=${options.playwrightConfig}`,
+    ...options.testFiles ?? []
+  ];
+  const env = {
+    ...process.env,
+    ...options.baseURL ? { PLAYWRIGHT_BASE_URL: options.baseURL } : {}
+  };
+  const results = [];
+  try {
+    const { stdout } = await execFileAsync("npx", args, {
+      env,
+      cwd: path3.dirname(options.playwrightConfig)
+    });
+    const report = JSON.parse(stdout);
+    for (const suite of report.suites) {
+      for (const spec of suite.specs) {
+        const lastResult = spec.tests[0]?.results.at(-1);
+        results.push({
+          filePath: spec.file,
+          passed: spec.ok,
+          error: lastResult?.error?.message,
+          durationMs: lastResult?.duration ?? 0
+        });
+      }
+    }
+  } catch (err) {
+    results.push({
+      filePath: "<unknown>",
+      passed: false,
+      error: String(err),
+      durationMs: 0
+    });
+  }
+  return results;
+}
+var index_default = run;
+export {
+  buildRuntimeSelector,
+  index_default as default,
+  impactToSeverity,
+  levelFromTags,
+  run,
+  runDynamicScan,
+  runRuntimeDiscovery,
+  scoreElement,
+  wcagRefsFromTags
+};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@selfcure/runner",
+  "version": "0.1.0",
+  "description": "Executes Playwright tests programmatically and captures traces on failure",
+  "type": "module",
+  "license": "MIT",
+  "author": "ricardofrancocustodio",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ricardofrancocustodio/selfcure.git",
+    "directory": "packages/runner"
+  },
+  "homepage": "https://github.com/ricardofrancocustodio/selfcure#readme",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "test": "vitest"
+  },
+  "dependencies": {
+    "@playwright/test": "1.60.0"
+  }
+}