feat(async): add async mapping support in AssertionContext and EvaluationContext

[thomhurst]

Fixes #3605

[claude]

Claude finished @thomhurst's task —— View job

---

Pull Request Review

Reviewing PR #3606: feat(async): add async mapping support in AssertionContext and EvaluationContext

Review Tasks:

• Analyze new AsyncMapTests.cs for test coverage and quality
• Review changes to AssertionContext.cs
• Review changes to EvaluationContext.cs
• Check documentation updates
• Assess code quality, performance, and security
• Verify adherence to TUnit standards

---

Overall Assessment: ✅ APPROVED WITH MINOR SUGGESTIONS

This is a well-implemented feature that adds async mapping support to TUnit's assertion system. The implementation follows established patterns and maintains consistency with the existing codebase.

Code Quality Analysis

✅ Strengths

1. Clean API Design: The async mapping functionality integrates seamlessly with existing patterns

   • context.Map<TNew>(async value => await transformAsync(value)) is intuitive
   • Maintains the same fluent chaining experience

2. Proper Exception Handling: Both AssertionContext.cs:87-90 and EvaluationContext.cs:109-129 correctly wrap async operations in try-catch blocks and propagate exceptions properly

3. Comprehensive Test Coverage: The test file covers multiple scenarios:

   • Real-world HTTP/JSON parsing (Map_WithAsyncMapper_HttpResponseExample)
   • Simple async transformations (Map_WithAsyncMapper_ComplexObjectTransformation)
   • Exception propagation (Map_WithAsyncMapper_PropagatesExceptions)
   • Mixed sync/async usage (Map_WithAsyncMapper_SyncCode)

4. Documentation Updated: The extensibility docs now properly document async mapping with practical examples

5. Follows TUnit Patterns: Uses ValueTask, proper exception handling, and maintains the evaluation context design

🔍 Areas for Improvement

Minor Issues

1. Test Method Naming (AsyncMapTests.cs:61):

   public async Task Map_WithAsyncMapper_SyncCode()

   This test name is confusing - it suggests sync code but tests async mapping. Consider renaming to Map_WithAsyncMapper_WorksForSyncOperations or similar.

2. Minimal Async Work in Test (AsyncMapTests.cs:144):

   await Task.Delay(1); // Simulate async work

   While functional, this could be more realistic. Consider using Task.FromResult() or a more meaningful async operation.

Performance Considerations

3. Task Wrapping Overhead: The async mapping always creates a Task even for simple transformations. This is acceptable given the design, but worth noting for high-frequency scenarios.

4. No Cancellation Token Support: The async mappers don't accept CancellationToken. Consider if this should be added for long-running async operations, though it may complicate the API.

🔒 Security & Robustness

• ✅ Exception Safety: Proper exception handling prevents swallowed errors
• ✅ No Security Concerns: The code doesn't expose sensitive data or create security vulnerabilities
• ✅ Null Safety: Proper null handling throughout

📊 Architecture Compliance

• ✅ Follows TUnit Patterns: Maintains consistency with existing Map() overloads
• ✅ Single Responsibility: Each method has a clear, focused purpose
• ✅ Immutability: Evaluation contexts are properly immutable
• ✅ Async/Await Best Practices: Proper use of async/await patterns

Test Coverage Assessment

The test coverage is solid but could be enhanced:

✅ Well Covered

• Basic async mapping functionality
• Exception propagation during mapping
• Integration with assertion chaining
• Real-world scenarios (HTTP/JSON)

🔄 Could Add (Optional)

• Edge cases with null values during async mapping
• Performance characteristics with deeply nested async chains
• Concurrent async mapping scenarios

Final Recommendation

This PR successfully adds async mapping support while maintaining TUnit's design principles. The implementation is clean, well-tested, and follows established patterns. The minor suggestions above are not blockers.

Recommended Actions:

1. ✅ Merge after addressing the test naming issue (optional but recommended)
2. 📝 Consider the cancellation token question for future iterations
3. 🧪 The current test coverage is adequate for the initial implementation

The feature will enable powerful scenarios like the HTTP response parsing example and maintains TUnit's excellent developer experience.

---

[claude]

Claude finished @thomhurst's task —— View job

---

Pull Request Review

Reviewing PR #3606: feat(async): add async mapping support in AssertionContext and EvaluationContext

Review Tasks:

• Read TUnit development guidelines from CLAUDE.md
• Analyze new AsyncMapTests.cs for test coverage and quality
• Review changes to AssertionContext.cs
• Review changes to EvaluationContext.cs
• Check documentation updates
• Assess code quality, performance, and security
• Verify adherence to TUnit standards

---

Overall Assessment: ✅ APPROVED WITH MINOR SUGGESTIONS

This is a well-implemented feature that adds async mapping support to TUnit's assertion system. The implementation follows established patterns and maintains consistency with the existing codebase.

Code Quality Analysis

✅ Strengths

1. Clean API Design: The async mapping functionality integrates seamlessly with existing patterns

   • context.Map<TNew>(async value => await transformAsync(value)) is intuitive
   • Maintains the same fluent chaining experience

2. Proper Exception Handling: Both AssertionContext.cs:87-90 and EvaluationContext.cs:109-129 correctly wrap async operations in try-catch blocks and propagate exceptions properly

3. Comprehensive Test Coverage: The test file covers multiple scenarios:

   • Real-world HTTP/JSON parsing (Map_WithAsyncMapper_HttpResponseExample)
   • Simple async transformations (Map_WithAsyncMapper_ComplexObjectTransformation)
   • Exception propagation (Map_WithAsyncMapper_PropagatesExceptions)
   • Mixed sync/async usage (Map_WithAsyncMapper_SyncCode)

4. Documentation Updated: The extensibility docs now properly document async mapping with practical examples

5. Follows TUnit Patterns: Uses ValueTask, proper exception handling, and maintains the evaluation context design

🔍 Areas for Improvement

Minor Issues

1. Test Method Naming (AsyncMapTests.cs:61):

   public async Task Map_WithAsyncMapper_SyncCode()

   This test name is confusing - it suggests sync code but tests async mapping. Consider renaming to Map_WithAsyncMapper_WorksForSyncOperations or similar.

2. Minimal Async Work in Test (AsyncMapTests.cs:144):

   await Task.Delay(1); // Simulate async work

   While functional, this could be more realistic. Consider using Task.FromResult() or a more meaningful async operation.

Performance Considerations

3. Task Wrapping Overhead: The async mapping always creates a Task even for simple transformations. This is acceptable given the design, but worth noting for high-frequency scenarios.

4. No Cancellation Token Support: The async mappers don't accept CancellationToken. Consider if this should be added for long-running async operations, though it may complicate the API.

🔒 Security & Robustness

• ✅ Exception Safety: Proper exception handling prevents swallowed errors
• ✅ No Security Concerns: The code doesn't expose sensitive data or create security vulnerabilities
• ✅ Null Safety: Proper null handling throughout

📊 Architecture Compliance

• ✅ Follows TUnit Patterns: Maintains consistency with existing Map() overloads
• ✅ Single Responsibility: Each method has a clear, focused purpose
• ✅ Immutability: Evaluation contexts are properly immutable
• ✅ Async/Await Best Practices: Proper use of async/await patterns

Test Coverage Assessment

The test coverage is solid but could be enhanced:

✅ Well Covered

• Basic async mapping functionality
• Exception propagation during mapping
• Integration with assertion chaining
• Real-world scenarios (HTTP/JSON)

🔄 Could Add (Optional)

• Edge cases with null values during async mapping
• Performance characteristics with deeply nested async chains
• Concurrent async mapping scenarios

TUnit Standards Compliance

✅ Follows CLAUDE.md Guidelines:

• Rule 4 - Performance: Uses proper async patterns, minimal allocations
• Code Style: Modern C# syntax, proper naming conventions
• Public API: Snapshots properly updated across all .NET versions
• Documentation: Extensibility guide updated with async examples

Final Recommendation

This PR successfully adds async mapping support while maintaining TUnit's design principles. The implementation is clean, well-tested, and follows established patterns. The minor suggestions above are not blockers.

Recommended Actions:

1. ✅ Merge after addressing the test naming issue (optional but recommended)
2. 📝 Consider the cancellation token question for future iterations
3. 🧪 The current test coverage is adequate for the initial implementation

The feature will enable powerful scenarios like the HTTP response parsing example and maintains TUnit's excellent developer experience.

---

[claude]

Claude finished @thomhurst's task —— View job

---

Pull Request Review

Reviewing PR #3606: feat(async): add async mapping support in AssertionContext and EvaluationContext

Review Tasks:

• Read TUnit development guidelines from CLAUDE.md
• Analyze new AsyncMapTests.cs for test coverage and quality
• Review changes to AssertionContext.cs
• Review changes to EvaluationContext.cs
• Check documentation updates
• Assess code quality, performance, and security
• Verify adherence to TUnit standards

---

Overall Assessment: ✅ APPROVED WITH MINOR SUGGESTIONS

This is a well-implemented feature that adds async mapping support to TUnit's assertion system. The implementation follows established patterns and maintains consistency with the existing codebase.

Code Quality Analysis

✅ Strengths

1. Clean API Design: The async mapping functionality integrates seamlessly with existing patterns

   • context.Map<TNew>(async value => await transformAsync(value)) is intuitive
   • Maintains the same fluent chaining experience

2. Proper Exception Handling: Both AssertionContext.cs:87-90 and EvaluationContext.cs:109-129 correctly wrap async operations in try-catch blocks and propagate exceptions properly

3. Comprehensive Test Coverage: The test file covers multiple scenarios:

   • Real-world HTTP/JSON parsing (Map_WithAsyncMapper_HttpResponseExample)
   • Simple async transformations (Map_WithAsyncMapper_ComplexObjectTransformation)
   • Exception propagation (Map_WithAsyncMapper_PropagatesExceptions)
   • Mixed sync/async usage (Map_WithAsyncMapper_SyncCode)

4. Documentation Updated: The extensibility docs now properly document async mapping with practical examples

5. Follows TUnit Patterns: Uses ValueTask, proper exception handling, and maintains the evaluation context design

🔍 Areas for Improvement

Minor Issues

1. Test Method Naming (AsyncMapTests.cs:61):

   public async Task Map_WithAsyncMapper_SyncCode()

   This test name is confusing - it suggests sync code but tests async mapping. Consider renaming to Map_WithAsyncMapper_WorksForSyncOperations or similar.

2. Minimal Async Work in Test (AsyncMapTests.cs:144):

   await Task.Delay(1); // Simulate async work

   While functional, this could be more realistic. Consider using Task.FromResult() or a more meaningful async operation.

Performance Considerations

3. Task Wrapping Overhead: The async mapping always creates a Task even for simple transformations. This is acceptable given the design, but worth noting for high-frequency scenarios.

4. No Cancellation Token Support: The async mappers don't accept CancellationToken. Consider if this should be added for long-running async operations, though it may complicate the API.

🔒 Security & Robustness

• ✅ Exception Safety: Proper exception handling prevents swallowed errors
• ✅ No Security Concerns: The code doesn't expose sensitive data or create security vulnerabilities
• ✅ Null Safety: Proper null handling throughout

📊 Architecture Compliance

• ✅ Follows TUnit Patterns: Maintains consistency with existing Map() overloads
• ✅ Single Responsibility: Each method has a clear, focused purpose
• ✅ Immutability: Evaluation contexts are properly immutable
• ✅ Async/Await Best Practices: Proper use of async/await patterns

Test Coverage Assessment

The test coverage is solid but could be enhanced:

✅ Well Covered

• Basic async mapping functionality
• Exception propagation during mapping
• Integration with assertion chaining
• Real-world scenarios (HTTP/JSON)

🔄 Could Add (Optional)

• Edge cases with null values during async mapping
• Performance characteristics with deeply nested async chains
• Concurrent async mapping scenarios

TUnit Standards Compliance

✅ Follows CLAUDE.md Guidelines:

• Rule 4 - Performance: Uses proper async patterns, minimal allocations
• Code Style: Modern C# syntax, proper naming conventions
• Public API: Snapshots properly updated across all .NET versions
• Documentation: Extensibility guide updated with async examples

Final Recommendation

This PR successfully adds async mapping support while maintaining TUnit's design principles. The implementation is clean, well-tested, and follows established patterns. The minor suggestions above are not blockers.

Recommended Actions:

1. ✅ Merge after addressing the test naming issue (optional but recommended)
2. 📝 Consider the cancellation token question for future iterations
3. 🧪 The current test coverage is adequate for the initial implementation

The feature will enable powerful scenarios like the HTTP response parsing example and maintains TUnit's excellent developer experience.

---