Test Build Result Utility

1.1.2 · active · verified Sun Apr 19

The `test-build-result` package provides a utility for comparing the output of a build process against a set of expected files or directories. This is crucial for integration testing, ensuring that build tools, compilers, or bundlers produce consistent and correct artifacts over time. It offers features for specifying actual and expected file paths, handling file content comparisons, and reporting discrepancies. As of version 1.1.2, the package has been updated with features like `testExists` to verify the presence of specific files and the ability to automatically generate expected directories if they do not exist, streamlining the setup for initial tests. The package maintains an active release cadence, with several minor updates recently, indicating ongoing maintenance and responsiveness to user needs. Its primary differentiator lies in its focused approach to asserting the correctness of filesystem-based build outputs, contrasting with more general-purpose assertion libraries.

Common errors

```
Error: Build result mismatch between actualDir and expectedDir. Details: ...
```
cause One or more files in the actual build output differ in content or existence from the expected build output.

fix Examine the detailed error message to identify the specific file(s) and discrepancies. Update your expected files if the new output is correct, or fix your build process if it's producing incorrect artifacts.
```
Error: ENOENT: no such file or directory, stat '<path_to_dir>'
```
cause Either the `actualDirPath` or `expectedDirPath` provided to `testBuildResult` does not exist on the file system.

fix Ensure that both the actual build output directory and the expected reference directory exist before invoking `testBuildResult`. The package can generate `expectedDirPath` if it's missing (since v1.1.0) but `actualDirPath` must exist.

Warnings

gotcha File path normalization differences across operating systems (Windows vs. macOS/Linux) can lead to unexpected mismatches if not handled carefully. Ensure your build process and test expectations use consistent, normalized paths.
Fix: Use Node.js `path.normalize()` or `path.resolve()` when constructing paths for comparison. Consider using cross-platform path utilities if direct string comparison is part of your testing logic.
gotcha When comparing large directories or numerous files, `test-build-result` performs file system operations which are inherently asynchronous. Not awaiting the `testBuildResult` promise can lead to tests completing prematurely without proper assertions.
Fix: Always `await` the result of `testBuildResult` within an `async` function to ensure all comparisons are completed before the test finishes.
gotcha Dynamic content (e.g., timestamps, build IDs, random hashes) in generated files will cause mismatches unless explicitly handled. The `replaceContent` option can mitigate this but requires careful configuration.
Fix: Identify dynamic parts of your build output and configure the `replaceContent` option to normalize these sections during comparison, or use a custom comparison logic for specific files.

Install

npm install test-build-result npm
yarn add test-build-result yarn
pnpm add test-build-result pnpm

Imports

testBuildResult
wrong:
```
const { testBuildResult } = require('test-build-result');
```
correct:
```
import { testBuildResult } from 'test-build-result';
```
The library primarily uses named exports for its utility functions. While CommonJS `require` might work in some environments, ESM `import` is the recommended and modern approach.

Quickstart

Demonstrates comparing a generated build output directory (`dist_actual`) with an expected output directory (`dist_expected`) using `testBuildResult`, showcasing how to identify discrepancies in build artifacts.

import { testBuildResult } from 'test-build-result';
import * as fs from 'node:fs/promises';
import * as path from 'node:path';

// Mock directories for demonstration
const actualDirPath = './dist_actual';
const expectedDirPath = './dist_expected';

async function setupMockFiles() {
  await fs.mkdir(actualDirPath, { recursive: true });
  await fs.mkdir(expectedDirPath, { recursive: true });
  await fs.writeFile(path.join(actualDirPath, 'index.js'), 'console.log("Hello from actual!");');
  await fs.writeFile(path.join(actualDirPath, 'style.css'), 'body { color: blue; }');
  await fs.writeFile(path.join(expectedDirPath, 'index.js'), 'console.log("Hello from actual!");');
  await fs.writeFile(path.join(expectedDirPath, 'style.css'), 'body { color: red; }'); // Intentional difference
}

async function cleanupMockFiles() {
  await fs.rm(actualDirPath, { recursive: true, force: true });
  await fs.rm(expectedDirPath, { recursive: true, force: true });
}

async function runTest() {
  await cleanupMockFiles(); // Ensure clean slate
  await setupMockFiles();

  try {
    console.log('Running build result test...');
    await testBuildResult(actualDirPath, expectedDirPath, {
      // Optional: replace content during comparison if dynamic parts exist
      // replaceContent: { 'dynamic_timestamp': 'fixed_timestamp' }
    });
    console.log('Build result matches expected output.');
  } catch (error) {
    if (error instanceof Error) {
      console.error('Build result mismatch detected:', error.message);
      // In a real test, you'd throw or assert here
    } else {
      console.error('An unexpected error occurred:', error);
    }
  } finally {
    await cleanupMockFiles();
  }
}

runTest();

view raw JSON →