Charon/tests/phase4-uat/README.md

Phase 4 UAT Test Suite

Comprehensive User Acceptance Testing for Charon reverse proxy system before production beta release.

Overview

Test Count: 70 tests across 8 feature areas Framework: Playwright Test (Firefox) Base URL: http://127.0.0.1:8080 (Docker container) Coverage: Admin onboarding, user management, proxy hosts, security configuration, domain/DNS, monitoring, backup/recovery, emergency operations

Test Files

01-admin-onboarding.spec.ts (8 tests)

• Purpose: Validate first-time admin setup and dashboard experience
• Tests:
  • Admin login with performance measurement (<5s)
  • Dashboard widget display and functionality
  • Settings page navigation and access
  • Emergency token generation (modal and inline display)
  • Encryption key setup and storage
  • Navigation menu item visibility and navigation
  • Logout and session cleanup
  • Re-login validation and session restoration

02-user-management.spec.ts (10 tests)

• Purpose: User CRUD operations and role-based access control
• Tests:
  • Create user (all fields, minimal fields)
  • Assign and modify user roles
  • Delete user with confirmation
  • Login as user with restricted permissions
  • Unauthorized API access from guest role
  • Guest role minimal permissions
  • Email address modification
  • Password reset workflow with login validation
  • Search users by email address
  • Pagination with large user count (>25 users)

03-proxy-host-management.spec.ts (12 tests)

• Purpose: Reverse proxy lifecycle and configuration
• Tests:
  • Create proxy with domain and target validation
  • Edit proxy configuration
  • Delete proxy with cleanup
  • SSL/TLS certificate setup
  • Traffic routing and verification
  • Access list configuration and enforcement
  • WAF integration with proxy
  • Rate limiting application to proxy
  • Domain regex pattern validation
  • Proxy statistics display
  • Disable/enable proxy toggle
  • Form validation error handling

04-security-configuration.spec.ts (10 tests)

• Purpose: Security module enablement and configuration
• Tests:
  • Enable Cerberus ACL module
  • Enable Coraza WAF module
  • Enable rate limiting
  • Enable CrowdSec integration
  • Configure ACL rules (IP whitelist)
  • Adjust WAF sensitivity levels
  • Set rate limiting thresholds (100 req/60s example)
  • CrowdSec API key field verification
  • Malicious payload blocking via API call
  • Security dashboard status display

05-domain-dns-management.spec.ts (8 tests)

• Purpose: Domain and DNS provider lifecycle
• Tests:
  • Add domain (test.example.com)
  • View DNS records (A, AAAA, CNAME)
  • Add DNS provider with credentials
  • Verify domain ownership (DNS TXT/CNAME)
  • Renew SSL certificate with confirmation
  • View domain statistics (cert expiry, uptime, DNS status)
  • Disable domain toggle
  • Export domains as JSON file

06-monitoring-audit.spec.ts (8 tests)

• Purpose: Logging, monitoring, and audit trail functionality
• Tests:
  • Real-time log stream display
  • Filter logs by severity level (error, info, etc.)
  • Search logs by keyword
  • Export logs to CSV file with download handling
  • Pagination with 100+ log entries
  • Audit trail showing user actions with timestamps
  • Security events logged and displayed
  • Log retention policy enforcement

07-backup-recovery.spec.ts (9 tests)

• Purpose: Backup and disaster recovery
• Tests:
  • Create manual backup through UI
  • Schedule automatic backups (daily)
  • Download backup file
  • Restore from backup with confirmation
  • Verify data integrity post-restore (users, proxies)
  • Delete backup with confirmation
  • Enable encryption for backups
  • Restore with password protection field
  • Retention policy (keep 7 backups max)

08-emergency-operations.spec.ts (5 tests)

• Purpose: Break-glass recovery and emergency procedures
• Tests:
  • Emergency token availability and access
  • Break-glass recovery procedures (navigation)
  • Disable WAF in emergency mode (no auth required)
  • Reset encryption key (availability verification)
  • Emergency token usage logging in audit trail

Execution

Run all UAT tests:

cd /projects/Charon
npx playwright test tests/phase4-uat/ --project=firefox

Run specific feature tests:

npx playwright test tests/phase4-uat/02-user-management.spec.ts --project=firefox

Run with debugging:

npx playwright test tests/phase4-uat/ --project=firefox --debug

Run with headed browser (visible):

npx playwright test tests/phase4-uat/ --project=firefox --headed

View test report:

npx playwright show-report

Prerequisites

1. Docker environment running:

   .github/skills/scripts/skill-runner.sh docker-rebuild-e2e
   

   This starts the Charon application on http://127.0.0.1:8080

2. Playwright dependencies installed:

   npm install
   npx playwright install firefox
   

3. Valid admin credentials for initial login (from environment or .env file)

Test Data Management

• Test users: Created with unique emails (test-FEATURE@test.local)
• Test proxies: Domains like feature-test.local
• Cleanup: afterEach hooks delete all created test data via UI operations
• No data persistence: Each test run is isolated, no test data leaks

Success Criteria

✅ All 8 test files compile without syntax errors ✅ All 70 tests execute and pass against staging environment ✅ Dashboard loads within 5 seconds ✅ User creation completes within 10 seconds ✅ Proxy creation completes within 10 seconds ✅ Emergency procedures accessible and documented ✅ Backup/restore workflow functional ✅ Security modules configurable and togglable ✅ Audit logging captures all user actions ✅ Data cleanup runs successfully (no orphaned test data)

Troubleshooting

Container not running

.github/skills/scripts/skill-runner.sh docker-rebuild-e2e

Tests timeout

• Increase timeout: --timeout=120000
• Check container health: docker ps | grep charon-e2e

Locator failures (element not found)

• Run in headed mode: --headed
• Use --debug to pause and inspect
• Check selector patterns in test file (getByRole, getByLabel, getByText)

Port already in use

• Kill existing container: docker kill charon-e2e
• Rebuild fresh: docker-rebuild-e2e

Notes

• Firefox only: Phase 4 tests run Firefox to save time (tests are feature-focused, not browser-specific)
• Performance measurements: Login, user creation, proxy creation are timed for baseline metrics
• Soft assertions: Optional features use .isVisible().catch(() => false) to handle deployment variations
• Test organization: Tests group by functional feature area, not by technical layer
• Accessibility: Uses semantic selectors (getByRole, getByLabel) for better resilience

Integration with CI/CD

These tests run as part of the Phase 4 validation gate before production beta release:

# .github/workflows/phase4-uat.yml
- runs: npx playwright test tests/phase4-uat/ --project=firefox
  timeout: 30 minutes
  screenshots: retain-on-failure

Contact & Support

For issues or questions about the test suite:

1. Check test output for specific failure messages
2. Run individual test in debug mode
3. Verify Docker container is healthy and responsive
4. Check application logs: docker logs charon-e2e