@rettangoli/vt 1.0.1 → 1.0.3

package/README.md

@@ -126,6 +126,7 @@ Step action reference:
 
 - `docs/step-actions.md`
 - canonical format is structured action objects (`- action: ...`); legacy one-line string steps are not supported.
+- `action: select` accepts exactly one of `testId` or `selector` for interaction targeting.
 - `assert` supports `js` deep-equal checks for object/array values.
 
 Screenshot naming:
@@ -141,15 +142,15 @@ 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-rc27
+docker pull han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.10
 ```
 
 Run commands against a local project:
 
 ```bash
-docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc27 rtgl vt screenshot
-docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc27 rtgl vt report
-docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc27 rtgl vt accept
+docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.10 rtgl vt screenshot
+docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.10 rtgl vt report
+docker run --rm -v "$(pwd):/workspace" han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.10 rtgl vt accept
 ```
 
 Note:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rettangoli/vt",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Rettangoli Visual Testing",
   "type": "module",
   "repository": {

package/src/cli/templates/index.html

@@ -60,8 +60,8 @@
         {% for file in files %}
         <rtgl-view w="f">
           <a style="display: contents; text-decoration: none; color: inherit;"
-            href="#{{ file.frontMatter.title | slug }}">
-            <rtgl-text id="{{ file.frontMatter.title | slug }}" s="h3">{{ file.frontMatter.title | default: file.path
+            href="#{{ file.anchorId }}">
+            <rtgl-text id="{{ file.anchorId }}" s="h3">{{ file.frontMatter.title | default: file.path
               }}</rtgl-text>
           </a>
 

package/src/common.js

@@ -15,7 +15,7 @@ import path from "path";
 import { validateFiniteNumber, validateFrontMatter } from "./validation.js";
 import { createCaptureTasks } from "./capture/spec-loader.js";
 import { runCaptureScheduler } from "./capture/capture-scheduler.js";
-import { deriveSectionPageKey } from "./section-page-key.js";
+import { deriveAnchorId, deriveSectionPageKey } from "./section-page-key.js";
 
 const removeExtension = (filePath) => filePath.replace(/\.[^/.]+$/, "");
 
@@ -44,10 +44,9 @@ async function readYaml(filePath) {
   }
 }
 
-// Add custom filter to convert string to lowercase and replace spaces with hyphens
-engine.registerFilter("slug", (value) => {
-  if (typeof value !== "string") return "";
-  return value.toLowerCase().replace(/\s+/g, "-");
+// Add custom filter to derive slug-safe ids for URLs and anchors.
+engine.registerFilter("slug", (value, fallbackValue) => {
+  return deriveAnchorId(value, fallbackValue);
 });
 
 // Add custom filter to remove file extension
@@ -416,13 +415,18 @@ function generateOverview(data, templatePath, outputPath, configData) {
       try {
         renderedContent = engine.parseAndRenderSync(templateContent, {
           ...configData,
-          files: data.filter((file) => {
-            const filePath = path.normalize(file.path);
-            const sectionPath = path.normalize(section.files);
-            // Check if file is in the folder or any subfolder
-            const fileDir = path.dirname(filePath);
-            return fileDir === sectionPath || fileDir.startsWith(sectionPath + path.sep);
-          }),
+          files: data
+            .filter((file) => {
+              const filePath = path.normalize(file.path);
+              const sectionPath = path.normalize(section.files);
+              // Check if file is in the folder or any subfolder
+              const fileDir = path.dirname(filePath);
+              return fileDir === sectionPath || fileDir.startsWith(sectionPath + path.sep);
+            })
+            .map((file) => ({
+              ...file,
+              anchorId: deriveAnchorId(file.frontMatter?.title, removeExtension(file.path)),
+            })),
           currentSection: section,
           sidebarItems: encodeURIComponent(JSON.stringify(sidebarItems)),
         });

package/src/createSteps.js

@@ -180,6 +180,27 @@ function requireStructuredString(stepObject, key, actionName) {
   return value;
 }
 
+function resolveStructuredSelectTarget(stepObject, actionName) {
+  const hasTestId = Object.prototype.hasOwnProperty.call(stepObject, "testId");
+  const hasSelector = Object.prototype.hasOwnProperty.call(stepObject, "selector");
+
+  if (hasTestId === hasSelector) {
+    throw new Error(`Structured action "${actionName}" requires exactly one of \`testId\` or \`selector\`.`);
+  }
+
+  if (hasTestId) {
+    return {
+      type: "testId",
+      value: requireStructuredString(stepObject, "testId", actionName),
+    };
+  }
+
+  return {
+    type: "selector",
+    value: requireStructuredString(stepObject, "selector", actionName),
+  };
+}
+
 function requireStructuredNumber(stepObject, key, actionName) {
   const value = stepObject[key];
   if (typeof value !== "number" || !Number.isFinite(value)) {
@@ -224,13 +245,13 @@ function normalizeStructuredActionStep(stepObject) {
   }
 
   if (action === "select") {
-    assertStructuredKeys(stepObject, new Set(["action", "testId", "steps"]), action);
-    const testId = requireStructuredString(stepObject, "testId", action);
+    assertStructuredKeys(stepObject, new Set(["action", "testId", "selector", "steps"]), action);
+    const target = resolveStructuredSelectTarget(stepObject, action);
     if (!Array.isArray(stepObject.steps)) {
       throw new Error('Structured action "select" requires array `steps`.');
     }
     const nestedSteps = stepObject.steps.map((nestedStep) => normalizeStepValue(nestedStep));
-    return { kind: "block", command: "select", args: [testId], nestedSteps };
+    return { kind: "block", command: "select", args: [`${target.type}=${target.value}`], nestedSteps };
   }
 
   if (action === "click" || action === "dblclick" || action === "hover" || action === "rclick") {
@@ -828,22 +849,32 @@ async function assertStructured(page, assertionConfig, selectedElement) {
 }
 
 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(
-    'input, textarea, button, select, a'
-  ).first();
-  
+  const { named, positional } = parseNamedArgs(args);
+  const testId = typeof named.testId === "string" && named.testId.length > 0
+    ? named.testId
+    : positional[0];
+  const selector = typeof named.selector === "string" && named.selector.length > 0
+    ? named.selector
+    : undefined;
+
+  if ((testId ? 1 : 0) + (selector ? 1 : 0) !== 1) {
+    throw new Error("`select` requires exactly one target: `testId` or `selector`.");
+  }
+
+  const hostElementLocator = selector
+    ? page.locator(selector)
+    : page.getByTestId(testId);
+
+  const interactiveElementLocator = hostElementLocator
+    .locator('input, textarea, button, select, a')
+    .first();
+
   const count = await interactiveElementLocator.count();
-  
+
   if (count > 0) {
     return interactiveElementLocator;
   }
-  
+
   return hostElementLocator;
 }
 

package/src/report/report-render.js

@@ -1,11 +1,11 @@
 import fs from "fs";
 import { Liquid } from "liquidjs";
+import { deriveAnchorId } from "../section-page-key.js";
 
 const engine = new Liquid();
 
-engine.registerFilter("slug", (value) => {
-  if (typeof value !== "string") return "";
-  return value.toLowerCase().replace(/\s+/g, "-");
+engine.registerFilter("slug", (value, fallbackValue) => {
+  return deriveAnchorId(value, fallbackValue);
 });
 
 export async function renderHtmlReport({ results, templatePath, outputPath }) {

package/src/section-page-key.js

@@ -5,10 +5,18 @@ function normalizeString(value) {
   return value.trim();
 }
 
-export function deriveSectionPageKey(sectionLike) {
-  return normalizeString(sectionLike?.title)
+export function derivePageKey(value) {
+  return normalizeString(value)
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/-+/g, "-")
     .replace(/^-+|-+$/g, "");
 }
+
+export function deriveSectionPageKey(sectionLike) {
+  return derivePageKey(sectionLike?.title) || derivePageKey(sectionLike?.files);
+}
+
+export function deriveAnchorId(value, fallbackValue = "") {
+  return derivePageKey(value) || derivePageKey(fallbackValue);
+}

package/src/validation.js

@@ -136,7 +136,7 @@ function assertDerivableSectionPageKey(sectionLike, path) {
   const pageKey = deriveSectionPageKey(sectionLike);
   assert(
     pageKey.length > 0,
-    `"${path}" must contain at least one letter or number.`,
+    `"${path}" must produce a page key from title or files.`,
   );
 }
 
@@ -169,14 +169,14 @@ function validateSection(section, index) {
 
       assert(typeof item.title === "string" && item.title.trim().length > 0, `"${itemPath}.title" is required.`);
       assert(typeof item.files === "string" && item.files.trim().length > 0, `"${itemPath}.files" is required.`);
-      assertDerivableSectionPageKey(item, `${itemPath}.title`);
+      assertDerivableSectionPageKey(item, itemPath);
     });
     return;
   }
 
   validateOptionalString(section.files, `${sectionPath}.files`);
   assert(typeof section.files === "string" && section.files.trim().length > 0, `"${sectionPath}.files" is required.`);
-  assertDerivableSectionPageKey(section, `${sectionPath}.title`);
+  assertDerivableSectionPageKey(section, sectionPath);
 }
 
 function collectSectionPageKeys(vtConfig) {
@@ -273,11 +273,18 @@ function validateStructuredActionStep(step, stepPath) {
   }
 
   if (action === "select") {
-    assertNoUnknownStepKeys(step, stepPath, new Set(["action", "testId", "steps"]));
+    assertNoUnknownStepKeys(step, stepPath, new Set(["action", "testId", "selector", "steps"]));
     validateOptionalString(step.testId, `${stepPath}.testId`);
+    validateOptionalString(step.selector, `${stepPath}.selector`);
     assert(
-      typeof step.testId === "string" && step.testId.trim().length > 0,
-      `"${stepPath}.testId" is required for action=select.`,
+      (
+        typeof step.testId === "string"
+        && step.testId.trim().length > 0
+      ) !== (
+        typeof step.selector === "string"
+        && step.selector.trim().length > 0
+      ),
+      `"${stepPath}" for action=select requires exactly one of "testId" or "selector".`,
     );
     assert(Array.isArray(step.steps), `"${stepPath}.steps" must be an array for action=select.`);
     step.steps.forEach((nestedStep, nestedIndex) => {