From 94bec29a1bc7ecd9ba257a0caee890985aed7981 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20St=C3=BChmer?= Date: Tue, 3 Jun 2025 13:43:19 +0200 Subject: [PATCH] docs: Further XML Summaries for `TUnit.Core/Attributes` --- .../Attributes/ParallelGroupAttribute.cs | 72 ++++++++++++++++++- .../Attributes/ParallelLimiterAttribute.cs | 49 +++++++++++++ .../Tests/InheritsTestsAttribute.cs | 7 ++ TUnit.Core/Attributes/Tests/TestAttribute.cs | 19 +++++ 4 files changed, 145 insertions(+), 2 deletions(-) diff --git a/TUnit.Core/Attributes/ParallelGroupAttribute.cs b/TUnit.Core/Attributes/ParallelGroupAttribute.cs index 0a5f328c9e..45c8bd140a 100644 --- a/TUnit.Core/Attributes/ParallelGroupAttribute.cs +++ b/TUnit.Core/Attributes/ParallelGroupAttribute.cs @@ -2,14 +2,82 @@ namespace TUnit.Core; + +/// +/// Specifies that a test method, class, or assembly belongs to a parallel execution group. +/// +/// +/// +/// Tests within the same parallel group will run in parallel with each other but not with tests from other groups. +/// This attribute helps to organize test execution when you want to control how certain tests run in relation to others. +/// +/// +/// The test engine processes parallel groups sequentially based on their property, but tests +/// within the same group execute in parallel with each other. This is useful for organizing tests that should +/// run concurrently but in separate batches from other test groups. +/// +/// +/// This attribute implements to register a +/// with the test discovery system, which the test execution engine uses to organize and schedule test execution. +/// +/// +/// Example usage: +/// +/// [Test, ParallelGroup("DatabaseTests")] +/// public async Task DatabaseTest1() +/// { +/// // This test will run in parallel with other tests in the "DatabaseTests" group +/// } +/// +/// [Test, ParallelGroup("DatabaseTests")] +/// public async Task DatabaseTest2() +/// { +/// // This will run in parallel with DatabaseTest1 +/// } +/// +/// [Test, ParallelGroup("UITests", Order = 1)] +/// public async Task UITest1() +/// { +/// // This test belongs to a different +/// } +/// +/// +/// public class ParallelGroupAttribute(string group) : TUnitAttribute, ITestDiscoveryEventReceiver { - int IEventReceiver.Order => 0; - + /// public int Order { get; set; } + /// + /// Gets the name of the parallel group to which the test belongs. + /// + /// + /// + /// The group name is used to identify which tests should be executed in parallel with each other. + /// Tests decorated with that have the same value + /// will be grouped together and executed concurrently, but isolated from tests in other groups. + /// + /// + /// Group names are case-sensitive string identifiers that should be chosen to represent a logical + /// set of tests that can safely run in parallel with each other. For example, "DatabaseTests", + /// "NetworkTests", or "UITests". + /// + /// + /// During test execution, the test engine organizes tests into groups based on this property, and + /// ensures that tests from different groups are not executed simultaneously, helping to manage + /// resource contention and test isolation. + /// + /// + /// This property is set via the constructor parameter and cannot be changed after the attribute + /// is instantiated. + /// + /// + /// + /// + /// public string Group { get; } = group; + /// public void OnTestDiscovery(DiscoveredTestContext discoveredTestContext) { discoveredTestContext.SetParallelConstraint(new ParallelGroupConstraint(Group, Order)); diff --git a/TUnit.Core/Attributes/ParallelLimiterAttribute.cs b/TUnit.Core/Attributes/ParallelLimiterAttribute.cs index f340618236..dd16b32063 100644 --- a/TUnit.Core/Attributes/ParallelLimiterAttribute.cs +++ b/TUnit.Core/Attributes/ParallelLimiterAttribute.cs @@ -2,12 +2,61 @@ namespace TUnit.Core; +/// +/// Limits the number of tests that can run in parallel for a test assembly, class, or method. +/// +/// +/// The type that implements and defines the maximum number +/// of tests that can execute concurrently. +/// +/// +/// +/// This attribute controls the degree of parallelism for test execution. When applied to a test assembly, +/// class, or method, it limits how many tests from that scope can run simultaneously. +/// +/// +/// The parallelism limit is defined by the property of the +/// instance. This value is used to create a semaphore that +/// controls concurrent test execution. +/// +/// +/// Common implementations include: +/// +/// DefaultParallelLimit - Uses as the limit +/// Custom implementations with fixed limits (e.g., ParallelLimit3 with a limit of 3) +/// +/// +/// +/// Example usage: +/// +/// // Apply to an assembly to limit all tests +/// [assembly: ParallelLimiter<DefaultParallelLimit>] +/// +/// // Apply to a class to limit tests in that class +/// [ParallelLimiter<ParallelLimit3>] +/// public class MyTestClass +/// { +/// // Tests in this class will run with a maximum of 3 in parallel +/// } +/// +/// // Apply to a specific test method +/// [Test] +/// [ParallelLimiter<ParallelLimit1>] +/// public void MyTest() +/// { +/// // This test will run exclusively (limit of 1) +/// } +/// +/// +/// [AttributeUsage(AttributeTargets.Assembly | AttributeTargets.Class | AttributeTargets.Method)] public sealed class ParallelLimiterAttribute : TUnitAttribute, ITestRegisteredEventReceiver where TParallelLimit : IParallelLimit, new() { + /// public int Order => 0; + /// public ValueTask OnTestRegistered(TestRegisteredContext testRegisteredContext) { testRegisteredContext.SetParallelLimiter(new TParallelLimit()); diff --git a/TUnit.Core/Attributes/Tests/InheritsTestsAttribute.cs b/TUnit.Core/Attributes/Tests/InheritsTestsAttribute.cs index 1bae435c97..28966e4c0d 100644 --- a/TUnit.Core/Attributes/Tests/InheritsTestsAttribute.cs +++ b/TUnit.Core/Attributes/Tests/InheritsTestsAttribute.cs @@ -1,4 +1,11 @@ namespace TUnit.Core; +/// +/// Marks a class as inheriting test methods from its base classes. +/// +/// +/// This attribute indicates to the TUnit test runner that test methods defined in base classes +/// should be considered part of the derived class's test suite. +/// [AttributeUsage(AttributeTargets.Class)] public sealed class InheritsTestsAttribute : TUnitAttribute; \ No newline at end of file diff --git a/TUnit.Core/Attributes/Tests/TestAttribute.cs b/TUnit.Core/Attributes/Tests/TestAttribute.cs index ded052adbf..196bc3f71b 100644 --- a/TUnit.Core/Attributes/Tests/TestAttribute.cs +++ b/TUnit.Core/Attributes/Tests/TestAttribute.cs @@ -2,6 +2,25 @@ namespace TUnit.Core; +/// +/// Marks a method as a test method in the TUnit testing framework. +/// +/// +/// Methods marked with this attribute will be discovered and executed as tests during test runs. +/// The attribute automatically captures the file path and line number where the test is defined. +/// +/// +/// +/// public class ExampleTests +/// { +/// [Test] +/// public void ExampleTest() +/// { +/// // Test code here +/// } +/// } +/// +/// [AttributeUsage(AttributeTargets.Method)] public sealed class TestAttribute( [CallerFilePath] string file = "",