mcp-tool/TESTING.md

Laravel Healthcare MCP Server - Testing Guide

Overview

This document provides comprehensive guidance for testing the Laravel Healthcare MCP Server. The test suite includes over 1000+ tests covering all authentication types, healthcare-specific scenarios, HIPAA compliance, and error handling.

Test Structure

Test Organization

tests/
├── mocks/                          # Mock utilities and factories
│   ├── httpMocks.js               # HTTP request/response mocking
│   ├── authMocks.js               # Authentication mocking
│   ├── healthcareDataMocks.js     # Healthcare data generation
│   └── mockFactory.js             # Centralized mock factory
├── public/                         # Public tools tests (77 tools)
│   ├── login.test.js              # Login and authentication
│   ├── registration.test.js       # User registration
│   ├── password-management.test.js # Password operations
│   ├── data-access.test.js        # Public data access
│   └── index.test.js              # Integration tests
├── provider/                       # Provider tools tests (400+ tools)
│   ├── emr-patient-management.test.js    # EMR and patient data
│   ├── prescription-management.test.js   # Prescriptions and medications
│   └── appointment-scheduling.test.js    # Appointments and scheduling
├── patient/                        # Patient tools tests (200+ tools)
│   ├── portal-authentication.test.js     # Patient portal access
│   └── data-management.test.js           # Patient data operations
├── partner-affiliate-network/      # Business tools tests (300+ tools)
│   └── business-operations.test.js       # Business operations
├── healthcare-specific/            # Healthcare compliance tests
│   ├── hipaa-compliance.test.js          # HIPAA compliance validation
│   └── clinical-workflows.test.js        # Clinical decision support
├── error-handling/                 # Error handling tests
│   ├── authentication-errors.test.js     # Auth error scenarios
│   └── api-network-errors.test.js        # API and network errors
└── coverage/                       # Test coverage and reporting
    └── test-runner.js              # Comprehensive test runner

Running Tests

Quick Start

# Run all tests with coverage
npm test

# Run quick test suite (essential tests only)
npm run test:quick

# Run tests with watch mode
npm run test:watch

Test Suites

# Public tools (login, registration, password management)
npm run test:public

# Provider tools (EMR, prescriptions, appointments)
npm run test:provider

# Patient tools (portal, data management)
npm run test:patient

# Business tools (partner, affiliate, network)
npm run test:business

# Healthcare-specific tests (HIPAA, clinical workflows)
npm run test:healthcare

# Error handling tests
npm run test:errors

Coverage and Reporting

# Generate coverage report only
npm run test:coverage

# Healthcare compliance validation
npm run test:compliance

# CI/CD pipeline tests (all reports)
npm run test:ci

Advanced Test Execution

# Run specific test suite with options
node run-tests.js suite provider --coverage --verbose

# Run all tests in parallel with detailed reporting
node run-tests.js all --parallel --format=detailed

# Generate compliance report
node run-tests.js compliance

Test Categories

1. Public Tools Tests (77 tools)

Coverage: All public authentication and registration endpoints

Key Test Areas:

• Login endpoints (9 different auth types)
• Registration workflows (8 user types)
• Password management (10 operations)
• Email verification and validation
• Public data access endpoints

Example Test:

test('should successfully login with valid credentials', async () => {
  const result = await toolGenerator.executeTool('public_create_login', {
    username: 'testuser',
    password: 'testpassword'
  });
  
  expect(result.success).toBe(true);
  expect(result.data.token).toBeDefined();
});

2. Provider Tools Tests (400+ tools)

Coverage: EMR, clinical data, prescriptions, appointments

Key Test Areas:

• Patient registration and management
• Medical records creation and updates
• Prescription management with drug interactions
• Appointment scheduling and cancellation
• Vital signs recording and validation
• Clinical decision support

HIPAA Compliance:

• PHI data encryption and access controls
• Audit trail generation
• Minimum necessary standard
• Provider authentication requirements

3. Patient Tools Tests (200+ tools)

Coverage: Patient portal and self-service operations

Key Test Areas:

• Patient portal authentication
• Profile management and updates
• Medical record access (own data only)
• Appointment scheduling and cancellation
• Prescription viewing
• Consent management

Security Features:

• Patient data isolation
• Access scope validation
• Session management
• Two-factor authentication

4. Business Tools Tests (300+ tools)

Coverage: Partner, affiliate, and network operations

Key Test Areas:

• Business data analytics
• Referral management
• Commission tracking
• Network status monitoring
• Member directory access
• Performance metrics

5. Healthcare-Specific Tests

HIPAA Compliance Validation:

• PHI handling and encryption
• Access controls and authorization
• Audit trails and logging
• Data breach prevention
• Business Associate Agreements

Clinical Workflows:

• Clinical Decision Support System (CDSS)
• Drug interaction alerts
• Medical coding validation (ICD-10, CPT)
• Care coordination workflows
• Quality measures tracking

6. Error Handling Tests

Authentication Errors:

• Invalid credentials
• Account lockout scenarios
• Token expiration
• Session conflicts
• Permission violations

API and Network Errors:

• Network connectivity issues
• HTTP status code handling
• Timeout scenarios
• Retry mechanisms
• Circuit breaker patterns

Mock System

HTTP Mocking

// Mock successful API response
mockFactory.httpMocks.mockRequest('POST', '/api/endpoint', {
  status: 200,
  data: { success: true, result: 'data' }
});

// Mock error response
mockFactory.httpMocks.mockRequest('POST', '/api/endpoint', null, true, {
  response: { status: 401, data: { error: 'Unauthorized' } }
});

Authentication Mocking

// Setup mock credentials
mockFactory.authMocks.setMockCredentials('provider', {
  username: 'test_provider',
  password: 'test_password'
});

// Create HIPAA-compliant mock data
const mockPatient = mockFactory.healthcareMocks.createHIPAACompliantData(
  'patient', 'provider'
);

Coverage Requirements

Minimum Coverage Thresholds

• Lines: 80%
• Functions: 80%
• Branches: 80%
• Statements: 80%

Per-File Thresholds

• Lines: 70%
• Functions: 70%
• Branches: 70%
• Statements: 70%

Healthcare Compliance Testing

HIPAA Compliance Checklist

• ✅ PHI data encryption (AES-256)
• ✅ Access controls and RBAC
• ✅ Comprehensive audit trails
• ✅ Minimum necessary standard
• ✅ Data breach prevention
• ✅ Patient consent verification
• ✅ Business Associate Agreement validation

Clinical Workflow Validation

• ✅ Drug interaction checking
• ✅ Allergy contraindication alerts
• ✅ Dosage adjustment recommendations
• ✅ Medical coding validation
• ✅ Care team coordination
• ✅ Quality measures tracking

Continuous Integration

CI/CD Pipeline Integration

# Example GitHub Actions workflow
- name: Run Healthcare MCP Tests
  run: npm run test:ci

- name: Upload Coverage Reports
  uses: codecov/codecov-action@v3
  with:
    file: ./coverage/lcov.info

- name: Generate Compliance Report
  run: npm run test:compliance

Test Reports

The test suite generates multiple report formats:

1. Detailed Report: Complete test results with metadata
2. Summary Report: High-level overview and statistics
3. Coverage Report: Code coverage analysis
4. Compliance Report: Healthcare compliance validation

Best Practices

Writing Tests

1. Use descriptive test names that explain the scenario
2. Follow AAA pattern: Arrange, Act, Assert
3. Mock external dependencies using the provided mock system
4. Test both success and failure scenarios
5. Include HIPAA compliance validation for healthcare data
6. Verify audit trails for sensitive operations

Healthcare-Specific Testing

1. Always test PHI handling with proper encryption
2. Validate access controls for different user roles
3. Test audit trail generation for compliance
4. Include clinical decision support validation
5. Test emergency access scenarios (break-glass)
6. Validate medical coding accuracy

Error Handling

1. Test all error scenarios including edge cases
2. Validate error messages are user-friendly
3. Test retry mechanisms and circuit breakers
4. Include security incident handling
5. Test graceful degradation scenarios

Troubleshooting

Common Issues

1. Mock not working: Ensure mock is set up before test execution
2. Authentication failures: Verify mock credentials are configured
3. Coverage gaps: Check for untested code paths
4. Flaky tests: Review async operations and timing

Debug Mode

# Run tests with verbose output
npm run test:jest -- --verbose

# Run specific test file
npm run test:jest -- tests/public/login.test.js

# Debug with Node.js inspector
node --inspect-brk run-tests.js all

Contributing

When adding new tests:

1. Follow the existing test structure and naming conventions
2. Include both positive and negative test cases
3. Add appropriate mocks for external dependencies
4. Ensure HIPAA compliance for healthcare-related tests
5. Update this documentation for new test categories
6. Maintain minimum coverage thresholds

Support

For testing support and questions:

• Review existing test examples in the test suites
• Check the mock factory for available utilities
• Refer to Jest documentation for advanced features
• Contact the development team for healthcare compliance questions