docs: add test lifecycle overview and update sidebar

[thomhurst]

Description

Related Issue

Fixes #

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Performance improvement
• Refactoring (no functional changes)

Checklist

Required

• I have read the Contributing Guidelines
• If this is a new feature, I started a discussion first and received agreement
• My code follows the project's code style (modern C# syntax, proper naming conventions)
• I have written tests that prove my fix is effective or my feature works

TUnit-Specific Requirements

• Dual-Mode Implementation: If this change affects test discovery/execution, I have implemented it in BOTH:
  • Source Generator path (TUnit.Core.SourceGenerator)
  • Reflection path (TUnit.Engine)
• Snapshot Tests: If I changed source generator output or public APIs:
  • I ran TUnit.Core.SourceGenerator.Tests and/or TUnit.PublicAPI tests
  • I reviewed the .received.txt files and accepted them as .verified.txt
  • I committed the updated .verified.txt files
• Performance: If this change affects hot paths (test discovery, execution, assertions):
  • I minimized allocations and avoided LINQ in hot paths
  • I cached reflection results where appropriate
• AOT Compatibility: If this change uses reflection:
  • I added appropriate [DynamicallyAccessedMembers] annotations
  • I verified the change works with dotnet publish -p:PublishAot=true

Testing

• All existing tests pass (dotnet test)
• I have added tests that cover my changes
• I have tested both source-generated and reflection modes (if applicable)

Additional Notes

[claude]

Code Review: Documentation - Test Lifecycle Overview

Summary

This PR adds comprehensive documentation for TUnit's test lifecycle with excellent visual diagrams and clear explanations. The content is high quality and well-structured. This is a pure documentation change with no code impact.

---

✅ Strengths

1. Excellent Visual Communication

• Multiple Mermaid diagrams effectively illustrate complex lifecycle flows
• Flowcharts, sequence diagrams, and hierarchical structures are well-chosen
• Color coding in the main diagram helps distinguish different phases

2. Comprehensive Coverage

• Covers all four lifecycle mechanisms (Hook Attributes, Event Receivers, Initialization, Disposal)
• Clear distinction between IAsyncInitializer vs IAsyncDiscoveryInitializer
• Complete execution order table (26 steps) is extremely valuable

3. Great Organization

• Logical progression from overview → discovery → execution → specific topics
• Quick reference ASCII diagram at the end is helpful for rapid scanning
• Related pages section provides good navigation

4. Practical Guidance

• Warning callouts about IAsyncInitializer not running during discovery
• "Early vs Late" stage explanation for event receivers
• Exception handling behavior clearly documented

5. Proper Integration

• Correctly placed at the top of the Core Concepts section in sidebar
• Good positioning as an overview before specific lifecycle topics

---

📝 Minor Suggestions

1. Terminology Consistency
Line 221: The table shows [Before(Class)] runs "after BeforeClass", but should clarify this means "after [Before(Class)] hooks":

Interface	When It Runs	Use Case
IAsyncInitializer	During test execution (after [Before(Class)] hooks)	Starting containers, DB connections

This matches the sequence diagram at line 146.

2. Disposal Order Clarity
The disposal section (lines 242-262) could benefit from explicitly stating that disposal happens in reverse order of initialization (although this is likely implied). Consider adding:

Note: Objects are disposed in reverse order of initialization (test instance first, then parent objects).

3. Minor Typo Check
Line 301: "runs after [Before(Class)] hooks" - verify this is accurate timing relative to the sequence diagram at lines 137-166, which shows IAsyncInitializer running after property setting but before [BeforeEvery(Test)].

---

✅ Documentation Quality Checklist

• ✅ Accuracy: Content aligns with TUnit architecture (dual-mode design, lifecycle phases)
• ✅ Completeness: Covers all major lifecycle mechanisms comprehensively
• ✅ Clarity: Well-written with good use of visuals and examples
• ✅ Structure: Logical flow from high-level to detailed information
• ✅ Navigation: Properly integrated into sidebar, includes related pages
• ✅ No Code Changes: Pure documentation, no risk to functionality

---

🎯 TUnit-Specific Compliance (per CLAUDE.md)

Since this is documentation only:

• ✅ No dual-mode implementation needed
• ✅ No snapshot tests required
• ✅ No performance impact
• ✅ No AOT compatibility concerns
• ✅ No VSTest references
• ✅ Follows documentation structure conventions

---

Final Verdict

APPROVED ✅

This is excellent documentation that will significantly help users understand TUnit's lifecycle. The visual diagrams are particularly valuable for grasping the complex execution flow. The minor suggestions above are optional improvements - the PR is ready to merge as-is.

Recommendation: Merge after addressing the minor terminology clarification in the IAsyncInitializer timing (suggestion #1), or merge immediately if the current description is verified as accurate.

Great work on creating such comprehensive lifecycle documentation! 🎉

[Copilot]

Pull request overview

This PR adds comprehensive documentation about TUnit's test lifecycle to help users understand when different hooks, events, and initialization methods execute during test discovery and execution.

Key Changes:

• New test lifecycle overview documentation with detailed diagrams and reference tables
• Updated sidebar to include the new page as the first item in the "Core Concepts" section

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
docs/sidebars.ts	Added lifecycle-overview as the first entry in the Core Concepts section, providing an overview before diving into specific topics
docs/docs/test-lifecycle/lifecycle-overview.md	Comprehensive new documentation covering all lifecycle phases, including discovery, execution, initialization, disposal, and event receivers with multiple Mermaid diagrams and reference tables

---

After thoroughly reviewing this documentation PR, I found no issues to report. The documentation is:

✅ Well-structured - Logical flow from overview to detailed reference
✅ Technically accurate - Correctly describes TUnit's dual-phase lifecycle
✅ Comprehensive - Covers all lifecycle mechanisms (hooks, events, initializers, disposal)
✅ Well-illustrated - Multiple Mermaid diagrams visualize complex flows
✅ Properly linked - All referenced pages exist in the documentation
✅ Grammatically correct - No spelling or grammatical errors detected

The new lifecycle overview page serves as an excellent reference for understanding when different mechanisms execute in TUnit's test lifecycle, and its placement at the beginning of the Core Concepts section is appropriate for guiding users through the rest of the test lifecycle documentation.