Charon/docs/plans/archive/phase_2_fix_plan.md

Phase 2 E2E Failure Fix Plan

1. Introduction

This plan analyzes Phase 2 E2E failures from the remediation checklist and prioritizes fixes that unblock the most tests. It focuses on shared root causes, dependency clusters, and ownership for targeted remediation.

2. Research Findings

2.1 Source of Truth

Primary input: E2E_REMEDIATION_CHECKLIST.md (Phase 2A, 2B, 2C failures).

2.2 Failure Clusters

• Core UI Docker integration: 2 failures on missing/blocked connection source control.
• Settings notifications: 7 failures with timeouts or page context closure.
• Settings strict-mode collisions: 5 failures from over-broad selectors.
• Tasks log viewing: 12 timeouts waiting for log responses.
• Caddy import sessions: 3 failures (import results and missing session banner).
• Monitoring real-time logs: 19 failures with WebSocket status stuck at Disconnected.
• Wait-helpers: 1 failure waiting for URL string match.

3. Root Cause Categorization

3.1 Failure Buckets (54 total)

Bucket	Count	Examples
Backend API issues	24	Notifications CRUD/timeouts, system settings save, Caddy import results, log viewing API timeouts
Frontend UI issues	3	Docker integration control missing, certificate email validation state
WebSocket issues	19	Real-time logs never connect (Disconnected state persists)
Test infrastructure issues	6	Strict-mode collisions (selectors), wait-helpers URL timeout
Admin access/permissions issues	2	Guest visibility of backup button, permissions uncheck disabled

3.2 Root Cause Patterns

• Logs viewing failures (12) all timeout on page.waitForResponse, indicating a shared logs API endpoint not returning or blocked in Docker mode.
• Real-time logs failures (19) all show Disconnected, indicating WebSocket handshake or server-side streaming not established for /api/v1/logs.
• Caddy import failures cluster on missing import session artifacts (no banner and zero parsed imports), suggesting a shared import-session persistence or retrieval issue.
• Settings notifications failures cluster on timeouts and context closure, suggesting API routes or navigation errors when provider lists/templates are queried or mutated.
• Strict-mode collisions in settings and monitoring point to test selectors resolving multiple nodes, indicating test infra refinement needed.
• Admin access failures show inconsistent RBAC enforcement between UI visibility and server-side enforcement.

4. Technical Specifications

4.1 Priority Ranking (Max Impact First)

1. WebSocket connection failures for real-time logs (19 tests blocked)
2. Logs API timeouts for static log viewing (12 tests blocked)
3. Notifications settings API timeouts/context closure (7 tests blocked)
4. Caddy import session persistence/results (3 tests blocked)
5. Docker integration UI controls missing (2 tests blocked)
6. Strict-mode collisions and wait-helpers (6 tests blocked)
7. Admin access/permissions mismatches (2 tests blocked)

4.2 Fix Batches

Critical Fixes (Block multiple suites)

• WebSocket connection / event delivery

  • Affected tests: 19 (monitoring/real-time-logs)
  • Root cause: WebSocket never reaches Connected; likely backend upgrade/streaming path or proxy config issue.
  • Recommendation: Backend Dev

• Logs API timeouts

  • Affected tests: 12 (tasks/logs-viewing)
  • Root cause: log listing endpoints timing out or blocked in container mode.
  • Recommendation: Backend Dev

• Notifications settings API timeouts

  • Affected tests: 7 (settings/notifications)
  • Root cause: provider/template APIs not responding or UI navigation error closing the page context.
  • Recommendation: Backend Dev with Frontend Dev support

• Caddy import session persistence

  • Affected tests: 3 (tasks/caddy-import-*)
  • Root cause: import sessions not persisted or banner data not returned.
  • Recommendation: Backend Dev

Secondary Fixes (Quick wins or infra)

• Docker integration UI controls

  • Affected tests: 2 (core/proxy-hosts Docker integration)
  • Root cause: missing/hidden form control for connection source.
  • Recommendation: Frontend Dev

• Strict-mode collisions and wait helpers

  • Affected tests: 6 (settings + monitoring + wait-helpers)
  • Root cause: selectors match multiple elements or URL helper too strict.
  • Recommendation: Playwright Dev

• Admin access/permissions mismatches

  • Affected tests: 2 (tasks/backups guest UI, settings permission uncheck)
  • Root cause: UI visibility vs RBAC mismatch or disabled inputs.
  • Recommendation: Backend Dev with Frontend Dev support

5. Effort and Impact Estimates

Category	Effort	Impact	Notes
WebSocket connection	L	Very High	Unblocks 19 monitoring tests
Logs API timeouts	M	High	Unblocks 12 task tests
Notifications API timeouts	M	High	Unblocks 7 settings tests
Caddy import sessions	M	Medium	Unblocks 3 task tests
Docker integration UI	S	Medium	Unblocks 2 core tests
Strict-mode + wait helpers	S	Medium	Unblocks 6 tests
Admin access mismatches	S	Low	Unblocks 2 tests

6. Implementation Plan

Phase 1: WebSocket and Logs APIs

1. Verify /api/v1/logs WebSocket handshake and server-side stream starts.
2. Validate static logs API endpoints and response time in Docker mode.
3. Confirm UI connects to correct WebSocket endpoint for app/security modes.

Phase 2: Notifications and Caddy Import Sessions

1. Validate notification providers CRUD endpoints and template endpoints.
2. Ensure notification routes do not crash the page context.
3. Validate import-session persistence and banner retrieval endpoints.

Phase 3: UI and Test Infrastructure Quick Wins

1. Restore Docker integration connection source control visibility.
2. Tighten selectors in strict-mode failures (system status, user management, uptime monitor).
3. Adjust wait-helpers URL matching to handle expected navigation timing.

Phase 4: RBAC Consistency

1. Ensure guest users cannot see Create Backup UI controls.
2. Ensure permission management inputs reflect actual capability and are enabled for admin flows.

7. Acceptance Criteria (EARS)

• WHEN the real-time logs page loads, THE SYSTEM SHALL establish a WebSocket connection and report Connected status within the test timeout.
• WHEN static logs are requested, THE SYSTEM SHALL return log data within the test timeout for pagination, filtering, and download flows.
• WHEN notification providers/templates are managed, THE SYSTEM SHALL respond to CRUD requests without page context closure or timeouts.
• WHEN a Caddy import session exists, THE SYSTEM SHALL return the session banner and import results for review flows.
• WHEN a guest user accesses backups, THE SYSTEM SHALL hide Create Backup controls and enforce server-side RBAC.
• WHEN strict-mode selectors are used, THE SYSTEM SHALL present a unique element for each targeted control in settings and monitoring pages.

8. Delegation Recommendations

• Backend Dev

  • WebSocket connection and streaming
  • Logs API timeouts
  • Notifications APIs
  • Caddy import session persistence
  • RBAC enforcement for backups and permissions

• Frontend Dev

  • Docker integration UI control visibility
  • UI state handling for notifications if backend responses are valid

• Playwright Dev

  • Strict-mode selector refinements
  • wait-helpers URL matching reliability

9. Confidence Score

Confidence: 78 percent

Rationale: Failure clusters are clear and repeated across suites, but root causes still require endpoint-level confirmation in backend logs and WebSocket diagnostics.