diff --git a/TUnit.Core/Interfaces/IAsyncInitializer.cs b/TUnit.Core/Interfaces/IAsyncInitializer.cs index f0fcc73808..20a5aafa2c 100644 --- a/TUnit.Core/Interfaces/IAsyncInitializer.cs +++ b/TUnit.Core/Interfaces/IAsyncInitializer.cs @@ -1,6 +1,39 @@ namespace TUnit.Core.Interfaces; +/// +/// Defines a contract for types that require asynchronous initialization before they can be used. +/// +/// +/// 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. +/// public interface IAsyncInitializer { + /// + /// Asynchronously initializes the instance. + /// + /// + /// A representing the asynchronous initialization operation. + /// + /// + /// + /// 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. + /// + /// + /// Use this method to perform setup operations such as: + /// + /// Connecting to databases or external services + /// Starting in-memory servers or test containers + /// Loading test data + /// Preparing the object's internal state + /// + /// + /// + /// For cleanup operations, consider implementing alongside this interface. + /// + /// Task InitializeAsync(); } \ No newline at end of file diff --git a/TUnit.Core/Interfaces/IClassConstructor.cs b/TUnit.Core/Interfaces/IClassConstructor.cs index 3c8992eccd..374f66326b 100644 --- a/TUnit.Core/Interfaces/IClassConstructor.cs +++ b/TUnit.Core/Interfaces/IClassConstructor.cs @@ -2,7 +2,25 @@ namespace TUnit.Core.Interfaces; +/// +/// Defines a constructor for test classes, allowing custom instantiation strategies. +/// public interface IClassConstructor { + /// + /// Creates an instance of the specified type using custom instantiation logic. + /// + /// The type to instantiate. Must have accessible public constructors. + /// Metadata containing the test session ID and builder context for the test being executed. + /// + /// A new instance of the specified type. The implementation is responsible for resolving constructor + /// parameters and dependencies. + /// + /// + /// 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 from the + /// to access shared data and event subscriptions for the current test execution. + /// object Create([DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] Type type, ClassConstructorMetadata classConstructorMetadata); } \ No newline at end of file diff --git a/TUnit.Core/Interfaces/IConfiguration.cs b/TUnit.Core/Interfaces/IConfiguration.cs index b1387dd62f..8bde81a944 100644 --- a/TUnit.Core/Interfaces/IConfiguration.cs +++ b/TUnit.Core/Interfaces/IConfiguration.cs @@ -1,6 +1,68 @@ namespace TUnit.Core.Interfaces; +/// +/// Defines an interface for accessing configuration values within the TUnit testing framework. +/// +/// +/// +/// The configuration system provides a way to influence test execution through external settings. +/// +/// +/// Configuration values can come from various sources, including: +/// +/// Command-line arguments passed to the test runner +/// Environment variables +/// Configuration files (like appsettings.json) +/// +/// +/// +/// This interface is primarily accessed through the static property, +/// making configuration values available to tests without requiring dependency injection. +/// +/// +/// Configuration keys can include nested paths using a colon separator (e.g., "Section:Key"). +/// +/// +/// +/// +/// [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"; +/// } +/// +/// public interface IConfiguration { + /// + /// Retrieves a configuration value from the test execution environment by key. + /// + /// The configuration key to look up. + /// + /// The configuration value associated with the specified key, or null if the key is not found. + /// + /// + /// 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. + /// + /// + /// + /// // Accessing a configuration value in a test + /// string? logLevel = TestContext.Configuration.Get("LogLevel"); + /// if (logLevel == "Verbose") + /// { + /// // Enable verbose logging for this test + /// } + /// + /// string? Get(string key); } \ No newline at end of file diff --git a/TUnit.Core/Interfaces/IContext.cs b/TUnit.Core/Interfaces/IContext.cs index af6ef4cfaf..1eb9fd0cd5 100644 --- a/TUnit.Core/Interfaces/IContext.cs +++ b/TUnit.Core/Interfaces/IContext.cs @@ -2,9 +2,45 @@ namespace TUnit.Core.Interfaces; +/// +/// Defines the core contextual capabilities for the TUnit testing framework. +/// +/// +/// The 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. +/// public interface IContext { + /// + /// Gets the standard output writer for the context. + /// + /// + /// The output writer captures standard output messages during test execution. + /// These messages can be retrieved later for verification or reporting purposes. + /// + /// A instance for writing standard output. TextWriter OutputWriter { get; } + + /// + /// Gets the error output writer for the context. + /// + /// + /// The error output writer captures error messages during test execution. + /// These messages can be retrieved later for verification or reporting purposes. + /// + /// A instance for writing error output. TextWriter ErrorOutputWriter { get; } + + /// + /// Gets the default logger for the context. + /// + /// + /// 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. + /// + /// A instance configured for this context. DefaultLogger GetDefaultLogger(); } \ No newline at end of file diff --git a/TUnit.Core/Interfaces/IFirstTestInAssemblyEventReceiver.cs b/TUnit.Core/Interfaces/IFirstTestInAssemblyEventReceiver.cs index 93f725b661..62c9b775c2 100644 --- a/TUnit.Core/Interfaces/IFirstTestInAssemblyEventReceiver.cs +++ b/TUnit.Core/Interfaces/IFirstTestInAssemblyEventReceiver.cs @@ -1,6 +1,39 @@ namespace TUnit.Core.Interfaces; +/// +/// Defines an event receiver interface that is triggered when the first test in an assembly is about to execute. +/// +/// +/// +/// 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. +/// +/// +/// The order of execution for assembly-level events is: +/// +/// - before any tests in the assembly run +/// Tests execute within the assembly +/// - after all tests in the assembly have completed +/// +/// +/// +/// The property can be used to control the execution order +/// when multiple implementations of this interface exist. +/// +/// public interface IFirstTestInAssemblyEventReceiver : IEventReceiver { + /// + /// Called when the first test in an assembly is about to be executed. + /// + /// + /// 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. + /// + /// The assembly hook context containing information about the assembly and its test classes. + /// The context of the first test that triggered this event. + /// A representing the asynchronous operation. ValueTask OnFirstTestInAssembly(AssemblyHookContext context, TestContext testContext); } \ No newline at end of file diff --git a/TUnit.Core/Interfaces/IFirstTestInClassEventReceiver.cs b/TUnit.Core/Interfaces/IFirstTestInClassEventReceiver.cs index 7920153181..64bed22a63 100644 --- a/TUnit.Core/Interfaces/IFirstTestInClassEventReceiver.cs +++ b/TUnit.Core/Interfaces/IFirstTestInClassEventReceiver.cs @@ -1,6 +1,39 @@ namespace TUnit.Core.Interfaces; +/// +/// Defines an event receiver interface that is triggered when the first test in a class is about to execute. +/// +/// +/// +/// 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. +/// +/// +/// The order of execution for class-level events is: +/// +/// - before any tests in the class run +/// Tests execute within the class +/// - after all tests in the class have completed +/// +/// +/// +/// The property can be used to control the execution order +/// when multiple implementations of this interface exist. +/// +/// public interface IFirstTestInClassEventReceiver : IEventReceiver { + /// + /// Called when the first test in a class is about to be executed. + /// + /// + /// 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. + /// + /// The class hook context containing information about the class and its test methods. + /// The context of the first test that triggered this event. + /// A representing the asynchronous operation. ValueTask OnFirstTestInClass(ClassHookContext context, TestContext testContext); } \ No newline at end of file diff --git a/TUnit.Core/Interfaces/IFirstTestInTestSessionEventReceiver.cs b/TUnit.Core/Interfaces/IFirstTestInTestSessionEventReceiver.cs index 47a2a55773..c9ec5fde5f 100644 --- a/TUnit.Core/Interfaces/IFirstTestInTestSessionEventReceiver.cs +++ b/TUnit.Core/Interfaces/IFirstTestInTestSessionEventReceiver.cs @@ -1,6 +1,39 @@ namespace TUnit.Core.Interfaces; +/// +/// Defines an event receiver interface that is triggered when the first test in a test session is about to execute. +/// +/// +/// +/// 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. +/// +/// +/// The order of execution for test session-level events is: +/// +/// - before any tests in the session run +/// Tests execute within the test session +/// - after all tests in the session have completed +/// +/// +/// +/// The property can be used to control the execution order +/// when multiple implementations of this interface exist. +/// +/// public interface IFirstTestInTestSessionEventReceiver : IEventReceiver { + /// + /// Called when the first test in a test session is about to be executed. + /// + /// + /// 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. + /// + /// The current test session context containing information about the session and its tests. + /// The context of the first test that triggered this event. + /// A representing the asynchronous operation. ValueTask OnFirstTestInTestSession(TestSessionContext current, TestContext testContext); } \ No newline at end of file diff --git a/TUnit.Core/Interfaces/IHasLoggers.cs b/TUnit.Core/Interfaces/IHasLoggers.cs index 7fc92db318..b83106d219 100644 --- a/TUnit.Core/Interfaces/IHasLoggers.cs +++ b/TUnit.Core/Interfaces/IHasLoggers.cs @@ -2,7 +2,22 @@ namespace TUnit.Core.Interfaces; +/// +/// Defines a contract for components that maintain a collection of loggers. +/// public interface IHasLoggers { + /// + /// Gets the collection of loggers available for logging operations. + /// + /// + /// The collection contains 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. + /// + /// + /// A of + /// instances configured for the component. + /// public List Loggers { get; } } \ No newline at end of file diff --git a/TUnit.Core/Interfaces/ILastTestInAssemblyEventReceiver.cs b/TUnit.Core/Interfaces/ILastTestInAssemblyEventReceiver.cs index 4c01c6bdf1..23c5c975a6 100644 --- a/TUnit.Core/Interfaces/ILastTestInAssemblyEventReceiver.cs +++ b/TUnit.Core/Interfaces/ILastTestInAssemblyEventReceiver.cs @@ -1,6 +1,39 @@ namespace TUnit.Core.Interfaces; +/// +/// Defines an event receiver interface that is triggered when the last test in an assembly has completed execution. +/// +/// +/// +/// 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. +/// +/// +/// The order of execution for assembly-level events is: +/// +/// - before any tests in the assembly run +/// Tests execute within the assembly +/// - after all tests in the assembly have completed +/// +/// +/// +/// The property can be used to control the execution order +/// when multiple implementations of this interface exist. +/// +/// public interface ILastTestInAssemblyEventReceiver : IEventReceiver { + /// + /// Called when the last test in an assembly has completed execution. + /// + /// + /// 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. + /// + /// The assembly hook context containing information about the assembly and its test classes. + /// The context of the last test that triggered this event. + /// A representing the asynchronous operation. ValueTask OnLastTestInAssembly(AssemblyHookContext context, TestContext testContext); } \ No newline at end of file diff --git a/TUnit.Core/Interfaces/ILastTestInClassEventReceiver.cs b/TUnit.Core/Interfaces/ILastTestInClassEventReceiver.cs index bde1a883f0..e6e05d7708 100644 --- a/TUnit.Core/Interfaces/ILastTestInClassEventReceiver.cs +++ b/TUnit.Core/Interfaces/ILastTestInClassEventReceiver.cs @@ -1,6 +1,39 @@ namespace TUnit.Core.Interfaces; +/// +/// Defines an event receiver interface that is triggered when the last test in a class has completed execution. +/// +/// +/// +/// Implement this interface to perform class-level cleanup operations that should occur once after +/// all tests in the class have executed. This event receiver is useful for cleaning up resources +/// or finalizing state that was shared across all tests in the class. +/// +/// +/// The order of execution for class-level events is: +/// +/// - before any tests in the class run +/// Tests execute within the class +/// - after all tests in the class have completed +/// +/// +/// +/// The property can be used to control the execution order +/// when multiple implementations of this interface exist. +/// +/// public interface ILastTestInClassEventReceiver : IEventReceiver { + /// + /// Called when the last test in a class has completed execution. + /// + /// + /// This event is triggered once per class after all tests within that class have completed execution. + /// It can be used to perform class-level cleanup tasks such as releasing resources that were + /// initialized for the tests in the class or generating class-level test reports. + /// + /// The class hook context containing information about the class and its test methods. + /// The context of the last test that triggered this event. + /// A representing the asynchronous operation. ValueTask OnLastTestInClass(ClassHookContext context, TestContext testContext); } \ No newline at end of file diff --git a/TUnit.Core/Interfaces/ILastTestInTestSessionEventReceiver.cs b/TUnit.Core/Interfaces/ILastTestInTestSessionEventReceiver.cs index e17cdd5ad8..d30c60b3c5 100644 --- a/TUnit.Core/Interfaces/ILastTestInTestSessionEventReceiver.cs +++ b/TUnit.Core/Interfaces/ILastTestInTestSessionEventReceiver.cs @@ -1,6 +1,39 @@ namespace TUnit.Core.Interfaces; +/// +/// Defines an event receiver interface that is triggered when the last test in a test session has completed execution. +/// +/// +/// +/// Implement this interface to perform test session-level cleanup operations that should occur once after +/// all tests in the session have executed. This event receiver is useful for cleaning up resources +/// or finalizing state that was shared across all tests in the test session. +/// +/// +/// The order of execution for test session-level events is: +/// +/// - before any tests in the session run +/// Tests execute within the test session +/// - after all tests in the session have completed +/// +/// +/// +/// The property can be used to control the execution order +/// when multiple implementations of this interface exist. +/// +/// public interface ILastTestInTestSessionEventReceiver : IEventReceiver { + /// + /// Called when the last test in a test session has completed execution. + /// + /// + /// This event is triggered once per test session after all tests within that session have completed execution. + /// It can be used to perform test session-level cleanup tasks such as releasing resources that were + /// initialized for the tests in the session or generating session-level test reports. + /// + /// The test session context containing information about the session and its test assemblies. + /// The context of the last test that triggered this event. + /// A representing the asynchronous operation. ValueTask OnLastTestInTestSession(TestSessionContext current, TestContext testContext); } \ No newline at end of file diff --git a/TUnit.Core/Interfaces/IParallelConstraint.cs b/TUnit.Core/Interfaces/IParallelConstraint.cs index b1f5dfd887..2abfde730b 100644 --- a/TUnit.Core/Interfaces/IParallelConstraint.cs +++ b/TUnit.Core/Interfaces/IParallelConstraint.cs @@ -1,3 +1,27 @@ namespace TUnit.Core.Interfaces; +/// +/// Defines a marker interface for constraints that control test parallelization behavior. +/// +/// +/// +/// This interface serves as a base for concrete constraint implementations that determine how tests are organized +/// and executed in parallel or sequentially. The test execution engine uses these constraints to group and schedule tests. +/// +/// +/// There are two primary implementations of this interface: +/// +/// : Prevents tests from running in parallel, either globally or within specified constraint keys. +/// : Groups tests together so they run in parallel with each other but not with tests from other groups. +/// +/// +/// +/// Constraints are typically applied to tests using attributes like +/// and . +/// +/// +/// +/// +/// +/// public interface IParallelConstraint; \ No newline at end of file diff --git a/TUnit.Core/Interfaces/IParallelLimit.cs b/TUnit.Core/Interfaces/IParallelLimit.cs index f732b3bddb..1a8253d20e 100644 --- a/TUnit.Core/Interfaces/IParallelLimit.cs +++ b/TUnit.Core/Interfaces/IParallelLimit.cs @@ -1,6 +1,60 @@ namespace TUnit.Core.Interfaces; +/// +/// Defines an interface for specifying the maximum degree of parallelism during test execution. +/// +/// +/// +/// The interface is a core component of TUnit's parallel test execution strategy. +/// It provides a mechanism for controlling how many tests can execute concurrently within a test session, +/// allowing for fine-grained control over system resource utilization. +/// +/// +/// Implementations of this interface are typically used in conjunction with the +/// to apply parallelism constraints at different levels: +/// +/// Assembly level - limiting parallelism across all tests in an assembly +/// Class level - controlling parallelism for tests within a specific test class +/// Method level - setting constraints for individual test methods +/// +/// +/// +/// Custom implementations can be created to address specific testing scenarios or resource constraints. +/// +/// +/// +/// +/// public interface IParallelLimit { + /// + /// Gets the maximum number of tests that can be executed in parallel. + /// + /// + /// A positive integer representing the maximum number of tests that can run concurrently. + /// This value is used to create a that limits + /// the degree of parallelism in test execution. + /// + /// + /// + /// The limit controls how many tests can run simultaneously within the test runner. + /// A higher value allows more tests to execute in parallel, which may speed up test execution + /// but could increase resource usage. + /// + /// + /// Common implementations include: + /// + /// DefaultParallelLimit - Uses as the limit + /// Custom implementations with fixed limits (e.g., ParallelLimit3 with a limit of 3) + /// + /// + /// + /// This property must return a positive value (greater than zero). Returning zero or a negative value + /// will result in an exception being thrown when the limit is used. + /// + /// + /// + /// Thrown by the test execution engine when this property returns a value less than or equal to zero. + /// int Limit { get; } } \ No newline at end of file diff --git a/TUnit.Core/Interfaces/ITestEndEventReceiver.cs b/TUnit.Core/Interfaces/ITestEndEventReceiver.cs index 452e7a918b..0fd91376c4 100644 --- a/TUnit.Core/Interfaces/ITestEndEventReceiver.cs +++ b/TUnit.Core/Interfaces/ITestEndEventReceiver.cs @@ -1,6 +1,49 @@ namespace TUnit.Core.Interfaces; +/// +/// Defines an event receiver interface that is triggered when a test has completed execution. +/// +/// +/// +/// Implement this interface to perform operations that should occur after each test has executed. +/// This event receiver is useful for post-test processing such as cleanup, logging, or modifying test results. +/// +/// +/// The property can be used to control the execution order +/// when multiple implementations of this interface exist. +/// +/// +/// The order of execution for test-level events is: +/// +/// - when a test is registered +/// - before a test runs +/// Test execution +/// - after a test completes +/// +/// +/// public interface ITestEndEventReceiver : IEventReceiver { + /// + /// Called when a test has completed execution. + /// + /// + /// This method is invoked after a test has finished executing, regardless of whether the test + /// passed, failed, or was skipped. It provides access to the test context and details through + /// the parameter. + /// + /// Implementations can use this method to: + /// + /// Perform cleanup after test execution + /// Log test results or execution details + /// Override or modify the test result using + /// Add artifacts or data to the test context + /// + /// + /// + /// The context containing information about the completed test, including its results and details. + /// This context also provides methods to override the test result if needed. + /// + /// A representing the asynchronous operation. ValueTask OnTestEnd(AfterTestContext afterTestContext); } \ No newline at end of file diff --git a/TUnit.Core/Interfaces/ITestExecutor.cs b/TUnit.Core/Interfaces/ITestExecutor.cs index b0a905b641..c923b89e18 100644 --- a/TUnit.Core/Interfaces/ITestExecutor.cs +++ b/TUnit.Core/Interfaces/ITestExecutor.cs @@ -1,6 +1,74 @@ namespace TUnit.Core.Interfaces; +/// +/// Defines a mechanism for executing tests within the TUnit test framework. +/// +/// +/// +/// The interface is a core component of the TUnit testing framework that +/// provides a way to customize how tests are executed. Implementers of this interface can control +/// the execution environment, threading model, synchronization context, or other aspects of test execution. +/// +/// +/// Built-in implementations include: +/// +/// - executes the test directly on the current thread +/// - executes the test on a dedicated thread +/// - executes the test on a Single-Threaded Apartment (STA) thread (Windows only) +/// +/// +/// +/// Test executors can be specified at the assembly, class, or method level using attributes such as +/// . +/// +/// +/// +/// +/// // Custom test executor implementation +/// public class CustomExecutor : GenericAbstractExecutor +/// { +/// protected override ValueTask ExecuteAsync(Func<ValueTask> action) +/// { +/// // Custom execution logic here +/// return action(); +/// } +/// } +/// +/// // Using a custom executor with a test +/// [Test] +/// [HookExecutor<CustomExecutor>] +/// public async Task TestWithCustomExecutor() +/// { +/// // Test code here +/// } +/// +/// public interface ITestExecutor { + /// + /// Executes a test within the provided test context. + /// + /// The test context containing information about the test being executed, including test details, + /// dependency information, and result tracking. + /// A function that represents the test body to be executed, which returns a . + /// + /// A that represents the asynchronous execution of the test. + /// When the returned task completes, the test execution has finished. + /// + /// + /// + /// This method is called by the test framework to execute a test. The implementation of this method + /// defines how the test is executed, such as on which thread or with what synchronization context. + /// + /// + /// Custom test executors can provide specialized execution environments, such as running tests on the STA thread + /// or with specific threading models. This is particularly useful for testing UI components or code that has + /// specific threading requirements. + /// + /// + /// The method should ensure that any exceptions thrown during test execution are properly propagated back to + /// the caller to ensure correct test result reporting. + /// + /// ValueTask ExecuteTest(TestContext context, Func action); } \ No newline at end of file