Skip to content

# 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:

1. 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

1. 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

1. Rate Limiting (`checkRateLimit`)
2. 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');
        }
      }
    });

1. Request Validation (`validateRequestHeaders`)
2. Tests content type validation
3. Checks request size limits
4. 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');
    });

1. Input Sanitization (`sanitizeValue`)
2. Sanitizes HTML tags
3. Handles nested objects
4. 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');
    });

1. Security Headers (`applySecurityHeaders`)
2. Verifies correct security header application
3. 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();
    });

1. Error Handling (`handleError`)
2. Tests error responses in production and development modes
3. 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

1. Use minimal, focused test cases
2. Test both successful and failure scenarios
3. Verify input sanitization and security measures
4. 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

1. Isolation: Each test should be independent and not rely on the state of other tests.
2. Mocking: Use the provided mock utilities for external dependencies.
3. Cleanup: Clean up any resources or state modifications in `afterEach` or `afterAll` hooks.
4. Descriptive Names: Use clear, descriptive test names that explain the expected behavior.
5. Assertions: Make specific, meaningful assertions rather than general ones.
6. Setup: Use `beforeEach` for common test setup to avoid repetition.
7. 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

1. Using Node Inspector:

       # Start tests with inspector
       bun test --inspect

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

2. 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" }
           }
         ]
       }

3. 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

February 4, 2025
February 4, 2025
Was this page helpful?
Thanks for your feedback!
Thanks for your feedback! Please consider creating an issue to help us improve.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings