@tea-agent/loop-agent 0.44.0-next.10 → 0.44.0-next.12

package/dist/workflows/dag/frontend-test-framework-adapters.js

@@ -0,0 +1,309 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+/**
+ * Framework adapters decouple the frontend behavior-verification contract from
+ * any single test runner.
+ *
+ * The contract, writer admission and execution all need three things from a
+ * frozen verify command:
+ *   1. whether the runner can emit a machine-readable execution report at all
+ *      (capability), so an unsupported runner fails closed *before* implement;
+ *   2. how to ask that runner for a report without clobbering the project's
+ *      own reporter configuration;
+ *   3. how to read that report back as uniform file/title/status triples.
+ *
+ * Historically all three were hardcoded to Vitest (`vitest-json-v1`), while the
+ * command classifier was already framework-agnostic. Jest and Playwright
+ * commands were therefore classified into the behavior lane correctly and then
+ * rejected as "unsupported", surfacing a capability gap to the user as if they
+ * had misconfigured their project. Adapters make the two sources of truth agree.
+ */
+/** Report protocols a frozen behavior command may be observed through. */
+export const frontendTestReportSchemeSchema = z.enum([
+    "vitest-json-v1",
+    "jest-json-v1",
+    "playwright-json-v1",
+]);
+/** Runtime guard for a persisted scheme, e.g. read back from a trace artifact. */
+export const isFrontendTestReportScheme = (value) => typeof value === "string" &&
+    frontendTestReportSchemeSchema.options.includes(value);
+const asRecord = (value) => typeof value === "object" && value !== null
+    ? value
+    : undefined;
+/**
+ * Resolve a runner-relative path into contract workspace coordinates.
+ *
+ * A runner may report an absolute path (`config.rootDir` is absolute in a
+ * Playwright report) or one relative to its own root. Either way the result is
+ * expressed against `workspaceRoot`, which is resolved physically first: a
+ * workspace reached through a symlink (macOS `/var` -> `/private/var`, i.e. the
+ * default `os.tmpdir()`) is never a lexical prefix of the runner's canonical
+ * path, so comparing raw strings would yield a `../..` escape instead of a
+ * contract-relative file.
+ */
+const toWorkspacePath = (raw, cwd, workspaceRoot) => {
+    const absolute = path.resolve(cwd, raw);
+    const physical = (target) => {
+        try {
+            return realpathSync(target);
+        }
+        catch {
+            return target;
+        }
+    };
+    const root = physical(path.resolve(workspaceRoot));
+    // The path may itself sit under the unresolved root; re-anchor it physically
+    // by resolving its root-relative tail against the physical root.
+    const anchored = absolute.startsWith(path.resolve(workspaceRoot) + path.sep)
+        ? path.join(root, path.relative(path.resolve(workspaceRoot), absolute))
+        : absolute;
+    return path.relative(root, physical(anchored)).replace(/\\/g, "/");
+};
+/**
+ * Strip package-manager indirection so `npx vitest run`, `pnpm exec vitest
+ * run`, `yarn exec vitest run` and a bare `vitest run` all reduce to the same
+ * runner invocation. Returns the remaining words.
+ */
+export function resolveRunnerArgv(argv) {
+    const words = [...argv];
+    // Skip leading env assignments (`CI=1 vitest run`).
+    while (words.length > 0 && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0])) {
+        words.shift();
+    }
+    const head = words[0];
+    if (head === "npx" || head === "pnpx" || head === "bunx") {
+        words.shift();
+        // `npx --no-install vitest run` / `npx -y vitest run`
+        while (words[0]?.startsWith("-"))
+            words.shift();
+        return words;
+    }
+    if ((head === "pnpm" || head === "yarn" || head === "npm") && words[1] === "exec") {
+        words.splice(0, 2);
+        while (words[0]?.startsWith("-"))
+            words.shift();
+        return words;
+    }
+    return words;
+}
+/** Runner binaries each adapter claims, keyed by adapter scheme. */
+const VITEST_BINARIES = new Set(["vitest"]);
+const JEST_BINARIES = new Set(["jest"]);
+const PLAYWRIGHT_BINARIES = new Set(["playwright"]);
+const basenameOf = (value) => value.split(/[\\/]/).pop() ?? "";
+/** True when `runner` invokes `binary` directly (allowing an explicit path). */
+const invokesBinary = (runner, binaries) => binaries.has(basenameOf(runner[0] ?? ""));
+const vitestAdapter = {
+    scheme: "vitest-json-v1",
+    runner: "vitest",
+    matches: ({ runner }) => invokesBinary(runner, VITEST_BINARIES),
+    // Vitest's json reporter writes to stdout unless an output file is given,
+    // and the executor reads the report from disk, so both flags are required.
+    reportSuffix: () => `--reporter=json --outputFile=`,
+    parse: (raw, cwd, workspaceRoot) => {
+        const schema = z.object({
+            testResults: z.array(z.object({
+                name: z.string().min(1),
+                assertionResults: z.array(z.object({
+                    title: z.string(),
+                    fullName: z.string().optional(),
+                    ancestorTitles: z.array(z.string()).optional(),
+                    status: z.string(),
+                })),
+            })),
+        });
+        return schema
+            .parse(raw)
+            .testResults.flatMap((suite) => suite.assertionResults.map((test) => ({
+            file: toWorkspacePath(suite.name, cwd, workspaceRoot),
+            title: test.fullName ??
+                [...(test.ancestorTitles ?? []), test.title].join(" "),
+            status: test.status,
+        })));
+    },
+};
+const jestAdapter = {
+    scheme: "jest-json-v1",
+    runner: "jest",
+    matches: ({ runner }) => invokesBinary(runner, JEST_BINARIES),
+    reportSuffix: () => `--json --outputFile`,
+    parse: (raw, cwd, workspaceRoot) => {
+        // Jest's `--json` shape: testResults[] carry a per-file `name` plus
+        // assertionResults[] that mirror Vitest's field names.
+        const schema = z.object({
+            testResults: z.array(z.object({
+                name: z.string().min(1),
+                assertionResults: z.array(z.object({
+                    title: z.string(),
+                    fullName: z.string().optional(),
+                    ancestorTitles: z.array(z.string()).optional(),
+                    status: z.string(),
+                })),
+            })),
+        });
+        return schema
+            .parse(raw)
+            .testResults.flatMap((suite) => suite.assertionResults.map((test) => ({
+            file: toWorkspacePath(suite.name, cwd, workspaceRoot),
+            title: test.fullName ??
+                [...(test.ancestorTitles ?? []), test.title].join(" "),
+            status: test.status,
+        })));
+    },
+};
+/**
+ * Playwright's JSON reporter emits a nested `suites` tree whose leaf `specs`
+ * carry `tests[].results[].status`. File paths live on the enclosing `file`
+ * field of each suite node, so the tree is walked while tracking it.
+ */
+const playwrightAdapter = {
+    scheme: "playwright-json-v1",
+    runner: "playwright",
+    matches: ({ runner }) => {
+        if (!invokesBinary(runner, PLAYWRIGHT_BINARIES))
+            return false;
+        // `playwright test` runs tests; `playwright install`/`codegen` do not.
+        return runner[1] === "test" || runner[1] === undefined;
+    },
+    reportSuffix: () => `--reporter=json`,
+    // Playwright ignores an output filename on the CLI (`--output` is its
+    // artifacts directory); its JSON reporter goes to stdout unless this
+    // variable names a file.
+    reportPathEnv: "PLAYWRIGHT_JSON_OUTPUT_NAME",
+    parse: (raw, cwd, workspaceRoot) => {
+        const suiteSchema = z.lazy(() => z.object({
+            file: z.string().optional(),
+            title: z.string().optional(),
+            specs: z
+                .array(z.object({
+                title: z.string(),
+                ok: z.boolean(),
+                tests: z.array(z.object({
+                    status: z.string().optional(),
+                    results: z
+                        .array(z.object({
+                        status: z.string(),
+                    }))
+                        .optional(),
+                })),
+            }))
+                .optional(),
+            suites: z.array(suiteSchema).optional(),
+        }));
+        const root = z
+            .object({
+            suites: z.array(suiteSchema).optional(),
+            // Playwright reports each suite's `file` relative to the resolved
+            // `testDir` (`config.rootDir`), not to the process cwd. A project
+            // with `testDir: "./tests"` reports `orders.spec.js` for
+            // `tests/orders.spec.js`, so resolving against cwd would produce a
+            // path that can never match a contract target.
+            config: z
+                .object({ rootDir: z.string().optional() })
+                .optional(),
+        })
+            .parse(raw);
+        // Prefer the runner's own reported root; fall back to cwd only when the
+        // report omitted it (older report shapes).
+        const reportedRoot = root.config?.rootDir;
+        const baseCwd = typeof reportedRoot === "string" && reportedRoot.length > 0
+            ? reportedRoot
+            : cwd;
+        const out = [];
+        const walk = (node, inheritedFile) => {
+            const record = asRecord(node);
+            if (!record)
+                return;
+            const file = typeof record.file === "string" ? record.file : inheritedFile;
+            for (const spec of record.specs ?? []) {
+                const specRecord = asRecord(spec);
+                if (!specRecord)
+                    continue;
+                const title = String(specRecord.title ?? "");
+                const tests = specRecord.tests ?? [];
+                // A spec with several projects/retries yields several tests; the
+                // spec only passes when every attempt passed.
+                const statuses = tests.flatMap((test) => {
+                    const testRecord = asRecord(test);
+                    const results = testRecord?.results ?? [];
+                    const attempts = results
+                        .map((result) => asRecord(result)?.status)
+                        .filter((value) => typeof value === "string");
+                    return attempts.length > 0
+                        ? attempts
+                        : [String(testRecord?.status ?? "unknown")];
+                });
+                const status = statuses.every((value) => value === "passed")
+                    ? "passed"
+                    : statuses.includes("passed")
+                        ? "failed"
+                        : (statuses[0] ?? "unknown");
+                out.push({
+                    file: toWorkspacePath(file ?? "", baseCwd, workspaceRoot),
+                    title,
+                    status,
+                });
+            }
+            for (const child of record.suites ?? []) {
+                walk(child, file);
+            }
+        };
+        for (const suite of root.suites ?? [])
+            walk(suite, undefined);
+        return out;
+    },
+};
+export const FRONTEND_TEST_ADAPTERS = [
+    vitestAdapter,
+    jestAdapter,
+    playwrightAdapter,
+];
+/**
+ * Runners the container classifier recognizes as behavior verification but
+ * that have no adapter yet. Naming them lets the capability gap read as
+ * "framework not adapted yet" instead of a user configuration error.
+ */
+const KNOWN_UNADAPTED_RUNNERS = new Set([
+    "mocha",
+    "ava",
+    "tap",
+    "cypress",
+    "testcafe",
+    "nightwatch",
+    "wdio",
+    "webdriverio",
+]);
+/** Resolve the adapter for a command, or `undefined` when none matches. */
+export function resolveFrontendTestAdapter(context) {
+    // A package script owns the detail: `npm test` must resolve through the
+    // script body, not the wrapper, or `npm test` and `vitest run` would
+    // disagree about capability.
+    if (context.scriptArgv) {
+        const scriptRunner = resolveRunnerArgv(context.scriptArgv);
+        const fromScript = FRONTEND_TEST_ADAPTERS.find((adapter) => adapter.matches({ ...context, runner: scriptRunner }));
+        if (fromScript)
+            return fromScript;
+    }
+    return FRONTEND_TEST_ADAPTERS.find((adapter) => adapter.matches(context));
+}
+/**
+ * Detect a recognized-but-unadapted runner so callers can report a capability
+ * gap. Returns the runner name when the command is a test runner we know of
+ * but cannot observe.
+ */
+export function detectUnadaptedRunner(runner) {
+    const binary = basenameOf(runner[0] ?? "").replace(/\.(?:js|cjs|mjs|cmd|exe)$/u, "");
+    if (KNOWN_UNADAPTED_RUNNERS.has(binary))
+        return binary;
+    // `node --test`, `node --test-only`, plus `deno test`/`bun test`.
+    if (binary === "node" && runner.includes("--test"))
+        return "node --test";
+    if (binary === "deno" && runner[1] === "test")
+        return "deno test";
+    if (binary === "bun" && runner[1] === "test")
+        return "bun test";
+    return undefined;
+}
+/** Empty `file` means the runner reported a spec outside the workspace. */
+export const isOutsideWorkspacePath = (file) => file === ".." || file.startsWith("../") || path.isAbsolute(file);