rxminder/tests/README.md

# 🧪 Testing Documentation

## Test Structure

```
tests/
├── setup.ts                    # Jest configuration and global test setup
├── integration/                # Integration tests for production validation
│   └── production.test.js      # CouchDB, deployment, and service testing
├── manual/                     # Manual testing scripts and debugging tools
│   ├── admin-login-debug.js    # Browser console debugging for admin login
│   ├── auth-db-debug.js        # Authentication database debugging
│   └── debug-email-validation.js # Email validation debugging
└── e2e/                        # End-to-end tests with Playwright
    ├── README.md               # E2E testing documentation
    ├── fixtures.ts             # Custom test fixtures
    ├── helpers.ts              # Test utilities and data
    ├── auth.spec.ts            # Authentication flow tests
    ├── medication.spec.ts      # Medication management tests
    ├── admin.spec.ts           # Admin interface tests
    ├── ui-navigation.spec.ts   # UI and navigation tests
    └── reminders.spec.ts       # Reminder system tests

services/
└── auth/
    └── __tests__/              # Unit tests for authentication services
        ├── auth.integration.test.ts
        ├── emailVerification.test.ts
        └── integration/
            └── token.service.integration.test.ts
```

## Running Tests

### Unit Tests (Jest)

```bash
# Run all unit tests
bun run test

# Run tests in watch mode
bun run test:watch

# Run with coverage
bun run test:coverage

# Run specific test file
bun run test auth.integration.test.ts
```

### Integration Tests

```bash
# Run production integration tests
bun run test:integration

# Run all tests (unit + integration + e2e)
bun run test:all

# Run E2E tests with Playwright
bun run test:e2e

# Run E2E tests in UI mode
bun run test:e2e:ui

# Debug E2E tests
bun run test:e2e:debug

# View E2E test reports
bun run test:e2e:report
```

#### TokenService CouchDB Integration

##### Using Docker Compose locally

You can spin up a local CouchDB for integration tests using the included docker-compose file:

```bash
docker compose -f meds/docker-compose.ci.yml up -d couchdb

export VITE_COUCHDB_URL=http://localhost:5984
export VITE_COUCHDB_USER=admin
export VITE_COUCHDB_PASSWORD=password

bun run test:integration
```

- The compose file is intended for local/CI testing only.
- Data is stored in a named volume (couchdb-test-data) and can be removed with:
  - docker compose -f meds/docker-compose.ci.yml down -v

##### Optional CI workflow

An optional GitHub Actions workflow exists to run these CouchDB-backed tests:

- Name: Integration Tests (CouchDB)
- Triggers:
  - Manually via “Run workflow” (workflow_dispatch), or
  - Automatically if repository variable RUN_COUCHDB_INTEGRATION is set to "true"
- It provisions a CouchDB service and runs:
  - bun run test:integration

To enable automatic runs, set the repository variable RUN_COUCHDB_INTEGRATION to "true" in your repo settings. You can also override credentials via:

- VITE_COUCHDB_URL (defaults to http://couchdb:5984 in CI)
- VITE_COUCHDB_USER (defaults to admin)
- VITE_COUCHDB_PASSWORD (defaults to password if not set as a secret)

Integration tests for the TokenService talk to a live CouchDB if available. They automatically skip when CouchDB is not reachable.

```bash
# Run TokenService integration tests (requires CouchDB at VITE_COUCHDB_URL)
# Defaults: VITE_COUCHDB_URL=http://localhost:5984, VITE_COUCHDB_USER=admin, VITE_COUCHDB_PASSWORD=password
VITE_COUCHDB_URL=http://localhost:5984 \
VITE_COUCHDB_USER=admin \
VITE_COUCHDB_PASSWORD=password \
bun run test meds/services/auth/__tests__/integration/token.service.integration.test.ts
```

- Provide your own CouchDB credentials via environment variables if different from the defaults above.
- These tests will provision an `auth_tokens` database automatically and clean up test data as part of the lifecycle.

#### OAuth Redirect Configuration

OAuth redirect URIs are derived from the unified configuration:

- Redirect URI = `${APP_BASE_URL}/auth/callback`
- Development default: `APP_BASE_URL=http://localhost:5173`
- Test default: `APP_BASE_URL=http://localhost:3000`

To exercise OAuth URL construction with your own IDs, set:

- `VITE_GOOGLE_CLIENT_ID`
- `VITE_GITHUB_CLIENT_ID`

Example:

```bash
APP_BASE_URL=http://localhost:5173 \
VITE_GOOGLE_CLIENT_ID=your-google-client-id \
VITE_GITHUB_CLIENT_ID=your-github-client-id \
bun run dev
```

### Manual Testing Scripts

#### Admin Login Debug

```bash
# Open browser to http://localhost:8080
# Open developer console
# Run:
bun tests/manual/admin-login-debug.js
```

#### Auth Database Debug

```bash
# Open browser to http://localhost:8080
# Open developer console
# Run:
bun tests/manual/auth-db-debug.js
```

## Test Categories

### ✅ Unit Tests (`services/auth/__tests__/`)

- **Purpose**: Test individual functions and services in isolation
- **Framework**: Jest + TypeScript
- **Coverage**: Authentication, email verification
- **Status**: ✅ Well-structured and maintained

### 🔧 Integration Tests (`tests/integration/`)

- **Purpose**: Test entire system interactions and deployment validation
- **Framework**: Bun native testing
- **Coverage**: CouchDB connectivity, database setup, production readiness
- **Status**: ✅ Useful for deployment validation

### 🛠️ Manual Tests (`tests/manual/`)

- **Purpose**: Browser-based debugging and manual verification
- **Framework**: Vanilla JavaScript for browser console
- **Coverage**: Admin authentication, database debugging
- **Status**: ⚠️ Useful for debugging but should be automated

### 🎯 E2E Tests (`tests/e2e/`)

- **Purpose**: Full user journey testing across browsers
- **Framework**: Playwright with TypeScript
- **Coverage**: Complete user workflows, cross-browser compatibility
- **Status**: ✅ Comprehensive test suite with 5 spec files

## Test Configuration

### Jest Configuration (`jest.config.json`)

- TypeScript transformed via babel-jest (@babel/preset-typescript); import.meta handled in Babel config
- jsdom environment for DOM testing
- Coverage reporting
- Module path mapping

### Test Setup (`tests/setup.ts`)

- localStorage mocking
- fetch mocking
- Console noise reduction
- Global test utilities

## Recommendations

### ✅ Keep These Tests

1. **Authentication unit tests** - Critical for security
2. **Production integration tests** - Essential for deployment validation
3. **Manual debugging scripts** - Useful for development

### 🔄 Future Improvements

1. **Remove temporary type declarations** once Playwright types are fully recognized
2. **Increase unit test coverage** for components and utilities
3. **Add visual regression tests** using Playwright screenshots
4. **Implement accessibility testing** in E2E suite
5. **Add performance tests** for large datasets
6. **Set up test data management** for E2E tests

### 🛡️ Testing Best Practices

- Run tests before every deployment
- Maintain >80% code coverage for critical paths
- Use integration tests to validate environment setup
- Keep manual tests for complex debugging scenarios

## CI/CD Integration

Add to your deployment pipeline:

```bash
# Validate tests before deployment
bun run test:all

# Run in production validation
bun run test:integration
```