113 lines
5.3 KiB
Markdown
113 lines
5.3 KiB
Markdown
# wait_for_ready_test_pattern_20260605 — Design
|
|
|
|
**Date:** 2026-06-05
|
|
**Status:** Draft
|
|
**Track:** wait_for_ready_test_pattern_20260605 (sub-project of v2)
|
|
|
|
## Problem Statement
|
|
|
|
Two failing live_gui tests use `time.sleep(N)` to wait for asynchronous GUI operations to complete:
|
|
|
|
- `tests/test_workspace_profiles_sim.py` — `time.sleep(2.0)` after save and after load; `time.sleep(1.0)` after each set_value.
|
|
- `tests/test_auto_switch_sim.py` — `time.sleep(1)` after each `push_event`.
|
|
|
|
Fixed sleeps are a fragile test pattern:
|
|
- On slow machines the sleep may be insufficient; the assertion runs before the operation completes.
|
|
- On fast machines the sleep is wasted; the test takes longer than necessary.
|
|
- Tests that pass with `time.sleep(2.0)` in CI may fail on a developer machine with different load.
|
|
|
|
After the state-sync fix (`live_gui_state_sync_20260605`) lands, these tests should pass at the current 2-second sleep. **But the test pattern is still wrong** — the tests should poll for completion, not assume timing.
|
|
|
|
## Design
|
|
|
|
### Approach: Migrate `time.sleep` to a wait-for-ready helper
|
|
|
|
`src/api_hook_client.py` already exposes `wait_for_event(event_type, timeout)` and `get_value(item)`. The tests can use these directly.
|
|
|
|
**Hypothetical example — the current pattern:**
|
|
|
|
```python
|
|
client.set_value('ui_separate_tier1', True)
|
|
time.sleep(1.0)
|
|
client.push_event("custom_callback", {"callback": "save_workspace_profile", "args": ["test_restore", "project"]})
|
|
time.sleep(2.0) # HOPE the save completes within 2s
|
|
client.set_value('ui_separate_tier1', False)
|
|
time.sleep(1.0)
|
|
client.push_event("custom_callback", {"callback": "load_workspace_profile", "args": ["test_restore"]})
|
|
time.sleep(2.0) # HOPE the load completes within 2s
|
|
assert client.get_value('ui_separate_tier1') is True
|
|
```
|
|
|
|
**Migrated pattern:**
|
|
|
|
```python
|
|
def wait_for_save_completion(client, profile_name, timeout=5.0):
|
|
"""Poll until the saved profile appears in the workspace profiles."""
|
|
import time
|
|
deadline = time.time() + timeout
|
|
while time.time() < deadline:
|
|
profiles = client.get_value('workspace_profiles') or {}
|
|
if profile_name in profiles:
|
|
return
|
|
time.sleep(0.1)
|
|
raise TimeoutError(f"Save did not complete within {timeout}s")
|
|
|
|
def wait_for_load_completion(client, item, expected, timeout=5.0):
|
|
"""Poll until the item's value matches expected."""
|
|
import time
|
|
deadline = time.time() + timeout
|
|
while time.time() < deadline:
|
|
if client.get_value(item) == expected:
|
|
return
|
|
time.sleep(0.1)
|
|
raise TimeoutError(f"Load did not apply {item}={expected} within {timeout}s")
|
|
|
|
client.set_value('ui_separate_tier1', True)
|
|
# No sleep needed; set_value returns when the value is set on the controller
|
|
client.push_event("custom_callback", {"callback": "save_workspace_profile", "args": ["test_restore", "project"]})
|
|
wait_for_save_completion(client, "test_restore")
|
|
client.set_value('ui_separate_tier1', False)
|
|
client.push_event("custom_callback", {"callback": "load_workspace_profile", "args": ["test_restore"]})
|
|
wait_for_load_completion(client, 'ui_separate_tier1', True)
|
|
```
|
|
|
|
### Why this approach
|
|
|
|
- **Polling, not fixed sleeps**: 100ms poll interval is responsive without busy-waiting.
|
|
- **Generous timeouts**: 5s default is well over the typical ~100ms operation; catches genuine hangs.
|
|
- **Reusable helpers**: `wait_for_save_completion` and `wait_for_load_completion` are simple and can be added to a shared test helper module.
|
|
- **Failure messages are clear**: TimeoutError explicitly says which operation timed out.
|
|
|
|
### Alternatives considered
|
|
|
|
- **A2: Add wait_for_X helpers to ApiHookClient itself.** Rejected: ApiHookClient should remain a thin transport; test-helper logic doesn't belong there. Keep helpers in `tests/conftest.py` or a `tests/helpers.py` module.
|
|
- **A3: Use `wait_for_event` exclusively.** The Hook API's `wait_for_event` listens for events the GUI emits. save/load may not emit events in a way the test can match. Polling `get_value` is more direct.
|
|
|
|
## File Changes
|
|
|
|
### Modify: `tests/test_workspace_profiles_sim.py`
|
|
|
|
Replace `time.sleep(...)` with `wait_for_save_completion` and `wait_for_load_completion` calls. Add the helper functions at the top of the file (or import from a shared helper).
|
|
|
|
### Modify: `tests/test_auto_switch_sim.py`
|
|
|
|
Replace `time.sleep(...)` with similar polling helpers.
|
|
|
|
### Optionally: Create: `tests/helpers.py`
|
|
|
|
If multiple tests need the same helpers, extract them to a shared module. For now, keep them inline (2 tests, ~30 lines of helpers total).
|
|
|
|
## Risk Assessment
|
|
|
|
| Risk | Likelihood | Impact | Mitigation |
|
|
|---|---|---|---|
|
|
| The polling masks a slow operation that's now flaky | Low | Medium | Generous 5s timeout; if a test times out, the test message points to which operation |
|
|
| Helper functions added in 2 places diverge | Medium | Low | If 3+ tests need the same helper, extract to `tests/helpers.py` |
|
|
|
|
## Out of Scope
|
|
|
|
- **State sync fix** — separate track (`live_gui_state_sync_20260605`).
|
|
- **prior_session test** — separate track (`prior_session_test_harden_20260605`).
|
|
- **Migrating other live_gui tests that use `time.sleep`** — out of scope for now. Track as a follow-up if more flakes appear.
|
|
- **Replacing `time.sleep` with `asyncio.sleep`** — out of scope; the live_gui tests are sync, and the GUI event queue is sync.
|