Testing Documentation

Quick Reference

# Most Common Commands
bun test                    # Run all tests
bun test --watch           # Run tests in watch mode
bun test --coverage        # Run tests with coverage
bun test path/to/test.ts   # Run a specific test file

# Additional Options
DEBUG=true bun test        # Run with debug output
bun test --pattern "auth"  # Run tests matching a pattern
bun test --timeout 60000   # Run with a custom timeout

Overview

This document describes the testing setup and practices used in the Home Assistant MCP project. We use Bun's test runner for both unit and integration testing, ensuring comprehensive coverage across modules.

Test Structure

Tests are organized in two main locations:

Root Level Integration Tests (/__tests__/):

__tests__/
├── ai/              # AI/ML component tests
├── api/             # API integration tests
├── context/         # Context management tests
├── hass/            # Home Assistant integration tests
├── schemas/         # Schema validation tests
├── security/        # Security integration tests
├── tools/           # Tools and utilities tests
├── websocket/       # WebSocket integration tests
├── helpers.test.ts  # Helper function tests
├── index.test.ts    # Main application tests
└── server.test.ts   # Server integration tests

Component Level Unit Tests (src/**/):

src/
├── __tests__/   # Global test setup and utilities
│   └── setup.ts # Global test configuration
├── component/
│   ├── __tests__/   # Component-specific unit tests
│   └── component.ts

Test Configuration

Bun Test Configuration (`bunfig.toml`)

[test]
preload = ["./src/__tests__/setup.ts"]  # Global test setup
coverage = true                         # Enable coverage by default
timeout = 30000                         # Test timeout in milliseconds
testMatch = ["**/__tests__/**/*.test.ts"] # Test file patterns

Bun Scripts

Available test commands in package.json:

# Run all tests
bun test

# Watch mode for development
bun test --watch

# Generate coverage report
bun test --coverage

# Run linting
bun run lint

# Format code
bun run format

Test Setup

Global Configuration

A global test setup file (src/__tests__/setup.ts) provides: - Environment configuration - Mock utilities - Test helper functions - Global lifecycle hooks

Test Environment

Environment variables are loaded from .env.test.
Console output is minimized unless DEBUG=true.
JWT secrets and tokens are preconfigured for testing.
Rate limiting and security features are initialized appropriately.

Running Tests

# Basic test run
bun test

# Run tests with coverage
bun test --coverage

# Run a specific test file
bun test path/to/test.test.ts

# Run tests in watch mode
bun test --watch

# Run tests with debug output
DEBUG=true bun test

# Run tests with increased timeout
bun test --timeout 60000

# Run tests matching a pattern
bun test --pattern "auth"

Advanced Debugging

Using Node Inspector

# Start tests with inspector
bun test --inspect

# Start tests with inspector and break on first line
bun test --inspect-brk

Using VS Code

Create a launch configuration in .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "bun",
      "request": "launch",
      "name": "Debug Tests",
      "program": "${workspaceFolder}/node_modules/bun/bin/bun",
      "args": ["test", "${file}"],
      "cwd": "${workspaceFolder}",
      "env": { "DEBUG": "true" }
    }
  ]
}

Test Isolation

To run a single test in isolation:

describe.only("specific test suite", () => {
  it.only("specific test case", () => {
    // Only this test will run
  });
});

Writing Tests

Test File Naming

Place test files in a __tests__ directory adjacent to the code being tested.
Name files with the pattern *.test.ts.
Mirror the structure of the source code in your test organization.

Example Test Structure

describe("Security Features", () => {
  it("should validate tokens correctly", () => {
    const payload = { userId: "123", role: "user" };
    const token = jwt.sign(payload, validSecret, { expiresIn: "1h" });
    const result = TokenManager.validateToken(token, testIp);
    expect(result.valid).toBe(true);
  });
});

Coverage

The project maintains strict coverage: - Overall coverage: at least 80% - Critical paths: 90%+ - New features: ≥85% coverage

Generate a coverage report with:

bun test --coverage

Security Middleware Testing

Utility Function Testing

The security middleware now uses a utility-first approach, which allows for more granular and comprehensive testing. Each security function is now independently testable, improving code reliability and maintainability.

Key Utility Functions

Rate Limiting (checkRateLimit)
Tests multiple scenarios:
- Requests under threshold
- Requests exceeding threshold
- Rate limit reset after window expiration

// Example test
it('should throw when requests exceed threshold', () => {
  const ip = '127.0.0.2';
  for (let i = 0; i < 11; i++) {
    if (i < 10) {
      expect(() => checkRateLimit(ip, 10)).not.toThrow();
    } else {
      expect(() => checkRateLimit(ip, 10)).toThrow('Too many requests from this IP');
    }
  }
});

Request Validation (validateRequestHeaders)
Tests content type validation
Checks request size limits
Validates authorization headers

it('should reject invalid content type', () => {
  const mockRequest = new Request('http://localhost', {
    method: 'POST',
    headers: { 'content-type': 'text/plain' }
  });
  expect(() => validateRequestHeaders(mockRequest)).toThrow('Content-Type must be application/json');
});

Input Sanitization (sanitizeValue)
Sanitizes HTML tags
Handles nested objects
Preserves non-string values

it('should sanitize HTML tags', () => {
  const input = '<script>alert("xss")</script>Hello';
  const sanitized = sanitizeValue(input);
  expect(sanitized).toBe('&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;Hello');
});

Security Headers (applySecurityHeaders)
Verifies correct security header application
Checks CSP, frame options, and other security headers

it('should apply security headers', () => {
  const mockRequest = new Request('http://localhost');
  const headers = applySecurityHeaders(mockRequest);
  expect(headers['content-security-policy']).toBeDefined();
  expect(headers['x-frame-options']).toBeDefined();
});

Error Handling (handleError)
Tests error responses in production and development modes
Verifies error message and stack trace inclusion

it('should include error details in development mode', () => {
  const error = new Error('Test error');
  const result = handleError(error, 'development');
  expect(result).toEqual({
    error: true,
    message: 'Internal server error',
    error: 'Test error',
    stack: expect.any(String)
  });
});

Testing Philosophy

Isolation: Each utility function is tested independently
Comprehensive Coverage: Multiple scenarios for each function
Predictable Behavior: Clear expectations for input and output
Error Handling: Robust testing of error conditions

Best Practices

Use minimal, focused test cases
Test both successful and failure scenarios
Verify input sanitization and security measures
Mock external dependencies when necessary

Running Security Tests

# Run all tests
bun test

# Run specific security tests
bun test __tests__/security/

Continuous Improvement

Regularly update test cases
Add new test scenarios as security requirements evolve
Perform periodic security audits

Best Practices

Isolation: Each test should be independent and not rely on the state of other tests.
Mocking: Use the provided mock utilities for external dependencies.
Cleanup: Clean up any resources or state modifications in afterEach or afterAll hooks.
Descriptive Names: Use clear, descriptive test names that explain the expected behavior.
Assertions: Make specific, meaningful assertions rather than general ones.
Setup: Use beforeEach for common test setup to avoid repetition.
Error Cases: Test both success and error cases for complete coverage.

Coverage

The project aims for high test coverage, particularly focusing on: - Security-critical code paths - API endpoints - Data validation - Error handling - Event broadcasting

Run coverage reports using:

bun test --coverage

Debugging Tests

To debug tests: 1. Set DEBUG=true to enable console output during tests 2. Use the --watch flag for development 3. Add console.log() statements (they're only shown when DEBUG is true) 4. Use the test utilities' debugging helpers

Advanced Debugging

Using Node Inspector:

# Start tests with inspector
bun test --inspect

# Start tests with inspector and break on first line
bun test --inspect-brk

Using VS Code:

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "bun",
      "request": "launch",
      "name": "Debug Tests",
      "program": "${workspaceFolder}/node_modules/bun/bin/bun",
      "args": ["test", "${file}"],
      "cwd": "${workspaceFolder}",
      "env": { "DEBUG": "true" }
    }
  ]
}

Test Isolation: To run a single test in isolation:

describe.only("specific test suite", () => {
  it.only("specific test case", () => {
    // Only this test will run
  });
});

Contributing

When contributing new code: 1. Add tests for new features 2. Ensure existing tests pass 3. Maintain or improve coverage 4. Follow the existing test patterns and naming conventions 5. Document any new test utilities or patterns

Coverage Requirements

The project maintains strict coverage requirements:

Minimum overall coverage: 80%
Critical paths (security, API, data validation): 90%
New features must include tests with >= 85% coverage

Coverage reports are generated in multiple formats: - Console summary - HTML report (./coverage/index.html) - LCOV report (./coverage/lcov.info)

To view detailed coverage:

# Generate and open coverage report
bun test --coverage && open coverage/index.html

Testing Documentation

Quick Reference

Overview

Test Structure

Test Configuration

Bun Test Configuration (bunfig.toml)

Bun Scripts

Test Setup

Global Configuration

Test Environment

Running Tests

Advanced Debugging

Using Node Inspector

Using VS Code

Test Isolation

Writing Tests

Test File Naming

Example Test Structure

Coverage

Security Middleware Testing

Utility Function Testing

Key Utility Functions

Testing Philosophy

Best Practices

Running Security Tests

Continuous Improvement

Best Practices

Coverage

Debugging Tests

Advanced Debugging

Contributing

Coverage Requirements

Bun Test Configuration (`bunfig.toml`)