@reshotdev/screenshot 0.0.1-beta.0

package/src/lib/output-path-template.js

@@ -0,0 +1,318 @@
+// output-path-template.js - Output path templating with variable interpolation
+// Allows developers to define custom output paths: "./docs/assets/{{locale}}/{{name}}.png"
+
+const path = require("path");
+const fs = require("fs-extra");
+
+/**
+ * Supported template variables:
+ * - {{scenario}} / {{scenarioKey}} - Scenario key
+ * - {{scenarioName}} - Human-readable scenario name
+ * - {{name}} / {{assetName}} - Asset/screenshot name
+ * - {{step}} / {{stepIndex}} - Step index (1-based)
+ * - {{locale}} - Current locale from variant (e.g., "en", "ko")
+ * - {{role}} - Current role from variant (e.g., "admin", "viewer")
+ * - {{theme}} - Current theme from variant (e.g., "light", "dark")
+ * - {{variant}} - Full variant slug (e.g., "locale-en_role-admin_theme-dark")
+ * - {{timestamp}} - ISO timestamp for this run
+ * - {{date}} - Date portion (YYYY-MM-DD)
+ * - {{time}} - Time portion (HH-MM-SS)
+ * - {{viewport}} - Viewport preset name or WxH (e.g., "desktop", "1280x720")
+ * - {{viewportWidth}} - Viewport width
+ * - {{viewportHeight}} - Viewport height
+ * - {{ext}} / {{extension}} - File extension (default: "png")
+ * 
+ * Custom dimension variables are also supported automatically from variant config.
+ */
+
+/**
+ * Default output template when none specified
+ */
+const DEFAULT_OUTPUT_TEMPLATE = ".reshot/output/{{scenario}}/{{timestamp}}/{{variant}}/{{name}}.{{ext}}";
+
+/**
+ * Template presets for common use cases
+ */
+const TEMPLATE_PRESETS = {
+  default: DEFAULT_OUTPUT_TEMPLATE,
+  
+  // Flat structure - all assets in one folder per scenario
+  flat: ".reshot/output/{{scenario}}/{{name}}_{{variant}}.{{ext}}",
+  
+  // Locale-first organization (good for i18n documentation)
+  "locale-first": "./docs/{{locale}}/{{scenario}}/{{name}}.{{ext}}",
+  
+  // Versioned by timestamp
+  versioned: ".reshot/output/{{scenario}}/{{date}}_{{time}}/{{variant}}/{{name}}.{{ext}}",
+  
+  // Simple docs structure
+  docs: "./docs/assets/{{scenario}}/{{name}}.{{ext}}",
+  
+  // Variant-focused (good for matrix testing)
+  "variant-matrix": ".reshot/output/{{scenario}}/{{locale}}/{{role}}/{{theme}}/{{name}}.{{ext}}",
+  
+  // GitHub Pages / Static site friendly
+  "static-site": "./public/screenshots/{{locale}}/{{scenario}}/{{name}}.{{ext}}",
+  
+  // CI/CD artifacts
+  ci: "./artifacts/screenshots/{{scenario}}/{{viewport}}/{{variant}}/{{name}}.{{ext}}",
+};
+
+/**
+ * Parse a template string and extract all variable names
+ * @param {string} template - Template string with {{variable}} placeholders
+ * @returns {string[]} Array of variable names found in template
+ */
+function parseTemplateVariables(template) {
+  const regex = /\{\{([a-zA-Z][a-zA-Z0-9_]*)\}\}/g;
+  const variables = [];
+  let match;
+  
+  while ((match = regex.exec(template)) !== null) {
+    if (!variables.includes(match[1])) {
+      variables.push(match[1]);
+    }
+  }
+  
+  return variables;
+}
+
+/**
+ * Build context object from capture state
+ * @param {Object} options - Capture context options
+ * @returns {Object} Template context with all available variables
+ */
+function buildTemplateContext(options = {}) {
+  const {
+    scenario = {},
+    assetName = "screenshot",
+    stepIndex = 0,
+    variant = {},
+    timestamp = null,
+    viewport = { width: 1280, height: 720 },
+    viewportPresetName = null,
+    extension = "png",
+    customVariables = {},
+  } = options;
+
+  // Handle timestamp - can be a Date, ISO string, or pre-formatted string (YYYY-MM-DD_HH-MM-SS)
+  let isoTimestamp;
+  let datePart;
+  let timePart;
+  
+  if (timestamp) {
+    // Check if timestamp is already in our formatted format (YYYY-MM-DD_HH-MM-SS)
+    const formattedMatch = String(timestamp).match(/^(\d{4}-\d{2}-\d{2})_(\d{2}-\d{2}-\d{2})$/);
+    if (formattedMatch) {
+      // Already formatted, use directly
+      isoTimestamp = timestamp;
+      datePart = formattedMatch[1];
+      timePart = formattedMatch[2];
+    } else {
+      // Try to parse as Date
+      const now = new Date(timestamp);
+      if (!isNaN(now.getTime())) {
+        isoTimestamp = now.toISOString().replace(/[:.]/g, "-").replace("T", "_").slice(0, 19);
+        [datePart, timePart] = isoTimestamp.split("_");
+      } else {
+        // Fall back to current time
+        const fallback = new Date();
+        isoTimestamp = fallback.toISOString().replace(/[:.]/g, "-").replace("T", "_").slice(0, 19);
+        [datePart, timePart] = isoTimestamp.split("_");
+      }
+    }
+  } else {
+    // No timestamp provided, use current time
+    const now = new Date();
+    isoTimestamp = now.toISOString().replace(/[:.]/g, "-").replace("T", "_").slice(0, 19);
+    [datePart, timePart] = isoTimestamp.split("_");
+  }
+
+  // Build variant slug from all variant dimensions
+  const variantSlug = Object.entries(variant)
+    .filter(([_, v]) => v != null)
+    .map(([k, v]) => `${k}-${v}`)
+    .join("_") || "default";
+
+  // Core context
+  const context = {
+    // Scenario info
+    scenario: scenario.key || "unknown",
+    scenarioKey: scenario.key || "unknown",
+    scenarioName: (scenario.name || scenario.key || "unknown").replace(/[^a-zA-Z0-9-_]/g, "-"),
+    
+    // Asset info
+    name: assetName,
+    assetName: assetName,
+    step: String(stepIndex + 1), // 1-based for human readability
+    stepIndex: String(stepIndex),
+    
+    // Variant info - individual dimensions
+    locale: variant.locale || "default",
+    role: variant.role || "default",
+    theme: variant.theme || "default",
+    variant: variantSlug,
+    
+    // Timestamp info
+    timestamp: isoTimestamp,
+    date: datePart,
+    time: timePart,
+    
+    // Viewport info
+    viewport: viewportPresetName || `${viewport.width}x${viewport.height}`,
+    viewportWidth: String(viewport.width),
+    viewportHeight: String(viewport.height),
+    
+    // Extension
+    ext: extension,
+    extension: extension,
+  };
+
+  // Add any custom variant dimensions dynamically
+  for (const [key, value] of Object.entries(variant)) {
+    if (!context[key]) {
+      context[key] = String(value);
+    }
+  }
+
+  // Add any custom variables provided
+  for (const [key, value] of Object.entries(customVariables)) {
+    context[key] = String(value);
+  }
+
+  return context;
+}
+
+/**
+ * Resolve a template string with context values
+ * @param {string} template - Template string or preset name
+ * @param {Object} context - Context object with variable values
+ * @returns {string} Resolved path string
+ */
+function resolveTemplate(template, context = {}) {
+  // Check if template is a preset name
+  const actualTemplate = TEMPLATE_PRESETS[template] || template || DEFAULT_OUTPUT_TEMPLATE;
+  
+  // Replace all {{variable}} placeholders
+  let resolved = actualTemplate.replace(/\{\{([a-zA-Z][a-zA-Z0-9_]*)\}\}/g, (match, varName) => {
+    const value = context[varName];
+    if (value !== undefined && value !== null) {
+      return String(value);
+    }
+    // Unknown variables are replaced with empty string
+    return "";
+  });
+
+  // Clean up any double slashes from empty replacements
+  resolved = resolved.replace(/\/+/g, "/");
+  
+  // Remove leading ./ if present and path is absolute
+  if (path.isAbsolute(resolved.replace(/^\.\//, ""))) {
+    resolved = resolved.replace(/^\.\//, "");
+  }
+
+  return resolved;
+}
+
+/**
+ * Resolve output path for a capture
+ * @param {string} templateOrPreset - Template string, preset name, or null for default
+ * @param {Object} options - Capture context options (see buildTemplateContext)
+ * @returns {string} Fully resolved output file path
+ */
+function resolveOutputPath(templateOrPreset, options = {}) {
+  const context = buildTemplateContext(options);
+  return resolveTemplate(templateOrPreset, context);
+}
+
+/**
+ * Resolve output directory (without filename) for a capture run
+ * Useful for creating directories before capture
+ * @param {string} templateOrPreset - Template string or preset name
+ * @param {Object} options - Capture context options
+ * @returns {string} Resolved directory path
+ */
+function resolveOutputDirectory(templateOrPreset, options = {}) {
+  const fullPath = resolveOutputPath(templateOrPreset, options);
+  return path.dirname(fullPath);
+}
+
+/**
+ * Validate a template string
+ * @param {string} template - Template string to validate
+ * @returns {{ valid: boolean, error?: string, variables?: string[] }}
+ */
+function validateTemplate(template) {
+  if (!template || typeof template !== "string") {
+    return { valid: false, error: "Template must be a non-empty string" };
+  }
+
+  // Check for valid template syntax
+  const variables = parseTemplateVariables(template);
+  
+  // Check for unbalanced braces
+  const openBraces = (template.match(/\{\{/g) || []).length;
+  const closeBraces = (template.match(/\}\}/g) || []).length;
+  if (openBraces !== closeBraces) {
+    return { valid: false, error: "Unbalanced template braces - check {{}} syntax" };
+  }
+
+  // Check for invalid variable syntax
+  const invalidMatches = template.match(/\{\{[^}]*[^a-zA-Z0-9_}][^}]*\}\}/g);
+  if (invalidMatches) {
+    return { 
+      valid: false, 
+      error: `Invalid variable syntax: ${invalidMatches.join(", ")}. Variables must be alphanumeric with underscores.`
+    };
+  }
+
+  // Must include at least {{name}} or {{assetName}} to be useful
+  if (!variables.includes("name") && !variables.includes("assetName")) {
+    return {
+      valid: true,
+      warning: "Template should include {{name}} or {{assetName}} to distinguish different captures",
+      variables,
+    };
+  }
+
+  return { valid: true, variables };
+}
+
+/**
+ * Get list of available template presets
+ * @returns {Array<{name: string, template: string, description: string}>}
+ */
+function getTemplatePresets() {
+  return [
+    { name: "default", template: TEMPLATE_PRESETS.default, description: "Standard versioned output" },
+    { name: "flat", template: TEMPLATE_PRESETS.flat, description: "Flat structure with variant suffix" },
+    { name: "locale-first", template: TEMPLATE_PRESETS["locale-first"], description: "Organized by locale for i18n docs" },
+    { name: "versioned", template: TEMPLATE_PRESETS.versioned, description: "Date-based versioning" },
+    { name: "docs", template: TEMPLATE_PRESETS.docs, description: "Simple docs asset structure" },
+    { name: "variant-matrix", template: TEMPLATE_PRESETS["variant-matrix"], description: "Hierarchical by variant dimensions" },
+    { name: "static-site", template: TEMPLATE_PRESETS["static-site"], description: "GitHub Pages / static site friendly" },
+    { name: "ci", template: TEMPLATE_PRESETS.ci, description: "CI/CD artifact organization" },
+  ];
+}
+
+/**
+ * Ensure output directory exists
+ * @param {string} filePath - Full file path
+ */
+function ensureOutputDirectory(filePath) {
+  const dir = path.dirname(filePath);
+  fs.ensureDirSync(dir);
+}
+
+module.exports = {
+  DEFAULT_OUTPUT_TEMPLATE,
+  TEMPLATE_PRESETS,
+  parseTemplateVariables,
+  buildTemplateContext,
+  resolveTemplate,
+  resolveOutputPath,
+  resolveOutputDirectory,
+  validateTemplate,
+  getTemplatePresets,
+  ensureOutputDirectory,
+};

package/src/lib/playwright-runner.js

@@ -0,0 +1,252 @@
+// playwright-runner.js - Generic Playwright runner for executing steps
+const { chromium } = require("playwright");
+const path = require("path");
+const fs = require("fs-extra");
+const { buildLaunchOptions } = require("./ci-detect");
+const { resolveSecretsInObject } = require("./secrets");
+
+/**
+ * Wait for element with retries and fallbacks
+ * @param {Page} page - Playwright page
+ * @param {string} selector - CSS selector
+ * @param {Object} options - Options
+ * @returns {Promise<Locator>}
+ */
+async function waitForElement(page, selector, options = {}) {
+  const { timeout = 10000, action = "interact" } = options;
+
+  // First, wait for the page to be stable (no network activity)
+  try {
+    await page.waitForLoadState("networkidle", { timeout: 5000 });
+  } catch (e) {
+    // Continue even if networkidle times out
+  }
+
+  // Try the selector directly
+  const locator = page.locator(selector);
+
+  try {
+    await locator.first().waitFor({ state: "visible", timeout });
+    return locator.first();
+  } catch (e) {
+    // If selector fails, try some fallback strategies
+    console.log(
+      `    ⚠ Selector "${selector}" not immediately found, trying fallbacks...`
+    );
+
+    // Strategy 1: Wait a bit longer for dynamic content
+    await page.waitForTimeout(1000);
+
+    try {
+      await locator.first().waitFor({ state: "visible", timeout: 3000 });
+      return locator.first();
+    } catch (e2) {
+      // Strategy 2: Try scrolling to make element visible
+      try {
+        await page.evaluate(() =>
+          window.scrollTo(0, document.body.scrollHeight / 2)
+        );
+        await page.waitForTimeout(500);
+        await locator.first().waitFor({ state: "visible", timeout: 2000 });
+        return locator.first();
+      } catch (e3) {
+        // Give up with helpful error
+        const count = await locator.count();
+        if (count === 0) {
+          throw new Error(
+            `Element not found: "${selector}" - no matching elements on page`
+          );
+        } else {
+          throw new Error(
+            `Element "${selector}" exists (${count} matches) but not visible/clickable`
+          );
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Run a sequence of steps with Playwright
+ * Based on test/persona-injection/generic_runner.js and test/capturing-target/element_runner.js
+ *
+ * @param {Object} options - Run options
+ * @param {string} options.url - URL to navigate to
+ * @param {Array} options.steps - Array of step objects
+ * @param {string} options.outputDir - Directory to save output files
+ * @param {Object} options.context - Context object for variable resolution
+ */
+async function runSteps({ url, steps, outputDir, context }) {
+  const browser = await chromium.launch(buildLaunchOptions({ headless: true }));
+  const page = await browser.newPage();
+
+  // Set viewport for consistent rendering
+  await page.setViewportSize({ width: 1280, height: 720 });
+
+  // Set a reasonable default timeout
+  page.setDefaultTimeout(20000); // 20 seconds
+
+  try {
+    console.log(`  Navigating to ${url}`);
+    await page.goto(url, { waitUntil: "domcontentloaded", timeout: 30000 });
+
+    // Wait for initial page load
+    await page
+      .waitForLoadState("networkidle", { timeout: 10000 })
+      .catch(() => {});
+
+    for (let index = 0; index < steps.length; index++) {
+      const step = steps[index];
+      console.log(
+        `  Executing step ${index + 1}/${steps.length}: ${step.action} ${
+          step.selector || ""
+        }`
+      );
+
+      // Resolve secrets in all step fields
+      const resolvedStep = resolveSecretsInObject(step);
+
+      try {
+        switch (resolvedStep.action) {
+          case "goto":
+            await page.goto(resolvedStep.url || url, {
+              waitUntil: "domcontentloaded",
+            });
+            await page
+              .waitForLoadState("networkidle", { timeout: 10000 })
+              .catch(() => {});
+            break;
+
+          case "type":
+          case "input": {
+            const inputElement = await waitForElement(
+              page,
+              resolvedStep.selector,
+              { action: "fill" }
+            );
+            await inputElement.fill(resolvedStep.text || "");
+            break;
+          }
+
+          case "click": {
+            const clickElement = await waitForElement(
+              page,
+              resolvedStep.selector,
+              { action: "click" }
+            );
+            await clickElement.click();
+            // Small delay after click to let page react
+            await page.waitForTimeout(300);
+            break;
+          }
+
+          case "hover": {
+            const hoverElement = await waitForElement(
+              page,
+              resolvedStep.selector,
+              { action: "hover" }
+            );
+            await hoverElement.hover();
+            break;
+          }
+
+          case "waitForSelector":
+            await waitForElement(page, resolvedStep.selector);
+            break;
+
+          case "wait":
+            await page.waitForTimeout(
+              resolvedStep.ms || resolvedStep.duration || 1000
+            );
+            break;
+
+          case "screenshot":
+            await handleScreenshot(page, resolvedStep, outputDir, index);
+            break;
+
+          default:
+            console.warn(`  ⚠ Unknown action: ${resolvedStep.action}`);
+        }
+
+        console.log(`    ✓ Step ${index + 1} completed`);
+      } catch (stepError) {
+        // Enhanced error message for selector failures
+        const selectorInfo = resolvedStep.selector
+          ? ` (selector: "${resolvedStep.selector}")`
+          : "";
+        console.error(
+          `  ❌ Step ${index + 1} failed: ${step.action}${selectorInfo}`
+        );
+        console.error(`     Error: ${stepError.message}`);
+
+        // Take a screenshot for debugging
+        try {
+          const debugPath = path.join(
+            outputDir || ".",
+            `debug-step-${index + 1}-failure.png`
+          );
+          await page.screenshot({ path: debugPath, fullPage: true });
+          console.error(`     Debug screenshot saved: ${debugPath}`);
+        } catch (ssError) {
+          // Ignore screenshot errors
+        }
+
+        // Re-throw to stop execution
+        throw new Error(
+          `Step ${index + 1} (${step.action}) failed: ${stepError.message}`
+        );
+      }
+    }
+
+    console.log(`  ✔ All ${steps.length} steps completed successfully`);
+  } finally {
+    await browser.close();
+  }
+}
+
+/**
+ * Handle screenshot step
+ * Based on test/capturing-target/element_runner.js
+ */
+function resolveScreenshotPath(step, index) {
+  if (step.path) {
+    return step.path;
+  }
+
+  const baseName = step.captureKey || step.key;
+  if (baseName) {
+    return path.extname(baseName) ? baseName : `${baseName}.png`;
+  }
+
+  return `step-${(index ?? 0) + 1}.png`;
+}
+
+async function handleScreenshot(page, step, outputDir, index) {
+  const relativePath = resolveScreenshotPath(step, index);
+  const finalPath = path.join(outputDir, relativePath);
+  fs.ensureDirSync(path.dirname(finalPath));
+
+  if (step.selector) {
+    // Capture specific element
+    const element = await page.locator(step.selector).first();
+    await element.screenshot({ path: finalPath });
+    console.log(`  ✔ Captured element and saved to ${finalPath}`);
+  } else {
+    // Capture full page
+    const screenshotOptions = {
+      path: finalPath,
+      fullPage: !step.clip,
+    };
+
+    if (step.clip) {
+      screenshotOptions.clip = step.clip;
+    }
+
+    await page.screenshot(screenshotOptions);
+    console.log(`  ✔ Captured full page and saved to ${finalPath}`);
+  }
+}
+
+module.exports = {
+  runSteps,
+};