Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

Docs: Improve test polling guidelines for CI reliability

Maximilian Roos61e4793a5cb0
diff --git a/CLAUDE.md b/CLAUDE.md
index 77e17b6c3..35fd7d486 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -519,9 +519,33 @@ Users can clean up old logs manually or use a git hook. No automatic cleanup is
## Testing Guidelines
-### Timing Tests: Poll with Long Timeouts
+### Timing Tests: Long Timeouts with Fast Polling
-Tests waiting for background operations must **poll with long timeouts**, never use fixed sleeps. Use the helpers in `tests/common/mod.rs`:
+**Core principle:** Use long timeouts (5+ seconds) for reliability on slow CI, but poll frequently (10-50ms) so tests complete quickly when things work.
+
+This achieves both goals:
+- **No flaky failures** on slow machines - generous timeout accommodates worst-case
+- **Fast tests** on normal machines - frequent polling means no unnecessary waiting
+
+```rust
+// ✅ GOOD: Long timeout, fast polling
+let timeout = Duration::from_secs(5);
+let poll_interval = Duration::from_millis(10);
+let start = Instant::now();
+while start.elapsed() < timeout {
+ if condition_met() { break; }
+ thread::sleep(poll_interval);
+}
+
+// ❌ BAD: Fixed sleep (always slow, might still fail)
+thread::sleep(Duration::from_millis(500));
+assert!(condition_met());
+
+// ❌ BAD: Short timeout (flaky on slow CI)
+let timeout = Duration::from_millis(100);
+```
+
+Use the helpers in `tests/common/mod.rs`:
```rust
use crate::common::{wait_for_file, wait_for_file_count};
diff --git a/tests/common/progressive_output.rs b/tests/common/progressive_output.rs
index 7a6441bbd..dad53a79d 100644
--- a/tests/common/progressive_output.rs
+++ b/tests/common/progressive_output.rs
@@ -104,10 +104,12 @@ use portable_pty::{CommandBuilder, PtySize, native_pty_system};
use std::io::Read;
use std::time::{Duration, Instant};
-/// Time to wait for final output to flush after child process exits
-const FINAL_OUTPUT_FLUSH_MS: u64 = 50;
+/// Maximum time to spend draining remaining PTY data after child exits.
+/// Long timeout ensures reliability on slow CI; fast polling ensures quick completion.
+const FINAL_DRAIN_TIMEOUT_MS: u64 = 5000;
-/// Polling interval when waiting for output or child process exit
+/// Polling interval when waiting for output or child process exit.
+/// Short interval ensures tests complete quickly when data is available.
const OUTPUT_POLL_INTERVAL_MS: u64 = 10;
/// Strategy for capturing progressive output snapshots
@@ -425,10 +427,10 @@ pub fn capture_progressive_output(
Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => {
// Check if child exited
if let Ok(Some(_)) = child.try_wait() {
- // Give it a moment to flush final output
- std::thread::sleep(Duration::from_millis(FINAL_OUTPUT_FLUSH_MS));
-
- // Read any remaining data
+ // Drain remaining PTY data with long timeout but fast polling.
+ // Long timeout (5s) ensures reliability on slow CI machines.
+ // Fast polling (10ms) ensures quick completion when data is available.
+ let drain_start = Instant::now();
loop {
match reader.read(&mut temp_buf) {
Ok(0) => break,
@@ -436,6 +438,15 @@ pub fn capture_progressive_output(
total_bytes += n;
parser.process(&temp_buf[..n]);
}
+ Err(e) if e.kind() == std::io::ErrorKind::WouldBlock => {
+ // PTY may still have buffered data; retry with timeout
+ if drain_start.elapsed()
+ > Duration::from_millis(FINAL_DRAIN_TIMEOUT_MS)
+ {
+ break;
+ }
+ std::thread::sleep(Duration::from_millis(OUTPUT_POLL_INTERVAL_MS));
+ }
Err(_) => break,
}
}