@rettangoli/vt 0.0.1 → 0.0.2-rc2

package/README.md

@@ -1,3 +1,98 @@
 
 # Rettangoli Visual Testing
 
+A visual testing framework for UI components using Playwright and screenshot comparison. Perfect for regression testing and ensuring UI consistency across changes.
+
+**In production**, this package is typically used through the `rtgl` CLI tool. For development and testing of this package itself, you should call the local CLI directly.
+
+## Features
+
+- **Screenshot Generation** - Automatically generate screenshots from HTML specifications
+- **Visual Comparison** - Compare screenshots to detect visual changes
+- **Test Reports** - Generate detailed reports with diff highlights
+- **Playwright Integration** - Uses Playwright for reliable cross-browser testing
+- **Template System** - Liquid templates for flexible HTML generation
+- **Configuration** - YAML-based configuration for easy customization
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+ or Bun
+- Playwright browsers (automatically installed)
+
+### Setup
+
+1. **Install dependencies**:
+```bash
+bun install
+```
+
+2. **Install Playwright browsers** (if not already installed):
+```bash
+npx playwright install
+```
+
+### Project Structure
+
+```
+src/
+├── cli/
+│   ├── generate.js    # Generate screenshots from specifications
+│   ├── report.js      # Generate visual comparison reports
+│   ├── accept.js      # Accept screenshot changes as new reference
+│   ├── templates/     # HTML templates for reports
+│   └── static/        # Static assets (CSS, etc.)
+├── common.js          # Shared utilities and functions
+└── index.js           # Main export (empty - CLI focused)
+```
+
+### Core Functionality
+
+The visual testing framework provides three main commands:
+
+#### 1. Generate (`vt generate`)
+- Reads HTML specifications from `vt/specs/` directory
+- Generates screenshots using Playwright
+- Saves candidate screenshots for comparison
+- Creates a static site for viewing results
+
+#### 2. Report (`vt report`)
+- Compares candidate screenshots with reference screenshots
+- Generates visual diff reports highlighting changes
+- Creates an HTML report with before/after comparisons
+- Uses `looks-same` library for pixel-perfect comparison
+
+#### 3. Accept (`vt accept`)
+- Accepts candidate screenshots as new reference images
+- Updates the golden/reference screenshot directory
+- Used when visual changes are intentional
+
+### Configuration
+
+The framework reads configuration from `rettangoli.config.yaml`:
+
+```yaml
+vt:
+  port: 3001
+  screenshotWaitTime: 500
+  skipScreenshots: false
+```
+
+### Testing Your Changes
+
+**Note**: This package doesn't include example files in its directory. For testing during development, use examples from other packages (like `rettangoli-ui`) and call the CLI directly:
+
+```bash
+# Call the local CLI directly for development
+node ../rettangoli-cli/cli.js vt generate
+node ../rettangoli-cli/cli.js vt report
+node ../rettangoli-cli/cli.js vt accept
+```
+
+**Production usage** (when rtgl is installed globally):
+```bash
+rtgl vt generate
+rtgl vt report
+rtgl vt accept
+```

package/package.json

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

package/src/cli/accept.js

@@ -34,10 +34,10 @@ async function copyWebpFiles(sourceDir, destDir) {
  */
 async function acceptReference(options = {}) {
   const {
-    vizPath = "./viz",
+    vtPath = "./vt",
   } = options;
 
-  const referenceDir = join(vizPath, "reference");
+  const referenceDir = join(vtPath, "reference");
   const siteOutputPath = join(".rettangoli", "vt", "_site");
   const candidateDir = join(siteOutputPath, "candidate");
 

package/src/cli/generate.js

@@ -19,12 +19,12 @@ const libraryStaticPath = new URL('./static', import.meta.url).pathname;
 async function main(options) {
   const {
     skipScreenshots = false,
-    vizPath = "./vt",
+    vtPath = "./vt",
     screenshotWaitTime = 0,
     port = 3001
   } = options;
 
-  const specsPath = join(vizPath, "specs");
+  const specsPath = join(vtPath, "specs");
   const mainConfigPath = "rettangoli.config.yaml";
   const siteOutputPath = join(".rettangoli", "vt", "_site");
   const candidatePath = join(siteOutputPath, "candidate");
@@ -46,13 +46,13 @@ async function main(options) {
   await cp(libraryStaticPath, siteOutputPath, { recursive: true });
   
   // Copy user's static files if they exist
-  const userStaticPath = join(vizPath, "static");
+  const userStaticPath = join(vtPath, "static");
   if (existsSync(userStaticPath)) {
     await cp(userStaticPath, siteOutputPath, { recursive: true });
   }
 
   // Check for local templates first, fallback to library templates
-  const localTemplatesPath = join(vizPath, "templates");
+  const localTemplatesPath = join(vtPath, "templates");
   const defaultTemplatePath = existsSync(join(localTemplatesPath, "default.html"))
     ? join(localTemplatesPath, "default.html")
     : join(libraryTemplatesPath, "default.html");
@@ -80,7 +80,7 @@ async function main(options) {
     // Start web server from site output path to serve both /public and /candidate
     const server = startWebServer(
       siteOutputPath,
-      vizPath,
+      vtPath,
       port
     );
     try {
@@ -94,7 +94,7 @@ async function main(options) {
       );
     } finally {
       // Stop server
-      server.stop();
+      server.close();
       console.log("Server stopped");
     }
   }

package/src/cli/report.js

@@ -79,11 +79,11 @@ async function generateReport({ results, templatePath, outputPath }) {
 }
 
 async function main(options = {}) {
-  const { vizPath = "./viz" } = options;
+  const { vtPath = "./vt" } = options;
 
   const siteOutputPath = path.join(".rettangoli", "vt", "_site");
   const candidateDir = path.join(siteOutputPath, "candidate");
-  const originalReferenceDir = path.join(vizPath, "reference");
+  const originalReferenceDir = path.join(vtPath, "reference");
   const siteReferenceDir = path.join(siteOutputPath, "reference");
   const templatePath = path.join(libraryTemplatesPath, "report.html");
   const outputPath = path.join(siteOutputPath, "report.html");

package/src/common.js

@@ -5,8 +5,10 @@ import {
   writeFileSync,
   mkdirSync,
   existsSync,
+  unlinkSync,
 } from "fs";
 import { join, dirname, resolve, extname } from "path";
+import http from "http";
 import { load as loadYaml } from "js-yaml";
 import { Liquid } from "liquidjs";
 import { chromium } from "playwright";
@@ -181,49 +183,47 @@ async function generateHtml(specsDir, templatePath, outputDir) {
  * Start a web server to serve static files
  */
 function startWebServer(artifactsDir, staticDir, port) {
-  const server = Bun.serve({
-    port: port,
-    fetch(req) {
-      const url = new URL(req.url);
-      let path = url.pathname;
-
-      // Default to index.html for root path
-      if (path === "/") {
-        path = "/index.html";
-      }
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url, `http://localhost:${port}`);
+    let path = url.pathname;
 
-      // Remove leading slash for file path
-      const filePath = path.startsWith("/") ? path.slice(1) : path;
+    // Default to index.html for root path
+    if (path === "/") {
+      path = "/index.html";
+    }
 
-      // Try to serve from artifacts directory first
-      const artifactsPath = join(artifactsDir, filePath);
-      if (existsSync(artifactsPath) && statSync(artifactsPath).isFile()) {
-        const fileContent = readFileSync(artifactsPath);
-        const contentType = getContentType(artifactsPath);
-        return new Response(fileContent, {
-          headers: { "Content-Type": contentType },
-        });
-      }
+    // Remove leading slash for file path
+    const filePath = path.startsWith("/") ? path.slice(1) : path;
+
+    // Try to serve from artifacts directory first
+    const artifactsPath = join(artifactsDir, filePath);
+    if (existsSync(artifactsPath) && statSync(artifactsPath).isFile()) {
+      const fileContent = readFileSync(artifactsPath);
+      const contentType = getContentType(artifactsPath);
+      res.writeHead(200, { "Content-Type": contentType });
+      res.end(fileContent);
+      return;
+    }
 
-      // Then try to serve from static directory
-      const staticPath = join(staticDir, filePath);
-      if (existsSync(staticPath) && statSync(staticPath).isFile()) {
-        const fileContent = readFileSync(staticPath);
-        const contentType = getContentType(staticPath);
-        return new Response(fileContent, {
-          headers: { "Content-Type": contentType },
-        });
-      }
+    // Then try to serve from static directory
+    const staticPath = join(staticDir, filePath);
+    if (existsSync(staticPath) && statSync(staticPath).isFile()) {
+      const fileContent = readFileSync(staticPath);
+      const contentType = getContentType(staticPath);
+      res.writeHead(200, { "Content-Type": contentType });
+      res.end(fileContent);
+      return;
+    }
 
-      // If not found in either directory, return 404
-      return new Response("Not Found", {
-        status: 404,
-        headers: { "Content-Type": "text/plain" },
-      });
-    },
+    // If not found in either directory, return 404
+    res.writeHead(404, { "Content-Type": "text/plain" });
+    res.end("Not Found");
   });
 
-  console.log(`Server started at http://localhost:${port}`);
+  server.listen(port, () => {
+    console.log(`Server started at http://localhost:${port}`);
+  });
+  
   return server;
 }
 
@@ -311,7 +311,7 @@ async function takeScreenshots(
 
           // Remove temporary PNG file
           if (existsSync(tempPngPath)) {
-            await import('fs').then(fs => fs.promises.unlink(tempPngPath));
+            unlinkSync(tempPngPath);
           }
 
           // example instructions:
@@ -350,7 +350,7 @@ async function takeScreenshots(
 
                 // Remove temporary PNG file
                 if (existsSync(tempAdditionalPngPath)) {
-                  await import('fs').then(fs => fs.promises.unlink(tempAdditionalPngPath));
+                  unlinkSync(tempAdditionalPngPath);
                 }
 
                 console.log(

package/src/cli.js

@@ -1,36 +0,0 @@
-import { Command } from 'commander';
-import generate from './generate.js';
-import accept from './accept.js'; 
-import report from './report.js';
-
-const program = new Command();
-
-program
-  .version('0.0.1')
-  .description('Rettangoli visualization CLI');
-
-program
-  .command('generate')
-  .description('Generate visualizations')
-  .option('--skip-screenshots', 'Skip screenshot generation')
-  .option('--screenshot-wait-time <time>', 'Wait time between screenshots', '0')
-  .option('--viz-path <path>', 'Path to the viz directory', './viz')
-  .action((options) => {
-    generate(options);
-  });
-
-program
-  .command('report')
-  .description('Create reports')
-  .action(() => {
-    report();
-  });
-
-program
-  .command('accept')
-  .description('Accept changes')
-  .action(() => {
-    accept();
-  });
-
-program.parse(process.argv);