2025-07-11 19:27:14 +00:00
# Testing Documentation
This document describes all available test targets in the Task build system and their specific purposes.
## Primary Test Suites
### `task test:functional`
**Default comprehensive test suite with intelligent incremental testing**
- **Purpose**: Main test runner that adapts behavior based on context
- **Unique Features**:
- **Incremental Mode** (default): Only tests packages affected by changes since `origin/main`
- **Coverage Merging**: Maintains cumulative coverage across incremental runs
- **Full Fallback**: Automatically runs full suite if no baseline exists or git branch issues
- **Coverage**: 80% total threshold, 60% function threshold
- **Parallelism**: Minimal settings to avoid resource contention (GOMAXPROCS=2, -p 1, -parallel 2)
- **Use Case**: Development workflow, pre-commit checks
### `task test:functional:full`
**Complete test suite with coverage reset**
- **Purpose**: Run all tests from scratch, ignoring previous coverage
- **Unique Features**:
- Deletes existing coverage file before running
- Forces full test execution regardless of git changes
- **Use Case**: Clean slate testing, debugging coverage issues, release validation
### `task fullsuite:ci`
**CI/CD optimized complete workflow**
- **Purpose**: Full build, lint, and test pipeline for continuous integration
- **Unique Features**:
- Forces `INCREMENTAL=false` to ensure all tests run
- Includes generation, building, linting, and testing
- No shortcuts or incremental optimizations
- **Use Case**: CI/CD pipelines, release builds, comprehensive validation
## Specialized Test Types
### `task test:race`
**Race condition detection**
- **Purpose**: Detect data races and concurrency issues
- **Unique Features**: Uses Go's `-race` flag to detect race conditions
- **Use Case**: Debugging concurrency issues, ensuring thread safety
### `task test:unit:short`
**Fast unit tests only**
- **Purpose**: Quick feedback loop for development
- **Unique Features**:
- Uses `-short` flag to skip long-running tests
- Focuses on `./internal/...` and `./api/...` packages only
- Generates mocks automatically before running
- **Use Case**: Rapid development feedback, pre-commit quick checks
### `task test:permitio`
**Permit.io integration tests**
- **Purpose**: Run tests that require local Permit.io PDP service
- **Unique Features**:
- Uses `-tags=permitio` to include only tagged integration tests
- Requires `PERMIT_IO_API_KEY` environment variable
- Requires local PDP running on port 7766
- Provides clear error messages about requirements
- **Use Case**: Testing authorization integration, local development with full Permit.io stack
### `task test:bench`
**Benchmark testing**
- **Purpose**: Performance testing and optimization
- **Unique Features**:
- Runs only benchmark functions (`-run ^Benchmark` )
- Uses `benchstat` for statistical analysis of results
- Outputs performance metrics to `out/bench.out`
- **Use Case**: Performance optimization, regression testing for speed
## Performance Analysis
### `task test:perf`
**Performance profiling and slowest test identification**
- **Purpose**: Identify performance bottlenecks in the test suite
- **Unique Features**:
- Reports top 5 slowest packages
- Reports top 5 slowest individual tests
- Deep-dives into slowest package for detailed analysis
- Uses JSON output for precise timing analysis
- **Use Case**: Test suite optimization, CI performance tuning
### `task test:mem`
**Memory usage analysis**
- **Purpose**: Monitor memory consumption across test packages
- **Unique Features**:
- Runs tests with memory profiling for each package
- Ranks packages by memory usage (top 5)
- Provides total memory consumption summary
- Individual timeout protection (120s per package)
- **Use Case**: Memory optimization, resource planning, leak detection
### `task test:timeline`
**Visual test execution timeline**
- **Purpose**: Visualize test execution flow and timing
- **Unique Features**:
- Uses JSON output piped to visual timeline generator
- Shows parallel execution patterns
- Helps identify bottlenecks and optimization opportunities
- **Use Case**: Understanding test execution patterns, optimization planning
## Test Infrastructure
### `task test:mocks:generate`
**Mock generation for testing**
- **Purpose**: Generate test mocks from interfaces
- **Unique Features**:
- Uses mockery tool to auto-generate mocks
- Clears existing mocks before regeneration
- Runs only once per task execution cycle
- **Use Case**: Maintaining test isolation, dependency mocking
### `task test:wait`
**Test environment preparation**
- **Purpose**: Ensure clean test environment before running tests
- **Unique Features**:
- Waits for testcontainers cleanup (Ryuk containers)
- Prunes Docker containers and volumes
- Prevents resource conflicts between test runs
- **Use Case**: Test environment hygiene, CI stability
### `task test:prune`
**Docker resource cleanup**
- **Purpose**: Clean up Docker resources left by tests
- **Unique Features**:
- Force removes unused containers and volumes
- Prevents disk space issues from accumulated test artifacts
- **Use Case**: Resource management, CI environment maintenance
## Visualization and Analysis
### `task test:graph`
**Resource usage visualization during testing**
- **Purpose**: Monitor system resources during test execution
- **Unique Features**:
- Uses `psrecord` to track CPU/memory during `test:functional`
- Generates visual plots of resource usage
- Includes child processes in monitoring
- **Use Case**: Performance analysis, resource optimization
### `task fullsuite:graph`
**Complete build and test resource monitoring**
- **Purpose**: Monitor resources during entire build and test cycle
- **Unique Features**: Same as `test:graph` but for the complete `fullsuite` workflow
- **Use Case**: End-to-end performance analysis, CI optimization
## Test Execution Patterns
### Incremental Testing Logic
The `test:functional` target implements sophisticated incremental testing:
1. **Full Mode Triggers ** :
- `INCREMENTAL=false` explicitly set
- No existing coverage file found
- Cannot find `origin/main` branch reference
2. **Incremental Mode ** :
- Compares against `origin/main` branch
- Only tests packages with changed Go files
- Merges coverage with existing baseline
- Skips testing if no Go files changed
3. **Coverage Merging ** :
- Preserves existing coverage for unchanged packages
- Adds new coverage for changed packages
- Maintains comprehensive coverage metrics
### Parallelism Settings
All test targets use conservative parallelism to avoid resource contention:
- **GOMAXPROCS**: 2 (fixed minimal value)
- **Package Parallelism**: 1 (single package at a time)
- **Test Parallelism**: 2 (minimal test parallelism)
This ensures stable execution in resource-constrained environments like CI.
## Usage Recommendations
- **Development**: Use `task test:functional` for normal development workflow
- **Pre-commit**: Use `task test:unit:short` for quick feedback
- **CI/CD**: Use `task fullsuite:ci` for comprehensive validation
- **Performance**: Use `task test:perf` and `task test:mem` for optimization
- **Debugging**: Use `task test:race` for concurrency issues
- **Clean Slate**: Use `task test:functional:full` when coverage gets corrupted
- **Permit.io Integration**: Use `task test:permitio` for testing authorization features with local PDP
## Integration with Build Tags
Some tests may use build tags to control execution:
- Tests requiring external services (like Permit.io PDP) may be tagged
- Use `-tags=tagname` with `go test` commands to include tagged tests
2026-01-22 18:17:27 +00:00
- CI typically excludes integration tests that require external dependencies
## Test User Header Injection (DISABLE_AUTH Mode)
When running the service with `DISABLE_AUTH=true` , a special middleware (`TestUserMiddleware` ) activates that allows injecting user identity via HTTP headers. This enables testing of user-authenticated endpoints without requiring real JWT authentication.
### How It Works
The `TestUserMiddleware` (located in `internal/cognitoauth/test_middleware.go` ):
1. Only activates when `DISABLE_AUTH=true` environment variable is set
2. Checks for the `X-Test-User-Subject` header on each request
3. If present, injects user identity into the request context
4. Handlers can then retrieve user info via `GetUserSubject()` and `GetUserInfo()`
### Headers
| Header | Required | Description |
|--------|----------|-------------|
| `X-Test-User-Subject` | Yes | The user's subject ID (Cognito sub claim) |
| `X-Test-User-Email` | No | The user's email (defaults to `<subject>@test.local` ) |
### Example Usage
``` bash
# Start the service with DISABLE_AUTH=true (default for local compose)
task compose:refresh
# Call user-authenticated endpoint with test user headers
curl -X GET http://localhost:8080/eula/status \
-H "X-Test-User-Subject: test-user-123" \
-H "X-Test-User-Email: testuser@example.com"
# User agrees to EULA
curl -X POST http://localhost:8080/eula/agree \
-H "X-Test-User-Subject: test-user-123" \
-H "X-Test-User-Email: testuser@example.com"
```
### Integration Test Scripts
Three integration test scripts are available for EULA functionality:
1. **Complete EULA Tests ** (`test/text_eula_all_integration_test.sh` ) * * (Recommended)**
- Comprehensive test suite combining admin and user EULA testing
- Tests full EULA lifecycle: version management, user agreements, version upgrades, compliance
- 24 test steps across 9 phases
- Uses both admin endpoints (system user) and user endpoints (header injection)
2. **Admin EULA Tests ** (`test/text_eula_admin_integration_test.sh` )
- Tests admin-only endpoints: create, activate, update, list EULA versions
- Uses system user (no headers needed with DISABLE_AUTH=true)
3. **User EULA Tests ** (`test/text_eula_user_integration_test.sh` )
- Tests user-authenticated endpoints: `/eula/status` , `/eula/agree`
- Uses `X-Test-User-Subject` header to inject test user identity
- Tests multiple users and idempotency
``` bash
# Run complete EULA integration tests (recommended)
./test/text_eula_all_integration_test.sh http://localhost:8080
# Run individual test suites
./test/text_eula_admin_integration_test.sh http://localhost:8080
./test/text_eula_user_integration_test.sh http://localhost:8080
```
### Security Note
The `TestUserMiddleware` is **only active when `DISABLE_AUTH=true` ** . In production environments where `DISABLE_AUTH` is not set or is `false` , this middleware does nothing and the headers are ignored. The real authentication middleware handles all requests normally.
