hana-developer-cli-tool-example e2e-test-creation.instructions.md

End-to-End (E2E) Test Creation Guide

Use this guide when creating end-to-end tests that validate complete CLI command workflows through subprocess execution. E2E tests execute real commands and verify their output, behavior, flags, and integration scenarios.

What Are E2E Tests?

E2E tests are subprocess-based tests that:

• Execute real CLI commands via node bin/cli.js <command>
• Validate actual command output (stdout/stderr)
• Verify flag behavior and combinations
• Test help output and documentation
• Validate error conditions and edge cases
• Ensure commands work independently and in sequences

When to use E2E tests:

• Testing CLI command behavior and output
• Validating command flags and options work correctly
• Verifying help/documentation output
• Testing commands that require real execution (not mock-friendly)
• Integration tests between command and system

When NOT to use E2E tests:

• Unit testing utility functions (use tests/utils/*.test.js instead)
• Testing route handlers (use tests/routes/*.test.js instead)
• Testing internal class methods (use unit tests instead)

File Naming and Organization

• Naming Convention: commandName.e2e.Test.js
• Location: tests/e2e/ directory (use tests/e2e/routes/ for route/WebSocket E2E tests)
• Pattern: Files matching tests/e2e/**/*.e2e.Test.js are discovered and run by E2E test scripts

Examples:

• tests/e2e/version.e2e.Test.js - E2E tests for version command
• tests/e2e/tables.e2e.Test.js - E2E tests for tables command
• tests/e2e/status.e2e.Test.js - E2E tests for status command

Test Infrastructure

Base Module (tests/base.js)

The base.js module provides core functionality for E2E tests:

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

// Execute a CLI command and capture output
base.exec(command, (error, stdout, stderr) => {
  // error: null if command succeeded, otherwise Error object
  // stdout: standard output as string
  // stderr: standard error as string
})

// Add test context to mochawesome report
base.addContext(this, { title: 'Label', value: 'content' })

// Assertion library
import { expect } from 'chai'
expect(value).to.equal(expected)