feat(assertions): add CollectionNotNullAssertion for collection null checks with chaining support

[thomhurst]

Fixes #3471

[claude]

Claude finished @thomhurst's task —— View job

---

PR Review: CollectionNotNullAssertion Feature

I've completed my review of this pull request that adds CollectionNotNullAssertion for collection null checks with chaining support.

Todo List:

• Read repository guidelines (CLAUDE.md)
• Analyze the new CollectionNullAssertion class
• Review extension methods and API changes
• Examine test coverage and quality
• Check for potential bugs and performance issues
• Evaluate security considerations
• Provide comprehensive feedback

---

Review Summary

This PR successfully addresses issue #3471 by adding specialized collection null assertion support that preserves type information for proper chaining. The implementation is well-designed and follows TUnit's patterns.

✅ Strengths

1. Code Quality & Design

• Clean, focused implementation that follows existing TUnit patterns
• Proper inheritance from CollectionAssertionBase<TCollection, TItem>
• Excellent XML documentation with clear examples
• Follows modern C# conventions (collection expressions, var usage)

2. Type Safety & API Design

• Brilliant solution to the type inference problem: preserves both TCollection and TItem generics
• Enables fluent chaining: Assert.That(collection).IsNotNull().And.Contains(x => predicate)
• Proper constraint: where TCollection : class, IEnumerable<TItem>
• Returns CollectionNotNullAssertion<TCollection, TItem> for continued collection operations

3. Test Coverage

• Comprehensive tests covering the exact issue scenarios from Contains lambda not compiling when coupled with IsNotNull #3471
• Tests both Dictionary and List scenarios with lambda predicates
• Regression tests ensure the fix works for real-world use cases
• Good edge case coverage with nullable/non-nullable comparisons

4. Documentation & Maintenance

• Snapshots properly updated for all target frameworks (.NET 4.7, 8.0, 9.0, 10.0)
• Clear commit message linking to the issue
• API changes correctly reflected in public API verification files

🔍 Technical Analysis

Performance: ✅ Excellent

• Minimal overhead: simple null check with Task.FromResult
• No unnecessary allocations or reflection
• Follows TUnit's performance-first philosophy

Security: ✅ No concerns

• No security-sensitive operations
• Standard defensive null checking
• No external dependencies

Thread Safety: ✅ Safe

• Stateless assertion class
• Immutable context passing
• No shared mutable state

🧪 Code Implementation Review

The core implementation in CollectionNullAssertion.cs:

protected override Task<AssertionResult> CheckAsync(EvaluationMetadata<TCollection> metadata)
{
    var value = metadata.Value;
    if (value != null)
    {
        return Task.FromResult(AssertionResult.Passed);
    }
    return Task.FromResult(AssertionResult.Failed("value is null"));
}

This is exactly right - simple, efficient, and clear.

The extension method in AssertionExtensions.cs:58-67 is well-designed:

• Proper generic constraints
• Clear type mapping from nullable to non-nullable
• Consistent with existing patterns

📋 Repository Compliance

✅ Follows CLAUDE.md guidelines:

• API snapshots updated correctly
• Modern C# syntax used throughout
• Performance-conscious implementation
• Proper XML documentation
• No reflection or AOT/trimming issues

🎯 Addresses Issue #3471 Perfectly

The implementation directly solves the compilation error described in the issue. Before this fix:

// This failed to compile
await Assert.That(dictionary).IsNotNull().And.Contains(x => x.Key == "key");

After this fix, it works perfectly because IsNotNull() now returns CollectionNotNullAssertion<TCollection, TItem> which maintains the item type information needed for lambda type inference in Contains().

🔄 Minor Suggestions

1. Consider adding ValueTask optimization: The current implementation uses Task.FromResult(). For even better performance, consider using ValueTask<AssertionResult> return type to avoid allocations for synchronous operations.

2. Error message consistency: The error message "value is null" could be more descriptive: "collection is null" to be more specific about what failed.

✅ Final Assessment

This is a high-quality implementation that:

• ✅ Solves the exact problem described in issue Contains lambda not compiling when coupled with IsNotNull #3471
• ✅ Follows all repository guidelines and patterns
• ✅ Has comprehensive test coverage
• ✅ Maintains backward compatibility
• ✅ Has no performance, security, or threading concerns
• ✅ Properly updates API snapshots

Recommendation: Approve and merge - This PR is ready for production.

---