feat: add string length assertions and update documentation for new assertion methods

[thomhurst]

Fixes #3912

[claude]

Claude finished @thomhurst's task —— View job

---

PR Review: String Length Assertions

I've completed a comprehensive review of this PR that adds string length assertions to TUnit. Here's my detailed feedback:

✅ Overall Assessment: Excellent Implementation

This is a well-executed PR that adds valuable functionality while maintaining TUnit's high code quality standards.

🎯 Strengths

Code Quality & Design

• Clean Architecture: The StringLengthValueAssertion class follows TUnit's established patterns perfectly
• Proper Type Mapping: Elegant use of AssertionContext<string>.Map<int>() to transform string context to length context
• Null Safety: Correctly handles null strings by returning length 0 (s?.Length ?? 0)
• API Consistency: The new Length() method integrates seamlessly with existing assertion chains

Test Coverage

• Comprehensive Testing: 15 test methods cover all numeric assertion scenarios
• Edge Cases: Properly tests null strings, empty strings, and boundary conditions
• Error Validation: Tests verify proper exception messages for failed assertions
• Chaining Support: Tests confirm .And chaining works correctly

Documentation Updates

• Well-Documented: Clear examples in /docs/docs/assertions/string.md showing usage patterns
• Multiple Approaches: Shows both simple .Length().IsEqualTo(6) and chained .Length().IsGreaterThan(3).And.IsLessThan(20) usage
• Range Support: Documents .IsBetween() usage for length ranges

🔍 Technical Analysis

Performance Considerations ✅

• Minimal Overhead: Single property access (s?.Length) with no LINQ or allocations
• Hot Path Friendly: No reflection, no dynamic code generation
• Efficient Mapping: Uses TUnit's optimized context mapping system

Security Assessment ✅

• No Security Concerns: Pure computational logic with no external dependencies
• Safe Null Handling: No risk of null reference exceptions
• Input Validation: Relies on underlying numeric assertions for bounds checking

Best Practices Compliance ✅

• Modern C# Features: Uses null-conditional operators appropriately
• Consistent Naming: Follows TUnit's Length() convention vs deprecated HasLength()
• Proper Inheritance: Extends ValueAssertion<int> to inherit all numeric assertion methods
• Expression Builder: Correctly updates expression context for debugging

🚀 API Design Excellence

The new API provides excellent ergonomics:

// Simple length check
await Assert.That(str).Length().IsEqualTo(5);

// Chained comparisons  
await Assert.That(username)
    .Length().IsGreaterThan(3)
    .And.Length().IsLessThan(20);

// Range validation
await Assert.That(password).Length().IsBetween(8, 128);

// All numeric assertions available
await Assert.That(input).Length().IsPositive();
await Assert.That(input).Length().IsZero(); // for empty strings

🔧 Minor Observations

1. Deprecation Handling: The PR maintains backward compatibility with deprecated HasLength() methods while promoting the new Length() API

2. Documentation Quality: The documentation updates are thorough and include practical examples that developers will find useful

3. Test Organization: Tests are well-structured with descriptive names following TUnit conventions

📊 Change Impact Assessment

• 20 Files Modified: Primarily documentation updates with focused code changes
• Additive Changes: No breaking changes to existing APIs
• Minimal Risk: New functionality doesn't affect existing assertion behavior

✅ Final Recommendation: APPROVE

This PR represents high-quality work that:

• Adds valuable functionality developers will appreciate
• Follows TUnit's architectural patterns perfectly
• Includes comprehensive tests and documentation
• Introduces no performance or security concerns
• Maintains full backward compatibility

The string length assertions will be a welcome addition to TUnit's assertion library, providing an intuitive and powerful way to validate string lengths with the full power of numeric assertions.

Ready for merge! 🚢

[claude]

Claude finished @thomhurst's task —— View job

---

PR Review: String Length Assertions

I've completed a comprehensive review of this PR that adds string length assertions to TUnit. Here's my detailed analysis:

Todo List:

• Read repository guidelines (CLAUDE.md)
• Examine core implementation (StringLengthValueAssertion.cs)
• Review assertion extension methods
• Analyze test coverage and quality
• Check documentation updates
• Review public API changes
• Assess performance implications
• Check for security concerns
• Provide comprehensive review feedback

---

✅ Overall Assessment: Excellent Implementation

This is a well-executed PR that adds valuable functionality while maintaining TUnit's high code quality standards.

🎯 Strengths

Code Quality & Design

• Clean Architecture: The StringLengthValueAssertion class follows TUnit's established patterns perfectly
• Proper Type Mapping: Elegant use of AssertionContext<string>.Map<int>() to transform string context to length context
• Null Safety: Correctly handles null strings by returning length 0 (s?.Length ?? 0)
• API Consistency: The new Length() method integrates seamlessly with existing assertion chains

Test Coverage

• Comprehensive Testing: 15 test methods cover all numeric assertion scenarios
• Edge Cases: Properly tests null strings, empty strings, and boundary conditions
• Error Validation: Tests verify proper exception messages for failed assertions
• Chaining Support: Tests confirm .And chaining works correctly

Documentation Updates

• Well-Documented: Clear examples in /docs/docs/assertions/string.md showing usage patterns
• Multiple Approaches: Shows both simple .Length().IsEqualTo(6) and chained .Length().IsGreaterThan(3).And.IsLessThan(20) usage
• Range Support: Documents .IsBetween() usage for length ranges

🔍 Technical Analysis

Performance Considerations ✅

• Minimal Overhead: Single property access (s?.Length) with no LINQ or allocations
• Hot Path Friendly: No reflection, no dynamic code generation
• Efficient Mapping: Uses TUnit's optimized context mapping system

Security Assessment ✅

• No Security Concerns: Pure computational logic with no external dependencies
• Safe Null Handling: No risk of null reference exceptions
• Input Validation: Relies on underlying numeric assertions for bounds checking

Best Practices Compliance ✅

• Modern C# Features: Uses null-conditional operators appropriately
• Consistent Naming: Follows TUnit's Length() convention vs deprecated HasLength()
• Proper Inheritance: Extends ValueAssertion<int> to inherit all numeric assertion methods
• Expression Builder: Correctly updates expression context for debugging

🚀 API Design Excellence

The new API provides excellent ergonomics:

// Simple length check
await Assert.That(str).Length().IsEqualTo(5);

// Chained comparisons  
await Assert.That(username)
    .Length().IsGreaterThan(3)
    .And.Length().IsLessThan(20);

// Range validation
await Assert.That(password).Length().IsBetween(8, 128);

// All numeric assertions available
await Assert.That(input).Length().IsPositive();
await Assert.That(input).Length().IsZero(); // for empty strings

🔧 Minor Observations

1. Deprecation Handling: The PR maintains backward compatibility with deprecated HasLength() methods while promoting the new Length() API

2. Documentation Quality: The documentation updates are thorough and include practical examples that developers will find useful

3. Test Organization: Tests are well-structured with descriptive names following TUnit conventions

📊 Change Impact Assessment

• 20+ Files Modified: Primarily documentation updates with focused code changes
• Additive Changes: No breaking changes to existing APIs
• Minimal Risk: New functionality doesn't affect existing assertion behavior

✅ Repository Guidelines Compliance

Per TUnit's CLAUDE.md guidelines, this PR:

• ✅ Rule 1: Does not require dual-mode implementation (assertion library feature)
• ✅ Rule 2: Correctly updates public API snapshots across all target frameworks
• ✅ Rule 3: Uses appropriate testing platform (Microsoft.Testing.Platform)
• ✅ Rule 4: Minimal performance impact - no allocations in hot paths
• ✅ Rule 5: No AOT/trimming concerns - simple property access

Public API Updates: The PR correctly updates snapshot files for all target frameworks (Net4.7, DotNet8.0, DotNet9.0, DotNet10.0) showing the new StringLengthValueAssertion class and Length() method.

✅ Final Recommendation: APPROVE

This PR represents high-quality work that:

• Adds valuable functionality developers will appreciate
• Follows TUnit's architectural patterns perfectly
• Includes comprehensive tests and documentation
• Introduces no performance or security concerns
• Maintains full backward compatibility

The string length assertions will be a welcome addition to TUnit's assertion library, providing an intuitive and powerful way to validate string lengths with the full power of numeric assertions.

Ready for merge! 🚢

---