FluffyLabs / FluffyLabs/pvm-debugger

Add unit tests for useOrchestratorState buffered flush mechanism

Open
#7 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
1
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## Context

The `useOrchestratorState` hook uses a rAF-based buffered flush mechanism to batch rapid-fire orchestrator events into single React state updates. A race condition was discovered and fixed where post-flush event handlers would fall back to a stale `initial` closure, reverting already-loaded PVM states to pre-`loadProgram` defaults. This caused false divergence when enabling/disabling the second PVM.

The fix (adding a `lastFlushedSnapshots` ref) is in place, but the existing E2E tests cannot reliably trigger the race condition since both web workers typically respond within the same animation frame.

## Proposed work

Add unit tests for `useOrchestratorState` that mock `requestAnimationFrame` and orchestrator events to deterministically test:

1. **Post-flush event preservation** — after PVM A's `pvmStateChanged` is flushed via rAF, PVM B's event should build on A's flushed state, not the stale `initial`
2. **Multiple flush cycles** — accumulated state survives across multiple rAF flush boundaries
3. **Orchestrator switch cleanup** — when the orchestrator changes, `lastFlushedSnapshots` and `pendingSnapshots` are properly reset, preventing cross-orchestrator state leakage
4. **Concurrent PVM loading** — simulating `loadProgram` where workers respond at different times across rAF boundaries

## Technical notes

- Vitest's `vi.useFakeTimers()` doesn't mock rAF by default; may need explicit `vi.stubGlobal('requestAnimationFrame', ...)` or `--environment jsdom`
- The hook depends on `OrchestratorContext` — tests will need a mock orchestrator (EventEmitter implementing `OrchestratorEvents`) wrapped in the provider
- Pre-existing issue: many unit tests fail with `document is not defined` due to missing jsdom environment config — fixing that would be a prerequisite

## Related

- Fix commit on branch `td-fix-pvm-disable-diverge`
- File: `apps/web/src/hooks/useOrchestratorState.ts`

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with apps/web/src/hooks/useOrchestratorState.ts and inspect its OrchestratorContext usage, pendingSnapshots, and lastFlushedSnapshots handling. Check the unit-test setup and resolve the noted document is not defined/jsdom prerequisite before mocking requestAnimationFrame and an EventEmitter-style orchestrator. Done means deterministic tests cover post-flush preservation, multiple flush cycles, orchestrator switching, and staggered PVM loading.

Written by the indexing model from the issue text.

Assessment

Tech stack
react, typescript
Domain
frontend, testing
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.