@vizzly-testing/cli 0.4.0 → 0.6.0

package/dist/utils/ci-env.js

@@ -0,0 +1,293 @@
+/**
+ * CI Environment Detection
+ *
+ * Generic functions to extract git and PR information from any CI provider
+ */
+
+/**
+ * Get the branch name from CI environment variables
+ * @returns {string|null} Branch name or null if not available
+ */
+export function getBranch() {
+  return process.env.VIZZLY_BRANCH ||
+  // Vizzly override
+  process.env.GITHUB_HEAD_REF ||
+  // GitHub Actions (for PRs)
+  process.env.GITHUB_REF_NAME ||
+  // GitHub Actions (for pushes)
+  process.env.CI_COMMIT_REF_NAME ||
+  // GitLab CI
+  process.env.CIRCLE_BRANCH ||
+  // CircleCI
+  process.env.TRAVIS_BRANCH ||
+  // Travis CI
+  process.env.BUILDKITE_BRANCH ||
+  // Buildkite
+  process.env.DRONE_BRANCH ||
+  // Drone CI
+  process.env.BRANCH_NAME ||
+  // Jenkins
+  process.env.GIT_BRANCH ||
+  // Jenkins (alternative)
+  process.env.BITBUCKET_BRANCH ||
+  // Bitbucket Pipelines
+  process.env.WERCKER_GIT_BRANCH ||
+  // Wercker
+  process.env.APPVEYOR_REPO_BRANCH ||
+  // AppVeyor
+  process.env.BUILD_SOURCEBRANCH?.replace(/^refs\/heads\//, '') ||
+  // Azure DevOps
+  process.env.CODEBUILD_WEBHOOK_HEAD_REF?.replace(/^refs\/heads\//, '') ||
+  // AWS CodeBuild
+  process.env.SEMAPHORE_GIT_BRANCH ||
+  // Semaphore
+  null;
+}
+
+/**
+ * Get the commit SHA from CI environment variables
+ * @returns {string|null} Commit SHA or null if not available
+ */
+export function getCommit() {
+  return process.env.VIZZLY_COMMIT_SHA ||
+  // Vizzly override
+  process.env.GITHUB_SHA ||
+  // GitHub Actions
+  process.env.CI_COMMIT_SHA ||
+  // GitLab CI
+  process.env.CIRCLE_SHA1 ||
+  // CircleCI
+  process.env.TRAVIS_COMMIT ||
+  // Travis CI
+  process.env.BUILDKITE_COMMIT ||
+  // Buildkite
+  process.env.DRONE_COMMIT_SHA ||
+  // Drone CI
+  process.env.GIT_COMMIT ||
+  // Jenkins
+  process.env.BITBUCKET_COMMIT ||
+  // Bitbucket Pipelines
+  process.env.WERCKER_GIT_COMMIT ||
+  // Wercker
+  process.env.APPVEYOR_REPO_COMMIT ||
+  // AppVeyor
+  process.env.BUILD_SOURCEVERSION ||
+  // Azure DevOps
+  process.env.CODEBUILD_RESOLVED_SOURCE_VERSION ||
+  // AWS CodeBuild
+  process.env.SEMAPHORE_GIT_SHA ||
+  // Semaphore
+  process.env.HEROKU_TEST_RUN_COMMIT_VERSION ||
+  // Heroku CI
+  process.env.COMMIT_SHA ||
+  // Generic
+  process.env.HEAD_COMMIT ||
+  // Alternative generic
+  process.env.SHA ||
+  // Another generic option
+  null;
+}
+
+/**
+ * Get the commit message from CI environment variables
+ * @returns {string|null} Commit message or null if not available
+ */
+export function getCommitMessage() {
+  return process.env.VIZZLY_COMMIT_MESSAGE ||
+  // Vizzly override
+  process.env.CI_COMMIT_MESSAGE ||
+  // GitLab CI
+  process.env.TRAVIS_COMMIT_MESSAGE ||
+  // Travis CI
+  process.env.BUILDKITE_MESSAGE ||
+  // Buildkite
+  process.env.DRONE_COMMIT_MESSAGE ||
+  // Drone CI
+  process.env.APPVEYOR_REPO_COMMIT_MESSAGE ||
+  // AppVeyor
+  process.env.COMMIT_MESSAGE ||
+  // Generic
+  null;
+}
+
+/**
+ * Get the pull request number from CI environment variables
+ * @returns {number|null} PR number or null if not available/not a PR
+ */
+export function getPullRequestNumber() {
+  // Check VIZZLY override first
+  if (process.env.VIZZLY_PR_NUMBER) {
+    return parseInt(process.env.VIZZLY_PR_NUMBER, 10);
+  }
+
+  // GitHub Actions - extract from GITHUB_REF
+  if (process.env.GITHUB_ACTIONS && process.env.GITHUB_EVENT_NAME === 'pull_request') {
+    const prMatch = process.env.GITHUB_REF?.match(/refs\/pull\/(\d+)\/merge/);
+    if (prMatch?.[1]) return parseInt(prMatch[1], 10);
+  }
+
+  // GitLab CI
+  if (process.env.CI_MERGE_REQUEST_ID) {
+    return parseInt(process.env.CI_MERGE_REQUEST_ID, 10);
+  }
+
+  // CircleCI - extract from PR URL
+  if (process.env.CIRCLE_PULL_REQUEST) {
+    const prMatch = process.env.CIRCLE_PULL_REQUEST.match(/\/pull\/(\d+)$/);
+    if (prMatch?.[1]) return parseInt(prMatch[1], 10);
+  }
+
+  // Travis CI
+  if (process.env.TRAVIS_PULL_REQUEST && process.env.TRAVIS_PULL_REQUEST !== 'false') {
+    return parseInt(process.env.TRAVIS_PULL_REQUEST, 10);
+  }
+
+  // Buildkite
+  if (process.env.BUILDKITE_PULL_REQUEST && process.env.BUILDKITE_PULL_REQUEST !== 'false') {
+    return parseInt(process.env.BUILDKITE_PULL_REQUEST, 10);
+  }
+
+  // Drone CI
+  if (process.env.DRONE_PULL_REQUEST) {
+    return parseInt(process.env.DRONE_PULL_REQUEST, 10);
+  }
+
+  // Jenkins (GitHub Pull Request Builder plugin)
+  if (process.env.ghprbPullId) {
+    return parseInt(process.env.ghprbPullId, 10);
+  }
+
+  // Azure DevOps
+  if (process.env.SYSTEM_PULLREQUEST_PULLREQUESTID) {
+    return parseInt(process.env.SYSTEM_PULLREQUEST_PULLREQUESTID, 10);
+  }
+
+  // AppVeyor
+  if (process.env.APPVEYOR_PULL_REQUEST_NUMBER) {
+    return parseInt(process.env.APPVEYOR_PULL_REQUEST_NUMBER, 10);
+  }
+  return null;
+}
+
+/**
+ * Get the PR head SHA from CI environment variables
+ * @returns {string|null} PR head SHA or null if not available
+ */
+export function getPullRequestHeadSha() {
+  return process.env.VIZZLY_PR_HEAD_SHA ||
+  // Vizzly override
+  process.env.GITHUB_SHA ||
+  // GitHub Actions
+  process.env.CI_COMMIT_SHA ||
+  // GitLab CI
+  process.env.CIRCLE_SHA1 ||
+  // CircleCI
+  process.env.TRAVIS_COMMIT ||
+  // Travis CI
+  process.env.BUILDKITE_COMMIT ||
+  // Buildkite
+  process.env.DRONE_COMMIT_SHA ||
+  // Drone CI
+  process.env.ghprbActualCommit ||
+  // Jenkins
+  process.env.GIT_COMMIT ||
+  // Jenkins fallback
+  process.env.BUILD_SOURCEVERSION ||
+  // Azure DevOps
+  process.env.APPVEYOR_REPO_COMMIT ||
+  // AppVeyor
+  null;
+}
+
+/**
+ * Get the PR base SHA from CI environment variables
+ * @returns {string|null} PR base SHA or null if not available
+ */
+export function getPullRequestBaseSha() {
+  return process.env.VIZZLY_PR_BASE_SHA ||
+  // Vizzly override
+  process.env.CI_MERGE_REQUEST_TARGET_BRANCH_SHA ||
+  // GitLab CI
+  null // Most CIs don't provide this
+  ;
+}
+
+/**
+ * Get the PR head ref (branch) from CI environment variables
+ * @returns {string|null} PR head ref or null if not available
+ */
+export function getPullRequestHeadRef() {
+  return process.env.VIZZLY_PR_HEAD_REF ||
+  // Vizzly override
+  process.env.GITHUB_HEAD_REF ||
+  // GitHub Actions
+  process.env.CI_MERGE_REQUEST_SOURCE_BRANCH_NAME ||
+  // GitLab CI
+  process.env.TRAVIS_PULL_REQUEST_BRANCH ||
+  // Travis CI
+  process.env.DRONE_SOURCE_BRANCH ||
+  // Drone CI
+  process.env.ghprbSourceBranch ||
+  // Jenkins
+  process.env.SYSTEM_PULLREQUEST_SOURCEBRANCH?.replace(/^refs\/heads\//, '') ||
+  // Azure DevOps
+  process.env.APPVEYOR_PULL_REQUEST_HEAD_REPO_BRANCH ||
+  // AppVeyor
+  null;
+}
+
+/**
+ * Get the PR base ref (target branch) from CI environment variables
+ * @returns {string|null} PR base ref or null if not available
+ */
+export function getPullRequestBaseRef() {
+  return process.env.VIZZLY_PR_BASE_REF ||
+  // Vizzly override
+  process.env.GITHUB_BASE_REF ||
+  // GitHub Actions
+  process.env.CI_MERGE_REQUEST_TARGET_BRANCH_NAME ||
+  // GitLab CI
+  process.env.TRAVIS_BRANCH ||
+  // Travis CI (target branch)
+  process.env.BUILDKITE_PULL_REQUEST_BASE_BRANCH ||
+  // Buildkite
+  process.env.DRONE_TARGET_BRANCH ||
+  // Drone CI
+  process.env.ghprbTargetBranch ||
+  // Jenkins
+  process.env.SYSTEM_PULLREQUEST_TARGETBRANCH?.replace(/^refs\/heads\//, '') ||
+  // Azure DevOps
+  process.env.APPVEYOR_REPO_BRANCH ||
+  // AppVeyor (target branch)
+  null;
+}
+
+/**
+ * Check if we're currently in a pull request context
+ * @returns {boolean} True if in a PR context
+ */
+export function isPullRequest() {
+  return getPullRequestNumber() !== null;
+}
+
+/**
+ * Get the CI provider name
+ * @returns {string} CI provider name or 'unknown'
+ */
+export function getCIProvider() {
+  if (process.env.GITHUB_ACTIONS) return 'github-actions';
+  if (process.env.GITLAB_CI) return 'gitlab-ci';
+  if (process.env.CIRCLECI) return 'circleci';
+  if (process.env.TRAVIS) return 'travis-ci';
+  if (process.env.BUILDKITE) return 'buildkite';
+  if (process.env.DRONE) return 'drone-ci';
+  if (process.env.JENKINS_URL) return 'jenkins';
+  if (process.env.AZURE_HTTP_USER_AGENT || process.env.TF_BUILD) return 'azure-devops';
+  if (process.env.CODEBUILD_BUILD_ID) return 'aws-codebuild';
+  if (process.env.APPVEYOR) return 'appveyor';
+  if (process.env.SEMAPHORE) return 'semaphore';
+  if (process.env.WERCKER) return 'wercker';
+  if (process.env.BITBUCKET_BUILD_NUMBER) return 'bitbucket-pipelines';
+  if (process.env.HEROKU_TEST_RUN_ID) return 'heroku-ci';
+  return 'unknown';
+}

package/dist/utils/config-loader.js

@@ -25,6 +25,10 @@ const DEFAULT_CONFIG = {
   // Comparison Configuration
   comparison: {
     threshold: 0.1
+  },
+  // TDD Configuration
+  tdd: {
+    openReport: false // Whether to auto-open HTML report in browser
   }
 };
 export async function loadConfig(configPath = null, cliOverrides = {}) {
@@ -42,6 +46,9 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
     },
     comparison: {
       ...DEFAULT_CONFIG.comparison
+    },
+    tdd: {
+      ...DEFAULT_CONFIG.tdd
     }
   };
 

package/dist/utils/git.js

@@ -1,5 +1,6 @@
 import { exec } from 'child_process';
 import { promisify } from 'util';
+import { getBranch as getCIBranch, getCommit as getCICommit, getCommitMessage as getCICommitMessage, getPullRequestNumber } from './ci-env.js';
 const execAsync = promisify(exec);
 export async function getCommonAncestor(commit1, commit2, cwd = process.cwd()) {
   try {
@@ -144,6 +145,23 @@ export async function getCommitMessage(cwd = process.cwd()) {
   }
 }
 
+/**
+ * Detect commit message with override and environment variable support
+ * @param {string} override - Commit message override from CLI
+ * @param {string} cwd - Working directory
+ * @returns {Promise<string|null>} Commit message or null if not available
+ */
+export async function detectCommitMessage(override = null, cwd = process.cwd()) {
+  if (override) return override;
+
+  // Try CI environment variables first
+  const ciCommitMessage = getCICommitMessage();
+  if (ciCommitMessage) return ciCommitMessage;
+
+  // Fallback to regular git log
+  return await getCommitMessage(cwd);
+}
+
 /**
  * Check if the working directory is a git repository
  * @param {string} cwd - Working directory
@@ -193,6 +211,12 @@ export async function getGitStatus(cwd = process.cwd()) {
  */
 export async function detectBranch(override = null, cwd = process.cwd()) {
   if (override) return override;
+
+  // Try CI environment variables first
+  const ciBranch = getCIBranch();
+  if (ciBranch) return ciBranch;
+
+  // Fallback to git command when no CI environment variables
   const currentBranch = await getCurrentBranch(cwd);
   return currentBranch || 'unknown';
 }
@@ -205,6 +229,12 @@ export async function detectBranch(override = null, cwd = process.cwd()) {
  */
 export async function detectCommit(override = null, cwd = process.cwd()) {
   if (override) return override;
+
+  // Try CI environment variables first
+  const ciCommit = getCICommit();
+  if (ciCommit) return ciCommit;
+
+  // Fallback to git command when no CI environment variables
   return await getCurrentCommitSha(cwd);
 }
 
@@ -223,4 +253,12 @@ export async function generateBuildNameWithGit(override = null, cwd = process.cw
     return `${branch}-${shortCommit}`;
   }
   return generateBuildName();
+}
+
+/**
+ * Detect pull request number from CI environment
+ * @returns {number|null} Pull request number or null if not in PR context
+ */
+export function detectPullRequestNumber() {
+  return getPullRequestNumber();
 }

package/dist/utils/security.js

@@ -0,0 +1,154 @@
+/**
+ * Security utilities for path sanitization and validation
+ * Protects against path traversal attacks and ensures safe file operations
+ */
+
+import { resolve, normalize, isAbsolute, join } from 'path';
+import { createServiceLogger } from './logger-factory.js';
+const logger = createServiceLogger('SECURITY');
+
+/**
+ * Sanitizes a screenshot name to prevent path traversal and ensure safe file naming
+ * @param {string} name - Original screenshot name
+ * @param {number} maxLength - Maximum allowed length (default: 255)
+ * @returns {string} Sanitized screenshot name
+ */
+export function sanitizeScreenshotName(name, maxLength = 255) {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new Error('Screenshot name must be a non-empty string');
+  }
+  if (name.length > maxLength) {
+    throw new Error(`Screenshot name exceeds maximum length of ${maxLength} characters`);
+  }
+
+  // Block directory traversal patterns
+  if (name.includes('..') || name.includes('/') || name.includes('\\')) {
+    throw new Error('Screenshot name contains invalid path characters');
+  }
+
+  // Block absolute paths
+  if (isAbsolute(name)) {
+    throw new Error('Screenshot name cannot be an absolute path');
+  }
+
+  // Allow only safe characters: alphanumeric, hyphens, underscores, and dots
+  // Replace other characters with underscores
+  let sanitized = name.replace(/[^a-zA-Z0-9._-]/g, '_');
+
+  // Prevent names that start with dots (hidden files)
+  if (sanitized.startsWith('.')) {
+    sanitized = 'file_' + sanitized;
+  }
+
+  // Ensure we have a valid filename
+  if (sanitized.length === 0 || sanitized === '.' || sanitized === '..') {
+    sanitized = 'unnamed_screenshot';
+  }
+  return sanitized;
+}
+
+/**
+ * Validates that a path stays within the allowed working directory bounds
+ * @param {string} targetPath - Path to validate
+ * @param {string} workingDir - Working directory that serves as the security boundary
+ * @returns {string} Resolved and normalized path if valid
+ * @throws {Error} If path is invalid or outside bounds
+ */
+export function validatePathSecurity(targetPath, workingDir) {
+  if (typeof targetPath !== 'string' || targetPath.length === 0) {
+    throw new Error('Path must be a non-empty string');
+  }
+  if (typeof workingDir !== 'string' || workingDir.length === 0) {
+    throw new Error('Working directory must be a non-empty string');
+  }
+
+  // Normalize and resolve both paths
+  let resolvedWorkingDir = resolve(normalize(workingDir));
+  let resolvedTargetPath = resolve(normalize(targetPath));
+
+  // Ensure the target path starts with the working directory
+  if (!resolvedTargetPath.startsWith(resolvedWorkingDir)) {
+    logger.warn(`Path traversal attempt blocked: ${targetPath} (resolved: ${resolvedTargetPath}) is outside working directory: ${resolvedWorkingDir}`);
+    throw new Error('Path is outside the allowed working directory');
+  }
+  return resolvedTargetPath;
+}
+
+/**
+ * Safely constructs a path within the working directory
+ * @param {string} workingDir - Base working directory
+ * @param {...string} pathSegments - Path segments to join
+ * @returns {string} Safely constructed path
+ * @throws {Error} If resulting path would be outside working directory
+ */
+export function safePath(workingDir, ...pathSegments) {
+  if (pathSegments.length === 0) {
+    return validatePathSecurity(workingDir, workingDir);
+  }
+
+  // Sanitize each path segment
+  let sanitizedSegments = pathSegments.map(segment => {
+    if (typeof segment !== 'string') {
+      throw new Error('Path segment must be a string');
+    }
+
+    // Block directory traversal in segments
+    if (segment.includes('..')) {
+      throw new Error('Path segment contains directory traversal sequence');
+    }
+    return segment;
+  });
+  let targetPath = join(workingDir, ...sanitizedSegments);
+  return validatePathSecurity(targetPath, workingDir);
+}
+
+/**
+ * Validates screenshot properties object for safe values
+ * @param {Object} properties - Properties to validate
+ * @returns {Object} Validated properties object
+ */
+export function validateScreenshotProperties(properties = {}) {
+  if (properties === null || typeof properties !== 'object') {
+    return {};
+  }
+  let validated = {};
+
+  // Validate common properties with safe constraints
+  if (properties.browser && typeof properties.browser === 'string') {
+    try {
+      validated.browser = sanitizeScreenshotName(properties.browser, 50);
+    } catch (error) {
+      // Skip invalid browser names, don't include them
+      logger.warn(`Invalid browser name '${properties.browser}': ${error.message}`);
+    }
+  }
+  if (properties.viewport && typeof properties.viewport === 'object') {
+    let viewport = {};
+    if (typeof properties.viewport.width === 'number' && properties.viewport.width > 0 && properties.viewport.width <= 10000) {
+      viewport.width = Math.floor(properties.viewport.width);
+    }
+    if (typeof properties.viewport.height === 'number' && properties.viewport.height > 0 && properties.viewport.height <= 10000) {
+      viewport.height = Math.floor(properties.viewport.height);
+    }
+    if (Object.keys(viewport).length > 0) {
+      validated.viewport = viewport;
+    }
+  }
+
+  // Allow other safe string properties but sanitize them
+  for (let [key, value] of Object.entries(properties)) {
+    if (key === 'browser' || key === 'viewport') continue; // Already handled
+
+    if (typeof key === 'string' && key.length <= 50 && /^[a-zA-Z0-9_-]+$/.test(key)) {
+      if (typeof value === 'string' && value.length <= 200) {
+        // Store sanitized version of string values
+        validated[key] = value.replace(/[<>&"']/g, ''); // Basic HTML entity prevention
+      } else if (typeof value === 'number' && !isNaN(value) && isFinite(value)) {
+        validated[key] = value;
+      } else if (typeof value === 'boolean') {
+        validated[key] = value;
+      }
+    }
+  }
+  return validated;
+}

package/docs/api-reference.md

@@ -481,14 +481,29 @@ Configuration loaded via cosmiconfig in this order:
 
 ### Environment Variables
 
+**Core Configuration:**
 - `VIZZLY_TOKEN` - API authentication token
 - `VIZZLY_API_URL` - API base URL override
 - `VIZZLY_LOG_LEVEL` - Logger level (`debug`, `info`, `warn`, `error`)
+
+**Git Information Override (CI/CD Enhancement):**
+- `VIZZLY_COMMIT_SHA` - Override detected commit SHA
+- `VIZZLY_COMMIT_MESSAGE` - Override detected commit message
+- `VIZZLY_BRANCH` - Override detected branch name
+- `VIZZLY_PR_NUMBER` - Override detected pull request number
+
+**Runtime (Set by CLI):**
 - `VIZZLY_SERVER_URL` - Screenshot server URL (set by CLI)
 - `VIZZLY_ENABLED` - Enable/disable client (set by CLI)
 - `VIZZLY_BUILD_ID` - Current build ID (set by CLI)
 - `VIZZLY_TDD_MODE` - TDD mode active (set by CLI)
 
+**Priority Order for Git Information:**
+1. CLI arguments (`--commit`, `--branch`, `--message`)
+2. `VIZZLY_*` environment variables
+3. CI-specific environment variables (e.g., `GITHUB_SHA`, `CI_COMMIT_SHA`)
+4. Git command detection
+
 ## Error Handling
 
 ### Client Errors