Fix WebSocket real-time updates - Connection refused errors

[frankbria]

Problem

E2E test for WebSocket real-time updates is failing with ERR_CONNECTION_REFUSED, indicating the WebSocket connection is not being established properly.

Current Behavior

From test output:

[error] Failed to load resource: net::ERR_CONNECTION_REFUSED
[log] WebSocket connected

The frontend WebSocket client attempts to connect, shows "connected" in logs, but the connection is actually failing with ERR_CONNECTION_REFUSED.

Failed Test

File: tests/e2e/test_dashboard.spec.ts
Test: should receive real-time updates via WebSocket (line 221)

Expected: Dashboard receives real-time agent/task updates via WebSocket
Actual: Connection refused, no updates received

Root Cause Investigation

1. Verify WebSocket endpoint exists in backend

Check if backend has WebSocket route configured:

# Search for WebSocket route in backend
grep -r "websocket" codeframe/ui/server.py
grep -r "WebSocket" codeframe/ui/server.py

2. Check WebSocket connection URL

Frontend WebSocket client configuration:

// web-ui/src/lib/websocket.ts
const wsUrl = `ws://localhost:${port}/ws`;

Verify:

• Port matches backend server port (8080)
• Path matches backend WebSocket route (/ws or similar)
• Protocol is ws:// (not wss:// for local testing)

3. Test WebSocket manually

# Start backend
cd /home/frankbria/projects/codeframe
uv run uvicorn codeframe.ui.server:app --port 8080

# In another terminal, test WebSocket
wscat -c ws://localhost:8080/ws

Expected: Connection established
Actual: ?

4. Check backend WebSocket implementation

Expected FastAPI WebSocket route:

from fastapi import WebSocket

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    # ... send updates

Likely Causes

1. WebSocket route missing - Backend doesn't have /ws endpoint
2. Wrong port - Frontend connecting to wrong port
3. Wrong path - Frontend using /websocket but backend expects /ws
4. CORS issue - WebSocket blocked by CORS policy
5. Backend not running - WebSocket server not started (unlikely, HTTP works)

Expected Behavior

1. Frontend opens WebSocket connection to ws://localhost:8080/ws
2. Backend accepts connection
3. Backend sends real-time events:
   • agent_created
   • agent_status_changed
   • task_assigned
   • task_status_changed
   • blocker_created
   • blocker_resolved
   • etc.
4. Frontend AgentStateProvider receives events and updates state
5. Dashboard UI updates in real-time

Debugging Steps

1. Check if WebSocket endpoint exists:

   grep -A 10 "websocket" codeframe/ui/server.py

2. Check frontend WebSocket URL:

   grep -r "getWebSocketClient\|new WebSocket" web-ui/src/

3. Monitor network traffic during test:

   • Open Chrome DevTools → Network tab
   • Filter by "WS" (WebSocket)
   • Run E2E test
   • Check if WebSocket connection attempted and what error occurs

4. Add debug logging:

   // web-ui/src/lib/websocket.ts
   console.log('WebSocket connecting to:', wsUrl);
   ws.onopen = () => console.log('WebSocket OPEN');
   ws.onerror = (e) => console.error('WebSocket ERROR:', e);
   ws.onclose = (e) => console.log('WebSocket CLOSE:', e.code, e.reason);

Impact

Blocks 1/12 failed E2E tests - lowest priority but important for real-time UX.

Acceptance Criteria

• WebSocket endpoint exists at /ws in backend
• Frontend connects successfully (no ERR_CONNECTION_REFUSED)
• Real-time events sent from backend to frontend
• Dashboard updates in real-time when events received
• E2E test "should receive real-time updates via WebSocket" passes

Related Files

• web-ui/src/lib/websocket.ts - WebSocket client
• web-ui/src/components/AgentStateProvider.tsx - WebSocket event handler
• codeframe/ui/server.py - Backend WebSocket endpoint (if exists)
• tests/e2e/test_dashboard.spec.ts:221 - Failing test

References

• FastAPI WebSockets: https://fastapi.tiangolo.com/advanced/websockets/
• WebSocket debugging: https://developer.chrome.com/docs/devtools/network/reference/#websocket

[traycerai]

Plan

Observations

The WebSocket infrastructure is properly implemented with a backend endpoint at file:codeframe/ui/routers/websocket.py (/ws), a ConnectionManager in file:codeframe/ui/shared.py, and a frontend client in file:web-ui/src/lib/websocket.ts. The E2E test at file:tests/e2e/test_dashboard.spec.ts (line 204-238) fails with ERR_CONNECTION_REFUSED despite the backend being started by Playwright's webServer configuration. The issue stems from a timing problem where the test attempts to establish a WebSocket connection before the backend is fully ready to accept WebSocket connections, even though the HTTP /health endpoint responds successfully.

Approach

The fix addresses the timing issue by adding explicit WebSocket readiness checks before running tests. Since HTTP endpoints can be ready before WebSocket endpoints (different connection handling), we'll add a pre-test verification step that confirms WebSocket connectivity. Additionally, we'll improve the test's WebSocket connection detection logic to properly handle connection failures and add retry mechanisms. The solution maintains the existing architecture while adding robustness through better synchronization and error handling.

Implementation Steps

1. Add WebSocket Health Check Endpoint

File: file:codeframe/ui/routers/websocket.py

Add a simple HTTP endpoint to verify WebSocket server readiness:

• Add a new GET endpoint /ws/health that returns {"status": "ready"} when the WebSocket server is operational
• This endpoint should be added to the same router as the WebSocket endpoint
• Place it before the @router.websocket("/ws") decorator
• Use @router.get("/ws/health") decorator
• Return a simple JSON response indicating WebSocket readiness

2. Update Playwright Configuration to Wait for WebSocket Readiness

File: file:tests/e2e/playwright.config.ts

Modify the backend webServer configuration to wait for WebSocket readiness:

• Change the url property from 'http://localhost:8080/health' to 'http://localhost:8080/ws/health' (line 90)
• This ensures Playwright waits for the WebSocket endpoint to be ready before starting tests
• Keep the same timeout (120000ms) and other configuration

3. Improve E2E Test WebSocket Connection Handling

File: file:tests/e2e/test_dashboard.spec.ts

Enhance the WebSocket test (line 204-238) to properly detect and handle connection failures:

• Before page reload: Add a check to verify the backend WebSocket endpoint is accessible by making a test connection
• Connection detection: Instead of just waiting for the websocket event, also listen for connection errors
• Add explicit wait: After page reload, wait for the AgentStateProvider to mount and attempt connection (wait for [data-testid="agent-status-panel"] to be visible)
• Verify connection status: Check for the WebSocket connection indicator in the UI (the green dot at [data-testid="ws-connection-status"] or similar)
• Error handling: If connection fails, log the error details and fail with a descriptive message

Specific changes:

• Add a helper function waitForWebSocketReady() that polls the /ws/health endpoint
• Call this helper before the test starts
• Modify the test to wait for UI indicators of WebSocket connection rather than just the browser's WebSocket event
• Add timeout handling with clear error messages

4. Add WebSocket Connection Status Indicator to Dashboard

File: file:web-ui/src/components/Dashboard.tsx

Add a testable connection status indicator:

• Locate the existing connection status display (around line 253-260 based on grep results)
• Ensure it has a data-testid="ws-connection-status" attribute
• The indicator should show green when wsConnected is true (from AgentStateProvider state)
• The indicator should show red/gray when disconnected
• This allows the E2E test to verify connection status via the UI

5. Enhance WebSocket Client Error Logging

File: file:web-ui/src/lib/websocket.ts

Improve error logging for debugging connection issues:

• In the connect() method (line 22-63), add more detailed logging:
  • Log the WebSocket URL being connected to
  • Log connection state changes
  • In onerror handler (line 60-62), log the error details including the URL and any error message
  • In onclose handler (line 54-58), log the close code and reason
• Add a check in connect() to verify the URL is valid before attempting connection
• Consider adding a connection timeout that triggers if onopen doesn't fire within 5 seconds

6. Add WebSocket Connectivity Test Script

File: file:scripts/test-websocket.py

Enhance the existing test script (if it exists) or create a new one:

• Add a test that verifies the /ws/health endpoint responds
• Add a test that establishes a WebSocket connection to ws://localhost:8080/ws
• Send a ping message and verify pong response
• This script can be run manually or in CI to verify WebSocket functionality
• Document usage in the test output

7. Update E2E Test Documentation

File: file:tests/e2e/README.md (create if doesn't exist)

Document the WebSocket testing approach:

• Explain the WebSocket health check mechanism
• Document the timing requirements (backend must be fully ready)
• Provide troubleshooting steps for WebSocket connection failures
• Include examples of running the WebSocket test script

8. Add Retry Logic to AgentStateProvider WebSocket Connection

File: file:web-ui/src/components/AgentStateProvider.tsx

Improve initial connection reliability:

• In the useEffect hook that connects to WebSocket (line 151-243), add a check to verify the connection succeeds
• If the initial connection fails, the existing reconnect logic will handle it, but add logging to indicate this is happening
• Consider adding a small delay (100-200ms) before the initial connection attempt to ensure the component is fully mounted
• This helps with race conditions during page load

Verification Steps

After implementing these changes:

1. Manual verification: Start the backend with uv run uvicorn codeframe.ui.server:app --port 8080, verify /ws/health endpoint responds, then connect with a WebSocket client (wscat or browser console)

2. Run WebSocket test script: Execute uv run python scripts/test-websocket.py to verify connectivity

3. Run E2E test: Execute npm run test:e2e from the tests/e2e directory and verify the WebSocket test passes

4. Check browser DevTools: During E2E test execution, verify in the Network tab (WS filter) that the WebSocket connection is established successfully

Architecture Diagram

sequenceDiagram
    participant PT as Playwright Test
    participant BE as Backend Server
    participant FE as Frontend (Next.js)
    participant WS as WebSocket Client
    participant WSE as WebSocket Endpoint

    Note over PT,WSE: Test Startup Sequence
    PT->>BE: Start backend server
    BE->>BE: Initialize FastAPI app
    BE->>BE: Mount WebSocket router
    PT->>BE: Poll /ws/health
    BE-->>PT: 200 OK (WebSocket ready)
    PT->>FE: Start frontend dev server
    
    Note over PT,WSE: Test Execution
    PT->>FE: Navigate to /projects/1
    FE->>FE: Render AgentStateProvider
    FE->>WS: Initialize WebSocket client
    WS->>WSE: Connect to ws://localhost:8080/ws
    WSE-->>WS: Connection accepted
    WS-->>FE: onopen event (connected)
    FE->>FE: Update UI (green indicator)
    
    Note over PT,WSE: Test Verification
    PT->>FE: Wait for ws-connection-status
    FE-->>PT: Element visible (green)
    PT->>PT: Test passes ✓

Loading

Key Files Reference

• file:codeframe/ui/routers/websocket.py - Backend WebSocket endpoint
• file:codeframe/ui/server.py - FastAPI app with router mounting
• file:codeframe/ui/shared.py - ConnectionManager singleton
• file:web-ui/src/lib/websocket.ts - Frontend WebSocket client
• file:web-ui/src/components/AgentStateProvider.tsx - WebSocket connection initialization
• file:web-ui/src/components/Dashboard.tsx - Connection status UI
• file:tests/e2e/test_dashboard.spec.ts - Failing E2E test
• file:tests/e2e/playwright.config.ts - Playwright configuration
• file:tests/e2e/e2e-config.ts - E2E test configuration

Import In IDE

🤖 Prompt for AI Agents

## Observations

The WebSocket infrastructure is properly implemented with a backend endpoint at `file:codeframe/ui/routers/websocket.py` (`/ws`), a ConnectionManager in `file:codeframe/ui/shared.py`, and a frontend client in `file:web-ui/src/lib/websocket.ts`. The E2E test at `file:tests/e2e/test_dashboard.spec.ts` (line 204-238) fails with `ERR_CONNECTION_REFUSED` despite the backend being started by Playwright's `webServer` configuration. The issue stems from a timing problem where the test attempts to establish a WebSocket connection before the backend is fully ready to accept WebSocket connections, even though the HTTP `/health` endpoint responds successfully.

## Approach

The fix addresses the timing issue by adding explicit WebSocket readiness checks before running tests. Since HTTP endpoints can be ready before WebSocket endpoints (different connection handling), we'll add a pre-test verification step that confirms WebSocket connectivity. Additionally, we'll improve the test's WebSocket connection detection logic to properly handle connection failures and add retry mechanisms. The solution maintains the existing architecture while adding robustness through better synchronization and error handling.

## Implementation Steps

### 1. Add WebSocket Health Check Endpoint

**File**: `file:codeframe/ui/routers/websocket.py`

Add a simple HTTP endpoint to verify WebSocket server readiness:

- Add a new GET endpoint `/ws/health` that returns `{"status": "ready"}` when the WebSocket server is operational
- This endpoint should be added to the same router as the WebSocket endpoint
- Place it before the `@router.websocket("/ws")` decorator
- Use `@router.get("/ws/health")` decorator
- Return a simple JSON response indicating WebSocket readiness

### 2. Update Playwright Configuration to Wait for WebSocket Readiness

**File**: `file:tests/e2e/playwright.config.ts`

Modify the backend webServer configuration to wait for WebSocket readiness:

- Change the `url` property from `'http://localhost:8080/health'` to `'http://localhost:8080/ws/health'` (line 90)
- This ensures Playwright waits for the WebSocket endpoint to be ready before starting tests
- Keep the same timeout (120000ms) and other configuration

### 3. Improve E2E Test WebSocket Connection Handling

**File**: `file:tests/e2e/test_dashboard.spec.ts`

Enhance the WebSocket test (line 204-238) to properly detect and handle connection failures:

- **Before page reload**: Add a check to verify the backend WebSocket endpoint is accessible by making a test connection
- **Connection detection**: Instead of just waiting for the `websocket` event, also listen for connection errors
- **Add explicit wait**: After page reload, wait for the AgentStateProvider to mount and attempt connection (wait for `[data-testid="agent-status-panel"]` to be visible)
- **Verify connection status**: Check for the WebSocket connection indicator in the UI (the green dot at `[data-testid="ws-connection-status"]` or similar)
- **Error handling**: If connection fails, log the error details and fail with a descriptive message

**Specific changes**:
- Add a helper function `waitForWebSocketReady()` that polls the `/ws/health` endpoint
- Call this helper before the test starts
- Modify the test to wait for UI indicators of WebSocket connection rather than just the browser's WebSocket event
- Add timeout handling with clear error messages

### 4. Add WebSocket Connection Status Indicator to Dashboard

**File**: `file:web-ui/src/components/Dashboard.tsx`

Add a testable connection status indicator:

- Locate the existing connection status display (around line 253-260 based on grep results)
- Ensure it has a `data-testid="ws-connection-status"` attribute
- The indicator should show green when `wsConnected` is true (from AgentStateProvider state)
- The indicator should show red/gray when disconnected
- This allows the E2E test to verify connection status via the UI

### 5. Enhance WebSocket Client Error Logging

**File**: `file:web-ui/src/lib/websocket.ts`

Improve error logging for debugging connection issues:

- In the `connect()` method (line 22-63), add more detailed logging:
  - Log the WebSocket URL being connected to
  - Log connection state changes
  - In `onerror` handler (line 60-62), log the error details including the URL and any error message
  - In `onclose` handler (line 54-58), log the close code and reason
- Add a check in `connect()` to verify the URL is valid before attempting connection
- Consider adding a connection timeout that triggers if `onopen` doesn't fire within 5 seconds

### 6. Add WebSocket Connectivity Test Script

**File**: `file:scripts/test-websocket.py`

Enhance the existing test script (if it exists) or create a new one:

- Add a test that verifies the `/ws/health` endpoint responds
- Add a test that establishes a WebSocket connection to `ws://localhost:8080/ws`
- Send a ping message and verify pong response
- This script can be run manually or in CI to verify WebSocket functionality
- Document usage in the test output

### 7. Update E2E Test Documentation

**File**: `file:tests/e2e/README.md` (create if doesn't exist)

Document the WebSocket testing approach:

- Explain the WebSocket health check mechanism
- Document the timing requirements (backend must be fully ready)
- Provide troubleshooting steps for WebSocket connection failures
- Include examples of running the WebSocket test script

### 8. Add Retry Logic to AgentStateProvider WebSocket Connection

**File**: `file:web-ui/src/components/AgentStateProvider.tsx`

Improve initial connection reliability:

- In the `useEffect` hook that connects to WebSocket (line 151-243), add a check to verify the connection succeeds
- If the initial connection fails, the existing reconnect logic will handle it, but add logging to indicate this is happening
- Consider adding a small delay (100-200ms) before the initial connection attempt to ensure the component is fully mounted
- This helps with race conditions during page load

## Verification Steps

After implementing these changes:

1. **Manual verification**: Start the backend with `uv run uvicorn codeframe.ui.server:app --port 8080`, verify `/ws/health` endpoint responds, then connect with a WebSocket client (wscat or browser console)

2. **Run WebSocket test script**: Execute `uv run python scripts/test-websocket.py` to verify connectivity

3. **Run E2E test**: Execute `npm run test:e2e` from the `tests/e2e` directory and verify the WebSocket test passes

4. **Check browser DevTools**: During E2E test execution, verify in the Network tab (WS filter) that the WebSocket connection is established successfully

## Architecture Diagram

```mermaid
sequenceDiagram
    participant PT as Playwright Test
    participant BE as Backend Server
    participant FE as Frontend (Next.js)
    participant WS as WebSocket Client
    participant WSE as WebSocket Endpoint

    Note over PT,WSE: Test Startup Sequence
    PT->>BE: Start backend server
    BE->>BE: Initialize FastAPI app
    BE->>BE: Mount WebSocket router
    PT->>BE: Poll /ws/health
    BE-->>PT: 200 OK (WebSocket ready)
    PT->>FE: Start frontend dev server
    
    Note over PT,WSE: Test Execution
    PT->>FE: Navigate to /projects/1
    FE->>FE: Render AgentStateProvider
    FE->>WS: Initialize WebSocket client
    WS->>WSE: Connect to ws://localhost:8080/ws
    WSE-->>WS: Connection accepted
    WS-->>FE: onopen event (connected)
    FE->>FE: Update UI (green indicator)
    
    Note over PT,WSE: Test Verification
    PT->>FE: Wait for ws-connection-status
    FE-->>PT: Element visible (green)
    PT->>PT: Test passes ✓
```

## Key Files Reference

- `file:codeframe/ui/routers/websocket.py` - Backend WebSocket endpoint
- `file:codeframe/ui/server.py` - FastAPI app with router mounting
- `file:codeframe/ui/shared.py` - ConnectionManager singleton
- `file:web-ui/src/lib/websocket.ts` - Frontend WebSocket client
- `file:web-ui/src/components/AgentStateProvider.tsx` - WebSocket connection initialization
- `file:web-ui/src/components/Dashboard.tsx` - Connection status UI
- `file:tests/e2e/test_dashboard.spec.ts` - Failing E2E test
- `file:tests/e2e/playwright.config.ts` - Playwright configuration
- `file:tests/e2e/e2e-config.ts` - E2E test configuration

---

Execution Information

Branch: main
Commit: 360e111

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

🔗 Similar Issues

Related Issues

• Fix checkpoint panel visibility - CheckpointList not rendering items #85
• Fix SWR timing/cache issues causing flaky frontend tests #41
• Implement Task Statistics Display in Dashboard #44
• Add data-testid attributes to Dashboard tabs for E2E testing #84
• [P1][Ops] Add comprehensive health checks and metrics claude-code-orchestrator#8

🔗 Related PRs

#23 - feat: Add 'codeframe serve' command to start dashboard server [merged]
#26 - Feature 013: Context Panel Integration with TypeScript Fixes [merged]
#35 - fix: Resolve E2E test timeout failures in GitHub Actions [merged]
#38 - fix(e2e): Improve Playwright test pass rate from 18% to 57% [merged]
#51 - feat: Add TaskStats component to Dashboard Overview tab [merged]

👤 Suggested Assignees

• frankbria

---

🧪 Issue enrichment is currently in early access.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

[frankbria]

@traycerai Update bug fix plan

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

New Plan

Observations

The WebSocket infrastructure is properly implemented with a backend endpoint at file:codeframe/ui/routers/websocket.py (/ws), a ConnectionManager in file:codeframe/ui/shared.py, and a frontend client in file:web-ui/src/lib/websocket.ts. The E2E test at file:tests/e2e/test_dashboard.spec.ts (line 204-238) fails with ERR_CONNECTION_REFUSED despite the backend being started by Playwright's webServer configuration. The issue stems from a timing problem where the test attempts to establish a WebSocket connection before the backend is fully ready to accept WebSocket connections, even though the HTTP /health endpoint responds successfully.

Approach

The fix addresses the timing issue by adding explicit WebSocket readiness checks before running tests. Since HTTP endpoints can be ready before WebSocket endpoints (different connection handling), we'll add a pre-test verification step that confirms WebSocket connectivity. Additionally, we'll improve the test's WebSocket connection detection logic to properly handle connection failures and add retry mechanisms. The solution maintains the existing architecture while adding robustness through better synchronization and error handling.

Implementation Steps

1. Add WebSocket Health Check Endpoint

File: file:codeframe/ui/routers/websocket.py

Add a simple HTTP endpoint to verify WebSocket server readiness:

• Add a new GET endpoint /ws/health that returns {"status": "ready"} when the WebSocket server is operational
• This endpoint should be added to the same router as the WebSocket endpoint
• Place it before the @router.websocket("/ws") decorator
• Use @router.get("/ws/health") decorator
• Return a simple JSON response indicating WebSocket readiness

2. Update Playwright Configuration to Wait for WebSocket Readiness

File: file:tests/e2e/playwright.config.ts

Modify the backend webServer configuration to wait for WebSocket readiness:

• Change the url property from 'http://localhost:8080/health' to 'http://localhost:8080/ws/health' (line 90)
• This ensures Playwright waits for the WebSocket endpoint to be ready before starting tests
• Keep the same timeout (120000ms) and other configuration

3. Improve E2E Test WebSocket Connection Handling

File: file:tests/e2e/test_dashboard.spec.ts

Enhance the WebSocket test (line 204-238) to properly detect and handle connection failures:

• Before page reload: Add a check to verify the backend WebSocket endpoint is accessible by making a test connection
• Connection detection: Instead of just waiting for the websocket event, also listen for connection errors
• Add explicit wait: After page reload, wait for the AgentStateProvider to mount and attempt connection (wait for [data-testid="agent-status-panel"] to be visible)
• Verify connection status: Check for the WebSocket connection indicator in the UI (the green dot at [data-testid="ws-connection-status"] or similar)
• Error handling: If connection fails, log the error details and fail with a descriptive message

Specific changes:

• Add a helper function waitForWebSocketReady() that polls the /ws/health endpoint
• Call this helper before the test starts
• Modify the test to wait for UI indicators of WebSocket connection rather than just the browser's WebSocket event
• Add timeout handling with clear error messages

4. Add WebSocket Connection Status Indicator to Dashboard

File: file:web-ui/src/components/Dashboard.tsx

Add a testable connection status indicator:

• Locate the existing connection status display (around line 253-260 based on grep results)
• Ensure it has a data-testid="ws-connection-status" attribute
• The indicator should show green when wsConnected is true (from AgentStateProvider state)
• The indicator should show red/gray when disconnected
• This allows the E2E test to verify connection status via the UI

5. Enhance WebSocket Client Error Logging

File: file:web-ui/src/lib/websocket.ts

Improve error logging for debugging connection issues:

• In the connect() method (line 22-63), add more detailed logging:
  • Log the WebSocket URL being connected to
  • Log connection state changes
  • In onerror handler (line 60-62), log the error details including the URL and any error message
  • In onclose handler (line 54-58), log the close code and reason
• Add a check in connect() to verify the URL is valid before attempting connection
• Consider adding a connection timeout that triggers if onopen doesn't fire within 5 seconds

6. Add WebSocket Connectivity Test Script

File: file:scripts/test-websocket.py

Enhance the existing test script (if it exists) or create a new one:

• Add a test that verifies the /ws/health endpoint responds
• Add a test that establishes a WebSocket connection to ws://localhost:8080/ws
• Send a ping message and verify pong response
• This script can be run manually or in CI to verify WebSocket functionality
• Document usage in the test output

7. Update E2E Test Documentation

File: file:tests/e2e/README.md (create if doesn't exist)

Document the WebSocket testing approach:

• Explain the WebSocket health check mechanism
• Document the timing requirements (backend must be fully ready)
• Provide troubleshooting steps for WebSocket connection failures
• Include examples of running the WebSocket test script

8. Add Retry Logic to AgentStateProvider WebSocket Connection

File: file:web-ui/src/components/AgentStateProvider.tsx

Improve initial connection reliability:

• In the useEffect hook that connects to WebSocket (line 151-243), add a check to verify the connection succeeds
• If the initial connection fails, the existing reconnect logic will handle it, but add logging to indicate this is happening
• Consider adding a small delay (100-200ms) before the initial connection attempt to ensure the component is fully mounted
• This helps with race conditions during page load

Verification Steps

After implementing these changes:

1. Manual verification: Start the backend with uv run uvicorn codeframe.ui.server:app --port 8080, verify /ws/health endpoint responds, then connect with a WebSocket client (wscat or browser console)

2. Run WebSocket test script: Execute uv run python scripts/test-websocket.py to verify connectivity

3. Run E2E test: Execute npm run test:e2e from the tests/e2e directory and verify the WebSocket test passes

4. Check browser DevTools: During E2E test execution, verify in the Network tab (WS filter) that the WebSocket connection is established successfully

Architecture Diagram

sequenceDiagram
    participant PT as Playwright Test
    participant BE as Backend Server
    participant FE as Frontend (Next.js)
    participant WS as WebSocket Client
    participant WSE as WebSocket Endpoint

    Note over PT,WSE: Test Startup Sequence
    PT->>BE: Start backend server
    BE->>BE: Initialize FastAPI app
    BE->>BE: Mount WebSocket router
    PT->>BE: Poll /ws/health
    BE-->>PT: 200 OK (WebSocket ready)
    PT->>FE: Start frontend dev server
    
    Note over PT,WSE: Test Execution
    PT->>FE: Navigate to /projects/1
    FE->>FE: Render AgentStateProvider
    FE->>WS: Initialize WebSocket client
    WS->>WSE: Connect to ws://localhost:8080/ws
    WSE-->>WS: Connection accepted
    WS-->>FE: onopen event (connected)
    FE->>FE: Update UI (green indicator)
    
    Note over PT,WSE: Test Verification
    PT->>FE: Wait for ws-connection-status
    FE-->>PT: Element visible (green)
    PT->>PT: Test passes ✓

Loading

Key Files Reference

• file:codeframe/ui/routers/websocket.py - Backend WebSocket endpoint
• file:codeframe/ui/server.py - FastAPI app with router mounting
• file:codeframe/ui/shared.py - ConnectionManager singleton
• file:web-ui/src/lib/websocket.ts - Frontend WebSocket client
• file:web-ui/src/components/AgentStateProvider.tsx - WebSocket connection initialization
• file:web-ui/src/components/Dashboard.tsx - Connection status UI
• file:tests/e2e/test_dashboard.spec.ts - Failing E2E test
• file:tests/e2e/playwright.config.ts - Playwright configuration
• file:tests/e2e/e2e-config.ts - E2E test configuration

Import In IDE

🤖 Prompt for AI Agents

## Observations

The WebSocket infrastructure is properly implemented with a backend endpoint at `file:codeframe/ui/routers/websocket.py` (`/ws`), a ConnectionManager in `file:codeframe/ui/shared.py`, and a frontend client in `file:web-ui/src/lib/websocket.ts`. The E2E test at `file:tests/e2e/test_dashboard.spec.ts` (line 204-238) fails with `ERR_CONNECTION_REFUSED` despite the backend being started by Playwright's `webServer` configuration. The issue stems from a timing problem where the test attempts to establish a WebSocket connection before the backend is fully ready to accept WebSocket connections, even though the HTTP `/health` endpoint responds successfully.

## Approach

The fix addresses the timing issue by adding explicit WebSocket readiness checks before running tests. Since HTTP endpoints can be ready before WebSocket endpoints (different connection handling), we'll add a pre-test verification step that confirms WebSocket connectivity. Additionally, we'll improve the test's WebSocket connection detection logic to properly handle connection failures and add retry mechanisms. The solution maintains the existing architecture while adding robustness through better synchronization and error handling.

## Implementation Steps

### 1. Add WebSocket Health Check Endpoint

**File**: `file:codeframe/ui/routers/websocket.py`

Add a simple HTTP endpoint to verify WebSocket server readiness:

- Add a new GET endpoint `/ws/health` that returns `{"status": "ready"}` when the WebSocket server is operational
- This endpoint should be added to the same router as the WebSocket endpoint
- Place it before the `@router.websocket("/ws")` decorator
- Use `@router.get("/ws/health")` decorator
- Return a simple JSON response indicating WebSocket readiness

### 2. Update Playwright Configuration to Wait for WebSocket Readiness

**File**: `file:tests/e2e/playwright.config.ts`

Modify the backend webServer configuration to wait for WebSocket readiness:

- Change the `url` property from `'http://localhost:8080/health'` to `'http://localhost:8080/ws/health'` (line 90)
- This ensures Playwright waits for the WebSocket endpoint to be ready before starting tests
- Keep the same timeout (120000ms) and other configuration

### 3. Improve E2E Test WebSocket Connection Handling

**File**: `file:tests/e2e/test_dashboard.spec.ts`

Enhance the WebSocket test (line 204-238) to properly detect and handle connection failures:

- **Before page reload**: Add a check to verify the backend WebSocket endpoint is accessible by making a test connection
- **Connection detection**: Instead of just waiting for the `websocket` event, also listen for connection errors
- **Add explicit wait**: After page reload, wait for the AgentStateProvider to mount and attempt connection (wait for `[data-testid="agent-status-panel"]` to be visible)
- **Verify connection status**: Check for the WebSocket connection indicator in the UI (the green dot at `[data-testid="ws-connection-status"]` or similar)
- **Error handling**: If connection fails, log the error details and fail with a descriptive message

**Specific changes**:
- Add a helper function `waitForWebSocketReady()` that polls the `/ws/health` endpoint
- Call this helper before the test starts
- Modify the test to wait for UI indicators of WebSocket connection rather than just the browser's WebSocket event
- Add timeout handling with clear error messages

### 4. Add WebSocket Connection Status Indicator to Dashboard

**File**: `file:web-ui/src/components/Dashboard.tsx`

Add a testable connection status indicator:

- Locate the existing connection status display (around line 253-260 based on grep results)
- Ensure it has a `data-testid="ws-connection-status"` attribute
- The indicator should show green when `wsConnected` is true (from AgentStateProvider state)
- The indicator should show red/gray when disconnected
- This allows the E2E test to verify connection status via the UI

### 5. Enhance WebSocket Client Error Logging

**File**: `file:web-ui/src/lib/websocket.ts`

Improve error logging for debugging connection issues:

- In the `connect()` method (line 22-63), add more detailed logging:
  - Log the WebSocket URL being connected to
  - Log connection state changes
  - In `onerror` handler (line 60-62), log the error details including the URL and any error message
  - In `onclose` handler (line 54-58), log the close code and reason
- Add a check in `connect()` to verify the URL is valid before attempting connection
- Consider adding a connection timeout that triggers if `onopen` doesn't fire within 5 seconds

### 6. Add WebSocket Connectivity Test Script

**File**: `file:scripts/test-websocket.py`

Enhance the existing test script (if it exists) or create a new one:

- Add a test that verifies the `/ws/health` endpoint responds
- Add a test that establishes a WebSocket connection to `ws://localhost:8080/ws`
- Send a ping message and verify pong response
- This script can be run manually or in CI to verify WebSocket functionality
- Document usage in the test output

### 7. Update E2E Test Documentation

**File**: `file:tests/e2e/README.md` (create if doesn't exist)

Document the WebSocket testing approach:

- Explain the WebSocket health check mechanism
- Document the timing requirements (backend must be fully ready)
- Provide troubleshooting steps for WebSocket connection failures
- Include examples of running the WebSocket test script

### 8. Add Retry Logic to AgentStateProvider WebSocket Connection

**File**: `file:web-ui/src/components/AgentStateProvider.tsx`

Improve initial connection reliability:

- In the `useEffect` hook that connects to WebSocket (line 151-243), add a check to verify the connection succeeds
- If the initial connection fails, the existing reconnect logic will handle it, but add logging to indicate this is happening
- Consider adding a small delay (100-200ms) before the initial connection attempt to ensure the component is fully mounted
- This helps with race conditions during page load

## Verification Steps

After implementing these changes:

1. **Manual verification**: Start the backend with `uv run uvicorn codeframe.ui.server:app --port 8080`, verify `/ws/health` endpoint responds, then connect with a WebSocket client (wscat or browser console)

2. **Run WebSocket test script**: Execute `uv run python scripts/test-websocket.py` to verify connectivity

3. **Run E2E test**: Execute `npm run test:e2e` from the `tests/e2e` directory and verify the WebSocket test passes

4. **Check browser DevTools**: During E2E test execution, verify in the Network tab (WS filter) that the WebSocket connection is established successfully

## Architecture Diagram

```mermaid
sequenceDiagram
    participant PT as Playwright Test
    participant BE as Backend Server
    participant FE as Frontend (Next.js)
    participant WS as WebSocket Client
    participant WSE as WebSocket Endpoint

    Note over PT,WSE: Test Startup Sequence
    PT->>BE: Start backend server
    BE->>BE: Initialize FastAPI app
    BE->>BE: Mount WebSocket router
    PT->>BE: Poll /ws/health
    BE-->>PT: 200 OK (WebSocket ready)
    PT->>FE: Start frontend dev server
    
    Note over PT,WSE: Test Execution
    PT->>FE: Navigate to /projects/1
    FE->>FE: Render AgentStateProvider
    FE->>WS: Initialize WebSocket client
    WS->>WSE: Connect to ws://localhost:8080/ws
    WSE-->>WS: Connection accepted
    WS-->>FE: onopen event (connected)
    FE->>FE: Update UI (green indicator)
    
    Note over PT,WSE: Test Verification
    PT->>FE: Wait for ws-connection-status
    FE-->>PT: Element visible (green)
    PT->>PT: Test passes ✓
```

## Key Files Reference

- `file:codeframe/ui/routers/websocket.py` - Backend WebSocket endpoint
- `file:codeframe/ui/server.py` - FastAPI app with router mounting
- `file:codeframe/ui/shared.py` - ConnectionManager singleton
- `file:web-ui/src/lib/websocket.ts` - Frontend WebSocket client
- `file:web-ui/src/components/AgentStateProvider.tsx` - WebSocket connection initialization
- `file:web-ui/src/components/Dashboard.tsx` - Connection status UI
- `file:tests/e2e/test_dashboard.spec.ts` - Failing E2E test
- `file:tests/e2e/playwright.config.ts` - Playwright configuration
- `file:tests/e2e/e2e-config.ts` - E2E test configuration

---

Execution Information

Branch: main
Commit: 360e111