feat: add more regex assertions

[thomhurst]

No description provided.

[claude]

Claude finished @thomhurst's task —— View job

---

Code Review Complete ✅

Todo List:

• Read repository guidelines (CLAUDE.md)
• Analyze the RegexMatchResult class implementation
• Review StringMatchesAssertionExtensions
• Examine test coverage and quality
• Check StringAssertions.cs modifications
• Review public API changes
• Assess documentation quality
• Provide comprehensive feedback on code quality, bugs, performance, security, and test coverage

---

Overall Assessment

This PR successfully adds robust regex assertion capabilities to TUnit with proper match result access. The implementation follows TUnit's coding standards and performance requirements well.

✅ Strengths

Code Quality & Design

• Clean API design: The fluent await Assert.That(text).Matches(pattern).GetMatchAsync() pattern is intuitive and follows TUnit's existing conventions
• Proper encapsulation: RegexMatchResult class appropriately wraps System.Text.RegularExpressions.Match with validation
• Thread-safe: The implementation doesn't introduce shared mutable state
• AOT-compatible: Uses direct method calls instead of reflection, following TUnit's AOT/trimming requirements

Performance Considerations

• Match caching: StringMatchesAssertion now caches the Match object (line 433 in StringAssertions.cs:494), avoiding duplicate regex execution
• Lazy evaluation: Match execution only happens during assertion, not during setup
• No unnecessary allocations: Reuses existing Match object from .NET's regex engine

Test Coverage

• Comprehensive test suite: RegexMatchResultTests.cs covers all key scenarios:
  • Named groups (Group("username"))
  • Indexed groups (Group(1))
  • Match properties (Index, Length, Value)
  • Case-insensitive matching
  • Error conditions (invalid group names/indices)

Security & Robustness

• Input validation: Proper argument validation in RegexMatchResult.Group() methods
• Error handling: Clear exception messages for invalid group access
• Regex validation: The pattern is validated by creating a Regex object before null-checking the input

🔍 Areas for Improvement

Minor Issues

1. Exception Ordering (StringAssertions.cs:484-491)

The current implementation validates regex before checking null input:

var regex = _regex ?? new Regex(_pattern, _options);  // May throw RegexParseException
if (value == null)  // Check comes after regex validation
{
    throw new ArgumentNullException(nameof(value), "value was null");
}

Impact: Low - This is likely intentional based on the comment, but could be confusing.

2. Documentation Gap

The documentation in docs/docs/assertions/regex-assertions.md shows examples using .Group() and .AtIndex() methods that don't exist yet:

// This doesn't match the actual API:
await Assert.That(email)
    .Matches(pattern)
    .Group("username", user => user.IsEqualTo("john.doe"))  // This doesn't exist

The actual API is:

var match = await Assert.That(email).Matches(pattern).GetMatchAsync();
await Assert.That(match.Group("username")).IsEqualTo("john.doe");

3. Missing using statement (RegexMatchResult.cs:14)

The ArgumentNullException is used but System namespace isn't explicitly imported. This works due to global usings but could be made explicit for clarity.

📋 Repository Compliance

✅ Follows TUnit Guidelines

• Dual-mode compatibility: ✅ This is assertions-only, no source generator changes needed
• Performance-first: ✅ Efficient match caching implementation
• Modern C# syntax: ✅ Uses nullable references, collection expressions where appropriate
• Public API snapshots: ✅ All .verified.txt files properly updated across all target frameworks

✅ Testing Standards

• Comprehensive coverage: Tests cover happy path, edge cases, and error conditions
• Follows TUnit patterns: Uses async/await properly with Assert.That() syntax
• Good test naming: Descriptive test method names clearly indicate what's being tested

🚀 Recommendations

High Priority

1. Update documentation to match the actual API - either implement the fluent .Group() methods shown in docs, or update docs to show the current GetMatchAsync() approach

Low Priority

2. Consider adding explicit using System; to RegexMatchResult.cs for clarity
3. Consider documenting the exception ordering rationale in StringMatchesAssertion if intentional

🎯 Verdict

Recommend approval with documentation updates. This is a well-implemented feature that:

• Adds valuable functionality for regex assertion scenarios
• Follows TUnit's performance and design principles
• Has excellent test coverage
• Maintains AOT/trimming compatibility
• Properly updates public API snapshots

The only significant issue is the documentation mismatch, which should be addressed before merge.

---

[claude]

Claude finished @thomhurst's task —— View job

---

Code Review Complete ✅

Todo List:

• Read repository guidelines (CLAUDE.md)
• Analyze the RegexMatchResult class implementation
• Review StringMatchesAssertionExtensions
• Examine test coverage and quality
• Check StringAssertions.cs modifications
• Review public API changes
• Assess documentation quality
• Provide comprehensive feedback on code quality, bugs, performance, security, and test coverage

---

Overall Assessment

This PR successfully adds robust regex assertion capabilities to TUnit with proper match result access. The implementation follows TUnit's coding standards and performance requirements well.

✅ Strengths

Code Quality & Design

• Clean API design: The fluent await Assert.That(text).Matches(pattern).GetMatchAsync() pattern is intuitive and follows TUnit's existing conventions
• Proper encapsulation: RegexMatchResult class appropriately wraps System.Text.RegularExpressions.Match with validation
• Thread-safe: The implementation doesn't introduce shared mutable state
• AOT-compatible: Uses direct method calls instead of reflection, following TUnit's AOT/trimming requirements

Performance Considerations

• Match caching: StringMatchesAssertion now caches the Match object (TUnit.Assertions/Conditions/StringAssertions.cs:494), avoiding duplicate regex execution
• Lazy evaluation: Match execution only happens during assertion, not during setup
• No unnecessary allocations: Reuses existing Match object from .NET's regex engine

Test Coverage

• Comprehensive test suite: RegexMatchResultTests.cs covers all key scenarios:
  • Named groups (Group("username"))
  • Indexed groups (Group(1))
  • Match properties (Index, Length, Value)
  • Case-insensitive matching
  • Error conditions (invalid group names/indices)

Security & Robustness

• Input validation: Proper argument validation in RegexMatchResult.Group() methods
• Error handling: Clear exception messages for invalid group access
• Regex validation: The pattern is validated by creating a Regex object before null-checking the input

🔍 Areas for Improvement

Critical Issue

Documentation API Mismatch

The documentation in docs/docs/assertions/regex-assertions.md shows examples using .Group() and .AtIndex() methods that don't exist in the actual implementation:

Documentation shows:

await Assert.That(email)
    .Matches(pattern)
    .Group("username", user => user.IsEqualTo("john.doe"))  // This doesn't exist
    .And.Group("domain", domain => domain.IsEqualTo("example.com"));

Actual API is:

var match = await Assert.That(email).Matches(pattern).GetMatchAsync();
await Assert.That(match.Group("username")).IsEqualTo("john.doe");
await Assert.That(match.Group("domain")).IsEqualTo("example.com");

The entire documentation (lines 30-291) describes fluent group assertion methods that aren't implemented.

Minor Issues

1. Missing using statement (RegexMatchResult.cs:14)

The ArgumentNullException is used but System namespace isn't explicitly imported. This works due to global usings but could be made explicit for clarity.

2. Exception Ordering (StringAssertions.cs:484-491)

The implementation validates regex before checking null input:

var regex = _regex ?? new Regex(_pattern, _options);  // May throw RegexParseException
if (value == null)  // Check comes after regex validation
{
    throw new ArgumentNullException(nameof(value), "value was null");
}

Impact: Low - This appears intentional based on the comment, but could be confusing.

📋 Repository Compliance

✅ Follows TUnit Guidelines

• Dual-mode compatibility: ✅ This is assertions-only, no source generator changes needed
• Performance-first: ✅ Efficient match caching implementation
• Modern C# syntax: ✅ Uses nullable references, collection expressions where appropriate
• Public API snapshots: ✅ All .verified.txt files properly updated across all target frameworks

✅ Testing Standards

• Comprehensive coverage: Tests cover happy path, edge cases, and error conditions
• Follows TUnit patterns: Uses async/await properly with Assert.That() syntax
• Good test naming: Descriptive test method names clearly indicate what's being tested

🚀 Recommendations

High Priority

1. Fix documentation - Update docs/docs/assertions/regex-assertions.md to match the actual API implementation. Either:
   • Implement the fluent .Group() methods shown in docs, or
   • Update docs to show the current GetMatchAsync() approach

Low Priority

2. Consider adding explicit using System; to RegexMatchResult.cs for clarity
3. Consider documenting the exception ordering rationale in StringMatchesAssertion if intentional

🎯 Verdict

Recommend approval with documentation updates. This is a well-implemented feature that:

• Adds valuable functionality for regex assertion scenarios
• Follows TUnit's performance and design principles
• Has excellent test coverage
• Maintains AOT/trimming compatibility
• Properly updates public API snapshots

The critical issue is the documentation mismatch which creates confusion between expected vs actual API usage. This should be addressed before merge.

---

[claude]

Claude finished @thomhurst's task —— View job

---

Code Review Complete ✅

Todo List:

• Read repository guidelines (CLAUDE.md)
• Analyze the RegexMatchResult class implementation
• Review StringMatchesAssertionExtensions
• Examine test coverage and quality
• Check StringAssertions.cs modifications
• Review public API changes
• Assess documentation quality
• Provide comprehensive feedback on code quality, bugs, performance, security, and test coverage

---

Overall Assessment

This PR successfully adds robust regex assertion capabilities to TUnit with proper match result access. The implementation follows TUnit's coding standards and performance requirements well.

✅ Strengths

Code Quality & Design

• Clean API design: The fluent await Assert.That(text).Matches(pattern).GetMatchAsync() pattern is intuitive and follows TUnit's existing conventions
• Proper encapsulation: RegexMatchResult class appropriately wraps System.Text.RegularExpressions.Match with validation
• Thread-safe: The implementation doesn't introduce shared mutable state
• AOT-compatible: Uses direct method calls instead of reflection, following TUnit's AOT/trimming requirements

Performance Considerations

• Match caching: StringMatchesAssertion now caches the Match object (line 433 in StringAssertions.cs:494), avoiding duplicate regex execution
• Lazy evaluation: Match execution only happens during assertion, not during setup
• No unnecessary allocations: Reuses existing Match object from .NET's regex engine

Test Coverage

• Comprehensive test suite: RegexMatchResultTests.cs covers all key scenarios:
  • Named groups (Group("username"))
  • Indexed groups (Group(1))
  • Match properties (Index, Length, Value)
  • Case-insensitive matching
  • Error conditions (invalid group names/indices)

Security & Robustness

• Input validation: Proper argument validation in RegexMatchResult.Group() methods
• Error handling: Clear exception messages for invalid group access
• Regex validation: The pattern is validated by creating a Regex object before null-checking the input

🔍 Areas for Improvement

Minor Issues

1. Exception Ordering (StringAssertions.cs:484-491)

The current implementation validates regex before checking null input:

var regex = _regex ?? new Regex(_pattern, _options);  // May throw RegexParseException
if (value == null)  // Check comes after regex validation
{
    throw new ArgumentNullException(nameof(value), "value was null");
}

Impact: Low - This is likely intentional based on the comment, but could be confusing.

2. Documentation Gap

The documentation in docs/docs/assertions/regex-assertions.md shows examples using .Group() and .AtIndex() methods that don't exist yet:

// This doesn't match the actual API:
await Assert.That(email)
    .Matches(pattern)
    .Group("username", user => user.IsEqualTo("john.doe"))  // This doesn't exist

The actual API is:

var match = await Assert.That(email).Matches(pattern).GetMatchAsync();
await Assert.That(match.Group("username")).IsEqualTo("john.doe");

3. Missing using statement (RegexMatchResult.cs:14)

The ArgumentNullException is used but System namespace isn't explicitly imported. This works due to global usings but could be made explicit for clarity.

📋 Repository Compliance

✅ Follows TUnit Guidelines

• Dual-mode compatibility: ✅ This is assertions-only, no source generator changes needed
• Performance-first: ✅ Efficient match caching implementation
• Modern C# syntax: ✅ Uses nullable references, collection expressions where appropriate
• Public API snapshots: ✅ All .verified.txt files properly updated across all target frameworks

✅ Testing Standards

• Comprehensive coverage: Tests cover happy path, edge cases, and error conditions
• Follows TUnit patterns: Uses async/await properly with Assert.That() syntax
• Good test naming: Descriptive test method names clearly indicate what's being tested

🚀 Recommendations

High Priority

1. Update documentation to match the actual API - either implement the fluent .Group() methods shown in docs, or update docs to show the current GetMatchAsync() approach

Low Priority

2. Consider adding explicit using System; to RegexMatchResult.cs for clarity
3. Consider documenting the exception ordering rationale in StringMatchesAssertion if intentional

🎯 Verdict

Recommend approval with documentation updates. This is a well-implemented feature that:

• Adds valuable functionality for regex assertion scenarios
• Follows TUnit's performance and design principles
• Has excellent test coverage
• Maintains AOT/trimming compatibility
• Properly updates public API snapshots

The only significant issue is the documentation mismatch, which should be addressed before merge.

---

[claude]

Claude finished @thomhurst's task —— View job

---

Code Review Complete ✅

Todo List:

• Read repository guidelines (CLAUDE.md)
• Analyze new regex assertion classes and extensions
• Review StringMatchesAssertionExtensions implementation
• Examine test coverage and quality
• Check documentation accuracy and completeness
• Assess performance implications
• Review security considerations
• Provide comprehensive feedback

---

Overall Assessment

This PR adds a comprehensive and well-designed regex assertion API to TUnit. The implementation follows TUnit's architectural patterns and provides a fluent, intuitive interface for regex-based assertions with group access.

✅ Strengths

Architecture & Design

• Clean API Design: The fluent pattern using .And for chaining creates readable test code that expresses intent clearly
• Proper Encapsulation: RegexMatch and RegexMatchCollection classes appropriately wrap .NET's regex types while adding validation
• Consistent Patterns: Follows TUnit's existing assertion patterns with proper context mapping and error handling
• Good Separation of Concerns: Clear separation between collection-level and individual match operations

Code Quality

• Modern C# Usage: Uses collection expressions ([]), nullable reference types, and proper async patterns
• Comprehensive Error Handling: Validates input parameters and provides clear error messages
• Thread Safety: No shared mutable state, making the implementation inherently thread-safe
• AOT/Trimming Compatible: Uses direct method calls instead of reflection, aligning with TUnit's performance goals

Performance Considerations ⭐

• Efficient Caching: StringMatchesAssertion.cs:497 properly caches the Regex.Matches() result in the mapped context
• Lazy Evaluation: Regex matching only occurs during assertion execution, not during setup
• No Unnecessary Allocations: Reuses existing .NET Match objects without additional wrappers
• Smart Exception Ordering: StringAssertions.cs:488 validates regex pattern before null checks to ensure proper exception precedence

Test Coverage

• Comprehensive Test Suite: RegexAPITests.cs covers key usage patterns and edge cases
• Realistic Scenarios: Tests include practical examples like email parsing and date validation
• Error Conditions: Existing StringRegexAssertionTests.cs covers exception scenarios appropriately

🔍 Areas for Improvement

Critical Issues

1. Documentation API Mismatch 🚨

The documentation shows methods that don't exist in the implementation:

Documentation shows (docs/docs/assertions/regex-assertions.md:106):

await Assert.That(text)
    .Matches(pattern)
    .AtIndex(12);  // ❌ AtIndex method doesn't exist

Documentation shows (docs/docs/assertions/regex-assertions.md:110):

await Assert.That(text)
    .Matches(pattern)
    .HasLength(3);  // ❌ HasLength method doesn't exist

The documentation describes fluent .AtIndex() and .HasLength() methods that aren't implemented. The actual API requires using the RegexMatch properties:

Actual API:

var match = await Assert.That(text).Matches(pattern).And.Match(0);
// Then access match.Index, match.Length, match.Value

Minor Issues

2. Potential Confusion with Method Overloads

RegexAssertionExtensions.cs has multiple Group() method overloads that might be confusing:

• Lines 81-87: Group on collection (first match)
• Lines 93-99: Group on collection with index
• Lines 109-115: Group on specific match
• Lines 120-127: Group on specific match with index

While functionally correct, the API surface is quite large.

3. Missing Exception Documentation

The RegexMatch.GetGroup() methods throw exceptions but the XML docs could be more specific about when ArgumentException vs ArgumentOutOfRangeException are thrown.

📋 Repository Compliance

✅ Follows TUnit Guidelines

• Dual-mode compatibility: ✅ This is assertions-only, no source generator impact
• Performance-first: ✅ Efficient implementation with proper caching
• Modern C# syntax: ✅ Uses current language features appropriately
• Public API snapshots: ✅ All .verified.txt files properly updated for all target frameworks
• Thread safety: ✅ No shared mutable state

✅ Testing Standards

• Comprehensive coverage: Good test coverage for happy path and basic error scenarios
• Follows TUnit patterns: Proper use of async/await and assertion syntax
• Practical examples: Tests demonstrate real-world usage patterns

🔒 Security & Robustness

• Input Validation: Proper null checks and parameter validation throughout
• Exception Safety: Proper exception handling and cleanup
• No Security Concerns: No reflection usage, no security-sensitive operations
• Resource Management: No disposable resources to manage

🚀 Recommendations

High Priority

1. Fix Documentation: Update docs/docs/assertions/regex-assertions.md to either:
   • Implement the missing .AtIndex() and .HasLength() methods, or
   • Update documentation to show the actual API using RegexMatch properties

Medium Priority

2. Consider API Simplification: The current API has many overloads. Consider if some could be consolidated or if documentation could better guide users to the "preferred" patterns

Low Priority

3. Enhanced Documentation: Add more specific exception documentation to RegexMatch.GetGroup() methods
4. Performance Documentation: Document the regex caching behavior for users concerned about performance

🎯 Verdict

Strongly recommend approval with documentation fixes. This is an excellent implementation that:

• ✅ Provides valuable functionality for regex-based testing scenarios
• ✅ Follows TUnit's architectural patterns and performance requirements
• ✅ Has solid test coverage and error handling
• ✅ Maintains backward compatibility
• ✅ Is AOT/trimming compatible
• ✅ Properly updates public API snapshots

The main blocker is the documentation mismatch which could confuse users. Once the documentation accurately reflects the implemented API, this feature will be a valuable addition to TUnit.

Code Quality: A- | Architecture: A | Performance: A | Testing: B+ | Documentation: C (due to mismatch)

---