Test Debugging Guide

Overview

Tests are configured with minimal logging by default for clean output. When debugging is needed, there's a simple, unified approach using the standard LOG_LEVEL environment variable.

Quick Debugging Commands

1. Enable Verbose Test Logging

# Enable detailed logging and verbose reporter (recommended)
pnpm test:debug
 
# Run specific test with debug logging
pnpm test:debug tests/path/to/specific.test.ts
 
# Or enable debug logging with regular test command
LOG_LEVEL=debug pnpm test tests/path/to/specific.test.ts

2. Run Tests with Maximum Verbosity

# Full verbose output with reporter details
cd apps/web && LOG_LEVEL=debug vitest run --reporter=verbose tests/path/to/test.ts

3. Watch Mode for Development

# Watch tests with debugging enabled
LOG_LEVEL=debug pnpm test:watch

Unified Logging with LOG_LEVEL

The system uses a single LOG_LEVEL environment variable for all logging across development, production, and tests:

Available Log Levels

• silent - No logs
• error - Only errors
• warn - Warnings and errors
• info - Info, warnings, and errors
• debug - All logs including debug info
• trace - Maximum verbosity

What Gets Logged with LOG_LEVEL=debug

1. Payload Startup Logs: Email adapter warnings, migration info, sharp warnings, etc.
2. Application Logs: All pino logger output from the application (database operations, seeding, etc.)
3. Test Setup Details: Test environment creation, cleanup operations
4. Database Operations: Table truncation, seeding operations

Default Behavior (No Debug Flags)

• All logs: Suppressed (level: "silent")
• Test output: Only test results and failures
• Node.js warnings: Suppressed via NODE_OPTIONS="--no-warnings"

Common Debugging Scenarios

Database Issues

# See database operations and seeding
LOG_LEVEL=debug pnpm test tests/integration/services/seed-config.test.ts

Import/Processing Issues

# Debug import job processing
LOG_LEVEL=debug pnpm test tests/integration/import/

Payload Configuration Issues

# See Payload startup logs (email adapter, sharp warnings, migration info)
LOG_LEVEL=debug pnpm test tests/integration/

Application Logic Issues

# See all application logger output
LOG_LEVEL=debug pnpm test tests/integration/

Cross-Environment Usage

The same LOG_LEVEL variable works consistently across all environments:

# Development server with debug logs
LOG_LEVEL=debug pnpm dev
 
# Tests with debug logs
LOG_LEVEL=debug pnpm test
 
# Production with error-only logs
LOG_LEVEL=error pnpm start

Files with Logging Capabilities

• lib/logger.ts - Central logger configuration respecting LOG_LEVEL
• tests/setup/setup.ts - Test setup respecting LOG_LEVEL
• tests/setup/test-helpers.ts - Test helpers with unified logging
• tests/setup/TestEnvironmentBuilder.ts - Test environment builder

Package.json Scripts

• test:debug - Sets LOG_LEVEL=debug and uses --reporter=verbose
• dev:debug - Sets LOG_LEVEL=debug for development server
• test:watch - Watch mode (set LOG_LEVEL=debug for verbose output)
• test - Minimal output with --reporter=basic --silent

Benefits of Unified Logging

✅ Consistent: Same variable works everywhere
✅ Simple: One concept to remember (LOG_LEVEL)
✅ Standard: Follows common logging conventions
✅ Flexible: Works across all environments and tools
✅ Predictable: Same behavior whether in dev, test, or production

Notes

• Clean by default: Tests produce minimal output unless LOG_LEVEL is set
• Error logs always visible: Critical errors show regardless of log level
• Test failures show details: Full error information always available
• Migration errors always displayed: Critical for debugging database issues