@rettangoli/vt 1.0.0-rc2 → 1.0.0-rc4

package/README.md

@@ -5,12 +5,18 @@ Visual regression testing for Rettangoli specs using Playwright screenshots.
 ## Commands
 
 - `rtgl vt generate`
+- `rtgl vt screenshot`
 - `rtgl vt report`
 - `rtgl vt accept`
 
-## Public Generate Options
+Behavior split:
+
+- `generate` builds candidate HTML only (no Playwright capture)
+- `screenshot` runs generate flow and captures candidate screenshots
+- `report` compares existing artifacts only (does not run generate/screenshot)
+
+## Public Screenshot Options
 
-- `--skip-screenshots`
 - `--headed`
 - `--concurrency <number>`
 - `--timeout <ms>`
@@ -30,7 +36,7 @@ Visual regression testing for Rettangoli specs using Playwright screenshots.
 
 ## Scoped Runs
 
-Use selectors to run only part of VT in both `generate` and `report`:
+Use selectors to run only part of VT in both `screenshot` and `report`:
 
 - `folder`: matches specs by folder prefix under `vt/specs` (example: `components/forms`)
 - `group`: matches section page key from `vt.sections` (`title` for flat sections, `items[].title` for grouped sections)
@@ -45,17 +51,17 @@ Examples:
 
 ```bash
 # Only specs under a folder
-rtgl vt generate --folder components/forms
+rtgl vt screenshot --folder components/forms
 
 # Only one section/group key from vt.sections
-rtgl vt generate --group components_basic
+rtgl vt screenshot --group components_basic
 
 # Only one spec item (extension optional)
-rtgl vt generate --item components/forms/login
-rtgl vt generate --item components/forms/login.html
+rtgl vt screenshot --item components/forms/login
+rtgl vt screenshot --item components/forms/login.html
 
 # Combine selectors (union)
-rtgl vt generate --group components_basic --item pages/home
+rtgl vt screenshot --group components_basic --item pages/home
 
 # Same selectors for report
 rtgl vt report --folder components/forms
@@ -73,7 +79,9 @@ Everything else in capture is internal and intentionally not user-configurable.
 vt:
   path: ./vt
   port: 3001
-  skipScreenshots: false
+  url: http://127.0.0.1:4173
+  service:
+    start: bun run preview
   concurrency: 4
   timeout: 30000
   waitEvent: vt:ready
@@ -89,6 +97,8 @@ vt:
 Notes:
 
 - `vt.sections` is required.
+- `vt.service` is optional. When set, VT starts the command before capture, waits for `vt.url`, then stops it after capture.
+- when `vt.service` is omitted and `vt.url` is set, VT expects that URL to already be running.
 - Section page keys (`title` for flat sections and group `items[].title`) allow only letters, numbers, `-`, `_`.
 - `vt.viewport` supports object or array; each viewport requires `id`, `width`, `height`.
 - `vt.capture` is internal and must be omitted.
@@ -113,6 +123,8 @@ Supported frontmatter keys per spec file:
 Step action reference:
 
 - `docs/step-actions.md`
+- canonical format is structured action objects (`- action: ...`), with legacy string/block forms still supported.
+- `assert` supports `js` deep-equal checks for object/array values.
 
 Screenshot naming:
 
@@ -125,17 +137,22 @@ Screenshot naming:
 A pre-built Docker image with `rtgl` and Playwright browsers is available:
 
 ```bash
-docker pull han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc2
+docker pull han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc6
 ```
 
 Run commands against a local project:
 
 ```bash
-docker run --rm -v "$(pwd):/workspace" -w /workspace han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc2 rtgl vt generate
-docker run --rm -v "$(pwd):/workspace" -w /workspace han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc2 rtgl vt report
-docker run --rm -v "$(pwd):/workspace" -w /workspace han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc2 rtgl vt accept
+docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc6 rtgl vt screenshot
+docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc6 rtgl vt report
+docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc6 rtgl vt accept
 ```
 
+Note:
+
+- Image default working directory is `/workspace`.
+- Use `-w /workspace/<subdir>` only when running commands from a subfolder within the mounted project.
+
 Supports `linux/amd64` and `linux/arm64`.
 
 ## Development
@@ -146,6 +163,14 @@ Run unit tests:
 bun test
 ```
 
+Default unit run behavior:
+
+- `bun test` skips the real-browser smoke tests in `spec/e2e-smoke.spec.js` unless `VT_E2E=1`.
+- Skipped smoke tests are:
+  - `runs generate, accept, and report with real screenshots`
+  - `supports waitEvent readiness with real browser screenshots`
+  - `supports managed service lifecycle with vt.service.start and vt.url`
+
 Run real-browser smoke:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rettangoli/vt",
-  "version": "1.0.0-rc2",
+  "version": "1.0.0-rc4",
   "description": "Rettangoli Visual Testing",
   "type": "module",
   "main": "./src/index.js",

package/src/capture/spec-loader.js

@@ -70,8 +70,10 @@ export function createCaptureTasks(generatedFiles, options) {
     const frontMatter = file.frontMatter || {};
     const normalizedPath = normalizePathForUrl(file.path);
     const constructedUrl = toHtmlPath(`${serverUrl}/candidate/${normalizedPath}`);
-    const rawUrl = frontMatter.url ?? configUrl ?? constructedUrl;
-    const url = toAbsoluteUrl(rawUrl, serverUrl);
+    const resolvedConfigUrl = configUrl ? toAbsoluteUrl(configUrl, serverUrl) : null;
+    const urlResolutionBase = resolvedConfigUrl || serverUrl;
+    const rawUrl = frontMatter.url ?? resolvedConfigUrl ?? constructedUrl;
+    const url = toAbsoluteUrl(rawUrl, urlResolutionBase);
     const resolvedWaitEvent = frontMatter.waitEvent ?? waitEvent;
     const resolvedWaitSelector = frontMatter.waitSelector ?? waitSelector;
 

package/src/cli/generate-options.js

@@ -5,6 +5,7 @@ import { normalizeSelectors } from "../selector-filter.js";
 export function resolveGenerateOptions(options = {}, configData = {}) {
   const {
     skipScreenshots: cliSkipScreenshots,
+    captureScreenshots,
     vtPath: cliVtPath,
     port: cliPort,
     concurrency: cliConcurrency,
@@ -25,14 +26,26 @@ export function resolveGenerateOptions(options = {}, configData = {}) {
     item: cliItem,
   });
 
+  let resolvedSkipScreenshots;
+  if (captureScreenshots === true) {
+    resolvedSkipScreenshots = false;
+  } else if (captureScreenshots === false) {
+    resolvedSkipScreenshots = true;
+  } else if (cliSkipScreenshots === true) {
+    resolvedSkipScreenshots = true;
+  } else {
+    resolvedSkipScreenshots = configData.skipScreenshots ?? false;
+  }
+
   const resolvedOptions = {
     vtPath: cliVtPath ?? configData.path ?? "./vt",
-    skipScreenshots: cliSkipScreenshots ? true : (configData.skipScreenshots ?? false),
+    skipScreenshots: resolvedSkipScreenshots,
     port: cliPort ?? configData.port ?? 3001,
     waitEvent,
     headless: cliHeadless ?? true,
     configUrl: cliUrl ?? configData.url,
     ...(configData.viewport !== undefined ? { viewport: configData.viewport } : {}),
+    ...(configData.service?.start ? { serviceStart: configData.service.start } : {}),
     selectors,
 
     // Internal capture defaults (not user-configurable).

package/src/cli/generate.js

@@ -14,6 +14,11 @@ import {
   filterGeneratedFilesBySelectors,
   hasSelectors,
 } from "../selector-filter.js";
+import {
+  startManagedService,
+  stopManagedService,
+  waitForServiceReady,
+} from "./service-runtime.js";
 
 const libraryTemplatesPath = new URL("./templates", import.meta.url).pathname;
 const libraryStaticPath = new URL("./static", import.meta.url).pathname;
@@ -90,6 +95,7 @@ async function main(options = {}) {
     skipScreenshots,
     port,
     configUrl,
+    serviceStart,
   } = resolvedOptions;
 
   const specsPath = join(vtPath, "specs");
@@ -164,8 +170,22 @@ async function main(options = {}) {
       return;
     }
 
-    const server = configUrl ? null : await startWebServer(siteOutputPath, vtPath, port);
+    let server = null;
+    let managedService = null;
+
     try {
+      if (serviceStart) {
+        if (!configUrl) {
+          throw new Error(
+            "vt.service.start requires vt.url (or --url) so VT can wait for readiness and capture against that URL.",
+          );
+        }
+        managedService = startManagedService({ command: serviceStart });
+        await waitForServiceReady({ url: configUrl, handle: managedService });
+      } else if (!configUrl) {
+        server = await startWebServer(siteOutputPath, vtPath, port);
+      }
+
       await takeScreenshots(
         buildCaptureOptions({
           filesToScreenshot,
@@ -179,6 +199,9 @@ async function main(options = {}) {
         server.close();
         console.log("Server stopped");
       }
+      if (managedService) {
+        await stopManagedService(managedService);
+      }
     }
   }
 }

package/src/cli/index.js

@@ -1,9 +1,11 @@
 import generate from './generate.js';
+import screenshot from './screenshot.js';
 import report from './report.js';
 import accept from './accept.js';
 
 export {
   generate,
+  screenshot,
   report,
   accept,
-}
+}

package/src/cli/report.js

@@ -159,7 +159,7 @@ async function main(options = {}) {
 
   try {
     if (!fs.existsSync(candidateDir)) {
-      throw new Error(`Candidate screenshots directory not found: "${candidateDir}". Run "rtgl vt generate" first.`);
+      throw new Error(`Candidate screenshots directory not found: "${candidateDir}". Run "rtgl vt screenshot" first.`);
     }
 
     const candidateFiles = getAllFiles(candidateDir).filter((file) => file.endsWith(".webp"));

package/src/cli/screenshot.js

@@ -0,0 +1,8 @@
+import generate from "./generate.js";
+
+export default async function screenshot(options = {}) {
+  await generate({
+    ...options,
+    captureScreenshots: true,
+  });
+}

package/src/cli/service-runtime.js

@@ -0,0 +1,116 @@
+import { spawn } from "node:child_process";
+
+const READY_TIMEOUT_MS = 120000;
+const READY_INTERVAL_MS = 500;
+const STOP_TIMEOUT_MS = 10000;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function formatExitMessage(result) {
+  if (!result) return "unknown exit state";
+  if (result.code !== null && result.code !== undefined) {
+    return `code ${result.code}`;
+  }
+  if (result.signal) {
+    return `signal ${result.signal}`;
+  }
+  return "unknown exit state";
+}
+
+function sendSignal(handle, signal) {
+  const { child, useProcessGroup } = handle;
+  const pid = child.pid;
+  if (!pid) {
+    return;
+  }
+
+  try {
+    if (useProcessGroup) {
+      process.kill(-pid, signal);
+      return;
+    }
+    child.kill(signal);
+  } catch (error) {
+    if (error?.code !== "ESRCH") {
+      throw error;
+    }
+  }
+}
+
+export function startManagedService({ command }) {
+  const useProcessGroup = process.platform !== "win32";
+  const child = spawn(command, {
+    cwd: process.cwd(),
+    stdio: "inherit",
+    shell: true,
+    env: process.env,
+    detached: useProcessGroup,
+  });
+
+  const exitPromise = new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      resolve({ code, signal });
+    });
+  });
+
+  console.log(`Starting managed service: ${command}`);
+  return { child, exitPromise, useProcessGroup };
+}
+
+export async function waitForServiceReady({ url, handle }) {
+  const startMs = Date.now();
+
+  while (Date.now() - startMs < READY_TIMEOUT_MS) {
+    if (handle.child.exitCode !== null) {
+      const result = await handle.exitPromise.catch(() => null);
+      throw new Error(
+        `Managed service exited before becoming ready (${formatExitMessage(result)}).`,
+      );
+    }
+
+    try {
+      const response = await fetch(url);
+      console.log(`Managed service ready: ${url} (status ${response.status})`);
+      return;
+    } catch {
+      // Keep polling until timeout.
+    }
+
+    await sleep(READY_INTERVAL_MS);
+  }
+
+  throw new Error(
+    `Timed out waiting for managed service at ${url} after ${READY_TIMEOUT_MS}ms.`,
+  );
+}
+
+export async function stopManagedService(handle) {
+  if (!handle) return;
+
+  const { child, exitPromise } = handle;
+  if (child.exitCode !== null) {
+    return;
+  }
+
+  console.log("Stopping managed service (SIGTERM)...");
+  sendSignal(handle, "SIGTERM");
+
+  const exitedGracefully = await Promise.race([
+    exitPromise.then(() => true).catch(() => true),
+    sleep(STOP_TIMEOUT_MS).then(() => false),
+  ]);
+
+  if (exitedGracefully) {
+    return;
+  }
+
+  if (child.exitCode === null) {
+    console.warn("Managed service did not exit after SIGTERM, sending SIGKILL...");
+    sendSignal(handle, "SIGKILL");
+  }
+
+  await exitPromise.catch(() => null);
+}

package/src/common.js

@@ -248,7 +248,7 @@ function getContentType(filePath) {
 }
 
 function toSectionPageKey(sectionLike) {
-  return sectionLike.title;
+  return String(sectionLike.title || "").toLowerCase();
 }
 
 /**