feature: Added ExcludeOnAttribute and RunOnAttribute

as discussed in #2508

Author: samtrion

TUnit.Core/Attributes/TestMetadata/ExcludeOnAttribute.cs

@@ -0,0 +1,80 @@
+using System.Runtime.InteropServices;
+using TUnit.Core.Enums;
+
+namespace TUnit.Core;
+
+/// <summary>
+/// Attribute that excludes a test from running on specific operating systems.
+/// </summary>
+/// <param name="OperatingSystem">
+/// Defines the operating systems on which the test should not run.
+/// </param>
+/// <remarks>
+/// <para>
+/// The <see cref="ExcludeOnAttribute"/> is used to specify that a test should not run on certain operating systems.
+/// Tests with this attribute will be skipped on operating systems that match the specified criteria.
+/// </para>
+/// <para>
+/// You can specify multiple operating systems by combining the <see cref="OS"/> enum values with the bitwise OR operator.
+/// </para>
+/// </remarks>
+/// <example>
+/// <code>
+/// // Skip on Windows
+/// [Test, ExcludeOn(OS.Windows)]
+/// public void NonWindowsOnlyTest()
+/// {
+///     // This test will run on Linux and macOS, but not on Windows
+/// }
+/// 
+/// // Skip on both Windows and Linux
+/// [Test, ExcludeOn(OS.Windows | OS.Linux)]
+/// public void MacOsOnlyTest()
+/// {
+///     // This test will only run on macOS
+/// }
+/// 
+/// // Skip on all supported platforms (essentially always skips the test)
+/// [Test, ExcludeOn(OS.Windows | OS.Linux | OS.MacOs)]
+/// public void NeverRunTest()
+/// {
+///     // This test will not run on any supported platform
+/// }
+/// </code>
+/// </example>
+/// <seealso cref="SkipAttribute"/>
+/// <seealso cref="RunOnAttribute"/>
+/// <seealso cref="OS"/>
+public sealed class ExcludeOnAttribute(OS OperatingSystem) : SkipAttribute(GetReason(OperatingSystem))
+{
+    /// <inheritdoc />
+    public override Task<bool> ShouldSkip(BeforeTestContext context)
+    {
+        // Check if the current platform matches any of the excluded operating systems
+        bool shouldSkip =
+            (OperatingSystem.HasFlag(OS.Windows) && RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
+#if NET
+            // Only validate Linux and macOS on .NET 5+ where these OS flags are available
+            || (OperatingSystem.HasFlag(OS.Linux) && RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
+            || (OperatingSystem.HasFlag(OS.MacOs) && RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
+#endif
+            ;
+
+        // Return true if the test should be skipped (if we're on an excluded OS)
+        return Task.FromResult(shouldSkip);
+    }
+
+    private static string GetReason(OS operatingSystems)
+    {
+        var excludedOperatingSystems =
+#if NET
+            Enum.GetValues<OS>()
+#else
+            Enum.GetValues(typeof(OS)).Cast<OS>()
+#endif
+            .Where(os => operatingSystems.HasFlag(os))
+            .ToArray();
+
+        return $"The test is skipped because it is configured to not run on the current operating system: `{string.Join("`, `", excludedOperatingSystems)}`";
+    }
+}

TUnit.Core/Attributes/TestMetadata/RunOnAttribute.cs

@@ -0,0 +1,79 @@
+using System.Runtime.InteropServices;
+using TUnit.Core.Enums;
+
+namespace TUnit.Core;
+
+/// <summary>
+/// Attribute that restricts a test to run only on specific operating systems.
+/// </summary>
+/// <param name="OperatingSystem">
+/// Defines the operating systems on which the test should run.
+/// </param>
+/// <remarks>
+/// <para>
+/// The <see cref="RunOnAttribute"/> is used to specify that a test should only run on certain operating systems.
+/// Tests with this attribute will be skipped on operating systems that do not match the specified criteria.
+/// </para>
+/// <para>
+/// You can specify multiple operating systems by combining the <see cref="OS"/> enum values with the bitwise OR operator.
+/// </para>
+/// </remarks>
+/// <example>
+/// <code>
+/// // Run only on Windows
+/// [Test, RunOn(OS.Windows)]
+/// public void WindowsOnlyTest()
+/// {
+///     // This test will only run on Windows
+/// }
+/// 
+/// // Run on both Windows and Linux
+/// [Test, RunOn(OS.Windows | OS.Linux)]
+/// public void WindowsAndLinuxTest()
+/// {
+///     // This test will run on Windows and Linux, but not on macOS
+/// }
+/// 
+/// // Run on all supported platforms
+/// [Test, RunOn(OS.Windows | OS.Linux | OS.MacOs)]
+/// public void AllPlatformsTest()
+/// {
+///     // This test will run on all supported platforms
+/// }
+/// </code>
+/// </example>
+/// <seealso cref="SkipAttribute"/>
+/// <seealso cref="OS"/>
+public sealed class RunOnAttribute(OS OperatingSystem) : SkipAttribute(GetReason(OperatingSystem))
+{
+    /// <inheritdoc />
+    public override Task<bool> ShouldSkip(BeforeTestContext context)
+    {
+        // Check if the current platform matches any of the allowed operating systems
+        bool shouldRun =
+            (OperatingSystem.HasFlag(OS.Windows) && RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
+#if NET
+            // Only validate Linux and macOS on .NET 5+ where these OS flags are available
+            || (OperatingSystem.HasFlag(OS.Linux) && RuntimeInformation.IsOSPlatform(OSPlatform.Linux))
+            || (OperatingSystem.HasFlag(OS.MacOs) && RuntimeInformation.IsOSPlatform(OSPlatform.OSX))
+#endif
+            ;
+
+        // Return true if the test should be skipped (opposite of shouldRun)
+        return Task.FromResult(!shouldRun);
+    }
+
+    private static string GetReason(OS operatingSystems)
+    {
+        var selectedOperatingSystems =
+#if NET
+            Enum.GetValues<OS>()
+#else
+            Enum.GetValues(typeof(OS)).Cast<OS>()
+#endif
+            .Where(os => operatingSystems.HasFlag(os))
+            .ToArray();
+
+        return $"The test is skipped because it is configured to run on the current operating system: `{string.Join("`, `", selectedOperatingSystems)}`";
+    }
+}

TUnit.Core/Enums/OS.cs

@@ -0,0 +1,55 @@
+namespace TUnit.Core.Enums;
+
+/// <summary>
+/// Represents operating systems that can be specified for test execution constraints.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This enum is marked with the <see cref="FlagsAttribute"/>, which allows combining multiple operating systems
+/// using bitwise operations when used with attributes like <see cref="RunOnAttribute"/>.
+/// </para>
+/// <para>
+/// The primary use case is to restrict test execution to specific operating systems through
+/// the <see cref="RunOnAttribute"/>.
+/// </para>
+/// </remarks>
+/// <example>
+/// <code>
+/// // Specify a test should run only on Windows
+/// [RunOn(OS.Windows)]
+/// 
+/// // Specify a test should run on either Windows or Linux
+/// [RunOn(OS.Windows | OS.Linux)]
+/// 
+/// // Specify a test should run on all supported platforms
+/// [RunOn(OS.Windows | OS.Linux | OS.MacOs)]
+/// </code>
+/// </example>
+/// <seealso cref="RunOnAttribute"/>
+[Flags]
+public enum OS
+{
+    /// <summary>
+    /// Represents the Linux operating system.
+    /// </summary>
+    /// <remarks>
+    /// Tests with this flag will be executed on Linux platforms when used with <see cref="RunOnAttribute"/>.
+    /// </remarks>
+    Linux = 1,
+
+    /// <summary>
+    /// Represents the Windows operating system.
+    /// </summary>
+    /// <remarks>
+    /// Tests with this flag will be executed on Windows platforms when used with <see cref="RunOnAttribute"/>.
+    /// </remarks>
+    Windows = 2,
+
+    /// <summary>
+    /// Represents the macOS operating system.
+    /// </summary>
+    /// <remarks>
+    /// Tests with this flag will be executed on macOS platforms when used with <see cref="RunOnAttribute"/>.
+    /// </remarks>
+    MacOs = 4
+}