@vizzly-testing/cli 0.4.0 → 0.5.0

package/README.md

@@ -277,6 +277,10 @@ For CI/CD pipelines, use the `--wait` flag to wait for visual comparison results
   run: npx vizzly run "npm test" --wait
   env:
     VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}
+    # Optional: Provide correct git information from GitHub context
+    VIZZLY_COMMIT_MESSAGE: ${{ github.event.head_commit.message }}
+    VIZZLY_COMMIT_SHA: ${{ github.event.head_commit.id }}
+    VIZZLY_BRANCH: ${{ github.head_ref || github.ref_name }}
 ```
 
 ### GitLab CI
@@ -319,10 +323,30 @@ Check if Vizzly is enabled in the current environment.
 
 ## Environment Variables
 
+### Core Configuration
 - `VIZZLY_TOKEN`: API authentication token. Example: `export VIZZLY_TOKEN=your-token`.
 - `VIZZLY_API_URL`: Override API base URL. Default: `https://vizzly.dev`.
 - `VIZZLY_LOG_LEVEL`: Logger level. One of `debug`, `info`, `warn`, `error`. Example: `export VIZZLY_LOG_LEVEL=debug`.
 
+### Git Information Override
+For enhanced CI/CD integration, you can override git detection with these environment variables:
+
+- `VIZZLY_COMMIT_SHA`: Override detected commit SHA. Useful in CI environments.
+- `VIZZLY_COMMIT_MESSAGE`: Override detected commit message. Useful in CI environments.
+- `VIZZLY_BRANCH`: Override detected branch name. Useful in CI environments.
+- `VIZZLY_PR_NUMBER`: Override detected pull request number. Useful for PR-specific builds.
+
+**Example for GitHub Actions:**
+```yaml
+env:
+  VIZZLY_COMMIT_MESSAGE: ${{ github.event.head_commit.message }}
+  VIZZLY_COMMIT_SHA: ${{ github.event.head_commit.id }}
+  VIZZLY_BRANCH: ${{ github.head_ref || github.ref_name }}
+  VIZZLY_PR_NUMBER: ${{ github.event.pull_request.number }}
+```
+
+These variables take highest priority over both CLI arguments and automatic git detection.
+
 ## Contributing
 
 We welcome contributions! Whether you're fixing bugs, adding features, or improving documentation, your help makes Vizzly better for everyone.

package/dist/cli.js

@@ -38,10 +38,26 @@ program.command('tdd').description('Run tests in TDD mode with local visual comp
     validationErrors.forEach(error => console.error(`  - ${error}`));
     process.exit(1);
   }
-  const result = await tddCommand(command, options, globalOptions);
+  const {
+    result,
+    cleanup
+  } = await tddCommand(command, options, globalOptions);
+
+  // Set up cleanup on process signals
+  const handleCleanup = async () => {
+    await cleanup();
+  };
+  process.once('SIGINT', () => {
+    handleCleanup().then(() => process.exit(1));
+  });
+  process.once('SIGTERM', () => {
+    handleCleanup().then(() => process.exit(1));
+  });
   if (result && !result.success && result.exitCode > 0) {
+    await cleanup();
     process.exit(result.exitCode);
   }
+  await cleanup();
 });
 program.command('run').description('Run tests with Vizzly integration').argument('<command>', 'Test command to run').option('--port <port>', 'Port for screenshot server', '47392').option('-b, --build-name <name>', 'Custom build name').option('--branch <branch>', 'Git branch override').option('--commit <sha>', 'Git commit SHA').option('--message <msg>', 'Commit message').option('--environment <env>', 'Environment name', 'test').option('--token <token>', 'API token override').option('--wait', 'Wait for build completion').option('--timeout <ms>', 'Server timeout in milliseconds', '30000').option('--allow-no-token', 'Allow running without API token').option('--upload-all', 'Upload all screenshots without SHA deduplication').action(async (command, options) => {
   const globalOptions = program.opts();

package/dist/commands/run.js

@@ -1,7 +1,7 @@
 import { loadConfig } from '../utils/config-loader.js';
 import { ConsoleUI } from '../utils/console-ui.js';
 import { createServiceContainer } from '../container/index.js';
-import { detectBranch, detectCommit, getCommitMessage, generateBuildNameWithGit } from '../utils/git.js';
+import { detectBranch, detectCommit, detectCommitMessage, detectPullRequestNumber, generateBuildNameWithGit } from '../utils/git.js';
 
 /**
  * Run command implementation
@@ -55,8 +55,9 @@ export async function runCommand(testCommand, options = {}, globalOptions = {})
     // Collect git metadata and build info
     const branch = await detectBranch(options.branch);
     const commit = await detectCommit(options.commit);
-    const message = options.message || (await getCommitMessage());
+    const message = options.message || (await detectCommitMessage());
     const buildName = await generateBuildNameWithGit(options.buildName);
+    const pullRequestNumber = detectPullRequestNumber();
     if (globalOptions.verbose) {
       ui.info('Configuration loaded', {
         testCommand,
@@ -146,7 +147,8 @@ export async function runCommand(testCommand, options = {}, globalOptions = {})
       eager: config.eager || false,
       allowNoToken: config.allowNoToken || false,
       wait: config.wait || options.wait || false,
-      uploadAll: options.uploadAll || false
+      uploadAll: options.uploadAll || false,
+      pullRequestNumber
     };
 
     // Start test run

package/dist/commands/tdd.js

@@ -8,6 +8,7 @@ import { detectBranch, detectCommit } from '../utils/git.js';
  * @param {string} testCommand - Test command to execute
  * @param {Object} options - Command options
  * @param {Object} globalOptions - Global CLI options
+ * @returns {Promise<{result: Object, cleanup: Function}>} Result and cleanup function
  */
 export async function tddCommand(testCommand, options = {}, globalOptions = {}) {
   // Create UI handler
@@ -17,20 +18,17 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {})
     color: !globalOptions.noColor
   });
   let testRunner = null;
+  let isCleanedUp = false;
 
-  // Ensure cleanup on exit - store listeners for proper cleanup
+  // Create cleanup function that can be called by the caller
   const cleanup = async () => {
+    if (isCleanedUp) return;
+    isCleanedUp = true;
     ui.cleanup();
-    // The test runner's finally block will handle server cleanup
-    // We just need to ensure UI cleanup happens
-  };
-  const sigintHandler = async () => {
-    await cleanup();
-    process.exit(1);
+    if (testRunner?.cancel) {
+      await testRunner.cancel();
+    }
   };
-  const exitHandler = () => ui.cleanup();
-  process.on('SIGINT', sigintHandler);
-  process.on('exit', exitHandler);
   try {
     // Load configuration with CLI overrides
     const allOptions = {
@@ -166,22 +164,31 @@ export async function tddCommand(testCommand, options = {}, globalOptions = {})
     }
     ui.success('TDD test run completed');
 
-    // Exit with appropriate code based on comparison results
-    if (result.failed || result.comparisons && result.comparisons.some(c => c.status === 'failed')) {
+    // Determine success based on comparison results
+    const hasFailures = result.failed || result.comparisons && result.comparisons.some(c => c.status === 'failed');
+    if (hasFailures) {
       ui.error('Visual differences detected in TDD mode', {}, 0);
-      // Return error status without calling process.exit in tests
-      return {
-        success: false,
-        exitCode: 1
-      };
     }
-    ui.cleanup();
+
+    // Return result and cleanup function
+    return {
+      result: {
+        success: !hasFailures,
+        exitCode: hasFailures ? 1 : 0,
+        ...result
+      },
+      cleanup
+    };
   } catch (error) {
     ui.error('TDD test run failed', error);
-  } finally {
-    // Remove event listeners to prevent memory leaks
-    process.removeListener('SIGINT', sigintHandler);
-    process.removeListener('exit', exitHandler);
+    return {
+      result: {
+        success: false,
+        exitCode: 1,
+        error: error.message
+      },
+      cleanup
+    };
   }
 }
 

package/dist/commands/upload.js

@@ -1,7 +1,7 @@
 import { loadConfig } from '../utils/config-loader.js';
 import { ConsoleUI } from '../utils/console-ui.js';
 import { createServiceContainer } from '../container/index.js';
-import { detectBranch, detectCommit, getCommitMessage, generateBuildNameWithGit } from '../utils/git.js';
+import { detectBranch, detectCommit, detectCommitMessage, detectPullRequestNumber, generateBuildNameWithGit } from '../utils/git.js';
 import { ApiService } from '../services/api-service.js';
 
 /**
@@ -71,8 +71,9 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
     // Collect git metadata if not provided
     const branch = await detectBranch(options.branch);
     const commit = await detectCommit(options.commit);
-    const message = options.message || (await getCommitMessage());
+    const message = options.message || (await detectCommitMessage());
     const buildName = await generateBuildNameWithGit(options.buildName);
+    const pullRequestNumber = detectPullRequestNumber();
     ui.info(`Uploading screenshots from: ${screenshotsPath}`);
     if (globalOptions.verbose) {
       ui.info('Configuration loaded', {
@@ -99,6 +100,7 @@ export async function uploadCommand(screenshotsPath, options = {}, globalOptions
       threshold: config.comparison.threshold,
       uploadAll: options.uploadAll || false,
       metadata: options.metadata ? JSON.parse(options.metadata) : {},
+      pullRequestNumber,
       onProgress: progressData => {
         const {
           message: progressMessage,

package/dist/services/test-runner.js

@@ -114,13 +114,12 @@ export class TestRunner extends BaseService {
       const apiService = await this.createApiService();
       if (apiService) {
         const buildResult = await apiService.createBuild({
-          build: {
-            name: options.buildName || `Test Run ${new Date().toISOString()}`,
-            branch: options.branch || 'main',
-            environment: options.environment || 'test',
-            commit_sha: options.commit,
-            commit_message: options.message
-          }
+          name: options.buildName || `Test Run ${new Date().toISOString()}`,
+          branch: options.branch || 'main',
+          environment: options.environment || 'test',
+          commit_sha: options.commit,
+          commit_message: options.message,
+          github_pull_request_number: options.pullRequestNumber
         });
         this.logger.debug(`Build created with ID: ${buildResult.id}`);
 
@@ -154,10 +153,13 @@ export class TestRunner extends BaseService {
     }
     try {
       if (isTddMode) {
-        // TDD mode: use server handler to finalize
+        // TDD mode: use server handler to finalize (local-only)
         if (this.serverManager.server?.finishBuild) {
           await this.serverManager.server.finishBuild(buildId);
           this.logger.debug(`TDD build ${buildId} finalized with success: ${success}`);
+        } else {
+          // In TDD mode without a server, just log that finalization is skipped
+          this.logger.debug(`TDD build ${buildId} finalization skipped (local-only mode)`);
         }
       } else {
         // API mode: use API service to update build status

package/dist/services/uploader.js

@@ -50,6 +50,7 @@ export function createUploader({
     message,
     environment = 'production',
     threshold,
+    pullRequestNumber,
     onProgress = () => {}
   }) {
     try {
@@ -96,10 +97,11 @@ export function createUploader({
       const buildInfo = {
         name: buildName || `Upload ${new Date().toISOString()}`,
         branch: branch || (await getDefaultBranch()) || 'main',
-        commitSha: commit,
-        commitMessage: message,
+        commit_sha: commit,
+        commit_message: message,
         environment,
-        threshold
+        threshold,
+        github_pull_request_number: pullRequestNumber
       };
       const build = await api.createBuild(buildInfo);
       const buildId = build.id;

package/dist/types/commands/tdd.d.ts

@@ -3,10 +3,11 @@
  * @param {string} testCommand - Test command to execute
  * @param {Object} options - Command options
  * @param {Object} globalOptions - Global CLI options
+ * @returns {Promise<{result: Object, cleanup: Function}>} Result and cleanup function
  */
 export function tddCommand(testCommand: string, options?: any, globalOptions?: any): Promise<{
-    success: boolean;
-    exitCode: number;
+    result: any;
+    cleanup: Function;
 }>;
 /**
  * Validate TDD options

package/dist/types/services/uploader.d.ts

@@ -8,7 +8,7 @@ export function createUploader({ apiKey, apiUrl, userAgent, command, upload: upl
     command: any;
     upload?: {};
 }, options?: {}): {
-    upload: ({ screenshotsDir, buildName, branch, commit, message, environment, threshold, onProgress, }: {
+    upload: ({ screenshotsDir, buildName, branch, commit, message, environment, threshold, pullRequestNumber, onProgress, }: {
         screenshotsDir: any;
         buildName: any;
         branch: any;
@@ -16,6 +16,7 @@ export function createUploader({ apiKey, apiUrl, userAgent, command, upload: upl
         message: any;
         environment?: string;
         threshold: any;
+        pullRequestNumber: any;
         onProgress?: () => void;
     }) => Promise<{
         success: boolean;

package/dist/types/utils/ci-env.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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(): string | null;
+/**
+ * Get the commit SHA from CI environment variables
+ * @returns {string|null} Commit SHA or null if not available
+ */
+export function getCommit(): string | null;
+/**
+ * Get the commit message from CI environment variables
+ * @returns {string|null} Commit message or null if not available
+ */
+export function getCommitMessage(): string | 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(): number | null;
+/**
+ * Get the PR head SHA from CI environment variables
+ * @returns {string|null} PR head SHA or null if not available
+ */
+export function getPullRequestHeadSha(): string | null;
+/**
+ * Get the PR base SHA from CI environment variables
+ * @returns {string|null} PR base SHA or null if not available
+ */
+export function getPullRequestBaseSha(): string | null;
+/**
+ * Get the PR head ref (branch) from CI environment variables
+ * @returns {string|null} PR head ref or null if not available
+ */
+export function getPullRequestHeadRef(): string | 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(): string | null;
+/**
+ * Check if we're currently in a pull request context
+ * @returns {boolean} True if in a PR context
+ */
+export function isPullRequest(): boolean;
+/**
+ * Get the CI provider name
+ * @returns {string} CI provider name or 'unknown'
+ */
+export function getCIProvider(): string;

package/dist/types/utils/git.d.ts

@@ -9,6 +9,13 @@ export function generateBuildName(): string;
  * @returns {Promise<string|null>} Commit message or null if not available
  */
 export function getCommitMessage(cwd?: string): Promise<string | null>;
+/**
+ * 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 function detectCommitMessage(override?: string, cwd?: string): Promise<string | null>;
 /**
  * Check if the working directory is a git repository
  * @param {string} cwd - Working directory
@@ -42,3 +49,8 @@ export function detectCommit(override?: string, cwd?: string): Promise<string |
  * @returns {Promise<string>}
  */
 export function generateBuildNameWithGit(override?: string, cwd?: string): Promise<string>;
+/**
+ * Detect pull request number from CI environment
+ * @returns {number|null} Pull request number or null if not in PR context
+ */
+export function detectPullRequestNumber(): number | null;

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/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/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

package/docs/test-integration.md

@@ -275,8 +275,14 @@ jobs:
       - run: npx vizzly run "npm test" --wait
         env:
           VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}
+          # Optional: Enhanced git information from GitHub context
+          VIZZLY_COMMIT_MESSAGE: ${{ github.event.head_commit.message }}
+          VIZZLY_COMMIT_SHA: ${{ github.event.head_commit.id }}
+          VIZZLY_BRANCH: ${{ github.head_ref || github.ref_name }}
 ```
 
+**Enhanced Git Information:** The `VIZZLY_*` environment variables ensure accurate git metadata is captured in your builds, avoiding issues with merge commits that can occur in CI environments.
+
 ### GitLab CI
 
 ```yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizzly-testing/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Visual review platform for UI developers and designers",
   "keywords": [
     "visual-testing",
@@ -73,11 +73,11 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "commander": "^11.1.0",
+    "commander": "^14.0.0",
     "cosmiconfig": "^9.0.0",
     "dotenv": "^17.2.1",
     "form-data": "^4.0.0",
-    "glob": "^10.3.10",
+    "glob": "^11.0.3",
     "odiff-bin": "^3.2.1"
   },
   "devDependencies": {
@@ -93,8 +93,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.3",
     "prettier": "^3.6.2",
-    "puppeteer": "^24.16.1",
-    "rimraf": "^5.0.5",
+    "rimraf": "^6.0.1",
     "typescript": "^5.0.4",
     "vite": "^7.1.2",
     "vitest": "^3.2.4"