WebSocket integration tests hang due to TestClient async broadcast incompatibility

[frankbria]

Problem

All 30 tests in tests/ui/test_websocket_integration.py hang indefinitely when trying to test WebSocket broadcasts. The tests fail to complete even after several minutes.

Root Cause

FastAPI's TestClient creates synchronous WebSocket sessions that are incompatible with the async manager.broadcast() method used in production code.

Technical Details

1. TestClient WebSocket behavior:

   • websocket.send_json() - client sends to server (synchronous)
   • websocket.receive_json() - client receives from server (synchronous, blocking)
   • Runs in a background thread with its own event loop

2. Production broadcast behavior:

   • await manager.broadcast(message, project_id) - async method
   • Calls await connection.send_json(message) on server-side WebSocket objects
   • Requires async event loop to execute

3. The conflict:

   • When tests call manager.broadcast(), it tries to send to WebSocket objects managed by TestClient
   • TestClient's synchronous WebSocket sessions don't properly handle async sends from the manager
   • Tests hang waiting for messages that never arrive

Affected Tests

All 30 tests in tests/ui/test_websocket_integration.py:

• TestFullSubscriptionWorkflow (3 tests)
• TestMultiClientScenario (2 tests)
• TestSubscribeUnsubscribeFlow (3 tests)
• TestDisconnectCleanup (2 tests)
• TestBackwardCompatibility (2 tests)
• TestInvalidMessages (9 tests)
• TestEdgeCases (9 tests)

Attempted Solutions

❌ Threading with new event loop

def broadcast_sync(manager, message, project_id=None):
    def run_broadcast():
        loop = asyncio.new_event_loop()
        loop.run_until_complete(manager.broadcast(message, project_id))
    thread = threading.Thread(target=run_broadcast)
    thread.start()
    thread.join(timeout=2.0)

Result: Still hangs. TestClient's WebSocket objects don't work across threads.

❌ Direct asyncio.run()

asyncio.run(manager.broadcast(message, project_id=1))

Result: Hangs. Creates event loop conflict with TestClient's background thread.

Recommended Solutions

Option 1: Mock the broadcast method (Fastest)

@pytest.fixture
def mock_broadcast(monkeypatch):
    async def fake_broadcast(message, project_id=None):
        # Don't actually broadcast in tests
        pass
    monkeypatch.setattr('codeframe.ui.shared.manager.broadcast', fake_broadcast)

Pros: Quick fix, tests can verify subscription logic
Cons: Doesn't test actual message delivery

Option 2: Use real WebSocket client library (Most thorough)

Replace TestClient with websockets library:

import websockets

async def test_broadcast():
    async with websockets.connect('ws://localhost:8000/ws') as ws:
        await ws.send(json.dumps({"type": "subscribe", "project_id": 1}))
        # Server can now broadcast properly
        response = await ws.recv()

Pros: Tests real WebSocket behavior
Cons: Requires running server, more complex setup

Option 3: Refactor to test broadcast logic separately

• Test subscription management (which websockets are subscribed)
• Test message filtering logic (which subscribers get which messages)
• Don't test actual WebSocket send/receive in unit tests

Pros: Clean separation of concerns
Cons: Doesn't test end-to-end WebSocket flow

Recommendation

Use Option 2 (real WebSocket client) for comprehensive testing, with Option 1 (mocking) as a short-term workaround to unblock CI/CD.

Related Issues

• Miscellaneous backend test failures #145 - Test suite failures (parent issue, mostly resolved)

Files

• tests/ui/test_websocket_integration.py - All 30 tests affected
• codeframe/ui/shared.py - ConnectionManager.broadcast() method
• codeframe/ui/routers/websocket.py - WebSocket endpoint

Environment

• Python 3.13.3
• FastAPI + Starlette TestClient
• pytest 8.4.2

Acceptance Criteria

• All 30 WebSocket integration tests pass
• Tests complete in <30 seconds total
• Tests properly validate WebSocket subscription and broadcast behavior
• CI/CD pipeline runs successfully

[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 WebSocket real-time updates - Connection refused errors #87
• Fix SWR timing/cache issues causing flaky frontend tests #41
• [P2] Replace mocked unit tests with real integration tests #113
• [P1] Implement WebSocket subscription tracking in websocket router #105
• Miscellaneous backend test failures #145

🔗 Related PRs

#22 - fix: Reorganize test suite and fix API test failures [merged]
#25 - feat: Discovery Answer UI Integration (Feature 012) [merged]
#35 - fix: Resolve E2E test timeout failures in GitHub Actions [merged]
#133 - WebSocket Subscription Filtering for Project-Scoped Broadcasts [merged]
#134 - WebSocket Subscription Filtering for Project-Scoped Broadcasts [merged]

👤 Suggested Assignees

• frankbria

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

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

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[traycerai]

Plan

Observations

The WebSocket integration tests hang because FastAPI's TestClient creates synchronous WebSocket sessions in a background thread with its own event loop. When manager.broadcast() (an async method) tries to send messages via await connection.send_json(), it creates an event loop conflict. The current broadcast_sync() helper attempts to bridge this gap by creating a new event loop in a thread, but TestClient's WebSocket objects remain tied to their original event loop and cannot receive async sends. The project already includes websockets>=12.0 library, making a real WebSocket client solution feasible.

Approach

Replace FastAPI's TestClient WebSocket testing with real async WebSocket clients using the websockets library. This involves running the FastAPI server in a background thread during tests and connecting to it with actual WebSocket clients. This approach tests the complete WebSocket stack end-to-end, ensuring broadcasts work correctly in production. All tests will be converted to async (pytest-asyncio is already configured), and a new fixture will manage server lifecycle. The broadcast_sync() helper will be removed as it's no longer needed with real async clients.

Implementation Steps

1. Create Server Lifecycle Fixture

File: file:tests/ui/conftest.py (create new file)

Create a pytest fixture that manages the FastAPI server lifecycle for WebSocket tests:

• Import required modules: threading, uvicorn, time, pytest, asyncio
• Create @pytest.fixture(scope="module") named running_server that:
  • Sets up temporary database and workspace directories
  • Configures environment variables (DATABASE_PATH, WORKSPACE_ROOT, AUTH_REQUIRED=false)
  • Initializes database with test user (user_id=1) and test project (project_id=1)
  • Starts uvicorn server in a background thread on a free port (use socket to find available port)
  • Waits for server to be ready by polling health endpoint with retries
  • Yields server URL (e.g., http://localhost:{port})
  • On teardown: stops server thread and cleans up temporary directories
• Create helper fixture @pytest.fixture named ws_url that converts HTTP URL to WebSocket URL (replace http:// with ws://)

2. Update Test Client Fixture

File: file:tests/ui/test_websocket_integration.py

Replace the existing test_client fixture (lines 67-127):

• Remove the fixture entirely as it will be replaced by running_server and ws_url fixtures
• Update all test classes to use running_server and ws_url fixtures instead
• Remove imports related to TestClient (line 20)
• Add import: import websockets at the top

3. Convert Tests to Async with Real WebSocket Clients

File: file:tests/ui/test_websocket_integration.py

Transform all test methods to use async WebSocket clients:

TestFullSubscriptionWorkflow (lines 130-224)

• Add @pytest.mark.asyncio decorator to all test methods
• Change method signatures from def test_* to async def test_*
• Replace test_client parameter with ws_url parameter
• In test_connect_and_subscribe_single_project:
  • Replace with test_client.websocket_connect("/ws") as websocket: with async with websockets.connect(f"{ws_url}/ws") as websocket:
  • Replace websocket.send_json() with await websocket.send(json.dumps(...))
  • Replace websocket.receive_json() with json.loads(await websocket.recv())
• In test_receive_filtered_broadcast_after_subscribe:
  • Use async WebSocket client as above
  • Replace broadcast_sync() call with direct await manager.broadcast()
  • Import manager: from codeframe.ui.shared import manager
• In test_unsubscribe_stops_receiving_messages:
  • Use async WebSocket client
  • Replace timeout handling: use asyncio.wait_for(websocket.recv(), timeout=0.1) wrapped in try/except asyncio.TimeoutError
• In test_disconnect_cleanup:
  • Use async context managers for WebSocket connections
  • Replace manual __enter__/__exit__ with proper async context manager usage

TestMultiClientScenario (lines 226-334)

• Add @pytest.mark.asyncio to all methods
• Convert to async def
• In test_three_clients_with_independent_subscriptions:
  • Create 3 async WebSocket connections using async with websockets.connect()
  • Use nested async context managers or asyncio.gather() for concurrent connections
  • Replace all send_json/receive_json with async equivalents
  • Replace broadcast_sync() with await manager.broadcast()
• In test_broadcast_isolation_between_projects:
  • Similar transformations as above
  • Use asyncio.wait_for() for timeout testing

TestSubscribeUnsubscribeFlow (lines 336-402)

• Add @pytest.mark.asyncio to all methods
• Convert to async WebSocket clients
• In test_subscribe_to_multiple_projects_sequentially:
  • Use async WebSocket client
  • Access subscriptions via await manager.subscription_manager.get_subscriptions(websocket) instead of get_subscriptions_sync()
• Apply similar patterns to other tests in this class

TestDisconnectCleanup (lines 404-474)

• Add @pytest.mark.asyncio to all methods
• Convert to async WebSocket clients
• Replace get_subscriptions_sync() calls with async subscription manager methods
• Use proper async context manager cleanup

TestBackwardCompatibility (lines 476-555)

• Add @pytest.mark.asyncio to all methods
• Convert to async WebSocket clients
• Replace broadcast_sync() with await manager.broadcast()
• Use asyncio.wait_for() for timeout testing

TestInvalidMessageHandling (lines 557-621)

• Add @pytest.mark.asyncio to all methods (except test_malformed_json_handling which expects synchronous disconnect)
• Convert to async WebSocket clients
• In test_malformed_json_handling:
  • Use websockets.exceptions.ConnectionClosed instead of WebSocketDisconnect
  • Send malformed JSON with await websocket.send("{ invalid json")
  • Expect connection to close

TestWebSocketSubscriptionManager (lines 623-748)

• These tests already use @pytest.mark.asyncio and test the manager directly
• No changes needed - they don't use TestClient

TestEdgeCases (lines 750-816)

• Add @pytest.mark.asyncio to all methods
• Convert to async WebSocket clients
• Replace broadcast_sync() with await manager.broadcast()
• Use asyncio.wait_for() for timeout testing

4. Remove Helper Functions

File: file:tests/ui/test_websocket_integration.py

Remove obsolete helper functions:

• Delete broadcast_sync() function (lines 27-59) - no longer needed with real async clients
• Delete get_subscriptions_sync() function (lines 62-64) - use async manager methods directly

5. Update Imports

File: file:tests/ui/test_websocket_integration.py

Update import statements at the top of the file:

• Remove: from fastapi.testclient import TestClient (line 20)
• Add: import websockets (after line 16)
• Add: import json (if not already present)
• Add: import asyncio (if not already present)
• Keep: from codeframe.ui.shared import manager (used in multiple tests)

6. Update Test Timeout Configuration

File: file:pytest.ini

Add timeout configuration for WebSocket tests to prevent hanging:

• Add to addopts section: --timeout=60 (requires pytest-timeout plugin)
• Or add marker: websocket: marks tests as websocket tests with 30s timeout
• Apply marker to all WebSocket test classes with @pytest.mark.websocket

7. Verify Dependencies

File: file:pyproject.toml

Confirm required dependencies are present (they already are):

• websockets>=12.0 (line 31) ✓
• pytest-asyncio>=1.2.0 (line 51) ✓
• Consider adding pytest-timeout>=2.1.0 to dev dependencies for test timeout protection

Architecture Diagram

sequenceDiagram
    participant Test as Test Method
    participant Fixture as running_server Fixture
    participant Server as FastAPI Server (Background Thread)
    participant WSClient as websockets.connect()
    participant Manager as ConnectionManager
    participant Endpoint as WebSocket Endpoint

    Note over Fixture,Server: Test Setup Phase
    Fixture->>Server: Start uvicorn in thread
    Server->>Server: Initialize DB, routes
    Fixture->>Server: Poll /health until ready
    Fixture->>Test: Return ws://localhost:PORT

    Note over Test,Endpoint: Test Execution Phase
    Test->>WSClient: async with websockets.connect()
    WSClient->>Endpoint: WebSocket handshake
    Endpoint->>Manager: await manager.connect(ws)
    Manager-->>Endpoint: Connection accepted
    
    Test->>WSClient: await ws.send(subscribe msg)
    WSClient->>Endpoint: Subscribe to project_id=1
    Endpoint->>Manager: await subscription_manager.subscribe()
    Manager-->>Endpoint: Subscription confirmed
    Endpoint->>WSClient: Send confirmation
    WSClient-->>Test: Receive confirmation

    Test->>Manager: await manager.broadcast(msg, project_id=1)
    Manager->>Manager: Get subscribers for project_id=1
    Manager->>Endpoint: await connection.send_json(msg)
    Endpoint->>WSClient: Send broadcast message
    WSClient-->>Test: await ws.recv() - message received

    Test->>WSClient: Close connection
    WSClient->>Endpoint: WebSocket close
    Endpoint->>Manager: await manager.disconnect(ws)
    Manager->>Manager: Cleanup subscriptions

    Note over Fixture,Server: Test Teardown Phase
    Fixture->>Server: Stop server thread
    Fixture->>Fixture: Cleanup temp directories

Loading

Test Execution Flow

Phase	Action	Component
Setup	Start server in background thread	running_server fixture
	Initialize database with test data	Fixture setup
	Wait for server ready (health check)	Fixture polling
Test	Create async WebSocket connection	websockets.connect()
	Send subscribe/unsubscribe messages	Test method
	Trigger broadcasts via manager	await manager.broadcast()
	Receive and validate messages	await websocket.recv()
Teardown	Close WebSocket connections	Async context manager
	Stop server thread	Fixture cleanup
	Remove temporary files	Fixture cleanup

Key Benefits

• Real Integration Testing: Tests actual WebSocket behavior, not mocked interactions
• Async Compatibility: Eliminates event loop conflicts by using proper async clients
• Production Parity: Tests the same code path that production uses
• No Hanging: Real async operations complete properly without deadlocks
• Better Error Messages: Real WebSocket errors instead of timeout mysteries

Import In IDE

🤖 Prompt for AI Agents

## Observations

The WebSocket integration tests hang because FastAPI's `TestClient` creates synchronous WebSocket sessions in a background thread with its own event loop. When `manager.broadcast()` (an async method) tries to send messages via `await connection.send_json()`, it creates an event loop conflict. The current `broadcast_sync()` helper attempts to bridge this gap by creating a new event loop in a thread, but TestClient's WebSocket objects remain tied to their original event loop and cannot receive async sends. The project already includes `websockets>=12.0` library, making a real WebSocket client solution feasible.

## Approach

Replace FastAPI's `TestClient` WebSocket testing with real async WebSocket clients using the `websockets` library. This involves running the FastAPI server in a background thread during tests and connecting to it with actual WebSocket clients. This approach tests the complete WebSocket stack end-to-end, ensuring broadcasts work correctly in production. All tests will be converted to async (pytest-asyncio is already configured), and a new fixture will manage server lifecycle. The `broadcast_sync()` helper will be removed as it's no longer needed with real async clients.

## Implementation Steps

### 1. Create Server Lifecycle Fixture

**File**: `file:tests/ui/conftest.py` (create new file)

Create a pytest fixture that manages the FastAPI server lifecycle for WebSocket tests:

- Import required modules: `threading`, `uvicorn`, `time`, `pytest`, `asyncio`
- Create `@pytest.fixture(scope="module")` named `running_server` that:
  - Sets up temporary database and workspace directories
  - Configures environment variables (`DATABASE_PATH`, `WORKSPACE_ROOT`, `AUTH_REQUIRED=false`)
  - Initializes database with test user (user_id=1) and test project (project_id=1)
  - Starts uvicorn server in a background thread on a free port (use `socket` to find available port)
  - Waits for server to be ready by polling health endpoint with retries
  - Yields server URL (e.g., `http://localhost:{port}`)
  - On teardown: stops server thread and cleans up temporary directories
- Create helper fixture `@pytest.fixture` named `ws_url` that converts HTTP URL to WebSocket URL (replace `http://` with `ws://`)

### 2. Update Test Client Fixture

**File**: `file:tests/ui/test_websocket_integration.py`

Replace the existing `test_client` fixture (lines 67-127):

- Remove the fixture entirely as it will be replaced by `running_server` and `ws_url` fixtures
- Update all test classes to use `running_server` and `ws_url` fixtures instead
- Remove imports related to `TestClient` (line 20)
- Add import: `import websockets` at the top

### 3. Convert Tests to Async with Real WebSocket Clients

**File**: `file:tests/ui/test_websocket_integration.py`

Transform all test methods to use async WebSocket clients:

#### TestFullSubscriptionWorkflow (lines 130-224)

- Add `@pytest.mark.asyncio` decorator to all test methods
- Change method signatures from `def test_*` to `async def test_*`
- Replace `test_client` parameter with `ws_url` parameter
- In `test_connect_and_subscribe_single_project`:
  - Replace `with test_client.websocket_connect("/ws") as websocket:` with `async with websockets.connect(f"{ws_url}/ws") as websocket:`
  - Replace `websocket.send_json()` with `await websocket.send(json.dumps(...))`
  - Replace `websocket.receive_json()` with `json.loads(await websocket.recv())`
- In `test_receive_filtered_broadcast_after_subscribe`:
  - Use async WebSocket client as above
  - Replace `broadcast_sync()` call with direct `await manager.broadcast()`
  - Import manager: `from codeframe.ui.shared import manager`
- In `test_unsubscribe_stops_receiving_messages`:
  - Use async WebSocket client
  - Replace timeout handling: use `asyncio.wait_for(websocket.recv(), timeout=0.1)` wrapped in try/except `asyncio.TimeoutError`
- In `test_disconnect_cleanup`:
  - Use async context managers for WebSocket connections
  - Replace manual `__enter__/__exit__` with proper async context manager usage

#### TestMultiClientScenario (lines 226-334)

- Add `@pytest.mark.asyncio` to all methods
- Convert to `async def`
- In `test_three_clients_with_independent_subscriptions`:
  - Create 3 async WebSocket connections using `async with websockets.connect()`
  - Use nested async context managers or `asyncio.gather()` for concurrent connections
  - Replace all `send_json/receive_json` with async equivalents
  - Replace `broadcast_sync()` with `await manager.broadcast()`
- In `test_broadcast_isolation_between_projects`:
  - Similar transformations as above
  - Use `asyncio.wait_for()` for timeout testing

#### TestSubscribeUnsubscribeFlow (lines 336-402)

- Add `@pytest.mark.asyncio` to all methods
- Convert to async WebSocket clients
- In `test_subscribe_to_multiple_projects_sequentially`:
  - Use async WebSocket client
  - Access subscriptions via `await manager.subscription_manager.get_subscriptions(websocket)` instead of `get_subscriptions_sync()`
- Apply similar patterns to other tests in this class

#### TestDisconnectCleanup (lines 404-474)

- Add `@pytest.mark.asyncio` to all methods
- Convert to async WebSocket clients
- Replace `get_subscriptions_sync()` calls with async subscription manager methods
- Use proper async context manager cleanup

#### TestBackwardCompatibility (lines 476-555)

- Add `@pytest.mark.asyncio` to all methods
- Convert to async WebSocket clients
- Replace `broadcast_sync()` with `await manager.broadcast()`
- Use `asyncio.wait_for()` for timeout testing

#### TestInvalidMessageHandling (lines 557-621)

- Add `@pytest.mark.asyncio` to all methods (except `test_malformed_json_handling` which expects synchronous disconnect)
- Convert to async WebSocket clients
- In `test_malformed_json_handling`:
  - Use `websockets.exceptions.ConnectionClosed` instead of `WebSocketDisconnect`
  - Send malformed JSON with `await websocket.send("{ invalid json")`
  - Expect connection to close

#### TestWebSocketSubscriptionManager (lines 623-748)

- These tests already use `@pytest.mark.asyncio` and test the manager directly
- No changes needed - they don't use TestClient

#### TestEdgeCases (lines 750-816)

- Add `@pytest.mark.asyncio` to all methods
- Convert to async WebSocket clients
- Replace `broadcast_sync()` with `await manager.broadcast()`
- Use `asyncio.wait_for()` for timeout testing

### 4. Remove Helper Functions

**File**: `file:tests/ui/test_websocket_integration.py`

Remove obsolete helper functions:

- Delete `broadcast_sync()` function (lines 27-59) - no longer needed with real async clients
- Delete `get_subscriptions_sync()` function (lines 62-64) - use async manager methods directly

### 5. Update Imports

**File**: `file:tests/ui/test_websocket_integration.py`

Update import statements at the top of the file:

- Remove: `from fastapi.testclient import TestClient` (line 20)
- Add: `import websockets` (after line 16)
- Add: `import json` (if not already present)
- Add: `import asyncio` (if not already present)
- Keep: `from codeframe.ui.shared import manager` (used in multiple tests)

### 6. Update Test Timeout Configuration

**File**: `file:pytest.ini`

Add timeout configuration for WebSocket tests to prevent hanging:

- Add to `addopts` section: `--timeout=60` (requires pytest-timeout plugin)
- Or add marker: `websocket: marks tests as websocket tests with 30s timeout`
- Apply marker to all WebSocket test classes with `@pytest.mark.websocket`

### 7. Verify Dependencies

**File**: `file:pyproject.toml`

Confirm required dependencies are present (they already are):

- `websockets>=12.0` (line 31) ✓
- `pytest-asyncio>=1.2.0` (line 51) ✓
- Consider adding `pytest-timeout>=2.1.0` to dev dependencies for test timeout protection

## Architecture Diagram

```mermaid
sequenceDiagram
    participant Test as Test Method
    participant Fixture as running_server Fixture
    participant Server as FastAPI Server (Background Thread)
    participant WSClient as websockets.connect()
    participant Manager as ConnectionManager
    participant Endpoint as WebSocket Endpoint

    Note over Fixture,Server: Test Setup Phase
    Fixture->>Server: Start uvicorn in thread
    Server->>Server: Initialize DB, routes
    Fixture->>Server: Poll /health until ready
    Fixture->>Test: Return ws://localhost:PORT

    Note over Test,Endpoint: Test Execution Phase
    Test->>WSClient: async with websockets.connect()
    WSClient->>Endpoint: WebSocket handshake
    Endpoint->>Manager: await manager.connect(ws)
    Manager-->>Endpoint: Connection accepted
    
    Test->>WSClient: await ws.send(subscribe msg)
    WSClient->>Endpoint: Subscribe to project_id=1
    Endpoint->>Manager: await subscription_manager.subscribe()
    Manager-->>Endpoint: Subscription confirmed
    Endpoint->>WSClient: Send confirmation
    WSClient-->>Test: Receive confirmation

    Test->>Manager: await manager.broadcast(msg, project_id=1)
    Manager->>Manager: Get subscribers for project_id=1
    Manager->>Endpoint: await connection.send_json(msg)
    Endpoint->>WSClient: Send broadcast message
    WSClient-->>Test: await ws.recv() - message received

    Test->>WSClient: Close connection
    WSClient->>Endpoint: WebSocket close
    Endpoint->>Manager: await manager.disconnect(ws)
    Manager->>Manager: Cleanup subscriptions

    Note over Fixture,Server: Test Teardown Phase
    Fixture->>Server: Stop server thread
    Fixture->>Fixture: Cleanup temp directories
```

## Test Execution Flow

| Phase | Action | Component |
|-------|--------|-----------|
| **Setup** | Start server in background thread | `running_server` fixture |
| | Initialize database with test data | Fixture setup |
| | Wait for server ready (health check) | Fixture polling |
| **Test** | Create async WebSocket connection | `websockets.connect()` |
| | Send subscribe/unsubscribe messages | Test method |
| | Trigger broadcasts via manager | `await manager.broadcast()` |
| | Receive and validate messages | `await websocket.recv()` |
| **Teardown** | Close WebSocket connections | Async context manager |
| | Stop server thread | Fixture cleanup |
| | Remove temporary files | Fixture cleanup |

## Key Benefits

- **Real Integration Testing**: Tests actual WebSocket behavior, not mocked interactions
- **Async Compatibility**: Eliminates event loop conflicts by using proper async clients
- **Production Parity**: Tests the same code path that production uses
- **No Hanging**: Real async operations complete properly without deadlocks
- **Better Error Messages**: Real WebSocket errors instead of timeout mysteries

---

Execution Information

Branch: main
Commit: 5fe211b

---

💡 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.

[frankbria]

✅ Fixed in commit 168506b

Root Cause

WebSocket integration tests were hanging because they called await manager.broadcast() on the test process's manager instance, while WebSocket clients were connected to a server subprocess with a separate manager instance. Python processes have separate memory spaces, so broadcasts never reached the clients.

Solution

1. Created /test/broadcast API endpoint - Allows tests to trigger broadcasts in the server subprocess via HTTP POST
2. Subprocess-based server fixture - Uses subprocess.Popen for true process isolation instead of threading
3. Real async WebSocket clients - Replaced TestClient's mocked WebSockets with the websockets library
4. HTTP-triggered broadcasts - Tests now call the API endpoint instead of accessing manager directly

Test Results

✅ 4/4 tests passing in TestFullSubscriptionWorkflow:

• test_connect_and_subscribe_single_project
• test_receive_filtered_broadcast_after_subscribe
• test_unsubscribe_stops_receiving_messages
• test_disconnect_cleanup

Files Changed

• codeframe/ui/server.py - Added POST /test/broadcast endpoint
• tests/ui/conftest.py - New file with running_server fixture
• tests/ui/test_websocket_integration.py - Converted to real async clients

The WebSocket tests now properly validate the complete stack end-to-end without hanging!