{"id":14964,"library":"test-build-result","title":"Test Build Result Utility","description":"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.","status":"active","version":"1.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/sorrycc/test-build-result","tags":["javascript","test"],"install":[{"cmd":"npm install test-build-result","lang":"bash","label":"npm"},{"cmd":"yarn add test-build-result","lang":"bash","label":"yarn"},{"cmd":"pnpm add test-build-result","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { testBuildResult } = require('test-build-result');","symbol":"testBuildResult","correct":"import { testBuildResult } from 'test-build-result';"}],"quickstart":{"code":"import { testBuildResult } from 'test-build-result';\nimport * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\n\n// Mock directories for demonstration\nconst actualDirPath = './dist_actual';\nconst expectedDirPath = './dist_expected';\n\nasync function setupMockFiles() {\n  await fs.mkdir(actualDirPath, { recursive: true });\n  await fs.mkdir(expectedDirPath, { recursive: true });\n  await fs.writeFile(path.join(actualDirPath, 'index.js'), 'console.log(\"Hello from actual!\");');\n  await fs.writeFile(path.join(actualDirPath, 'style.css'), 'body { color: blue; }');\n  await fs.writeFile(path.join(expectedDirPath, 'index.js'), 'console.log(\"Hello from actual!\");');\n  await fs.writeFile(path.join(expectedDirPath, 'style.css'), 'body { color: red; }'); // Intentional difference\n}\n\nasync function cleanupMockFiles() {\n  await fs.rm(actualDirPath, { recursive: true, force: true });\n  await fs.rm(expectedDirPath, { recursive: true, force: true });\n}\n\nasync function runTest() {\n  await cleanupMockFiles(); // Ensure clean slate\n  await setupMockFiles();\n\n  try {\n    console.log('Running build result test...');\n    await testBuildResult(actualDirPath, expectedDirPath, {\n      // Optional: replace content during comparison if dynamic parts exist\n      // replaceContent: { 'dynamic_timestamp': 'fixed_timestamp' }\n    });\n    console.log('Build result matches expected output.');\n  } catch (error) {\n    if (error instanceof Error) {\n      console.error('Build result mismatch detected:', error.message);\n      // In a real test, you'd throw or assert here\n    } else {\n      console.error('An unexpected error occurred:', error);\n    }\n  } finally {\n    await cleanupMockFiles();\n  }\n}\n\nrunTest();\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always `await` the result of `testBuildResult` within an `async` function to ensure all comparisons are completed before the test finishes.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.1.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"One or more files in the actual build output differ in content or existence from the expected build output.","error":"Error: Build result mismatch between actualDir and expectedDir. Details: ..."},{"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.","cause":"Either the `actualDirPath` or `expectedDirPath` provided to `testBuildResult` does not exist on the file system.","error":"Error: ENOENT: no such file or directory, stat '<path_to_dir>'"}],"ecosystem":"npm"}