hana-developer-cli-tool-example test-utilities-reuse.instructions.md

Test Utilities Discovery and Reuse Guidelines

Use this guide when creating or updating test files to leverage the established testing infrastructure. This project has comprehensive test utilities in tests/utils/ and tests/base.js that should be discovered and reused rather than recoded.

Critical Principle: Reuse Before Recode

Always check tests/utils/ and tests/base.js for existing functionality before implementing new test helpers.

The project has:

• Comprehensive mocking patterns for ESM modules
• Shared assertion and reporting utilities
• CLI command execution helpers
• Database client testing patterns
• File system mocking conventions
• External CLI integration patterns (BTP, CF)

Core Test Infrastructure

Central Base Utilities (tests/base.js)

The tests/base.js file provides foundational test utilities used across all test files:

import { assert, addContext, exec, fork, myTest } from '../base.js'

Available exports:

1. assert - Node.js built-in assertion library

   assert.strictEqual(actual, expected)
   assert.deepStrictEqual(obj1, obj2)
   assert.ok(value)
   assert.throws(() => { /* code */ }, /error pattern/)
   

2. addContext - Mochawesome context injection for HTML reports

   addContext(this, { title: 'Debug Info', value: data })
   

3. exec - Child process execution for subprocess testing

   exec('command', (error, stdout, stderr) => { /* callback */ })
   

4. fork - Child process fork for concurrent execution

   fork('script.js', args, options)
   

5. myTest(command, done) - Specialized CLI command test helper

   • Executes CLI commands via subprocess
   • Automatically filters debug output from stderr
   • Injects stdout into Mochawesome context
   • Throws on unexpected stderr content

   Usage pattern:

   it("returns help output", function (done) {
       const localTest = base.myTest.bind(this)
       localTest("node bin/commandName.js --help", done)
   })