hana-developer-cli-tool-example testing.instructions.md

Testing Guidelines

Use this guide when creating or updating test files for this project. Tests validate CLI commands, utilities, routes, and error handling to ensure reliability and prevent regressions.

Scope and Test Types

This project contains multiple test types:

1. CLI Command Tests - Validate bin/*.js commands via subprocess execution
2. Unit Tests - Test individual utility functions in isolation
3. Integration Tests - Test routes and Express app functionality using appFactory
4. Error Handling Tests - Validate graceful error scenarios and edge cases
5. Flag Validation Tests - Verify command-line argument parsing and constraints

Test Framework and Configuration

• Test Runner: Mocha (@latest)
• Assertion Library: Node.js built-in assert module
• Reporting: mochawesome for HTML reports
• Execution: Parallel (16 jobs) via .mocharc.json
• Coverage Tool: mochawesome with context injection
• Timeout: Default 10 seconds (set per describe/it block as needed)

Configuration file: .mocharc.json

{
    "timeout": "10s",
    "parallel": true,
    "jobs": 16,
    "reporter": "spec",
    "exit": true,
    "require": ["./tests/helper.js"]
}

File Naming and Organization

• Naming: Use FileName.Test.js or fileName.test.js pattern (flexible casing + .Test.js or .test.js suffix)
• Location: Tests live in tests/ directory, mirroring source structure
• Grouping: Organize related tests in subdirectories:
  • tests/ - CLI command tests
  • tests/utils/ - Utility function tests
  • tests/routes/ - Route integration tests

Examples:

• CLI command: tests/tables.Test.js (tests bin/tables.js)
• Utility test: tests/utils/base.Test.js
• Route test: tests/routes/api.test.js
• Utility helper: tests/utils/connections.Test.js

Test Structure Template

CLI Command Tests

CLI tests execute commands via subprocess and validate output:

// @ts-check
/**
 * @module commandName - Tests for bin/commandName.js
 * 
 * Validates command-line execution, flag parsing, help output,
 * and integration with the CLI framework.
 */

import * as base from './base.js'

describe('commandName', function () {

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

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

    it("accepts and uses limit flag", function (done) {
        const localTest = base.myTest.bind(this)
        localTest("node bin/commandName.js --limit 10 --quiet", done)
    })

})