feat: introduce EventReceiverStage for controlling execution order of event receivers

[thomhurst]

Fixes #3824

[claude]

Claude finished @thomhurst's task —— View job

---

PR Review: EventReceiverStage Feature

I've completed a thorough review of this PR. Here are my findings:

Todo List:

• Read repository guidelines (CLAUDE.md)
• Review EventReceiverStage enum implementation
• Analyze interface modifications (ITestStartEventReceiver, ITestEndEventReceiver)
• Review EventReceiverOrchestrator changes
• Examine TestExecutor modifications
• Review test coverage and quality
• Check for dual-mode implementation compliance
• Verify snapshot test updates
• Check performance considerations
• Look for security concerns
• Provide final review summary

Overall Assessment: EXCELLENT ✅

This is a well-implemented feature that follows TUnit's design principles and coding standards exceptionally well.

✅ Code Quality & Best Practices

Excellent adherence to TUnit standards:

• ✅ Modern C# syntax with collection expressions: receivers ??= []
• ✅ Proper conditional compilation for .NET 8+ features: #if NET
• ✅ File-scoped namespaces and proper XML documentation
• ✅ Performance-first approach with manual filtering instead of LINQ
• ✅ ValueTask usage for potentially-sync operations
• ✅ Aggressive inlining for hot path methods

✅ Architecture & Design

Smart implementation choices:

• Backward compatibility: Default EventReceiverStage.Late preserves existing behavior
• Platform targeting: Uses #if NET to conditionally expose Stage property only on .NET 8+ (where default interface members are supported)
• Performance optimization: Manual sorting and filtering instead of LINQ in EventReceiverOrchestrator.cs:104-137
• Clean separation: New enum in TUnit.Core/Enums/ follows project structure

✅ Dual-Mode Implementation Compliance

Critical requirement satisfied:

• ✅ Reflection mode: Implemented in TUnit.Engine (EventReceiverOrchestrator, TestExecutor)
• ✅ Source-gen mode: No changes needed - this is a runtime execution ordering feature that affects both modes identically
• ✅ Both modes will execute receivers in the same order

✅ Test Coverage

Comprehensive test suite in EventReceiverStageTests.cs:

• ✅ Tests all stage combinations (Early/Late/Default)
• ✅ Verifies execution order with instance hooks
• ✅ Tests Order property interaction within stages
• ✅ Platform-specific conditional compilation for .NET Standard 2.0
• ✅ Uses shared tracker to verify execution sequence
• ✅ Excellent test naming and documentation

✅ Performance Considerations

Well-optimized for TUnit's performance-first principle:

• ✅ Fast-path checks with [MethodImpl(MethodImplOptions.AggressiveInlining)]
• ✅ Early return if no receivers: if (!_registry.HasTestStartReceivers()) return;
• ✅ Manual sorting to avoid LINQ allocations: receivers.Sort((a, b) => a.Order.CompareTo(b.Order))
• ✅ Conditional stage filtering only on .NET 8+ where property exists

✅ Snapshot Tests Updated

Proper API change documentation:

• ✅ All public API snapshots updated with EventReceiverStage enum
• ✅ Updates across all target frameworks (.NET 4.7, 8.0, 9.0, 10.0)

✅ Security & Safety

No security concerns identified:

• ✅ No reflection or dynamic code generation
• ✅ No external dependencies
• ✅ Defensive programming with null checks
• ✅ Exception handling preserved in event receiver execution

🎯 Minor Observations

These are very minor and don't require changes:

1. Documentation clarity: The XML docs clearly explain the .NET 8+ requirement and backward compatibility behavior

2. Edge case handling: The conditional compilation ensures graceful degradation on older frameworks

3. Test execution order: The use of Task.Delay(10) in tests for timing is acceptable for integration tests, though slightly brittle

📋 Verification Checklist

Based on TUnit's pre-commit checklist, this PR:

• ✅ Follows dual-mode implementation (runtime feature affects both modes identically)
• ✅ Updates public API snapshots correctly
• ✅ Follows modern C# code style
• ✅ Maintains performance in hot paths
• ✅ No AOT/trimming concerns (no reflection usage)
• ✅ Comprehensive test coverage

Final Recommendation: APPROVE 🚀

This PR is ready for merge. It demonstrates excellent understanding of TUnit's architecture, follows all coding standards, and provides a valuable feature with proper backward compatibility. The implementation is clean, performant, and well-tested.

The author clearly understood the importance of dual-mode compatibility and correctly identified that this runtime execution ordering feature works identically in both source-generated and reflection modes.

---