@brunosps00/dev-workflow 1.0.5 → 1.1.0

package/scaffold/scripts/functional-doc/generate-dossier.mjs

@@ -628,7 +628,7 @@ function toTitleCase(value) {
 function buildPlaywrightSteps(features, heading, s) {
   const safeHeading = heading.replace(/"/g, '\\"');
   const steps = [
-    `  await test.step("${s.validateInitialLoad}", async () => {`,
+    `  await step("${s.validateInitialLoad}", async () => {`,
     `    await expect(page.getByText(/${escapeRegex(safeHeading)}/i).first()).toBeVisible();`,
     `  });`,
   ];
@@ -636,8 +636,8 @@ function buildPlaywrightSteps(features, heading, s) {
   const firstEdge = features.flatMap((feature) => feature.cases).find((item) => item.type === "edge-case");
   if (firstEdge) {
     steps.push(
-      `  await test.step("${s.recordEdgeCase}", async () => {`,
-      `    await page.screenshot({ path: "evidence-edge-case.png", fullPage: true });`,
+      `  await step("${s.recordEdgeCase}", async () => {`,
+      `    await shot("edge-case");`,
       `  });`,
     );
   }
@@ -645,7 +645,7 @@ function buildPlaywrightSteps(features, heading, s) {
   const firstError = features.flatMap((feature) => feature.cases).find((item) => item.type === "error");
   if (firstError) {
     steps.push(
-      `  await test.step("${s.recordErrorCase}", async () => {`,
+      `  await step("${s.recordErrorCase}", async () => {`,
       `    await expect(page.locator("body")).toBeVisible();`,
       `  });`,
     );
@@ -715,7 +715,7 @@ function buildManifest({ projectRoot, target, targetType, routePath, baseUrl, ha
       features: path.join(outputRoot, "features.md"),
       caseMatrix: path.join(outputRoot, "case-matrix.md"),
       e2eRunbook: path.join(outputRoot, "e2e-runbook.md"),
-      script: path.join(outputRoot, "scripts", `${slugify(routePath || target)}.spec.ts`),
+      script: path.join(outputRoot, "scripts", `${slugify(routePath || target)}.flow.mjs`),
       captions: path.join(outputRoot, "captions", `${slugify(routePath || target)}.srt`),
     },
     blockers: hasPlaywright ? [] : ["Playwright configuration not detected"],
@@ -786,10 +786,8 @@ function main() {
   );
 
   writeFile(
-    path.join(outputRoot, "scripts", `${slugify(routePath || target)}.spec.ts`),
-    renderTemplate(path.join(templatesRoot, "playwright.spec.ts.tpl"), {
-      baseUrl,
-      testTitle: s.flowTest(routePath || target),
+    path.join(outputRoot, "scripts", `${slugify(routePath || target)}.flow.mjs`),
+    renderTemplate(path.join(templatesRoot, "playwright.flow.mjs.tpl"), {
       routePath,
       routeRegex: escapeRegex(routePath || "/"),
       testSteps: buildPlaywrightSteps(features, heading, s),

package/scaffold/scripts/functional-doc/run-playwright-flow.mjs

@@ -1,8 +1,20 @@
 #!/usr/bin/env node
 
+// Runs a functional-doc flow module through the Playwright Node API.
+//
+// Why the Node API (not `playwright test`): video must be captured with page.screencast,
+// which is the only mechanism that works over connectOverCDP (recordVideo does not).
+// Driving directly also removes the dependency on the project's playwright.config.*.
+//
+// Browser selection is delegated to ../lib/resolve-browser.mjs (WSL-resilient): a Windows
+// browser over CDP when reachable, otherwise the full headless Chromium (desktop-faithful,
+// no WSLg). The flow module is plain .mjs exporting `async function flow({ page, context,
+// expect, baseURL, step, shot })`.
+
 import fs from "node:fs";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+import { resolveBrowser } from "../lib/resolve-browser.mjs";
 
 function parseArgs(argv) {
   const result = {};
@@ -11,174 +23,98 @@ function parseArgs(argv) {
     if (!token.startsWith("--")) {
       continue;
     }
-
     const [rawKey, inlineValue] = token.slice(2).split("=", 2);
     const key = rawKey.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
     if (inlineValue !== undefined) {
       result[key] = inlineValue;
       continue;
     }
-
     const next = argv[index + 1];
     if (!next || next.startsWith("--")) {
       result[key] = true;
       continue;
     }
-
     result[key] = next;
     index += 1;
   }
   return result;
 }
 
-function detectPackageManager(projectRoot) {
-  if (fs.existsSync(path.join(projectRoot, "pnpm-lock.yaml"))) return "pnpm";
-  if (fs.existsSync(path.join(projectRoot, "package-lock.json"))) return "npm";
-  if (fs.existsSync(path.join(projectRoot, "yarn.lock"))) return "yarn";
-  return "npm";
-}
-
 function updateManifest(manifestPath, patch) {
   const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
   const next = {
     ...manifest,
-    execution: {
-      ...(manifest.execution ?? {}),
-      ...patch,
-    },
+    execution: { ...(manifest.execution ?? {}), ...patch },
   };
   fs.writeFileSync(manifestPath, `${JSON.stringify(next, null, 2)}\n`);
 }
 
-function detectTestDir(playwrightConfig) {
-  const content = fs.readFileSync(playwrightConfig, "utf8");
-  const match = content.match(/testDir:\s*"([^"]+)"/);
-  return match?.[1] ?? "e2e";
-}
-
 function ensureDir(dirPath) {
   fs.mkdirSync(dirPath, { recursive: true });
 }
 
-function escapeForTemplate(value) {
-  return JSON.stringify(value);
-}
-
 function parseResolution(rawValue) {
   const normalized = String(rawValue ?? "").trim().toLowerCase();
   if (!normalized || normalized === "fullhd") {
     return { width: 1920, height: 1080, label: "1920x1080" };
   }
-
   const match = normalized.match(/^(\d{3,5})x(\d{3,5})$/);
   if (!match) {
     return { width: 1920, height: 1080, label: "1920x1080" };
   }
-
-  return {
-    width: Number(match[1]),
-    height: Number(match[2]),
-    label: `${Number(match[1])}x${Number(match[2])}`,
-  };
+  return { width: Number(match[1]), height: Number(match[2]), label: `${Number(match[1])}x${Number(match[2])}` };
 }
 
-function createTemporaryPlaywrightConfig({
-  generatedDir,
-  flowDir,
-  baseUrl,
-  browserName,
-  resolution,
-}) {
-  const rawArtifactsDir = path.join(flowDir, "evidence", "playwright-artifacts");
-  ensureDir(rawArtifactsDir);
-
-  const configPath = path.join(generatedDir, "playwright.functional-doc.config.mjs");
-  const content = `import { defineConfig } from "@playwright/test";
-
-const rawOutputDir = ${escapeForTemplate(rawArtifactsDir)};
-const baseURL = process.env.BASE_URL ?? ${escapeForTemplate(baseUrl)};
-const generatedDir = ${escapeForTemplate(generatedDir)};
-
-export default defineConfig({
-  testDir: generatedDir,
-  outputDir: rawOutputDir,
-  fullyParallel: false,
-  retries: 0,
-  workers: 1,
-  reporter: "line",
-  use: {
-    baseURL,
-    video: {
-      mode: "on",
-      size: { width: ${resolution.width}, height: ${resolution.height} },
-    },
-    screenshot: "on",
-    trace: "retain-on-failure",
-    viewport: { width: ${resolution.width}, height: ${resolution.height} },
-  },
-  projects: [
-    {
-      name: ${escapeForTemplate(browserName)},
-      use: { browserName: ${escapeForTemplate(browserName)} },
-    },
-  ],
-});
-`;
-  fs.writeFileSync(configPath, content);
-  return { configPath, rawArtifactsDir };
+// Resolves Playwright from the target project (the runner lives under .dw/scripts, so a bare
+// import walks up to <projectRoot>/node_modules). Returns null when not installed.
+async function importPlaywright() {
+  try {
+    return await import("@playwright/test");
+  } catch {
+    try {
+      return await import("playwright");
+    } catch {
+      return null;
+    }
+  }
 }
 
-function collectFilesByExtension(rootDir, extension) {
-  if (!fs.existsSync(rootDir)) {
-    return [];
+async function openBrowser(chromium, descriptor) {
+  if (descriptor.mode === "cdp") {
+    const browser = await chromium.connectOverCDP(descriptor.endpoint);
+    return { browser, cleanup: descriptor.cleanup ?? (async () => {}) };
   }
-
-  const found = [];
-  const queue = [rootDir];
-  while (queue.length > 0) {
-    const current = queue.pop();
-    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
-      const absolutePath = path.join(current, entry.name);
-      if (entry.isDirectory()) {
-        queue.push(absolutePath);
-        continue;
-      }
-      if (absolutePath.toLowerCase().endsWith(extension.toLowerCase())) {
-        found.push(absolutePath);
+  const browser = await chromium.launch(descriptor.launchOptions);
+  return {
+    browser,
+    cleanup: async () => {
+      try {
+        await browser.close();
+      } catch {
+        // ignore
       }
-    }
-  }
-  return found.sort();
+    },
+  };
 }
 
-function copyArtifacts(flowDir, slug, rawArtifactsDir) {
-  const videoDir = path.join(flowDir, "evidence", "videos");
-  const screenshotDir = path.join(flowDir, "evidence", "screenshots");
-  ensureDir(videoDir);
-  ensureDir(screenshotDir);
-
-  const videos = collectFilesByExtension(rawArtifactsDir, ".webm");
-  const screenshots = collectFilesByExtension(rawArtifactsDir, ".png");
-
-  const copiedVideos = videos.map((sourcePath, index) => {
-    const destinationPath = path.join(videoDir, `${slug}${videos.length > 1 ? `-${index + 1}` : ""}.webm`);
-    fs.copyFileSync(sourcePath, destinationPath);
-    return destinationPath;
-  });
-
-  const copiedScreenshots = screenshots.map((sourcePath, index) => {
-    const destinationPath = path.join(screenshotDir, `${slug}${screenshots.length > 1 ? `-${index + 1}` : ""}.png`);
-    fs.copyFileSync(sourcePath, destinationPath);
-    return destinationPath;
+async function openContext(browser, descriptor, { resolution, baseURL }) {
+  // Over CDP the browser already owns a default context we must not close; for a launched
+  // browser we create (and own) a sized context.
+  if (descriptor.mode === "cdp") {
+    const existing = browser.contexts();
+    if (existing.length > 0) {
+      return { context: existing[0], owns: false };
+    }
+    return { context: await browser.newContext(), owns: true };
+  }
+  const context = await browser.newContext({
+    viewport: { width: resolution.width, height: resolution.height },
+    baseURL,
   });
-
-  return {
-    videos: copiedVideos,
-    screenshots: copiedScreenshots,
-  };
+  return { context, owns: true };
 }
 
-function main() {
+async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (!args.flowDir) {
     throw new Error("Missing required argument: --flow-dir");
@@ -189,87 +125,160 @@ function main() {
   const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
   const projectRoot = path.resolve(manifest.project);
   const scriptPath = path.resolve(manifest.outputs.script);
-  const packageManager = detectPackageManager(projectRoot);
-  const browserName = args.browserName || "chromium";
+  const baseURL = process.env.BASE_URL ?? manifest.baseUrl;
   const resolution = parseResolution(
-    args.videoResolution
-    ?? manifest.artifacts?.human_final?.resolution
-    ?? manifest.videoResolution
-    ?? "fullhd"
+    args.videoResolution ?? manifest.artifacts?.human_final?.resolution ?? manifest.videoResolution ?? "fullhd",
   );
-  const playwrightConfig = ["playwright.config.ts", "playwright.config.js"]
-    .map((file) => path.join(projectRoot, file))
-    .find((file) => fs.existsSync(file));
 
-  if (!playwrightConfig) {
+  const playwright = await importPlaywright();
+  if (!playwright) {
     updateManifest(manifestPath, {
       status: "blocked",
-      reason: "Playwright configuration not found",
+      reason: "Playwright is not installed in the project. Run: npx playwright install --with-deps",
     });
-    process.stdout.write("Playwright configuration not found.\n");
+    process.stdout.write("Playwright is not installed in the project.\n");
     process.exit(0);
   }
+  const { chromium, expect } = playwright;
 
-  const testDir = detectTestDir(playwrightConfig);
-  const generatedDir = path.join(projectRoot, testDir, ".functional-doc-generated");
-  ensureDir(generatedDir);
-  const materializedScriptPath = path.join(generatedDir, path.basename(scriptPath));
-  fs.copyFileSync(scriptPath, materializedScriptPath);
-  const slug = path.basename(scriptPath, path.extname(scriptPath));
-  const { configPath: temporaryConfigPath, rawArtifactsDir } = createTemporaryPlaywrightConfig({
-    generatedDir,
-    flowDir,
-    baseUrl: manifest.baseUrl,
-    browserName,
-    resolution,
-  });
-
-  const commandArgs = ["exec", "playwright", "test", materializedScriptPath, "--config", temporaryConfigPath];
   if (args.listOnly) {
-    commandArgs.push("--list");
+    try {
+      await import(pathToFileURL(scriptPath).href);
+      updateManifest(manifestPath, { status: "listed", script: scriptPath });
+      process.stdout.write(`Flow module loads: ${scriptPath}\n`);
+      process.exit(0);
+    } catch (error) {
+      updateManifest(manifestPath, { status: "list_failed", error: error.message });
+      process.stderr.write(`${error.message}\n`);
+      process.exit(1);
+    }
   }
 
-  const result = spawnSync(
-    packageManager,
-    commandArgs,
-    {
-      cwd: projectRoot,
-      env: {
-        ...process.env,
-        BASE_URL: manifest.baseUrl,
-      },
-      encoding: "utf8",
-    },
-  );
-
+  const videoDir = path.join(flowDir, "evidence", "videos");
+  const screenshotDir = path.join(flowDir, "evidence", "screenshots");
   const logDir = path.join(flowDir, "evidence", "logs");
-  fs.mkdirSync(logDir, { recursive: true });
-  fs.writeFileSync(path.join(logDir, "playwright.stdout.log"), result.stdout ?? "");
-  fs.writeFileSync(path.join(logDir, "playwright.stderr.log"), result.stderr ?? "");
+  [videoDir, screenshotDir, logDir].forEach(ensureDir);
+  const slug = path.basename(scriptPath).replace(/\.(flow\.mjs|mjs|spec\.ts)$/, "");
+  const videoPath = path.join(videoDir, `${slug}.webm`);
+
+  const logs = [];
+  const log = (line) => {
+    logs.push(line);
+    process.stdout.write(`${line}\n`);
+  };
+
+  const descriptor = await resolveBrowser({ projectRoot, headless: true });
+  log(`browser: mode=${descriptor.mode} source=${descriptor.source}`);
+  if (args.browserName && args.browserName !== "chromium") {
+    log(`note: --browser-name=${args.browserName} ignored; screencast/CDP require Chromium.`);
+  }
+
+  const { browser, cleanup: cleanupBrowser } = await openBrowser(chromium, descriptor);
+  const { context, owns: ownsContext } = await openContext(browser, descriptor, { resolution, baseURL });
+  const page = await context.newPage();
+  if (descriptor.mode === "cdp") {
+    try {
+      await page.setViewportSize({ width: resolution.width, height: resolution.height });
+    } catch {
+      // viewport may be fixed for an attached context; continue
+    }
+  }
+
+  let stepIndex = 0;
+  const stepLog = [];
+  const step = async (label, fn) => {
+    stepIndex += 1;
+    log(`  step ${stepIndex}: ${label}`);
+    stepLog.push(label);
+    await fn();
+    // Pacing for a human-watchable tour; dw-functional-doc tunes longer holds as needed.
+    await page.waitForTimeout(1500);
+  };
+  const screenshots = [];
+  const shot = async (name) => {
+    const target = path.join(screenshotDir, `${slug}-${name}.png`);
+    await page.screenshot({ path: target, fullPage: true });
+    screenshots.push(target);
+  };
+
+  // Video: page.screencast (works for launched AND CDP-attached browsers). Falls back to a
+  // recorded context only for a launched browser; over CDP without screencast, video is skipped.
+  let recording = "none";
+  const screencastAvailable = typeof page.screencast?.start === "function";
+  if (screencastAvailable) {
+    try {
+      await page.screencast.start({ path: videoPath });
+      recording = "screencast";
+    } catch (error) {
+      log(`screencast.start failed (${error.message}); continuing without video.`);
+    }
+  } else {
+    log("page.screencast unavailable (Playwright < 1.60). Upgrade Playwright to record video.");
+  }
+
+  let status = "passed";
+  let errorMessage = null;
+  try {
+    const module = await import(pathToFileURL(scriptPath).href);
+    const flow = module.default ?? module.flow;
+    if (typeof flow !== "function") {
+      throw new Error(`Flow module ${scriptPath} has no default export function.`);
+    }
+    await flow({ page, context, expect, baseURL, step, shot });
+  } catch (error) {
+    status = "failed";
+    errorMessage = error.message;
+    log(`flow error: ${error.message}`);
+    try {
+      await shot("failure");
+    } catch {
+      // ignore
+    }
+  } finally {
+    if (recording === "screencast") {
+      try {
+        await page.screencast.stop();
+      } catch (error) {
+        log(`screencast.stop failed: ${error.message}`);
+      }
+    }
+    try {
+      await page.close();
+    } catch {
+      // ignore
+    }
+    if (ownsContext) {
+      try {
+        await context.close();
+      } catch {
+        // ignore
+      }
+    }
+    await cleanupBrowser();
+  }
 
-  const copiedArtifacts = args.listOnly
-    ? { videos: [], screenshots: [] }
-    : copyArtifacts(flowDir, slug, rawArtifactsDir);
+  const logFile = path.join(logDir, "playwright.log");
+  fs.writeFileSync(logFile, `${logs.join("\n")}\n`);
+  const videoExists = recording === "screencast" && fs.existsSync(videoPath);
 
   updateManifest(manifestPath, {
-    status: args.listOnly ? (result.status === 0 ? "listed" : "list_failed") : (result.status === 0 ? "passed" : "failed"),
-    command: `${packageManager} ${commandArgs.join(" ")}`,
-    exitCode: result.status ?? 1,
+    status,
+    browserMode: descriptor.mode,
+    browserSource: descriptor.source,
+    recording,
     videoResolution: resolution.label,
-    materializedScript: materializedScriptPath,
-    temporaryConfig: temporaryConfigPath,
-    video: copiedArtifacts.videos[0] ?? null,
-    videos: copiedArtifacts.videos,
-    screenshots: copiedArtifacts.screenshots,
-    logs: [
-      path.join(logDir, "playwright.stdout.log"),
-      path.join(logDir, "playwright.stderr.log"),
-    ],
+    video: videoExists ? videoPath : null,
+    videos: videoExists ? [videoPath] : [],
+    screenshots,
+    steps: stepLog,
+    error: errorMessage,
+    logs: [logFile],
   });
 
-  process.stdout.write(result.stdout ?? "");
-  process.stderr.write(result.stderr ?? "");
-  process.exit(result.status ?? 1);
+  process.exit(status === "passed" ? 0 : 1);
 }
 
-main();
+main().catch((error) => {
+  process.stderr.write(`run-playwright-flow: ${error.message}\n`);
+  process.exit(1);
+});

package/scaffold/scripts/lib/capture-screenshots.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+// Captures responsive screenshots of a URL via the Playwright Node API, using the
+// WSL-resilient browser resolution from ./resolve-browser.mjs. This is the fallback for
+// dw-qa / dw-redesign-ui when the Playwright MCP is unavailable or blocked.
+//
+// Usage:
+//   node .dw/scripts/lib/capture-screenshots.mjs --url http://localhost:3000/path \
+//     [--out ./evidence] [--widths 375,1440] [--height 900] [--slug home] [--full-page]
+//
+// Resolution is desktop-faithful (full Chromium, new headless — no WSLg). Prints a JSON
+// summary { url, shots: [{ width, path }] } and exits non-zero on failure.
+
+import fs from "node:fs";
+import path from "node:path";
+import { resolveBrowser } from "./resolve-browser.mjs";
+
+function parseArgs(argv) {
+  const result = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) {
+      continue;
+    }
+    const [rawKey, inlineValue] = token.slice(2).split("=", 2);
+    const key = rawKey.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    if (inlineValue !== undefined) {
+      result[key] = inlineValue;
+      continue;
+    }
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      result[key] = true;
+      continue;
+    }
+    result[key] = next;
+    index += 1;
+  }
+  return result;
+}
+
+async function importChromium() {
+  try {
+    return (await import("@playwright/test")).chromium;
+  } catch {
+    try {
+      return (await import("playwright")).chromium;
+    } catch {
+      return null;
+    }
+  }
+}
+
+function slugify(value) {
+  return (
+    String(value)
+      .toLowerCase()
+      .replace(/^https?:\/\//, "")
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 60) || "page"
+  );
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.url) {
+    throw new Error("Missing required argument: --url");
+  }
+
+  const url = String(args.url);
+  const outDir = path.resolve(args.out ? String(args.out) : "evidence/screenshots");
+  const widths = String(args.widths ?? "375,1440")
+    .split(",")
+    .map((value) => Number(value.trim()))
+    .filter((value) => Number.isFinite(value) && value > 0);
+  const height = Number(args.height) || 900;
+  const slug = args.slug ? slugify(args.slug) : slugify(url);
+  const fullPage = Boolean(args.fullPage);
+
+  const chromium = await importChromium();
+  if (!chromium) {
+    throw new Error("Playwright is not installed in the project. Run: npx playwright install --with-deps");
+  }
+
+  fs.mkdirSync(outDir, { recursive: true });
+  const descriptor = await resolveBrowser({ projectRoot: process.cwd(), headless: true });
+  process.stderr.write(`browser: mode=${descriptor.mode} source=${descriptor.source}\n`);
+
+  let browser;
+  let cleanup = async () => {};
+  if (descriptor.mode === "cdp") {
+    browser = await chromium.connectOverCDP(descriptor.endpoint);
+    cleanup = descriptor.cleanup ?? (async () => {});
+  } else {
+    browser = await chromium.launch(descriptor.launchOptions);
+    cleanup = async () => {
+      try {
+        await browser.close();
+      } catch {
+        // ignore
+      }
+    };
+  }
+
+  const shots = [];
+  try {
+    const existing = descriptor.mode === "cdp" ? browser.contexts()[0] : null;
+    const context = existing ?? (await browser.newContext());
+    const ownsContext = !existing;
+    const page = await context.newPage();
+    for (const width of widths) {
+      await page.setViewportSize({ width, height });
+      await page.goto(url, { waitUntil: "networkidle" }).catch(() => page.goto(url));
+      const target = path.join(outDir, `${slug}-${width}.png`);
+      await page.screenshot({ path: target, fullPage });
+      shots.push({ width, path: target });
+    }
+    await page.close();
+    if (ownsContext) {
+      await context.close();
+    }
+  } finally {
+    await cleanup();
+  }
+
+  process.stdout.write(`${JSON.stringify({ url, shots }, null, 2)}\n`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`capture-screenshots: ${error.message}\n`);
+  process.exit(1);
+});