feat: introduce ReflectionMode attribute and enhance execution mode handling

[thomhurst]

Fixes #3026

[claude]

Claude finished @thomhurst's task —— View job

---

PR Review: ReflectionMode Attribute and Execution Mode Handling

I've completed a comprehensive review of this PR. Overall, this is a well-designed enhancement that addresses issue #3026 with a clean, maintainable approach.

✅ Positive Findings

Excellent Design Decisions

• Clear priority hierarchy: Command line → Assembly attribute → Environment variable → Default
• Comprehensive documentation: Thorough XML docs with examples and usage guidance
• AOT compatibility: Proper RuntimeFeature.IsDynamicCodeSupported checks
• Follows TUnit conventions: Aligns with CLAUDE.md dual-mode requirements

Code Quality

• Modern C# patterns: Proper use of collection expressions and nullable annotations
• Thread-safe implementation: EnvironmentVariableCache uses proper locking
• Performance conscious: Environment variable caching reduces system calls
• Clean separation: ExecutionModeHelper centralizes mode detection logic

Testing & Compatibility

• Public API snapshots updated: All target frameworks properly documented
• Backward compatibility: No breaking changes to existing APIs
• Cross-platform support: Works across .NET Standard 2.0, .NET 6/8/9+

🔍 Technical Analysis

ReflectionModeAttribute (TUnit.Core/Attributes/ReflectionModeAttribute.cs:1-44)

• ✅ Sealed class prevents inheritance misuse
• ✅ Assembly-level targeting with proper AttributeUsage
• ✅ Excellent documentation with bUnit example
• ✅ Clear performance warnings

ExecutionModeHelper (TUnit.Engine/Helpers/ExecutionModeHelper.cs:1-87)

• ✅ Well-documented priority order in comments
• ✅ Proper AOT detection using RuntimeFeature.IsDynamicCodeSupported
• ✅ Centralized mode detection logic
• ✅ Efficient environment variable caching

Service Provider Integration (TUnit.Engine/Framework/TUnitServiceProvider.cs:83)

• ✅ Clean integration into existing initialization flow
• ✅ Maintains the dual-mode philosophy required by CLAUDE.md
• ✅ Early determination prevents inconsistent state

⚡ Performance Considerations

Strengths

• Environment variable caching reduces repeated system calls
• Early mode determination (line 83) prevents redundant checks
• Minimal allocations in hot paths

Potential Optimization

• Consider caching the reflection attribute lookup result for the same assembly to avoid repeated GetCustomAttributes calls

🔒 Security Assessment

• ✅ No security concerns identified
• ✅ Proper input validation for environment variables
• ✅ No dynamic code generation vulnerabilities
• ✅ Assembly attribute access is safe

📝 Minor Suggestions

Documentation Enhancement

The docs update in docs/docs/execution/engine-modes.md:45-73 provides excellent bUnit examples. Consider adding a note about performance implications when using reflection mode extensively.

Code Consistency

In ExecutionModeHelper.cs:62, the inherit: false parameter is explicit - good defensive programming practice.

🧪 Test Coverage Analysis

Missing Test Scenarios

While public API snapshots are updated, consider adding integration tests for:

1. Command line flag override behavior
2. Assembly attribute detection with multiple assemblies
3. Environment variable precedence scenarios
4. AOT platform behavior simulation

Current Coverage

• ✅ Public API changes properly documented in snapshots
• ✅ Dual-mode operation maintained (per CLAUDE.md requirements)

🎯 Final Assessment

Code Quality: A- - Well-architected, follows established patterns, excellent documentation

Performance: A - Efficient implementation with appropriate caching

Security: A - No concerns identified

Maintainability: A - Clear separation of concerns, comprehensive docs

Testing: B+ - Good API coverage, could benefit from more integration tests

🚀 Recommendation

APPROVE - This PR successfully addresses the requirements while maintaining TUnit's high standards for performance and maintainability. The implementation is production-ready and follows all repository guidelines.

Follow-up Suggestions

1. Consider adding integration tests for the priority scenarios
2. Monitor performance in production to validate the caching strategy
3. Document any learnings from bUnit integration scenarios

---

[azure-pipelines]

There was an error handling pipeline event ba9af624-5b79-45a8-b3b1-b66d2abfe97d.