tests

Nim Debug Adapter Tests

This directory contains comprehensive test suites for the Nim Debug Adapter.

Test Structure

tests/
├── unit/                  # Unit tests (fast, no external dependencies)
│   ├── test_all.nim      # Run all unit tests
│   ├── test_config.nim   # Configuration tests
│   ├── test_transport.nim # DAP transport tests
│   └── ...               # Other unit tests
│
├── integration/          # Integration tests (require GDB/LLDB)
│   ├── test_all.nim     # Run all integration tests
│   ├── test_gdb_real.nim    # GDB integration tests
│   ├── test_lldb_real.nim   # LLDB integration tests
│   └── test_dap_e2e.nim     # End-to-end DAP tests
│
└── test_all.nim         # Main test runner

Running Tests

Prerequisites Check

# Check if your system is ready for integration tests
nimble checkRequirements

Unit Tests (Fast, No Dependencies)

# Run all unit tests
nimble test

# Run individual unit tests
nimble testUnit

# Run specific test file
nim c -r tests/unit/test_config.nim

Integration Tests (Require GDB/LLDB)

# Check requirements first
nimble checkRequirements

# Run integration tests with timeout protection (recommended)
nimble testIntegration

# Run integration tests without timeout (may hang)
nimble testIntegrationUnsafe

# Run with environment variable
RUN_INTEGRATION_TESTS=1 nimble test

# Run specific integration test
nim c -d:integrationTests -r tests/integration/test_gdb_real.nim

Troubleshooting Integration Tests

If integration tests hang or fail:

1. Check requirements: nimble checkRequirements
2. Install missing tools:

   # Ubuntu/Debian
   sudo apt install gdb lldb build-essential
   
   # macOS
   brew install gdb lldb

3. Run with timeout: Use nimble testIntegration instead of nimble testIntegrationUnsafe
4. Debug specific test: Run individual test files directly

All Tests

# Run both unit and integration tests
nimble testAll

Test Categories

Unit Tests

• Configuration: Test configuration loading, environment variables, and defaults
• Transport: Test DAP message transport layer
• Handlers: Test DAP request handlers with mocks
• Breakpoints: Test breakpoint management
• Patterns: Test error handling, logging, factory, and observer patterns
• Enhanced Tests: Comprehensive tests for each component

Integration Tests

• GDB Real: Test actual GDB integration

  • Version checking
  • Program loading and execution
  • Breakpoint setting
  • Expression evaluation
  • Stack traces
  • Nim program debugging

• LLDB Real: Test actual LLDB integration

  • Similar to GDB tests but for LLDB
  • Platform-specific features
  • Watchpoints

• DAP End-to-End: Complete debug sessions

  • Full initialize-launch-debug-terminate cycle
  • Nim program debugging through DAP
  • Exception handling
  • Multi-threaded debugging

CI/CD Integration

The test suite is integrated with GitHub Actions:

1. Unit Tests: Run on every push/PR

   • Multiple OS: Ubuntu, macOS, Windows
   • Multiple Nim versions: stable, devel

2. Integration Tests: Run on supported platforms

   • Ubuntu with GDB
   • macOS with LLDB
   • Skip when debugger not available

3. Code Coverage: Tracked with lcov

   • Unit test coverage
   • Upload to Codecov

Writing New Tests

Unit Test Template

import std/unittest
import ../../src/nim_debug_adapter/module_to_test

suite "Component Tests":
  setup:
    # Setup before each test
    discard
  
  test "Feature test":
    # Arrange
    let input = createTestInput()
    
    # Act
    let result = functionUnderTest(input)
    
    # Assert
    check result.isSuccess
    check result.value == expected

Integration Test Template

import std/[unittest, os, osproc]
import ../../src/nim_debug_adapter/debugger/gdb

suite "GDB Integration Tests":
  setup:
    # Check prerequisites
    if findExe("gdb") == "":
      skip("GDB not found")
  
  test "Real GDB test":
    let gdb = newGdbInterface()
    waitFor gdb.launch()
    
    # Test with real GDB
    let response = waitFor gdb.sendCommand("-gdb-version")
    check response.contains("GNU gdb")
    
    waitFor gdb.terminate()

Test Coverage

Current test coverage: 98.5% (unit tests)

Coverage by Module

• Configuration: 100%
• Transport: 100%
• Handlers: 98%
• Breakpoints: 100%
• Error Handling: 100%
• Logging: 100%
• Factory Pattern: 100%
• Observer Pattern: 100%

Known Issues

1. Integration Test Requirements: Integration tests require GDB/LLDB to be installed
2. Platform Differences: Some tests behave differently on different operating systems
3. Async Test Timing: Some async tests may be sensitive to system load

Test Utilities

• mocks.nim - Mock implementations for debugger backends and processes
• run_individual_tests.nim - Utility to run tests with timeout
• benchmarks.nim - Performance benchmarks

Troubleshooting

Test Failures

1. Check test output for specific error messages
2. Run individual test files for isolation
3. Enable debug logging: setLogLevel(Debug)

Integration Test Issues

1. Ensure GDB/LLDB is installed
2. Check debugger version compatibility
3. Verify test programs compile correctly
4. Check for permission issues

Performance

• Unit tests should complete in < 5 seconds
• Integration tests may take 30-60 seconds
• Use nimble test for quick feedback during development
• Run nimble testAll before commits