AgentCare Logo
📚 AgentCare Documentation

AgentCare Testing Guide

Comprehensive testing strategy for multi-tenant healthcare SaaS platform

AgentCare implements a robust testing framework specifically designed for healthcare SaaS platforms, ensuring HIPAA compliance, data isolation, and system reliability across multiple healthcare organizations.

🧪 Testing Framework Overview

AgentCare’s testing strategy covers all aspects of a multi-tenant healthcare platform with specialized focus on security, compliance, and healthcare workflows.

Test Coverage Summary

🏗️ Test Architecture

graph TB subgraph "🧪 Multi-Tenant Testing Framework" subgraph "🔧 Unit Tests" UT1[OrganizationService Tests] UT2[Security Tests] UT3[Healthcare Workflow Tests] UT4[Data Validation Tests] end subgraph "🔄 Integration Tests" IT1[API Endpoint Tests] IT2[Database Integration] IT3[Multi-Tenant Validation] IT4[Performance Tests] end subgraph "🛡️ Security Tests" ST1[HIPAA Compliance] ST2[Data Isolation] ST3[Cross-Tenant Prevention] ST4[Audit Trail Verification] end subgraph "🎭 End-to-End Tests" E2E1[Healthcare User Workflows] E2E2[Appointment Booking] E2E3[Patient Registration] E2E4[Provider Management] end end

📋 Test Categories

1. Unit Tests (tests/unit/)

Unit tests focus on individual components and services with healthcare-specific validation.

OrganizationService Tests (tests/unit/services/OrganizationService.test.ts)

Coverage: 481 lines of healthcare-focused testing

describe('OrganizationService', () => {
  // Organization lifecycle testing
  describe('createOrganization', () => {
    it('should create hospital with HIPAA compliance settings', async () => {
      const hospitalData = {
        name: 'General Hospital',
        type: 'hospital',
        address: { /* ... */ },
        contactInfo: { /* ... */ }
      };
      
      const result = await organizationService.createOrganization(hospitalData);
      
      expect(result.type).toBe('hospital');
      expect(result.slug).toBe('general-hospital');
      expect(result.onboardingStatus).toBe('pending');
    });
    
    it('should enforce unique organization slugs', async () => {
      // Test duplicate slug prevention
      await expect(organizationService.createOrganization(duplicateData))
        .rejects.toThrow("Organization slug 'test-hospital' already exists");
    });
  });
  
  // Healthcare provider registration
  describe('registerProvider', () => {
    it('should register physician with license validation', async () => {
      const providerData = {
        email: 'doctor@hospital.com',
        name: 'Dr. Smith',
        role: 'attending_physician',
        licenseNumber: 'MD-12345',
        specialties: ['Cardiology']
      };
      
      const result = await organizationService.registerProvider(orgId, providerData);
      
      expect(result.user.email).toBe(providerData.email);
      expect(result.organizationUser.licenseNumber).toBe('MD-12345');
    });
  });
  
  // Patient registration with MRN generation
  describe('registerPatient', () => {
    it('should generate medical record number automatically', async () => {
      const patientData = {
        email: 'patient@email.com',
        name: 'John Doe',
        dateOfBirth: '1990-01-01'
      };
      
      const result = await organizationService.registerPatient(orgId, patientData);
      
      expect(result.medical_record_number).toMatch(/HOSPITAL-\d{6}/);
    });
  });
});

Security Tests (tests/unit/security/dataIsolation.test.ts)

Coverage: 582 lines of HIPAA compliance testing

describe('Data Isolation Security Tests', () => {
  // Cross-tenant data access prevention
  describe('Cross-Tenant Data Access Prevention', () => {
    it('should prevent accessing other organization patients', async () => {
      // Set context to Hospital A
      await setTenantContext(hospitalA);
      
      const hospitalAPatients = await query(`
        SELECT email, medical_record_number 
        FROM users 
        WHERE user_type = 'patient' AND organization_id = get_current_tenant()
      `);
      
      expect(hospitalAPatients.rows).toHaveLength(1);
      expect(hospitalAPatients.rows[0].email).toBe('patient1@hospital-a.com');
      
      // Switch to Hospital B
      await setTenantContext(hospitalB);
      
      const hospitalBPatients = await query(`
        SELECT email, medical_record_number 
        FROM users 
        WHERE user_type = 'patient' AND organization_id = get_current_tenant()
      `);
      
      expect(hospitalBPatients.rows).toHaveLength(1);
      expect(hospitalBPatients.rows[0].email).toBe('patient1@hospital-b.com');
    });
  });
  
  // HIPAA compliance validation
  describe('HIPAA Compliance Validation', () => {
    it('should enforce minimum necessary access principle', async () => {
      await setTenantContext(hospitalA);
      
      const records = await query(`
        SELECT record_type, is_sensitive 
        FROM medical_records 
        WHERE organization_id = get_current_tenant()
      `);
      
      expect(records.rows.filter(r => r.is_sensitive)).toHaveLength(2);
    });
  });
});

2. Integration Tests (tests/integration/)

Integration tests validate API endpoints and database interactions with multi-tenant context.

Organization Routes Tests (tests/integration/routes/organizationRoutes.test.ts)

Coverage: 709 lines of API testing

describe('Organization API Routes', () => {
  // Organization management endpoints
  describe('POST /api/v1/organizations', () => {
    it('should create new healthcare organization', async () => {
      const response = await request(app)
        .post('/api/v1/organizations')
        .send({
          name: 'Test Hospital',
          type: 'hospital',
          address: { /* ... */ },
          contactInfo: { /* ... */ }
        });
      
      expect(response.status).toBe(201);
      expect(response.body.success).toBe(true);
      expect(response.body.data.organization.type).toBe('hospital');
    });
  });
  
  // Provider registration endpoint
  describe('POST /api/v1/organizations/:id/providers', () => {
    it('should register healthcare provider with validation', async () => {
      const response = await request(app)
        .post(`/api/v1/organizations/${organizationId}/providers`)
        .set('Authorization', `Bearer ${authToken}`)
        .send({
          email: 'doctor@test.com',
          name: 'Dr. Test',
          role: 'attending_physician',
          licenseNumber: 'MD-TEST-123'
        });
      
      expect(response.status).toBe(201);
      expect(response.body.data.organizationUser.licenseNumber).toBe('MD-TEST-123');
    });
  });
  
  // Bulk operations testing
  describe('POST /api/v1/organizations/:id/bulk/providers', () => {
    it('should handle bulk provider registration with partial failures', async () => {
      const providers = [
        { email: 'valid@test.com', name: 'Valid Provider', role: 'nurse' },
        { email: 'invalid-email', name: 'Invalid Provider', role: 'doctor' }
      ];
      
      const response = await request(app)
        .post(`/api/v1/organizations/${organizationId}/bulk/providers`)
        .set('Authorization', `Bearer ${authToken}`)
        .send({ providers });
      
      expect(response.status).toBe(200);
      expect(response.body.data.summary.successful).toBe(1);
      expect(response.body.data.summary.failed).toBe(1);
    });
  });
});

Multi-Tenant Database Tests (tests/integration/database/multiTenant.test.ts)

Coverage: 549 lines of database integration testing

describe('Multi-Tenant Database Integration', () => {
  // Organization isolation testing
  describe('Organization Data Isolation', () => {
    beforeEach(async () => {
      // Create test organizations
      await createTestOrganizations([hospitalA, hospitalB, clinicC]);
    });
    
    it('should isolate patient data between organizations', async () => {
      // Create patients in different organizations
      await createTestPatients();
      
      // Test Hospital A isolation
      await setTenantContext(hospitalA);
      const hospitalAPatients = await getOrganizationPatients();
      expect(hospitalAPatients).toHaveLength(1);
      
      // Test Hospital B isolation
      await setTenantContext(hospitalB);
      const hospitalBPatients = await getOrganizationPatients();
      expect(hospitalBPatients).toHaveLength(1);
      
      // Verify no cross-contamination
      expect(hospitalAPatients[0].id).not.toBe(hospitalBPatients[0].id);
    });
  });
  
  // Performance testing with large datasets
  describe('Performance Testing', () => {
    it('should handle large patient datasets efficiently', async () => {
      // Create 1000 test patients
      await createLargePatientDataset(1000);
      
      const startTime = Date.now();
      const patients = await getOrganizationPatients();
      const endTime = Date.now();
      
      expect(patients).toHaveLength(1000);
      expect(endTime - startTime).toBeLessThan(100); // < 100ms
    });
  });
});

3. Security Tests (tests/unit/security/)

Specialized security tests for HIPAA compliance and healthcare data protection.

describe('Healthcare Security Compliance', () => {
  // SQL injection prevention
  describe('SQL Injection Prevention', () => {
    it('should prevent SQL injection in tenant context', async () => {
      const maliciousInput = "'; DROP TABLE users; --";
      
      await expect(setTenantContext(maliciousInput))
        .rejects.toThrow(); // Should fail due to invalid UUID format
      
      // Verify users table still exists
      const result = await query('SELECT COUNT(*) FROM users');
      expect(parseInt(result.rows[0].count)).toBeGreaterThanOrEqual(0);
    });
  });
  
  // Medical record confidentiality
  describe('Medical Record Security', () => {
    it('should never leak sensitive medical data across organizations', async () => {
      await setTenantContext(hospitalA);
      
      const sensitiveRecords = await query(`
        SELECT content FROM medical_records 
        WHERE organization_id = get_current_tenant() AND is_sensitive = true
      `);
      
      expect(sensitiveRecords.rows[0].content).toContain('Mental health treatment');
      expect(sensitiveRecords.rows[0].content).not.toContain('Substance abuse');
    });
  });
});

🚀 Running Tests

Setup Test Environment

# Install dependencies
npm install

# Setup test database
createdb agentcare_test
psql -d agentcare_test -f database/enhanced-multi-tenant-schema.sql

# Configure test environment
cp env.example .env.test
# Edit .env.test with test database settings

Run Test Suites

# Run all tests
npm run test

# Run specific test categories
npm run test:unit          # Unit tests only
npm run test:integration   # Integration tests only
npm run test:security     # Security tests only
npm run test:e2e          # End-to-end tests only

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run specific test files
npm test -- --testPathPattern="OrganizationService"
npm test -- --testNamePattern="HIPAA"

Healthcare-Specific Test Execution

# Run healthcare compliance tests
npm run test:hipaa

# Run multi-tenant isolation tests
npm run test:isolation

# Run performance tests
npm run test:performance

# Run medical workflow tests
npm run test:workflows

📊 Test Coverage & Metrics

Coverage Reports

# Generate detailed coverage report
npm run test:coverage

# View coverage in browser
open coverage/lcov-report/index.html

# Coverage thresholds (jest.config.js)
coverageThreshold: {
  global: {
    branches: 75,
    functions: 80,
    lines: 80,
    statements: 80
  },
  './backend/src/services/': {
    branches: 80,
    functions: 85,
    lines: 85,
    statements: 85
  }
}

Healthcare-Specific Metrics

// Custom coverage metrics for healthcare
const healthcareMetrics = {
  hipaaCompliance: '100%',      // All HIPAA requirements tested
  dataIsolation: '100%',        // Cross-tenant prevention
  medicalWorkflows: '95%',      // Healthcare-specific flows
  securityValidation: '100%',   // Security test coverage
  performanceBenchmarks: '90%'  // Performance targets met
};

🏥 Healthcare Test Scenarios

Patient Registration Workflow

describe('Patient Registration E2E', () => {
  it('should complete full patient onboarding', async () => {
    // 1. Register patient
    const patient = await registerPatient({
      email: 'patient@test.com',
      name: 'Test Patient',
      dateOfBirth: '1990-01-01'
    });
    
    // 2. Verify medical record number generation
    expect(patient.medicalRecordNumber).toMatch(/TEST-HOSPITAL-\d{6}/);
    
    // 3. Add emergency contact
    await addEmergencyContact(patient.id, {
      name: 'Emergency Contact',
      phone: '+1-555-0123'
    });
    
    // 4. Add insurance information
    await addInsurance(patient.id, {
      provider: 'Test Insurance',
      policyNumber: 'TEST-123456'
    });
    
    // 5. Verify patient can access portal
    const loginResponse = await loginPatient(patient.email);
    expect(loginResponse.success).toBe(true);
  });
});

Appointment Booking Workflow

describe('Appointment Booking E2E', () => {
  it('should complete appointment booking with AI assistance', async () => {
    // 1. Check provider availability
    const availability = await checkAvailability('provider-id', '2024-01-20');
    expect(availability.availableSlots.length).toBeGreaterThan(0);
    
    // 2. Use AI agent to book appointment
    const chatResponse = await chatWithAgent({
      message: 'I need to book an appointment with Dr. Smith',
      patientId: 'patient-id'
    });
    
    expect(chatResponse.intent).toBe('appointment_booking');
    expect(chatResponse.confidence).toBeGreaterThan(0.8);
    
    // 3. Confirm booking
    const appointment = await bookAppointment({
      patientId: 'patient-id',
      providerId: 'provider-id',
      scheduledAt: availability.availableSlots[0].startTime
    });
    
    expect(appointment.status).toBe('scheduled');
    expect(appointment.confirmationNumber).toBeDefined();
  });
});

🔒 Security Testing Strategy

HIPAA Compliance Testing

const hipaaTestSuite = {
  // Administrative safeguards
  adminSafeguards: [
    'access_management_testing',
    'workforce_training_validation',
    'security_officer_assignment'
  ],
  
  // Physical safeguards
  physicalSafeguards: [
    'facility_access_controls',
    'workstation_access_testing',
    'device_disposal_verification'
  ],
  
  // Technical safeguards
  technicalSafeguards: [
    'data_encryption_testing',
    'audit_trail_validation',
    'transmission_security_testing'
  ]
};

Data Isolation Testing

describe('Multi-Tenant Data Isolation', () => {
  const testScenarios = [
    {
      name: 'Patient Data Isolation',
      test: () => verifyPatientDataIsolation(),
      compliance: 'HIPAA_164.308'
    },
    {
      name: 'Medical Record Segregation',
      test: () => verifyMedicalRecordSegregation(),
      compliance: 'HIPAA_164.312'
    },
    {
      name: 'Appointment Data Protection',
      test: () => verifyAppointmentDataProtection(),
      compliance: 'HIPAA_164.502'
    }
  ];
  
  testScenarios.forEach(scenario => {
    it(`should enforce ${scenario.name}`, async () => {
      const result = await scenario.test();
      expect(result.compliant).toBe(true);
      expect(result.violations).toHaveLength(0);
    });
  });
});

🎯 Test Data Management

Healthcare Test Data

// Anonymized test data for healthcare scenarios
const testPatients = [
  {
    name: 'Test Patient Alpha',
    dateOfBirth: '1985-01-01',
    medicalConditions: ['Diabetes', 'Hypertension'],
    allergies: ['Penicillin']
  },
  {
    name: 'Test Patient Beta',
    dateOfBirth: '1990-06-15',
    medicalConditions: ['Asthma'],
    allergies: ['Shellfish']
  }
];

const testProviders = [
  {
    name: 'Dr. Test Cardiologist',
    specialty: 'Cardiology',
    licenseNumber: 'TEST-CARD-001'
  },
  {
    name: 'Dr. Test Internist',
    specialty: 'Internal Medicine',
    licenseNumber: 'TEST-INTERN-001'
  }
];

Test Data Cleanup

afterEach(async () => {
  // Clean up test data while maintaining referential integrity
  await cleanupTestData([
    'appointments',
    'medical_records',
    'patient_caregivers',
    'organization_users',
    'users',
    'organizations'
  ]);
});

📈 Performance Testing

Load Testing Scenarios

describe('Performance Testing', () => {
  it('should handle concurrent organization operations', async () => {
    const concurrentOperations = Array.from({ length: 10 }, (_, i) => 
      createOrganization(`test-org-${i}`)
    );
    
    const startTime = Date.now();
    const results = await Promise.all(concurrentOperations);
    const endTime = Date.now();
    
    expect(results).toHaveLength(10);
    expect(endTime - startTime).toBeLessThan(5000); // < 5 seconds
  });
  
  it('should maintain response times under load', async () => {
    // Simulate 100 concurrent patient registrations
    const operations = Array.from({ length: 100 }, () => 
      registerRandomPatient()
    );
    
    const results = await Promise.allSettled(operations);
    const successful = results.filter(r => r.status === 'fulfilled');
    
    expect(successful.length).toBeGreaterThan(95); // 95% success rate
  });
});

🔧 Test Infrastructure

Docker Test Environment

# docker-compose.test.yml
version: '3.8'
services:
  postgres-test:
    image: postgres:14
    environment:
      POSTGRES_DB: agentcare_test
      POSTGRES_USER: test_user
      POSTGRES_PASSWORD: test_password
    ports:
      - "5433:5432"
    
  redis-test:
    image: redis:7-alpine
    ports:
      - "6380:6379"

CI/CD Integration

# .github/workflows/test.yml
name: Healthcare SaaS Testing

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    services:
      postgres:
        image: postgres:14
        env:
          POSTGRES_PASSWORD: postgres
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    
    steps:
      - uses: actions/checkout@v2
      
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '22'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Setup test database
        run: |
          psql -h localhost -U postgres -c "CREATE DATABASE agentcare_test;"
          psql -h localhost -U postgres -d agentcare_test -f database/enhanced-multi-tenant-schema.sql
        env:
          PGPASSWORD: postgres
          
      - name: Run tests
        run: npm run test:ci
        env:
          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/agentcare_test
          
      - name: Upload coverage
        uses: codecov/codecov-action@v1

📚 Testing Best Practices

Healthcare Testing Guidelines

  1. Patient Data Protection
    • Never use real patient data in tests
    • Anonymize all test medical information
    • Implement data retention policies for test data
  2. Multi-Tenant Testing
    • Always set tenant context in tests
    • Verify data isolation between tests
    • Clean up after each test suite
  3. Compliance Testing
    • Test all HIPAA requirements systematically
    • Validate audit trail completeness
    • Verify access control enforcement
  4. Performance Testing
    • Test with realistic healthcare data volumes
    • Validate response times for critical workflows
    • Monitor resource usage during tests

🎯 Next Steps

  1. Security Guide - Implement security measures
  2. Deployment Guide - Deploy with testing pipeline
  3. API Reference - Test API endpoints

Comprehensive Testing for Healthcare Excellence

Ensuring reliability, security, and compliance in every healthcare interaction.