@rettangoli/vt 1.0.0-rc1 → 1.0.0-rc3

package/README.md

@@ -77,6 +77,10 @@ vt:
   concurrency: 4
   timeout: 30000
   waitEvent: vt:ready
+  viewport:
+    id: desktop
+    width: 1280
+    height: 720
   sections:
     - title: components_basic
       files: components
@@ -86,7 +90,9 @@ Notes:
 
 - `vt.sections` is required.
 - 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.
+- Viewport contract details: `docs/viewport-contract.md`.
 
 ## Spec Frontmatter
 
@@ -99,18 +105,47 @@ Supported frontmatter keys per spec file:
 - `waitEvent`
 - `waitSelector`
 - `waitStrategy` (`networkidle` | `load` | `event` | `selector`)
+- `viewport` (object or array of viewport objects)
 - `skipScreenshot`
 - `specs`
 - `steps`
 
+Step action reference:
+
+- `docs/step-actions.md`
+
 Screenshot naming:
 
 - First screenshot is `-01`.
 - Then `-02`, `-03`, up to `-99`.
+- When viewport id is configured, filenames include `--<viewportId>` before ordinal (for example `pages/home--mobile-01.webp`).
+
+## Docker
+
+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-rc4
+```
+
+Run commands against a local project:
+
+```bash
+docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc4 rtgl vt generate
+docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc4 rtgl vt report
+docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc4 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
 
-Run tests:
+Run unit tests:
 
 ```bash
 bun test
@@ -125,15 +160,13 @@ VT_E2E=1 bun test spec/e2e-smoke.spec.js
 Run Docker E2E tests (requires Docker daemon running):
 
 ```bash
-# Full pipeline: build image → verify → run all Docker E2E tests
-bun run test:docker:full
+# Full pipeline: build test image → run all E2E scenarios
+bun run test:e2e:full
 
-# Tests only (skip image build, assumes image already exists)
-bun run test:docker
+# Scenarios only (skip image build, assumes image already exists)
+bun run test:e2e
 ```
 
-The Docker E2E suite builds a local `rtgl-local-test:latest` image, then runs generate/report/accept in temp directories inside containers. Tests validate WebP screenshot headers, report.json schema, metrics.json schema, HTML content, directory structure, accept file copies, multi-spec fixtures, multi-screenshot ordinals, and pixelmatch diff detection.
-
 Optional benchmark fixture:
 
 ```bash

package/package.json

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

package/src/capture/playwright-runner.js

@@ -3,11 +3,7 @@ import { dirname, join } from "node:path";
 import sharp from "sharp";
 import { createSteps } from "../createSteps.js";
 import { formatScreenshotOrdinal } from "./screenshot-naming.js";
-
-const DEFAULT_VIEWPORT = Object.freeze({
-  width: 1280,
-  height: 720,
-});
+import { DEFAULT_VIEWPORT } from "../viewport.js";
 
 function nowMs() {
   return performance.now();
@@ -128,8 +124,11 @@ export class PlaywrightRunner {
     return context;
   }
 
-  async configurePage(page) {
-    await page.setViewportSize(DEFAULT_VIEWPORT);
+  async configurePage(page, viewport = DEFAULT_VIEWPORT) {
+    await page.setViewportSize({
+      width: viewport.width,
+      height: viewport.height,
+    });
     await page.setDefaultNavigationTimeout(this.navigationTimeout);
     await page.setDefaultTimeout(this.readyTimeout);
     await page.emulateMedia({
@@ -348,6 +347,7 @@ export class PlaywrightRunner {
 
     try {
       resetMs = await resetSession();
+      await this.configurePage(page, task.viewport ?? DEFAULT_VIEWPORT);
       const readyState = await this.navigateToReadyState(page, task, registeredReadyEvents);
       strategy = readyState.strategy;
       navigationMs = readyState.navigationMs;

package/src/capture/spec-loader.js

@@ -1,3 +1,5 @@
+import { appendViewportToBaseName, resolveViewports } from "../viewport.js";
+
 const removeExtension = (filePath) => filePath.replace(/\.[^/.]+$/, "");
 
 const toHtmlPath = (filePath) => {
@@ -58,9 +60,13 @@ export function createCaptureTasks(generatedFiles, options) {
     waitEvent,
     waitSelector,
     waitStrategy,
+    viewport,
   } = options;
 
-  return generatedFiles.map((file, index) => {
+  const tasks = [];
+  let taskIndex = 0;
+
+  generatedFiles.forEach((file, fileIndex) => {
     const frontMatter = file.frontMatter || {};
     const normalizedPath = normalizePathForUrl(file.path);
     const constructedUrl = toHtmlPath(`${serverUrl}/candidate/${normalizedPath}`);
@@ -75,25 +81,37 @@ export function createCaptureTasks(generatedFiles, options) {
       waitStrategy,
     });
 
-    const task = {
-      id: `${index}:${file.path}`,
-      index,
-      path: file.path,
-      url,
-      baseName: removeExtension(file.path),
-      frontMatter,
-      steps: frontMatter.steps || [],
-      waitStrategy: resolvedWaitStrategy,
-      estimatedCost: estimateTaskCost(frontMatter.steps || [], resolvedWaitStrategy),
-    };
+    const resolvedViewports = resolveViewports(frontMatter.viewport, viewport);
+    resolvedViewports.forEach((resolvedViewport) => {
+      const viewportId = resolvedViewport.id;
+      const task = {
+        id: `${fileIndex}:${file.path}:${viewportId ?? "default"}`,
+        index: taskIndex,
+        path: file.path,
+        url,
+        baseName: appendViewportToBaseName(removeExtension(file.path), viewportId),
+        frontMatter,
+        steps: frontMatter.steps || [],
+        waitStrategy: resolvedWaitStrategy,
+        estimatedCost: estimateTaskCost(frontMatter.steps || [], resolvedWaitStrategy),
+        viewport: {
+          id: viewportId,
+          width: resolvedViewport.width,
+          height: resolvedViewport.height,
+        },
+      };
 
-    if (resolvedWaitEvent !== undefined && resolvedWaitEvent !== null) {
-      task.waitEvent = resolvedWaitEvent;
-    }
-    if (resolvedWaitSelector !== undefined && resolvedWaitSelector !== null) {
-      task.waitSelector = resolvedWaitSelector;
-    }
+      if (resolvedWaitEvent !== undefined && resolvedWaitEvent !== null) {
+        task.waitEvent = resolvedWaitEvent;
+      }
+      if (resolvedWaitSelector !== undefined && resolvedWaitSelector !== null) {
+        task.waitSelector = resolvedWaitSelector;
+      }
 
-    return task;
+      tasks.push(task);
+      taskIndex += 1;
+    });
   });
+
+  return tasks;
 }

package/src/cli/generate-options.js

@@ -32,6 +32,7 @@ export function resolveGenerateOptions(options = {}, configData = {}) {
     waitEvent,
     headless: cliHeadless ?? true,
     configUrl: cliUrl ?? configData.url,
+    ...(configData.viewport !== undefined ? { viewport: configData.viewport } : {}),
     selectors,
 
     // Internal capture defaults (not user-configurable).

package/src/cli/generate.js

@@ -39,6 +39,7 @@ export function buildCaptureOptions({
     isolationMode,
     metricsPath,
     headless,
+    viewport,
   } = resolvedOptions;
 
   return {
@@ -59,6 +60,7 @@ export function buildCaptureOptions({
     isolationMode,
     metricsPath,
     headless,
+    viewport,
   };
 }
 

package/src/common.js

@@ -273,6 +273,7 @@ async function takeScreenshots(options) {
     isolationMode = "fast",
     metricsPath = join(".rettangoli", "vt", "metrics.json"),
     headless = true,
+    viewport = undefined,
   } = options;
 
   if (!Array.isArray(generatedFiles)) {
@@ -324,6 +325,7 @@ async function takeScreenshots(options) {
     waitEvent,
     waitSelector,
     waitStrategy,
+    viewport,
   });
 
   const { summary, failures } = await runCaptureScheduler({

package/src/createSteps.js

@@ -1,18 +1,86 @@
+function parseStepCommand(stepString) {
+  const tokens = stepString.trim().split(/\s+/).filter(Boolean);
+  const [command, ...args] = tokens;
+  return { command, args };
+}
+
+function parseNamedArgs(args) {
+  const named = {};
+  const positional = [];
+  args.forEach((token) => {
+    const separatorIndex = token.indexOf("=");
+    if (separatorIndex <= 0) {
+      positional.push(token);
+      return;
+    }
+    const key = token.slice(0, separatorIndex);
+    const value = token.slice(separatorIndex + 1);
+    named[key] = value;
+  });
+  return { named, positional };
+}
+
+function toNumber(value, fieldName) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`Invalid ${fieldName}: expected a finite number, got "${value}".`);
+  }
+  return parsed;
+}
+
+function toPositiveInteger(value, fieldName) {
+  const parsed = toNumber(value, fieldName);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error(`Invalid ${fieldName}: expected an integer >= 1, got "${value}".`);
+  }
+  return parsed;
+}
+
+function parseTimeoutValue(value) {
+  if (value === undefined) {
+    return undefined;
+  }
+  const timeout = toNumber(value, "timeout");
+  if (timeout < 0) {
+    throw new Error(`Invalid timeout: expected >= 0, got ${timeout}.`);
+  }
+  return timeout;
+}
+
+function requireSelectedElement(command, selectedElement) {
+  if (!selectedElement) {
+    throw new Error(`\`${command}\` requires a \`select\` block target.`);
+  }
+  return selectedElement;
+}
+
 async function click(page, args, context, selectedElement) {
   if (selectedElement) {
     await selectedElement.click();
   } else if (args.length >= 2) {
-    await page.mouse.click(Number(args[0]), Number(args[1]), { button: "left" });
+    await page.mouse.click(
+      toNumber(args[0], "x"),
+      toNumber(args[1], "y"),
+      { button: "left" },
+    );
   } else {
-    console.warn('`click` command needs a `select` block or coordinates.');
+    throw new Error("`click` requires a `select` block target or `x y` coordinates.");
   }
 }
 
 async function customEvent(page, args) {
+  if (args.length === 0) {
+    throw new Error("`customEvent` requires an event name.");
+  }
   const [eventName, ...params] = args;
   const payload = {};
-  params.forEach(param => {
-    const [key, value] = param.split('=');
+  params.forEach((param) => {
+    const [key, value] = param.split("=");
+    if (!key || value === undefined) {
+      throw new Error(
+        `Invalid customEvent argument "${param}". Expected key=value.`,
+      );
+    }
     payload[key] = value;
   });
   await page.evaluate(({ eventName, payload }) => {
@@ -21,6 +89,9 @@ async function customEvent(page, args) {
 }
 
 async function goto(page, args) {
+  if (!args[0]) {
+    throw new Error("`goto` requires a URL argument.");
+  }
   await page.goto(args[0], { waitUntil: "networkidle" });
   // Normalize font rendering for consistent screenshots
   await page.addStyleTag({
@@ -35,6 +106,9 @@ async function goto(page, args) {
 }
 
 async function keypress(page, args) {
+  if (!args[0]) {
+    throw new Error("`keypress` requires a key argument.");
+  }
   await page.keyboard.press(args[0]);
 }
 
@@ -46,47 +120,291 @@ async function mouseUp(page) {
   await page.mouse.up();
 }
 
-async function rMouseDown(page){
+async function rightMouseDown(page) {
   await page.mouse.down({ button: 'right' });
 }
 
-async function rMouseUp(page){
+async function rightMouseUp(page) {
   await page.mouse.up({ button: 'right' });
 }
 
 async function move(page, args) {
-  await page.mouse.move(Number(args[0]), Number(args[1]));
+  if (args.length < 2) {
+    throw new Error("`move` requires `x y` coordinates.");
+  }
+  await page.mouse.move(toNumber(args[0], "x"), toNumber(args[1], "y"));
 }
 
-async function scroll(page, args){
-  await page.mouse.wheel(Number(args[0]), Number(args[1]));
+async function scroll(page, args) {
+  if (args.length < 2) {
+    throw new Error("`scroll` requires `deltaX deltaY` values.");
+  }
+  await page.mouse.wheel(toNumber(args[0], "deltaX"), toNumber(args[1], "deltaY"));
 }
 
 async function rclick(page, args, context, selectedElement) {
   if (selectedElement) {
-    await selectedElement.click({ button: 'right' });
+    await selectedElement.click({ button: "right" });
   } else if (args.length >= 2) {
-    await page.mouse.click(Number(args[0]), Number(args[1]), { button: "right" });
+    await page.mouse.click(
+      toNumber(args[0], "x"),
+      toNumber(args[1], "y"),
+      { button: "right" },
+    );
   } else {
-    console.warn('`rclick` command needs a `select` block or coordinates.');
+    throw new Error("`rclick` requires a `select` block target or `x y` coordinates.");
   }
 }
 
 async function wait(page, args) {
-  await page.waitForTimeout(Number(args[0]));
+  if (!args[0]) {
+    throw new Error("`wait` requires a millisecond duration.");
+  }
+  await page.waitForTimeout(toNumber(args[0], "ms"));
+}
+
+async function setViewport(page, args) {
+  if (args.length < 2) {
+    throw new Error("`setViewport` requires `width height`.");
+  }
+  await page.setViewportSize({
+    width: toPositiveInteger(args[0], "width"),
+    height: toPositiveInteger(args[1], "height"),
+  });
 }
 
 async function write(page, args, context, selectedElement) {
+  const target = requireSelectedElement("write", selectedElement);
+  const textToWrite = args.join(" ");
+  await target.fill(textToWrite);
+}
+
+async function hover(page, args, context, selectedElement) {
   if (selectedElement) {
-    const textToWrite = args.join(' ');
-    await selectedElement.fill(textToWrite);
-  } else {
-    console.warn('`write` command called without a `select` block.');
+    await selectedElement.hover();
+    return;
+  }
+  if (args.length >= 2) {
+    await page.mouse.move(toNumber(args[0], "x"), toNumber(args[1], "y"));
+    return;
+  }
+  throw new Error("`hover` requires a `select` block target or `x y` coordinates.");
+}
+
+async function dblclick(page, args, context, selectedElement) {
+  if (selectedElement) {
+    await selectedElement.dblclick();
+    return;
+  }
+  if (args.length >= 2) {
+    await page.mouse.dblclick(toNumber(args[0], "x"), toNumber(args[1], "y"));
+    return;
+  }
+  throw new Error("`dblclick` requires a `select` block target or `x y` coordinates.");
+}
+
+async function focus(page, args, context, selectedElement) {
+  const target = requireSelectedElement("focus", selectedElement);
+  await target.focus();
+}
+
+async function blur(page, args, context, selectedElement) {
+  const target = requireSelectedElement("blur", selectedElement);
+  await target.evaluate((element) => element.blur());
+}
+
+async function clear(page, args, context, selectedElement) {
+  const target = requireSelectedElement("clear", selectedElement);
+  await target.fill("");
+}
+
+async function check(page, args, context, selectedElement) {
+  const target = requireSelectedElement("check", selectedElement);
+  await target.check();
+}
+
+async function uncheck(page, args, context, selectedElement) {
+  const target = requireSelectedElement("uncheck", selectedElement);
+  await target.uncheck();
+}
+
+async function selectOption(page, args, context, selectedElement) {
+  const target = requireSelectedElement("selectOption", selectedElement);
+  const { named, positional } = parseNamedArgs(args);
+
+  const hasNamed =
+    named.value !== undefined
+    || named.label !== undefined
+    || named.index !== undefined;
+
+  if (hasNamed) {
+    const option = {};
+    if (named.value !== undefined) {
+      option.value = named.value;
+    }
+    if (named.label !== undefined) {
+      option.label = named.label;
+    }
+    if (named.index !== undefined) {
+      option.index = toNumber(named.index, "index");
+    }
+    await target.selectOption(option);
+    return;
+  }
+
+  if (positional.length === 0) {
+    throw new Error(
+      "`selectOption` requires an option value/label or key=value args (value=, label=, index=).",
+    );
+  }
+  await target.selectOption(positional[0]);
+}
+
+async function upload(page, args, context, selectedElement) {
+  const target = requireSelectedElement("upload", selectedElement);
+  const files = args.filter((token) => token.length > 0);
+  if (files.length === 0) {
+    throw new Error("`upload` requires one or more file paths.");
+  }
+  await target.setInputFiles(files);
+}
+
+async function waitFor(page, args, context, selectedElement) {
+  const { named, positional } = parseNamedArgs(args);
+  const state = named.state ?? positional[1] ?? "visible";
+  const timeout = parseTimeoutValue(named.timeoutMs ?? named.timeout ?? positional[2]);
+  const waitOptions = { state };
+  if (timeout !== undefined) {
+    waitOptions.timeout = timeout;
+  }
+
+  if (selectedElement) {
+    await selectedElement.waitFor(waitOptions);
+    return;
+  }
+
+  const selector = named.selector ?? positional[0];
+  if (!selector) {
+    throw new Error(
+      "`waitFor` requires a selector (or a selected element in a `select` block).",
+    );
+  }
+  await page.waitForSelector(selector, waitOptions);
+}
+
+async function assert(page, args, context, selectedElement) {
+  const [assertion, ...rest] = args;
+  if (!assertion) {
+    throw new Error("`assert` requires an assertion type.");
+  }
+
+  if (assertion === "url" || assertion === "urlExact") {
+    const expected = rest.join(" ");
+    if (!expected) {
+      throw new Error(`\`assert ${assertion}\` requires an expected URL string.`);
+    }
+    const currentUrl = page.url();
+    if (assertion === "url") {
+      if (!currentUrl.includes(expected)) {
+        throw new Error(`assert url failed: expected "${currentUrl}" to include "${expected}".`);
+      }
+      return;
+    }
+    if (currentUrl !== expected) {
+      throw new Error(`assert urlExact failed: expected "${expected}", got "${currentUrl}".`);
+    }
+    return;
+  }
+
+  const { named, positional } = parseNamedArgs(rest);
+  const timeout = parseTimeoutValue(named.timeoutMs ?? named.timeout);
+  const timeoutOptions = timeout === undefined ? {} : { timeout };
+
+  if (assertion === "exists") {
+    if (selectedElement) {
+      const count = await selectedElement.count();
+      if (count < 1) {
+        throw new Error("assert exists failed: selected element was not found.");
+      }
+      return;
+    }
+    const selector = named.selector ?? positional[0];
+    if (!selector) {
+      throw new Error("`assert exists` requires a selector when not in a `select` block.");
+    }
+    const count = await page.locator(selector).count();
+    if (count < 1) {
+      throw new Error(`assert exists failed: selector "${selector}" matched 0 elements.`);
+    }
+    return;
+  }
+
+  if (assertion === "visible") {
+    if (selectedElement) {
+      await selectedElement.waitFor({ state: "visible", ...timeoutOptions });
+      return;
+    }
+    const selector = named.selector ?? positional[0];
+    if (!selector) {
+      throw new Error("`assert visible` requires a selector when not in a `select` block.");
+    }
+    await page.waitForSelector(selector, { state: "visible", ...timeoutOptions });
+    return;
+  }
+
+  if (assertion === "hidden") {
+    if (selectedElement) {
+      await selectedElement.waitFor({ state: "hidden", ...timeoutOptions });
+      return;
+    }
+    const selector = named.selector ?? positional[0];
+    if (!selector) {
+      throw new Error("`assert hidden` requires a selector when not in a `select` block.");
+    }
+    await page.waitForSelector(selector, { state: "hidden", ...timeoutOptions });
+    return;
   }
+
+  if (assertion === "text") {
+    if (selectedElement) {
+      const expected = positional.join(" ");
+      if (!expected) {
+        throw new Error("`assert text` requires expected text.");
+      }
+      const actualText = (await selectedElement.textContent()) ?? "";
+      if (!actualText.includes(expected)) {
+        throw new Error(
+          `assert text failed: expected selected element text to include "${expected}", got "${actualText}".`,
+        );
+      }
+      return;
+    }
+    const selector = named.selector ?? positional[0];
+    const expected = positional.slice(1).join(" ");
+    if (!selector || !expected) {
+      throw new Error(
+        "`assert text` requires `<selector> <expected...>` when not in a `select` block.",
+      );
+    }
+    const actualText = (await page.locator(selector).first().textContent()) ?? "";
+    if (!actualText.includes(expected)) {
+      throw new Error(
+        `assert text failed: expected selector "${selector}" text to include "${expected}", got "${actualText}".`,
+      );
+    }
+    return;
+  }
+
+  throw new Error(
+    `Unsupported assert type "${assertion}". Supported: url, urlExact, exists, visible, hidden, text.`,
+  );
 }
 
 async function select(page, args) {
   const testId = args[0];
+  if (!testId) {
+    throw new Error("`select` requires a test id.");
+  }
   const hostElementLocator = page.getByTestId(testId);
   
   const interactiveElementLocator = hostElementLocator.locator(
@@ -109,30 +427,45 @@ export function createSteps(page, context) {
   }
 
   const actionHandlers = {
+    assert,
+    blur,
+    check,
+    clear,
     click,
     customEvent,
+    dblclick,
+    focus,
     goto,
+    hover,
     keypress,
     mouseDown,
     mouseUp,
     move,
     rclick,
+    rightMouseDown,
+    rightMouseUp,
     scroll,
-    rMouseDown,
-    rMouseUp,
+    setViewport,
     screenshot,
     select,
+    selectOption,
+    uncheck,
+    upload,
     wait,
+    waitFor,
     write,
   };
 
   async function executeSingleStep(stepString, selectedElement) {
-    const [command, ...args] = stepString.split(" ");
+    const { command, args } = parseStepCommand(stepString);
+    if (!command) {
+      return;
+    }
     const actionFn = actionHandlers[command];
     if (actionFn) {
       await actionFn(page, args, context, selectedElement);
     } else {
-      console.warn(`Unknown step command: "${command}"`);
+      throw new Error(`Unknown step command: "${command}"`);
     }
   }
 
@@ -143,7 +476,7 @@ export function createSteps(page, context) {
       } else if (typeof step === 'object' && step !== null) {
         const blockCommandString = Object.keys(step)[0];
         const nestedStepStrings = step[blockCommandString];
-        const [command, ...args] = blockCommandString.split(" ");
+        const { command, args } = parseStepCommand(blockCommandString);
 
         const blockFn = actionHandlers[command];
         if (blockFn) {
@@ -152,7 +485,7 @@ export function createSteps(page, context) {
             await executeSingleStep(nestedStep, selectedElement);
           }
         } else {
-          console.warn(`Unsupported block command: "${command}".`);
+          throw new Error(`Unsupported block command: "${command}".`);
         }
       }
     }

package/src/selector-filter.js

@@ -1,4 +1,5 @@
 import path from "path";
+import { stripViewportSuffix } from "./viewport.js";
 
 function toList(value) {
   if (value === undefined || value === null) return [];
@@ -114,7 +115,8 @@ export function filterGeneratedFilesBySelectors(generatedFiles, selectors, confi
 
 function toScreenshotItemKey(relativeScreenshotPath) {
   const normalized = normalizePathValue(relativeScreenshotPath).replace(/\.webp$/i, "");
-  return normalized.replace(/-\d{1,3}$/i, "");
+  const withoutOrdinal = normalized.replace(/-\d{1,3}$/i, "");
+  return stripViewportSuffix(withoutOrdinal);
 }
 
 export function filterRelativeScreenshotPathsBySelectors(relativePaths, selectors, configSections = []) {

package/src/step-commands.js

@@ -0,0 +1,33 @@
+export const STEP_COMMANDS = Object.freeze([
+  "assert",
+  "blur",
+  "check",
+  "clear",
+  "click",
+  "customEvent",
+  "dblclick",
+  "focus",
+  "goto",
+  "hover",
+  "keypress",
+  "mouseDown",
+  "mouseUp",
+  "move",
+  "rclick",
+  "rightMouseDown",
+  "rightMouseUp",
+  "setViewport",
+  "screenshot",
+  "scroll",
+  "select",
+  "selectOption",
+  "uncheck",
+  "upload",
+  "wait",
+  "waitFor",
+  "write",
+]);
+
+export const BLOCK_COMMANDS = Object.freeze([
+  "select",
+]);

package/src/validation.js

@@ -1,3 +1,5 @@
+import { normalizeViewportField } from "./viewport.js";
+
 function isPlainObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -223,6 +225,7 @@ export function validateVtConfig(vtConfig, sourcePath = "rettangoli.config.yaml"
   validateOptionalNumber(vtConfig.concurrency, "vt.concurrency", { integer: true, min: 1 });
   validateOptionalNumber(vtConfig.timeout, "vt.timeout", { integer: true, min: 1 });
   validateOptionalString(vtConfig.waitEvent, "vt.waitEvent");
+  normalizeViewportField(vtConfig.viewport, "vt.viewport");
   validateOptionalNumber(vtConfig.colorThreshold, "vt.colorThreshold", { min: 0, max: 1 });
   validateOptionalNumber(vtConfig.diffThreshold, "vt.diffThreshold", { min: 0, max: 100 });
   assertNoLegacyCaptureFields(vtConfig, sourcePath);
@@ -252,6 +255,7 @@ export function validateFrontMatter(frontMatter, specPath) {
   validateOptionalString(frontMatter.url, `${specPath}: frontMatter.url`);
   validateOptionalString(frontMatter.waitEvent, `${specPath}: frontMatter.waitEvent`);
   validateOptionalString(frontMatter.waitSelector, `${specPath}: frontMatter.waitSelector`);
+  normalizeViewportField(frontMatter.viewport, `${specPath}: frontMatter.viewport`);
   validateOptionalEnum(
     frontMatter.waitStrategy,
     `${specPath}: frontMatter.waitStrategy`,

package/src/viewport.js

@@ -0,0 +1,99 @@
+const VIEWPORT_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+export const DEFAULT_VIEWPORT = Object.freeze({
+  width: 1280,
+  height: 720,
+});
+
+function valueType(value) {
+  if (Array.isArray(value)) return "array";
+  if (value === null) return "null";
+  return typeof value;
+}
+
+function assert(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+function validateViewportEntry(entry, path) {
+  assert(
+    entry !== null && typeof entry === "object" && !Array.isArray(entry),
+    `"${path}" must be an object, got ${valueType(entry)}.`,
+  );
+
+  assert(
+    typeof entry.id === "string" && entry.id.trim().length > 0,
+    `"${path}.id" is required and must be a non-empty string.`,
+  );
+  assert(
+    VIEWPORT_ID_PATTERN.test(entry.id),
+    `"${path}.id" must contain only letters, numbers, "-" or "_".`,
+  );
+  assert(
+    typeof entry.width === "number" && Number.isInteger(entry.width) && entry.width >= 1,
+    `"${path}.width" must be an integer >= 1.`,
+  );
+  assert(
+    typeof entry.height === "number" && Number.isInteger(entry.height) && entry.height >= 1,
+    `"${path}.height" must be an integer >= 1.`,
+  );
+
+  return {
+    id: entry.id,
+    width: entry.width,
+    height: entry.height,
+  };
+}
+
+export function normalizeViewportField(rawViewport, path = "viewport") {
+  if (rawViewport === undefined || rawViewport === null) {
+    return undefined;
+  }
+
+  const rawEntries = Array.isArray(rawViewport) ? rawViewport : [rawViewport];
+  assert(rawEntries.length > 0, `"${path}" cannot be an empty array.`);
+
+  const entries = rawEntries.map((entry, index) =>
+    validateViewportEntry(entry, `${path}[${index}]`),
+  );
+
+  const seen = new Map();
+  entries.forEach((entry, index) => {
+    const canonicalId = entry.id.toLowerCase();
+    const existingIndex = seen.get(canonicalId);
+    assert(
+      existingIndex === undefined,
+      `"${path}[${index}].id" duplicates "${path}[${existingIndex}].id" (case-insensitive).`,
+    );
+    seen.set(canonicalId, index);
+  });
+
+  return entries;
+}
+
+export function resolveViewports(frontMatterViewport, configViewport) {
+  const selected = frontMatterViewport ?? configViewport;
+  if (selected === undefined || selected === null) {
+    return [
+      {
+        id: null,
+        width: DEFAULT_VIEWPORT.width,
+        height: DEFAULT_VIEWPORT.height,
+      },
+    ];
+  }
+  return normalizeViewportField(selected, "viewport");
+}
+
+export function appendViewportToBaseName(baseName, viewportId) {
+  if (!viewportId) {
+    return baseName;
+  }
+  return `${baseName}--${viewportId}`;
+}
+
+export function stripViewportSuffix(itemKey) {
+  return itemKey.replace(/--[A-Za-z0-9_-]+$/, "");
+}