fix(core-backend): control randomness to fix flaky test

[Kriys94]

Explanation

Current State

The BackendWebSocketService tests were experiencing flakiness after introducing the new ExponentialBackoff logic using Cockatiel. The random jitter in the exponential backoff algorithm was causing non-deterministic test behavior, particularly in tests that relied on precise timing control with jest.advanceTimersByTime().

Symptoms:

• Tests would randomly fail with state mismatches (e.g., expecting "error" but receiving "connecting")
• Reconnection attempt counts would be inconsistent
• Coverage would fluctuate between runs (sometimes 99.39%, sometimes 100%)
• Specific lines (456, 552-553) would intermittently miss coverage

Solution

This PR fixes all flaky tests by making the exponential backoff behavior deterministic and adjusting test timing to prevent race conditions.

1. Added Math.random() Mock to 9 Tests

Mocked Math.random() to return 0 in tests that involve reconnection logic. This ensures Cockatiel's exponential backoff delays are predictable and consistent across test runs:

• should handle abnormal WebSocket close by triggering reconnection
• should reset reconnect attempts after stable connection
• should skip connect when reconnect timer is already scheduled
• should handle WebSocket onclose during connection phase
• should clear connection timeout in handleClose when timeout occurs then close fires
• should not schedule multiple reconnects when scheduleReconnect called multiple times
• should force reconnection and schedule connect
• should skip forceReconnection when reconnect timer is already scheduled
• should stop reconnection when isEnabled returns false during scheduled reconnect

2. Timing Adjustments to Prevent Race Conditions

Changed completeAsyncOperations(10) to completeAsyncOperations(0) in 6 tests to check state immediately after operations without allowing timers to execute prematurely:

• should handle WebSocket onclose during connection phase - After simulateClose
• should clear connection timeout in handleClose when timeout occurs then close fires - After manual close trigger
• should not schedule multiple reconnects when scheduleReconnect called multiple times - After both close events
• should force reconnection and schedule connect - After forceReconnection call
• should skip forceReconnection when reconnect timer is already scheduled - After simulateError
• should skip connect when reconnect timer is already scheduled - After simulateClose

3. Coverage Stability

Fixed intermittent coverage issues for:

• Line 456: Early return in connect() when reconnect timer is already scheduled
• Lines 552-553: Early return in forceReconnection() when reconnect timer is already scheduled

These lines are now consistently covered by ensuring reconnect timers remain scheduled during assertions.

Technical Details

Exponential Backoff with Jitter:

• Cockatiel uses Math.random() to add jitter to prevent thundering herd problems
• Without mocking, delays vary unpredictably: e.g., 500ms could become 250-750ms
• With Math.random() = 0, delays are deterministic and tests can advance time precisely

Timing Philosophy:

• completeAsyncOperations(0): Flush promises only, no time advancement
• Used when we want to check state immediately after scheduling timers
• Prevents race conditions where timers execute before assertions run

Testing

Verified stability with extensive testing:

• Individual flaky tests run 100 times each: ✅ All passed
• Full test suite run 100 times: ✅ Consistent 100% coverage
• All tests pass reliably without flakiness

References

• Related to ExponentialBackoff implementation in BackendWebSocketService
• Ensures reliable CI/CD test execution
• Fixes intermittent test failures that were blocking development

Checklist

• I've updated the test suite for new or updated code as appropriate
• I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
• I've communicated my changes to consumers by updating changelogs for packages I've changed, highlighting breaking changes as necessary
• I've prepared draft pull requests for clients and consumer packages to resolve any breaking changes

---

Note

Stabilizes BackendWebSocketService reconnection tests by mocking Math.random jitter and using immediate async flushing to avoid timer races, with minor state/idempotency assertions added.

• Tests (packages/core-backend/src/BackendWebSocketService.test.ts)
  • Mock Math.random() to 0 in reconnection-related tests to make Cockatiel backoff jitter deterministic.
  • Replace completeAsyncOperations(10) with completeAsyncOperations(0) where assertions must occur before timers run (e.g., after simulateClose/simulateError, post-forceReconnection).
  • Add targeted assertions and checks:
    • Verify CONNECTING state during connection-phase close handling.
    • Ensure early-return/idempotency when reconnect timer exists (connect/forceReconnection, multiple scheduleReconnect calls).
  • Result: deterministic timing, eliminated flakiness, stable reconnect attempt counts and coverage.

^{Written by Cursor Bugbot for commit 6333eda. This will update automatically on new commits. Configure here.}

[cursor]

Bug: WebSocket Test Flakiness Due to Timer Advancement

The 'should handle WebSocket onclose during connection phase' test advances timers by 10ms before asserting the CONNECTING state. This introduces a race condition, as the connection could progress beyond CONNECTING during this time, leading to flakiness and undermining the PR's goal of deterministic timing.