hana-cli/docs/developer-notes/generic-flags-testing.md

HANA Developer Command Line Interface

# Generic Flags Testing - Summary

## Problem Identified

The `--debug` flag was not working for any hana-cli commands. When users ran commands with `--debug`, no debug output appeared.

## Root Cause

In the `promptHandler` function in `utils/base.js`, flags like `--debug`, `--disableVerbose`, `--admin`, and `--conn` have `ask: askFalse` to prevent prompting the user. This caused `transformPromptConfig` to return `null`, filtering them out from the prompts array. As a result, these flag values from `argv` were never copied to the `result` object, so `isDebug(result)` always returned false and debug output was never enabled.

## Solution Implemented

Modified the `promptHandler` function to copy all values from `argv` to `result` **before** filtering prompts based on the `ask` property. This ensures that generic flags get their values transferred from command line arguments, even though they don't prompt the user.

**File Changed:** `utils/base.js`

## Tests Created to Prevent Regression

### 1. Integration Tests: `tests/genericFlags.Test.js` (26 tests)

Comprehensive integration tests that spawn actual CLI processes to validate generic flags work correctly across all commands.

**Test Coverage:**

- **Debug Flag Tests (5 tests):** Validates `--debug` and `--Debug` produce debug output
- **Quiet Flag Tests (2 tests):** Ensures `--quiet` and `--disableVerbose` suppress output
- **Help Flag Tests (3 tests):** Verifies `--help` and `-h` display usage information
- **Flag Combination Tests (3 tests):** Tests flags work together correctly
- **Admin/Connection Flag Tests (3 tests):** Validates `--admin`, `-a`, and `--conn` are recognized
- **Cross-Command Persistence Tests (10 tests):** Ensures flags work consistently across commands

**Commands Tested:** tables, views, functions, procedures, schemas

**Execution Time:** ~1 minute (spawns real CLI processes)

**Why This Matters:**

- **Framework-Level Validation:** Tests functionality injected by base framework
- **Early Detection:** Catches issues affecting all commands in one place
- **Regression Prevention:** Prevents similar bugs from recurring
- **Living Documentation:** Demonstrates expected flag behavior

### 2. Unit Tests: `tests/utils/base.Test.js` (33 tests)

Unit tests for base utility functions that support all commands.

**Test Coverage:**

- **isDebug (6 tests):** Flag detection with various inputs
- **isGui (3 tests):** GUI mode detection
- **getBuilder (6 tests):** Option builder with flag groups
- **getPromptSchema (6 tests):** Schema generation with flag injection
- **askFalse (1 test):** Helper for non-prompted options
- **debug function (3 tests):** Debug logging function
- **promptHandler (4 tests):** **Critical regression tests validating argv value transfer**
- **Utilities (2 tests):** Color and localization availability

**Critical Tests:**
The `promptHandler critical path` tests specifically validate that the bug fix works:

- Debug flag copied from argv to result even when `ask()` returns false
- Same validation for disableVerbose, admin, and conn flags
- These tests would have caught the original bug

**Execution Time:** ~36ms (pure unit tests)

## Test Execution

### Run All New Tests

```bash
node ./node_modules/mocha/bin/mocha.js --config=tests/.mocharc.json tests/genericFlags.Test.js tests/utils/base.Test.js
```

### Run Generic Flags Tests Only

```bash
node ./node_modules/mocha/bin/mocha.js --config=tests/.mocharc.json tests/genericFlags.Test.js
```

### Run Base Utility Tests Only

```bash
node ./node_modules/mocha/bin/mocha.js --config=tests/.mocharc.json tests/utils/base.Test.js
```

## Test Results

✅ All 59 tests passing

- 26 integration tests (genericFlags.Test.js)
- 33 unit tests (base.Test.js)

## Documentation Updated

Updated `tests/README_UNIT_TESTS.md` with:

- Documentation for both new test files
- Updated test statistics (now 142 total tests added)
- Updated execution times
- Added coverage information for generic flags
- Added notes about regression prevention

## Benefits

### Immediate

1. **Bug Fixed:** `--debug` flag now works correctly across all commands
2. **Validated:** 59 tests confirm the fix works as expected
3. **Documented:** Clear test documentation for future reference

### Long-Term

1. **Regression Prevention:** Future changes that break generic flags will be caught immediately
2. **Consistency:** All commands guaranteed to handle generic flags the same way
3. **Confidence:** Framework-level changes can be made with confidence
4. **Maintainability:** Tests serve as living documentation of expected behavior
5. **Early Detection:** Issues affecting all commands caught before release

## Files Changed

- ✅ `utils/base.js` - Fixed promptHandler to copy argv values early
- ✅ `tests/genericFlags.Test.js` - New 26 integration tests
- ✅ `tests/utils/base.Test.js` - New 33 unit tests
- ✅ `tests/README_UNIT_TESTS.md` - Updated documentation

## Verification

The fix has been verified to work correctly:

```bash
hana-cli tables --debug --limit 5
# Shows debug output including [cli] markers

hana-cli functions --debug --limit 3  
# Shows debug output including API calls

hana-cli views --quiet
# No debug output, properly suppressed
```