✨ Add VIZZLY_BUILD_NAME environment variable support (#195)

## Summary

- Add `VIZZLY_BUILD_NAME` environment variable for setting build names
in CI without CLI flags
- Makes CI configuration cleaner - no need to interpolate values in CLI
args

## Changes

- Add `getBuildName()` function to `environment-config.js`
- Wire into `config-loader.js` to set `config.build.name` from
environment
- Add tests for new functionality
- Update CLAUDE.md documentation

## Usage

```bash
# Instead of
vizzly run "npm test" --build-name "PR #${PR_NUMBER} - ${BRANCH_NAME}"

# You can now use
export VIZZLY_BUILD_NAME="PR #${PR_NUMBER} - ${BRANCH_NAME}"
vizzly run "npm test"
```

## Test plan

- [x] Unit tests pass for environment-config.js
- [x] Unit tests pass for config-loader.js
- [x] Lint passes

Author: Robdel12

CLAUDE.md

@@ -175,6 +175,7 @@ The React-based reporter works in two modes:
 - `VIZZLY_TOKEN` - API authentication token
 - `VIZZLY_API_URL` - API base URL (default: https://app.vizzly.dev)
 - `VIZZLY_LOG_LEVEL` - Logging level (debug|info|warn|error)
+- `VIZZLY_BUILD_NAME` - Custom build name (useful in CI for dynamic naming)
 - `VIZZLY_PARALLEL_ID` - Parallel build identifier
 - `VIZZLY_ENABLED` - Enable/disable SDK (default: auto-detect)
 - `VIZZLY_SERVER_URL` - Screenshot server URL for client

src/utils/config-loader.js

@@ -1,7 +1,12 @@
 import { resolve } from 'node:path';
 import { cosmiconfigSync } from 'cosmiconfig';
 import { validateVizzlyConfigWithDefaults } from './config-schema.js';
-import { getApiToken, getApiUrl, getParallelId } from './environment-config.js';
+import {
+  getApiToken,
+  getApiUrl,
+  getBuildName,
+  getParallelId,
+} from './environment-config.js';
 import { getProjectMapping } from './global-config.js';
 import * as output from './output.js';
 
@@ -105,13 +110,18 @@ export async function loadConfig(configPath = null, cliOverrides = {}) {
   // 4. Override with environment variables (higher priority than fallbacks)
   const envApiKey = getApiToken();
   const envApiUrl = getApiUrl();
+  const envBuildName = getBuildName();
   const envParallelId = getParallelId();
 
   if (envApiKey) {
     config.apiKey = envApiKey;
     output.debug('config', 'using token from environment');
   }
   if (envApiUrl !== 'https://app.vizzly.dev') config.apiUrl = envApiUrl;
+  if (envBuildName) {
+    config.build.name = envBuildName;
+    output.debug('config', 'using build name from environment');
+  }
   if (envParallelId) config.parallelId = envParallelId;
 
   // 5. Apply CLI overrides (highest priority)

src/utils/environment-config.js

@@ -77,6 +77,14 @@ export function getParallelId() {
   return process.env.VIZZLY_PARALLEL_ID;
 }
 
+/**
+ * Get build name from environment
+ * @returns {string|undefined} Build name
+ */
+export function getBuildName() {
+  return process.env.VIZZLY_BUILD_NAME;
+}
+
 /**
  * Check if TDD mode is enabled
  * @returns {boolean} Whether TDD mode is enabled
@@ -107,6 +115,7 @@ export function getAllEnvironmentConfig() {
     enabled: isVizzlyEnabled(),
     serverUrl: getServerUrl(),
     buildId: getBuildId(),
+    buildName: getBuildName(),
     parallelId: getParallelId(),
     tddMode: isTddMode(),
   };

tests/utils/config-loader.test.js

@@ -54,12 +54,14 @@ describe('utils/config-loader', () => {
       originalEnv = {
         VIZZLY_TOKEN: process.env.VIZZLY_TOKEN,
         VIZZLY_API_URL: process.env.VIZZLY_API_URL,
+        VIZZLY_BUILD_NAME: process.env.VIZZLY_BUILD_NAME,
         VIZZLY_PARALLEL_ID: process.env.VIZZLY_PARALLEL_ID,
         VIZZLY_HOME: process.env.VIZZLY_HOME,
       };
 
       // Clean env
       delete process.env.VIZZLY_TOKEN;
+      delete process.env.VIZZLY_BUILD_NAME;
       delete process.env.VIZZLY_PARALLEL_ID;
 
       // Create test directory
@@ -135,6 +137,22 @@ describe('utils/config-loader', () => {
       assert.strictEqual(config.parallelId, 'parallel-123');
     });
 
+    it('applies VIZZLY_BUILD_NAME environment variable', async () => {
+      process.env.VIZZLY_BUILD_NAME = 'CI Build #123';
+
+      let config = await loadConfig();
+
+      assert.strictEqual(config.build.name, 'CI Build #123');
+    });
+
+    it('CLI buildName overrides VIZZLY_BUILD_NAME', async () => {
+      process.env.VIZZLY_BUILD_NAME = 'env-build-name';
+
+      let config = await loadConfig(null, { buildName: 'cli-build-name' });
+
+      assert.strictEqual(config.build.name, 'cli-build-name');
+    });
+
     it('CLI token overrides env token', async () => {
       process.env.VIZZLY_TOKEN = 'env-token';
 

tests/utils/environment-config.test.js

@@ -5,6 +5,7 @@ import {
   getApiToken,
   getApiUrl,
   getBuildId,
+  getBuildName,
   getLogLevel,
   getParallelId,
   getServerUrl,
@@ -30,6 +31,7 @@ describe('utils/environment-config', () => {
       'VIZZLY_ENABLED',
       'VIZZLY_SERVER_URL',
       'VIZZLY_BUILD_ID',
+      'VIZZLY_BUILD_NAME',
       'VIZZLY_PARALLEL_ID',
       'VIZZLY_TDD',
     ];
@@ -156,6 +158,18 @@ describe('utils/environment-config', () => {
     });
   });
 
+  describe('getBuildName', () => {
+    it('returns undefined when not set', () => {
+      assert.strictEqual(getBuildName(), undefined);
+    });
+
+    it('returns VIZZLY_BUILD_NAME when set', () => {
+      process.env.VIZZLY_BUILD_NAME = 'My CI Build';
+
+      assert.strictEqual(getBuildName(), 'My CI Build');
+    });
+  });
+
   describe('isTddMode', () => {
     it('returns false when not set', () => {
       assert.strictEqual(isTddMode(), false);
@@ -213,6 +227,7 @@ describe('utils/environment-config', () => {
         enabled: false,
         serverUrl: undefined,
         buildId: undefined,
+        buildName: undefined,
         parallelId: undefined,
         tddMode: false,
       });
@@ -227,6 +242,7 @@ describe('utils/environment-config', () => {
       process.env.VIZZLY_ENABLED = 'true';
       process.env.VIZZLY_SERVER_URL = 'http://server';
       process.env.VIZZLY_BUILD_ID = 'build';
+      process.env.VIZZLY_BUILD_NAME = 'My Build';
       process.env.VIZZLY_PARALLEL_ID = 'parallel';
       process.env.VIZZLY_TDD = 'true';
 
@@ -241,6 +257,7 @@ describe('utils/environment-config', () => {
         enabled: true,
         serverUrl: 'http://server',
         buildId: 'build',
+        buildName: 'My Build',
         parallelId: 'parallel',
         tddMode: true,
       });