# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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**:
```javascript
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

```javascript
// 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

```javascript
// 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

```yaml
# 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

```bash
# 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