docs: XML Summaries for TUnit.Core/Interfaces

Author: samtrion

TUnit.Core/Interfaces/IAsyncInitializer.cs

@@ -1,6 +1,39 @@
 namespace TUnit.Core.Interfaces;
 
+/// <summary>
+/// Defines a contract for types that require asynchronous initialization before they can be used.
+/// </summary>
+/// <remarks>
+/// Implementations of this interface are automatically initialized by the TUnit framework when
+/// they are injected into test classes or used as data sources. The initialization occurs before
+/// any test execution that depends on the instance.
+/// </remarks>
 public interface IAsyncInitializer
 {
+    /// <summary>
+    /// Asynchronously initializes the instance.
+    /// </summary>
+    /// <returns>
+    /// A <see cref="Task"/> representing the asynchronous initialization operation.
+    /// </returns>
+    /// <remarks>
+    /// <para>
+    /// This method is called by the TUnit framework to initialize the instance before it is used
+    /// in test execution. The framework guarantees that this method will be called exactly once
+    /// per instance lifecycle.
+    /// </para>
+    /// <para>
+    /// Use this method to perform setup operations such as:
+    /// <list type="bullet">
+    /// <item><description>Connecting to databases or external services</description></item>
+    /// <item><description>Starting in-memory servers or test containers</description></item>
+    /// <item><description>Loading test data</description></item>
+    /// <item><description>Preparing the object's internal state</description></item>
+    /// </list>
+    /// </para>
+    /// <para>
+    /// For cleanup operations, consider implementing <see cref="IAsyncDisposable"/> alongside this interface.
+    /// </para>
+    /// </remarks>
     Task InitializeAsync();
 }

TUnit.Core/Interfaces/IClassConstructor.cs

@@ -2,7 +2,25 @@
 
 namespace TUnit.Core.Interfaces;
 
+/// <summary>
+/// Defines a constructor for test classes, allowing custom instantiation strategies.
+/// </summary>
 public interface IClassConstructor
 {
+    /// <summary>
+    /// Creates an instance of the specified type using custom instantiation logic.
+    /// </summary>
+    /// <param name="type">The type to instantiate. Must have accessible public constructors.</param>
+    /// <param name="classConstructorMetadata">Metadata containing the test session ID and builder context for the test being executed.</param>
+    /// <returns>
+    /// A new instance of the specified type. The implementation is responsible for resolving constructor
+    /// parameters and dependencies.
+    /// </returns>
+    /// <remarks>
+    /// This method is called by the test framework to create instances of test classes.
+    /// It allows for custom dependency injection or specialized test class instantiation.
+    /// Implementations can use the provided <see cref="TestBuilderContext"/> from the <paramref name="classConstructorMetadata"/>
+    /// to access shared data and event subscriptions for the current test execution.
+    /// </remarks>
     object Create([DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] Type type, ClassConstructorMetadata classConstructorMetadata);
 }

TUnit.Core/Interfaces/IConfiguration.cs

@@ -1,6 +1,68 @@
 namespace TUnit.Core.Interfaces;
 
+/// <summary>
+/// Defines an interface for accessing configuration values within the TUnit testing framework.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The configuration system provides a way to influence test execution through external settings.
+/// </para>
+/// <para>
+/// Configuration values can come from various sources, including:
+/// <list type="bullet">
+///   <item><description>Command-line arguments passed to the test runner</description></item>
+///   <item><description>Environment variables</description></item>
+///   <item><description>Configuration files (like appsettings.json)</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// This interface is primarily accessed through the static <see cref="TestContext.Configuration"/> property,
+/// making configuration values available to tests without requiring dependency injection.
+/// </para>
+/// <para>
+/// Configuration keys can include nested paths using a colon separator (e.g., "Section:Key").
+/// </para>
+/// </remarks>
+/// <example>
+/// <code>
+/// [Test]
+/// public async Task ConfigurationExample()
+/// {
+///     // Access a configuration value
+///     string? logLevel = TestContext.Configuration.Get("LogLevel");
+///     
+///     // Use a nested configuration path
+///     string? apiUrl = TestContext.Configuration.Get("Services:ApiService:Url");
+///     
+///     // Check if a feature flag is enabled
+///     bool isFeatureEnabled = TestContext.Configuration.Get("FeatureFlags:NewFeature") == "true";
+/// }
+/// </code>
+/// </example>
 public interface IConfiguration
 {
+    /// <summary>
+    /// Retrieves a configuration value from the test execution environment by key.
+    /// </summary>
+    /// <param name="key">The configuration key to look up.</param>
+    /// <returns>
+    /// The configuration value associated with the specified key, or <c>null</c> if the key is not found.
+    /// </returns>
+    /// <remarks>
+    /// This method provides access to configuration values that can be set via command-line arguments,
+    /// environment variables, or configuration files used in the test execution context.
+    /// The configuration system is used by the TUnit testing framework to provide runtime
+    /// configuration to tests and test infrastructure components.
+    /// </remarks>
+    /// <example>
+    /// <code>
+    /// // Accessing a configuration value in a test
+    /// string? logLevel = TestContext.Configuration.Get("LogLevel");
+    /// if (logLevel == "Verbose")
+    /// {
+    ///     // Enable verbose logging for this test
+    /// }
+    /// </code>
+    /// </example>
     string? Get(string key);
 }

TUnit.Core/Interfaces/IContext.cs

@@ -2,9 +2,45 @@
 
 namespace TUnit.Core.Interfaces;
 
+/// <summary>
+/// Defines the core contextual capabilities for the TUnit testing framework.
+/// </summary>
+/// <remarks>
+/// The <see cref="IContext"/> interface provides access to output writers and logging mechanisms used
+/// throughout the TUnit testing pipeline. Implementations of this interface serve as a foundation
+/// for various context types in the testing framework, including test contexts, hook contexts,
+/// and discovery contexts.
+/// </remarks>
 public interface IContext
 {
+    /// <summary>
+    /// Gets the standard output writer for the context.
+    /// </summary>
+    /// <remarks>
+    /// The output writer captures standard output messages during test execution.
+    /// These messages can be retrieved later for verification or reporting purposes.
+    /// </remarks>
+    /// <value>A <see cref="TextWriter"/> instance for writing standard output.</value>
     TextWriter OutputWriter { get; }
+    
+    /// <summary>
+    /// Gets the error output writer for the context.
+    /// </summary>
+    /// <remarks>
+    /// The error output writer captures error messages during test execution.
+    /// These messages can be retrieved later for verification or reporting purposes.
+    /// </remarks>
+    /// <value>A <see cref="TextWriter"/> instance for writing error output.</value>
     TextWriter ErrorOutputWriter { get; }
+    
+    /// <summary>
+    /// Gets the default logger for the context.
+    /// </summary>
+    /// <remarks>
+    /// The default logger provides a unified logging mechanism for the test execution environment.
+    /// It uses the context's output writers to record messages at various log levels, and supports
+    /// structured logging with properties.
+    /// </remarks>
+    /// <returns>A <see cref="DefaultLogger"/> instance configured for this context.</returns>
     DefaultLogger GetDefaultLogger();
 }

TUnit.Core/Interfaces/IFirstTestInAssemblyEventReceiver.cs

@@ -1,6 +1,39 @@
 namespace TUnit.Core.Interfaces;
 
+/// <summary>
+/// Defines an event receiver interface that is triggered when the first test in an assembly is about to execute.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Implement this interface to perform assembly-level setup operations that should occur once before
+/// any tests in the assembly are executed. This event receiver is useful for initializing resources
+/// or configuring state that should be shared across all tests in the assembly.
+/// </para>
+/// <para>
+/// The order of execution for assembly-level events is:
+/// <list type="number">
+/// <item><see cref="IFirstTestInAssemblyEventReceiver"/> - before any tests in the assembly run</item> 
+/// <item>Tests execute within the assembly</item> 
+/// <item><see cref="ILastTestInAssemblyEventReceiver"/> - after all tests in the assembly have completed</item> 
+/// </list>
+/// </para>
+/// <para>
+/// The <see cref="IEventReceiver.Order"/> property can be used to control the execution order
+/// when multiple implementations of this interface exist.
+/// </para>
+/// </remarks>
 public interface IFirstTestInAssemblyEventReceiver : IEventReceiver
 {
+    /// <summary>
+    /// Called when the first test in an assembly is about to be executed.
+    /// </summary>
+    /// <remarks>
+    /// This event is triggered once per assembly before any test within that assembly starts execution.
+    /// It can be used to perform assembly-level setup tasks such as initializing resources that should be
+    /// available for all tests in the assembly.
+    /// </remarks>
+    /// <param name="context">The assembly hook context containing information about the assembly and its test classes.</param>
+    /// <param name="testContext">The context of the first test that triggered this event.</param>
+    /// <returns>A <see cref="ValueTask"/> representing the asynchronous operation.</returns>
     ValueTask OnFirstTestInAssembly(AssemblyHookContext context, TestContext testContext);
 }

TUnit.Core/Interfaces/IFirstTestInClassEventReceiver.cs

@@ -1,6 +1,39 @@
 namespace TUnit.Core.Interfaces;
 
+/// <summary>
+/// Defines an event receiver interface that is triggered when the first test in a class is about to execute.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Implement this interface to perform class-level setup operations that should occur once before
+/// any tests in the class are executed. This event receiver is useful for initializing resources
+/// or configuring state that should be shared across all tests in the class.
+/// </para>
+/// <para>
+/// The order of execution for class-level events is:
+/// <list type="number">
+/// <item><see cref="IFirstTestInClassEventReceiver"/> - before any tests in the class run</item> 
+/// <item>Tests execute within the class</item>
+/// <item><see cref="ILastTestInClassEventReceiver"/> - after all tests in the class have completed</item>
+/// </list>
+/// </para>
+/// <para>
+/// The <see cref="IEventReceiver.Order"/> property can be used to control the execution order
+/// when multiple implementations of this interface exist.
+/// </para>
+/// </remarks>
 public interface IFirstTestInClassEventReceiver : IEventReceiver
 {
+    /// <summary>
+    /// Called when the first test in a class is about to be executed.
+    /// </summary>
+    /// <remarks>
+    /// This event is triggered once per class before any test within that class starts execution.
+    /// It can be used to perform class-level setup tasks such as initializing resources that should be
+    /// available for all tests in the class.
+    /// </remarks>
+    /// <param name="context">The class hook context containing information about the class and its test methods.</param>
+    /// <param name="testContext">The context of the first test that triggered this event.</param>
+    /// <returns>A <see cref="ValueTask"/> representing the asynchronous operation.</returns>
     ValueTask OnFirstTestInClass(ClassHookContext context, TestContext testContext);
 }

TUnit.Core/Interfaces/IFirstTestInTestSessionEventReceiver.cs

@@ -1,6 +1,39 @@
 namespace TUnit.Core.Interfaces;
 
+/// <summary>
+/// Defines an event receiver interface that is triggered when the first test in a test session is about to execute.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Implement this interface to perform test session-level setup operations that should occur once before
+/// any tests in the session are executed. This event receiver is useful for initializing resources
+/// or configuring state that should be shared across all tests in the test session.
+/// </para>
+/// <para>
+/// The order of execution for test session-level events is:
+/// <list type="number">
+/// <item><see cref="IFirstTestInTestSessionEventReceiver"/> - before any tests in the session run</item>
+/// <item>Tests execute within the test session</item>
+/// <item><see cref="ILastTestInTestSessionEventReceiver"/> - after all tests in the session have completed</item>
+/// </list>
+/// </para>
+/// <para>
+/// The <see cref="IEventReceiver.Order"/> property can be used to control the execution order
+/// when multiple implementations of this interface exist.
+/// </para>
+/// </remarks>
 public interface IFirstTestInTestSessionEventReceiver : IEventReceiver
 {
+    /// <summary>
+    /// Called when the first test in a test session is about to be executed.
+    /// </summary>
+    /// <remarks>
+    /// This event is triggered once per test session before any test within that session starts execution.
+    /// It can be used to perform test session-level setup tasks such as initializing resources that should be
+    /// available for all tests in the session.
+    /// </remarks>
+    /// <param name="current">The current test session context containing information about the session and its tests.</param>
+    /// <param name="testContext">The context of the first test that triggered this event.</param>
+    /// <returns>A <see cref="ValueTask"/> representing the asynchronous operation.</returns>
     ValueTask OnFirstTestInTestSession(TestSessionContext current, TestContext testContext);
 }

TUnit.Core/Interfaces/IHasLoggers.cs

@@ -2,7 +2,22 @@
 
 namespace TUnit.Core.Interfaces;
 
+/// <summary>
+/// Defines a contract for components that maintain a collection of loggers.
+/// </summary>
 public interface IHasLoggers
 {
+    /// <summary>
+    /// Gets the collection of loggers available for logging operations.
+    /// </summary>
+    /// <remarks>
+    /// The collection contains <see cref="TUnitLogger"/> instances that can be used
+    /// to record messages at various log levels throughout the testing pipeline. These loggers
+    /// provide both synchronous and asynchronous logging capabilities.
+    /// </remarks>
+    /// <value>
+    /// A <see cref="List{T}"/> of <see cref="TUnitLogger"/> 
+    /// instances configured for the component.
+    /// </value>
     public List<TUnitLogger> Loggers { get; }
 }

TUnit.Core/Interfaces/ILastTestInAssemblyEventReceiver.cs

@@ -1,6 +1,39 @@
 namespace TUnit.Core.Interfaces;
 
+/// <summary>
+/// Defines an event receiver interface that is triggered when the last test in an assembly has completed execution.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Implement this interface to perform assembly-level cleanup operations that should occur once after
+/// all tests in the assembly have executed. This event receiver is useful for cleaning up resources
+/// or finalizing state that was shared across all tests in the assembly.
+/// </para>
+/// <para>
+/// The order of execution for assembly-level events is:
+/// <list type="number">
+/// <item><see cref="IFirstTestInAssemblyEventReceiver"/> - before any tests in the assembly run</item>
+/// <item>Tests execute within the assembly</item>
+/// <item><see cref="ILastTestInAssemblyEventReceiver"/> - after all tests in the assembly have completed</item>
+/// </list>
+/// </para>
+/// <para>
+/// The <see cref="IEventReceiver.Order"/> property can be used to control the execution order
+/// when multiple implementations of this interface exist.
+/// </para>
+/// </remarks>
 public interface ILastTestInAssemblyEventReceiver : IEventReceiver
 {
+    /// <summary>
+    /// Called when the last test in an assembly has completed execution.
+    /// </summary>
+    /// <remarks>
+    /// This event is triggered once per assembly after all tests within that assembly have completed execution.
+    /// It can be used to perform assembly-level cleanup tasks such as releasing resources that were
+    /// initialized for the tests in the assembly or generating assembly-level test reports.
+    /// </remarks>
+    /// <param name="context">The assembly hook context containing information about the assembly and its test classes.</param>
+    /// <param name="testContext">The context of the last test that triggered this event.</param>
+    /// <returns>A <see cref="ValueTask"/> representing the asynchronous operation.</returns>
     ValueTask OnLastTestInAssembly(AssemblyHookContext context, TestContext testContext);
 }