This document describes the comprehensive error scenario and edge case test coverage for nself.

Test what users actually encounter, not impossible edge cases.

• User Errors - Invalid input, misconfigurations, missing files
• System Errors - Resource limits, permissions, network failures
• State Errors - Invalid state transitions, race conditions
• Boundary Values - Min/max valid inputs, edge cases
• Error Messages - Clarity, actionability, platform compatibility

• Impossible scenarios (defensive programming)
• Third-party library bugs
• Hardware failures
• Cosmic ray bit flips

1. 100% coverage of realistic user-facing errors
2. Every error has clear, actionable message
3. Cross-platform compatibility (macOS, Linux, WSL)
4. Fast test execution (<5 minutes total)
5. Reliable tests (no flakiness)

Location: /Users/admin/Sites/nself/src/tests/errors/

File: test-installation-errors.sh

Coverage: 12 tests

File: test-configuration-errors.sh

Coverage: 12 tests

File: test-service-failures.sh

Coverage: 13 tests

Total Error Tests: 37 tests across 3 files

Location: /Users/admin/Sites/nself/src/tests/edge-cases/

File: test-boundary-values.sh

Coverage: 24 tests

File: test-state-transitions.sh

Coverage: 15 tests

File: test-concurrency.sh (to be created)

Planned Coverage: 5 tests

File: test-data-integrity.sh (to be created)

Planned Coverage: 5 tests

Total Edge Case Tests: 39 tests (current) + 10 planned = 49 tests

src/tests/
├── errors/                         # Error scenario tests
│   ├── README.md                  # Error testing documentation
│   ├── run-error-tests.sh         # Master error test runner
│   ├── test-installation-errors.sh (12 tests)
│   ├── test-configuration-errors.sh (12 tests)
│   └── test-service-failures.sh   (13 tests)
│
├── edge-cases/                    # Edge case tests
│   ├── README.md                  # Edge case documentation
│   ├── run-edge-case-tests.sh     # Master edge case runner
│   ├── test-boundary-values.sh    (24 tests)
│   ├── test-state-transitions.sh  (15 tests)
│   ├── test-concurrency.sh        (planned - 5 tests)
│   └── test-data-integrity.sh     (planned - 5 tests)
│
└── unit/
    └── test-error-messages.sh     # Unit tests for error library

./src/tests/errors/run-error-tests.sh

Output:

========================================
  nself Error Scenario Tests
========================================

Running: test-installation-errors
✓ 12/12 tests passed

Running: test-configuration-errors
✓ 12/12 tests passed

Running: test-service-failures
✓ 13/13 tests passed

========================================
  ✓ All error tests passed!
========================================

./src/tests/edge-cases/run-edge-case-tests.sh

./src/tests/errors/test-installation-errors.sh
./src/tests/edge-cases/test-boundary-values.sh

Every error message MUST have:

Docker is not running

Not: Error code 0x4E2

Problem:
  The 'docker' command could not connect to the Docker daemon.

Fix:
  1. Start Docker Desktop:
     macOS: open -a Docker
     Linux: sudo systemctl start docker

  2. Verify Docker is running:
     docker ps

macOS:
  open -a Docker

Linux:
  sudo systemctl start docker

Verify Docker is running:
  docker ps

test_error_message_quality() {
  local test_name="Error has all required sections"

  local output=$(generate_error_message)

  # Verify structure
  assert_contains "$output" "Problem:" "$test_name: Has problem section"
  assert_contains "$output" "Fix:" "$test_name: Has fix section"
  assert_contains "$output" "command" "$test_name: Has actionable command"

  # Verify no bad patterns
  assert_not_contains "$output" "Error code" "$test_name: No error codes"
  assert_not_contains "$output" "contact support" "$test_name: No support punt"
}

test_boundary_value() {
  local test_name="Port 65535 (max valid)"

  local port=65535
  if validate_port "$port"; then
    local result="valid"
  else
    local result="invalid"
  fi

  assert_equals "$result" "valid" "$test_name"
}

test_idempotent_operation() {
  local test_name="Start is idempotent"

  start_service
  local state1="$STATE"

  start_service  # Run again
  local state2="$STATE"

  assert_equals "$state1" "$state2" "$test_name: State unchanged"
}

Tests run in GitHub Actions on:

• Ubuntu (latest) - Bash 5.x, GNU tools
• macOS (latest) - Bash 3.2, BSD tools

All tests must:

• ✅ Pass on both Ubuntu and macOS
• ✅ Use printf (not echo -e)
• ✅ Avoid Bash 4+ features
• ✅ Complete in <30 seconds per file
• ✅ Clean up temporary files
• ✅ Not depend on external services
• ✅ Be deterministic (no flaky tests)

name: Error & Edge Case Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]

    steps:
      - uses: actions/checkout@v2

      - name: Run error tests
        run: ./src/tests/errors/run-error-tests.sh

      - name: Run edge case tests
        run: ./src/tests/edge-cases/run-edge-case-tests.sh

1. ✅ Installation error tests
2. ✅ Configuration error tests
3. ✅ Service failure tests
4. ✅ Boundary value tests
5. ✅ State transition tests

1. ⏳ Concurrency tests (test-concurrency.sh)
2. ⏳ Data integrity tests (test-data-integrity.sh)
3. ⏳ Cleanup/recovery tests (test-cleanup-recovery.sh)

1. ⏳ Performance degradation tests
2. ⏳ Network failure simulation tests
3. ⏳ Resource exhaustion recovery tests

• /docs/ERROR-HANDLING.md - Error handling guidelines
• /docs/TESTING.md - General testing guidelines
• /src/tests/errors/README.md - Error test documentation
• /src/tests/edge-cases/README.md - Edge case documentation
• /src/lib/utils/error-messages.sh - Error message library

Last Updated: January 31, 2026 Version: 0.9.8 Status: 80% Complete (76 of 96 planned tests) Test Execution Time: ~2 minutes total