feat: add WaitsFor assertion for polling asynchronous conditions

[thomhurst]

Fixes #2984

[claude]

Claude finished @thomhurst's task —— View job

---

Pull Request Review: WaitsFor Assertion

I've completed a comprehensive review of the WaitsFor assertion implementation. Here's my detailed feedback:

✅ Excellent Code Quality

Strengths:

• Well-architected: The implementation properly leverages the existing assertion framework with EvaluationContext<T>.ReevaluateAsync() for polling
• Comprehensive error handling: Validates arguments, handles timeouts gracefully, and provides meaningful error messages
• Thread-safe: Uses CancellationTokenSource properly and doesn't introduce race conditions
• Performance-optimized: Efficient polling with configurable intervals and early exit on success
• Excellent test coverage: 13 comprehensive tests covering happy paths, edge cases, error conditions, and real-world scenarios

API Design:

• Follows TUnit's fluent assertion patterns consistently
• Supports method chaining with .And and .Or operations
• Intuitive parameter naming and optional polling interval
• Good use of CallerArgumentExpression for debugging

🔧 Technical Implementation

Architecture Compliance:

• ✅ Properly uses existing EvaluationContext<T>.ReevaluateAsync() method
• ✅ Integrates seamlessly with the assertion framework
• ✅ Follows established error handling patterns
• ✅ API snapshots correctly updated for all target frameworks

Performance Considerations:

• ✅ Efficient polling loop with Stopwatch for accurate timing
• ✅ Default 10ms polling interval is reasonable for most scenarios
• ✅ Early exit when assertion passes (no unnecessary waiting)
• ✅ Proper resource cleanup with using statements

🛡️ Security & Safety

Thread Safety:

• ✅ No shared mutable state between assertion instances
• ✅ Proper use of CancellationToken for timeout handling
• ✅ No deadlock potential in the polling loop

Error Handling:

• ✅ Validates timeout and polling interval are positive
• ✅ Graceful handling of assertion exceptions during polling
• ✅ Clear error messages with attempt counts and timing information

📋 Test Coverage Analysis

Comprehensive Test Suite:

• ✅ Immediate success: Verifies no unnecessary waiting when assertion passes immediately
• ✅ Retry logic: Tests multiple polling attempts until success
• ✅ Timeout handling: Confirms timeout is respected and provides useful error messages
• ✅ Chaining support: Validates .And and .Or continuation work correctly
• ✅ Custom intervals: Tests configurable polling intervals
• ✅ Real-world scenarios: GPIO event simulation and async state changes
• ✅ Edge cases: Validates argument validation (null, zero, negative values)
• ✅ Performance: Tests with high-frequency polling (100+ attempts)

🚨 Minor Observations

1. String manipulation in error messages (TUnit.Assertions/Conditions/WaitsForAssertion.cs:104):

   var atIndex = message.IndexOf("\nat Assert.That", StringComparison.Ordinal);

   This string parsing is brittle and may break with future changes to assertion error formatting. Consider a more robust approach.

2. Performance: The default 10ms polling interval is appropriate for most cases, but developers might appreciate guidance on when to adjust it.

✅ Repository Guidelines Compliance

• ✅ Modern C# syntax: Uses collection expressions, proper async/await patterns
• ✅ Code style: Follows TUnit's naming conventions and formatting
• ✅ No dual-mode concerns: This is purely assertion library code (no source generator impact)
• ✅ AOT compatibility: No reflection usage, works with trimming

🎯 Overall Assessment

This is a high-quality implementation that adds valuable functionality to TUnit's assertion library. The code is well-architected, thoroughly tested, and follows established patterns. It addresses a real need for polling assertions in asynchronous testing scenarios.

Recommendation: ✅ APPROVE

The implementation is production-ready and aligns with TUnit's design philosophy of being "fast, modern, reliable, and enjoyable to use." The only minor concern about string parsing in error messages doesn't affect functionality and can be addressed in future iterations if needed.

---

[claude]

Claude finished @thomhurst's task —— View job

---

Pull Request Review: WaitsFor Assertion Implementation

I've conducted a comprehensive review of the WaitsFor assertion implementation. Here's my detailed assessment:

✅ Excellent Implementation Quality

Architecture & Design

• Perfect integration: Leverages existing EvaluationContext<T>.ReevaluateAsync() method for polling—excellent architectural decision
• Clean API: Follows TUnit's fluent assertion patterns with intuitive method chaining
• Type safety: Proper generic constraints and return types throughout
• Consistent patterns: Matches existing assertion conventions in the codebase

Code Quality

• Modern C# syntax: Uses collection expressions, proper async/await patterns, and using statements
• Robust error handling: Comprehensive validation for timeout, polling interval, and null parameters
• Performance optimized: Efficient polling loop with Stopwatch and early exit on success
• Clean separation: Well-organized with clear responsibilities between classes

📋 Comprehensive Test Coverage

The test suite covers all critical scenarios:

• ✅ Immediate success (no unnecessary waiting)
• ✅ Retry logic (multiple polling attempts)
• ✅ Timeout handling (fails gracefully with useful error messages)
• ✅ Chaining support (.And and .Or continuation)
• ✅ Custom intervals (configurable polling frequency)
• ✅ Real-world scenarios (GPIO event simulation, async state changes)
• ✅ Edge cases (argument validation, performance with 100+ attempts)
• ✅ Thread safety (proper use of Interlocked operations)

🔧 Technical Implementation

Strengths:

• Thread-safe design: No shared mutable state, proper CancellationToken usage
• Resource management: Correct using statements and cleanup
• Error messaging: Detailed failure messages with attempt counts and timing
• API Surface: Properly updated across all target frameworks (.NET 4.7, 8.0, 9.0, 10.0)
• Integration: Uses CallerArgumentExpression for excellent debugging experience

Performance Considerations:

• ✅ Default 10ms polling interval is reasonable
• ✅ Efficient polling loop with minimal allocations
• ✅ Early exit prevents unnecessary waiting
• ✅ Stopwatch provides accurate timing measurements

🛡️ Security & Safety

Thread Safety:

• ✅ No race conditions or deadlock potential
• ✅ Proper cancellation token usage
• ✅ Safe concurrent access patterns

Error Handling:

• ✅ Validates all input parameters
• ✅ Graceful timeout handling
• ✅ Meaningful error messages with context

🎯 Repository Compliance

TUnit Guidelines:

• ✅ Dual-mode compatibility: This is assertion library code only—no source generator concerns
• ✅ AOT/Trimming compatible: No reflection usage, works with trimming
• ✅ Performance first: Optimized polling with minimal overhead
• ✅ Modern C# patterns: Uses recommended syntax and conventions
• ✅ API snapshots: Correctly updated for all target frameworks

🚨 Minor Observations

1. String parsing brittleness (WaitsForAssertion.cs:104):

   var atIndex = message.IndexOf("\nat Assert.That", StringComparison.Ordinal);

   This approach to cleaning error messages is fragile and could break with assertion framework changes. Consider a more robust approach or document the dependency.

2. Documentation: The XML documentation is excellent and comprehensive.

📊 Overall Assessment

This implementation demonstrates exceptional quality and addresses a real need for polling assertions in asynchronous testing scenarios. The code is:

• Well-architected with proper integration into existing framework
• Thoroughly tested with comprehensive edge case coverage
• Performance-optimized for production use
• Thread-safe and resource-conscious
• Follows all repository guidelines and conventions

Recommendation: ✅ APPROVE

This is a high-quality implementation that adds valuable functionality while maintaining TUnit's standards for being "fast, modern, reliable, and enjoyable to use." The only minor concern about string parsing doesn't affect core functionality and can be addressed in future iterations if needed.

The implementation successfully addresses issue #2984 and provides a robust solution for testing asynchronous state changes that's commonly needed in modern testing scenarios.

---