@jamaynor/hal-config 1.0.1

package/test/test-utils.test.js

@@ -0,0 +1,360 @@
+/**
+ * test-utils.test
+ *
+ * Responsibility: Verify all helpers exported by test-utils.js work correctly.
+ */
+
+import { describe, it, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+import {
+  makeTmpDir,
+  makeTmpDirAsync,
+  cleanup,
+  cleanupAsync,
+  scaffold,
+  captureLog,
+  captureStderr,
+  captureWarn,
+  captureOutput,
+  silent,
+  withCapturedLog,
+  writeJson,
+  mockProcessExit,
+} from '../test-utils.js';
+
+// ============================================================================
+// makeTmpDir / makeTmpDirAsync / cleanup / cleanupAsync
+// ============================================================================
+
+describe('makeTmpDir', () => {
+  it('returns a path that exists and starts with os.tmpdir()', () => {
+    const dir = makeTmpDir();
+    assert.ok(fs.existsSync(dir), 'directory must exist');
+    assert.ok(dir.startsWith(os.tmpdir()), 'must be under os.tmpdir()');
+    cleanup(dir);
+  });
+
+  it('uses a custom prefix', () => {
+    const dir = makeTmpDir('my-custom-prefix-');
+    assert.ok(fs.existsSync(dir));
+    const base = path.basename(dir);
+    assert.ok(base.startsWith('my-custom-prefix-'), `basename "${base}" should start with custom prefix`);
+    cleanup(dir);
+  });
+
+  it('makeTmpDirAsync returns a promise that resolves to an existing path', async () => {
+    const dir = await makeTmpDirAsync();
+    assert.ok(fs.existsSync(dir), 'directory must exist');
+    assert.ok(dir.startsWith(os.tmpdir()), 'must be under os.tmpdir()');
+    cleanup(dir);
+  });
+
+  it('cleanup removes the directory and all contents', () => {
+    const dir = makeTmpDir();
+    fs.writeFileSync(path.join(dir, 'file.txt'), 'hello');
+    cleanup(dir);
+    assert.ok(!fs.existsSync(dir), 'directory must not exist after cleanup');
+  });
+
+  it('cleanup(null) does not throw', () => {
+    assert.doesNotThrow(() => cleanup(null));
+  });
+
+  it('cleanup with nonexistent path does not throw', () => {
+    assert.doesNotThrow(() => cleanup('/nonexistent-path-xyz-hal-test'));
+  });
+
+  it('cleanupAsync removes the directory', async () => {
+    const dir = await makeTmpDirAsync();
+    fs.writeFileSync(path.join(dir, 'data.txt'), 'content');
+    await cleanupAsync(dir);
+    assert.ok(!fs.existsSync(dir), 'directory must not exist after cleanupAsync');
+  });
+});
+
+// ============================================================================
+// scaffold
+// ============================================================================
+
+describe('scaffold', () => {
+  let tmpDir;
+
+  afterEach(() => { cleanup(tmpDir); });
+
+  it('creates nested directories', () => {
+    tmpDir = makeTmpDir();
+    scaffold(tmpDir, { dirs: ['a/b/c', 'd/e'] });
+    assert.ok(fs.existsSync(path.join(tmpDir, 'a', 'b', 'c')));
+    assert.ok(fs.existsSync(path.join(tmpDir, 'd', 'e')));
+  });
+
+  it('writes string files verbatim', () => {
+    tmpDir = makeTmpDir();
+    scaffold(tmpDir, { files: { 'hello.txt': 'world\n' } });
+    const content = fs.readFileSync(path.join(tmpDir, 'hello.txt'), 'utf8');
+    assert.equal(content, 'world\n');
+  });
+
+  it('JSON-stringifies object files', () => {
+    tmpDir = makeTmpDir();
+    scaffold(tmpDir, { files: { 'config.json': { key: 'value', num: 42 } } });
+    const content = fs.readFileSync(path.join(tmpDir, 'config.json'), 'utf8');
+    const parsed = JSON.parse(content);
+    assert.equal(parsed.key, 'value');
+    assert.equal(parsed.num, 42);
+  });
+
+  it('creates parent directories for files automatically', () => {
+    tmpDir = makeTmpDir();
+    scaffold(tmpDir, { files: { 'deep/nested/dir/file.txt': 'data' } });
+    const full = path.join(tmpDir, 'deep', 'nested', 'dir', 'file.txt');
+    assert.ok(fs.existsSync(full));
+    assert.equal(fs.readFileSync(full, 'utf8'), 'data');
+  });
+});
+
+// ============================================================================
+// Output capture helpers
+// ============================================================================
+
+describe('captureLog', () => {
+  it('captures console.log calls', () => {
+    const cap = captureLog();
+    console.log('hello', 'world');
+    console.log('second');
+    cap.restore();
+    assert.deepStrictEqual(cap.lines, ['hello world', 'second']);
+  });
+
+  it('restore stops capturing', () => {
+    const cap = captureLog();
+    console.log('captured');
+    cap.restore();
+    console.log('not captured');
+    assert.deepStrictEqual(cap.lines, ['captured']);
+  });
+
+  it('captured lines are strings (arguments joined with space)', () => {
+    const cap = captureLog();
+    console.log('a', 'b', 'c');
+    cap.restore();
+    assert.equal(typeof cap.lines[0], 'string');
+    assert.equal(cap.lines[0], 'a b c');
+  });
+
+  it('restore is idempotent — calling twice does not throw', () => {
+    const cap = captureLog();
+    cap.restore();
+    assert.doesNotThrow(() => cap.restore());
+  });
+});
+
+describe('captureStderr', () => {
+  it('captures console.error calls', () => {
+    const cap = captureStderr();
+    console.error('err1');
+    console.error('err2', 'details');
+    cap.restore();
+    assert.deepStrictEqual(cap.lines, ['err1', 'err2 details']);
+  });
+
+  it('restore is idempotent', () => {
+    const cap = captureStderr();
+    cap.restore();
+    assert.doesNotThrow(() => cap.restore());
+  });
+});
+
+describe('captureWarn', () => {
+  it('captures console.warn calls', () => {
+    const cap = captureWarn();
+    console.warn('warning one');
+    console.warn('warning', 'two');
+    cap.restore();
+    assert.deepStrictEqual(cap.lines, ['warning one', 'warning two']);
+  });
+
+  it('restore is idempotent', () => {
+    const cap = captureWarn();
+    cap.restore();
+    assert.doesNotThrow(() => cap.restore());
+  });
+});
+
+describe('captureOutput', () => {
+  it('captures console.log into stdout array', () => {
+    const cap = captureOutput();
+    console.log('out1');
+    console.log('out2');
+    cap.restore();
+    assert.deepStrictEqual(cap.stdout, ['out1', 'out2']);
+  });
+
+  it('captures console.error into stderr array independently', () => {
+    const cap = captureOutput();
+    console.error('err1');
+    cap.restore();
+    assert.deepStrictEqual(cap.stderr, ['err1']);
+    assert.deepStrictEqual(cap.stdout, []);
+  });
+
+  it('captures process.stdout.write chunks into raw array', () => {
+    const cap = captureOutput();
+    process.stdout.write('chunk1');
+    process.stdout.write(Buffer.from('chunk2'));
+    cap.restore();
+    assert.equal(cap.raw.length, 2);
+    assert.equal(cap.raw[0], 'chunk1');
+  });
+
+  it('replaced process.stdout.write returns true', () => {
+    const cap = captureOutput();
+    const result = process.stdout.write('test');
+    cap.restore();
+    assert.equal(result, true);
+  });
+
+  it('all three channels captured independently', () => {
+    const cap = captureOutput();
+    console.log('log-msg');
+    console.error('err-msg');
+    process.stdout.write('raw-msg');
+    cap.restore();
+    assert.deepStrictEqual(cap.stdout, ['log-msg']);
+    assert.deepStrictEqual(cap.stderr, ['err-msg']);
+    assert.equal(cap.raw[0], 'raw-msg');
+  });
+
+  it('restore is idempotent', () => {
+    const cap = captureOutput();
+    cap.restore();
+    assert.doesNotThrow(() => cap.restore());
+  });
+});
+
+describe('silent', () => {
+  it('suppresses output and returns the function return value', () => {
+    let logged = false;
+    const origLog = console.log;
+    const result = silent(() => {
+      console.log('suppressed');
+      logged = true;
+      return 42;
+    });
+    // After silent, console.log should be restored
+    assert.equal(console.log, origLog);
+    assert.equal(result, 42);
+  });
+
+  it('handles async functions correctly', async () => {
+    const origLog = console.log;
+    const result = await silent(async () => {
+      console.log('async suppressed');
+      return 'async-result';
+    });
+    assert.equal(console.log, origLog);
+    assert.equal(result, 'async-result');
+  });
+});
+
+describe('withCapturedLog', () => {
+  it('returns captured lines from fn', () => {
+    const lines = withCapturedLog(() => {
+      console.log('line one');
+      console.log('line two');
+    });
+    assert.deepStrictEqual(lines, ['line one', 'line two']);
+  });
+
+  it('restores console.log after capture', () => {
+    const origLog = console.log;
+    withCapturedLog(() => { console.log('captured'); });
+    assert.equal(console.log, origLog);
+  });
+});
+
+// ============================================================================
+// writeJson
+// ============================================================================
+
+describe('writeJson', () => {
+  let tmpDir;
+
+  afterEach(() => { cleanup(tmpDir); });
+
+  it('creates parent directories and writes valid JSON', () => {
+    tmpDir = makeTmpDir();
+    const filePath = path.join(tmpDir, 'nested', 'dir', 'config.json');
+    const data = { foo: 'bar', count: 7 };
+    writeJson(filePath, data);
+    assert.ok(fs.existsSync(filePath));
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    assert.deepStrictEqual(parsed, data);
+  });
+
+  it('writes valid JSON that can be read back and parsed', () => {
+    tmpDir = makeTmpDir();
+    const filePath = path.join(tmpDir, 'data.json');
+    const data = { arr: [1, 2, 3], nested: { x: true } };
+    writeJson(filePath, data);
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    assert.deepStrictEqual(parsed, data);
+  });
+});
+
+// ============================================================================
+// mockProcessExit
+// ============================================================================
+
+describe('mockProcessExit', () => {
+  let mock;
+
+  afterEach(() => {
+    if (mock) {
+      mock.restore();
+      mock = null;
+    }
+  });
+
+  it('captures the exit code', () => {
+    mock = mockProcessExit();
+    try { process.exit(3); } catch { /* expected */ }
+    assert.equal(mock.code, 3);
+  });
+
+  it('throws on process.exit so test execution stops', () => {
+    mock = mockProcessExit();
+    assert.throws(
+      () => process.exit(1),
+      (err) => err.message === 'process.exit called'
+    );
+  });
+
+  it('thrown error has exitCode property', () => {
+    mock = mockProcessExit();
+    let caught;
+    try { process.exit(99); } catch (err) { caught = err; }
+    assert.equal(caught.exitCode, 99);
+  });
+
+  it('restore puts real process.exit back', () => {
+    mock = mockProcessExit();
+    mock.restore();
+    // After restore, calling our mock should no longer throw
+    // (we verify process.exit is the real one by checking it does not throw
+    // when called from our fake invoker — we do NOT actually call process.exit here)
+    assert.equal(typeof process.exit, 'function');
+    // The mock's throw should no longer be in effect — mock.restore() was called,
+    // so calling process.exit would use the real one. We just verify the type.
+  });
+
+  it('restore is idempotent — calling twice does not throw', () => {
+    mock = mockProcessExit();
+    mock.restore();
+    assert.doesNotThrow(() => mock.restore());
+  });
+});