diff --git a/README.md b/README.md index a4f0b0e..47ef35f 100644 --- a/README.md +++ b/README.md @@ -4,33 +4,33 @@ Xunit.SkippableFact [![GitHub Actions status](https://github.com/aarnott/Library.Template/workflows/CI/badge.svg)](https://github.com/AArnott/Xunit.SkippableFact/actions/workflows/build.yml) [![NuGet package](https://img.shields.io/nuget/v/xunit.skippablefact.svg)](https://nuget.org/packages/xunit.skippablefact) -This project allows for Xunit tests that can determine during execution -that they should report a "skipped" result. This can be useful when -a precondition is not satisfied, or the test is over functionality that -does not exist on the platform being tested. +This project allows for Xunit tests that can determine during execution that they should report a "skipped" result. +This can be useful when a precondition is not satisfied, or the test is over functionality that does not exist on the platform being tested. ## Installation This project is available as a [NuGet package][NuPkg] -## Example +## Usage + +[Learn more at our documentation site](https://aarnott.github.io/Xunit.SkippableFact/). + +Below is a sampling of uses. + +Skip based on a runtime check: ```csharp [SkippableFact] -public void SomeTestForWindowsOnly() +public void SomeMoodyTest() { - Skip.IfNot(Environment.IsWindows); - - // Test Windows only functionality. + Skip.IfNot(InTheMood); } ``` -You can also automatically report tests as skipped based on specific exception types. -This is particularly useful when the test runs against multiple target frameworks and -your library is not expected to be implemented in some of them. For example: +Skip based on a thrown exception: ```csharp -[SkippableFact(typeof(NotSupportedException), typeof(NotImplementedException))] +[SkippableFact(typeof(NotSupportedException))] public void TestFunctionalityWhichIsNotSupportedOnSomePlatforms() { // Test functionality. If it throws any of the exceptions listed in the attribute, @@ -38,23 +38,15 @@ public void TestFunctionalityWhichIsNotSupportedOnSomePlatforms() } ``` -## The `[SupportedOSPlatform]` attribute - -Since version 1.5, `Xunit.SkippableFact` understands the `SupportedOSPlatform` attribute to skip tests on unsupported platforms. +Skip based on `SupportedOSPlatformAttribute`: ```csharp [SkippableFact, SupportedOSPlatform("Windows")] public void TestCngKey() { - var key = CngKey.Create(CngAlgorithm.Sha256); + var key = CngKey.Create(CngAlgorithm.Rsa); Assert.NotNull(key); } ``` -Without `[SupportedOSPlatform("Windows")]` the [CA1416][CA1416] code analysis warning would trigger: -> This call site is reachable on all platforms. 'CngKey. Create(CngAlgorithm)' is only supported on: 'windows'. - -Adding `[SupportedOSPlatform("Windows")]` both suppresses this platform compatibility warning and skips the test when running on Linux or macOS. - [NuPkg]: https://www.nuget.org/packages/Xunit.SkippableFact -[CA1416]: https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca1416 diff --git a/Xunit.SkippableFact.sln b/Xunit.SkippableFact.sln index c59595b..c02a3f9 100644 --- a/Xunit.SkippableFact.sln +++ b/Xunit.SkippableFact.sln @@ -1,4 +1,4 @@ -Microsoft Visual Studio Solution File, Format Version 12.00 +Microsoft Visual Studio Solution File, Format Version 12.00 # Visual Studio 15 VisualStudioVersion = 15.0.26228.9 MinimumVisualStudioVersion = 10.0.40219.1 @@ -22,6 +22,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution EndProject Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Xunit.SkippableFact.Tests", "test\Xunit.SkippableFact.Tests\Xunit.SkippableFact.Tests.csproj", "{B6E55EBE-4D2D-48DE-97AF-6058169B517D}" EndProject +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Samples", "samples\Samples.csproj", "{115DBEC6-9D00-4070-82C3-C17D3F508EE0}" +EndProject Global GlobalSection(SolutionConfigurationPlatforms) = preSolution Debug|Any CPU = Debug|Any CPU @@ -36,6 +38,10 @@ Global {B6E55EBE-4D2D-48DE-97AF-6058169B517D}.Debug|Any CPU.Build.0 = Debug|Any CPU {B6E55EBE-4D2D-48DE-97AF-6058169B517D}.Release|Any CPU.ActiveCfg = Release|Any CPU {B6E55EBE-4D2D-48DE-97AF-6058169B517D}.Release|Any CPU.Build.0 = Release|Any CPU + {115DBEC6-9D00-4070-82C3-C17D3F508EE0}.Debug|Any CPU.ActiveCfg = Debug|Any CPU + {115DBEC6-9D00-4070-82C3-C17D3F508EE0}.Debug|Any CPU.Build.0 = Debug|Any CPU + {115DBEC6-9D00-4070-82C3-C17D3F508EE0}.Release|Any CPU.ActiveCfg = Release|Any CPU + {115DBEC6-9D00-4070-82C3-C17D3F508EE0}.Release|Any CPU.Build.0 = Release|Any CPU EndGlobalSection GlobalSection(SolutionProperties) = preSolution HideSolutionNode = FALSE diff --git a/docfx/docs/features.md b/docfx/docs/features.md index eb3fbeb..258ca2c 100644 --- a/docfx/docs/features.md +++ b/docfx/docs/features.md @@ -1,3 +1,6 @@ # Features -TODO +* Report tests as skipped instead of as pass or fail when the inputs, the operating system, or other factors render the test invalid or not applicable. +* A test result can be "Skipped" based on a runtime check within the test, an attribute on the test method, or a throwing one or more particular exceptions. +* Support for skipping facts or individual test cases in theories. +* Optionally provide the reason for a test being skipped for inclusion in the test log. diff --git a/docfx/docs/getting-started.md b/docfx/docs/getting-started.md index eff2c2f..89c7089 100644 --- a/docfx/docs/getting-started.md +++ b/docfx/docs/getting-started.md @@ -5,8 +5,40 @@ Consume this library via its NuGet Package. Click on the badge to find its latest version and the instructions for consuming it that best apply to your project. -[![NuGet package](https://img.shields.io/nuget/v/Library.svg)](https://nuget.org/packages/Library) +[![NuGet package](https://img.shields.io/nuget/v/Xunit.SkippableFact.svg)](https://nuget.org/packages/Xunit.SkippableFact) ## Usage -TODO +Always use the @Xunit.SkippableFactAttribute or @Xunit.SkippableTheoryAttribute on test methods that you want to potentially skip for. + +### Conditional runtime skipping + +Use methods on the @Xunit.Skip class to skip a test based on some runtime check. + +This can be useful when you need to test for specific runtime conditions. +It can also be useful to skip certain test cases in a theory when input combinations are invalid. + +[!code-csharp[](../../samples/GettingStarted.cs#RuntimeCheck)] + +### Exceptions thrown + +You can also automatically report tests as skipped based on specific exception types. +This is particularly useful when the test runs against multiple target frameworks and +your library is not expected to be implemented in some of them. For example: + +[!code-csharp[](../../samples/GettingStarted.cs#ThrownExceptions)] + +### Supported platforms + +Apply the @System.Runtime.Versioning.SupportedOSPlatformAttribute and/or @System.Runtime.Versioning.UnsupportedOSPlatformAttribute to a test method to skip it based on the platform the test is running on. + +[!code-csharp[](../../samples/GettingStarted.cs#OSCheck)] + +Without `[SupportedOSPlatform("Windows")]` the [CA1416][CA1416] code analysis warning would trigger: + +> This call site is reachable on all platforms. 'CngKey. Create(CngAlgorithm)' is only supported on: 'windows'. + +Adding `[SupportedOSPlatform("Windows")]` both suppresses this platform compatibility warning and skips the test when running on Linux or macOS. + +[NuPkg]: https://www.nuget.org/packages/Xunit.SkippableFact +[CA1416]: https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca1416 diff --git a/docfx/index.md b/docfx/index.md index fc1b9e2..f667215 100644 --- a/docfx/index.md +++ b/docfx/index.md @@ -4,6 +4,7 @@ _layout: landing # Overview -This is your docfx landing page. +This project allows for Xunit tests that can determine during execution that they should report a "skipped" result. +This can be useful when a precondition is not satisfied, or the test is over functionality that does not exist on the platform being tested. -Click "Docs" across the top to get get started. +Click "Docs" across the top to get started. diff --git a/samples/.editorconfig b/samples/.editorconfig new file mode 100644 index 0000000..d4e0446 --- /dev/null +++ b/samples/.editorconfig @@ -0,0 +1,55 @@ +[*.cs] + +# SA1123: Do not place regions within elements +dotnet_diagnostic.SA1123.severity = none + +# SA1124: Do not use regions +dotnet_diagnostic.SA1124.severity = none + +# SA1133: Do not combine attributes +dotnet_diagnostic.SA1133.severity = silent + +# SA1200: Using directives should be placed correctly +dotnet_diagnostic.SA1200.severity = none + +# SA1201: Elements should appear in the correct order +dotnet_diagnostic.SA1201.severity = silent + +# SA1205: Partial elements should declare access +dotnet_diagnostic.SA1205.severity = none + +# SA1400: Access modifier should be declared +dotnet_diagnostic.SA1400.severity = none + +# SA1402: File may only contains a single type +dotnet_diagnostic.SA1402.severity = none + +# SA1403: File may only contain a single namespace +dotnet_diagnostic.SA1403.severity = none + +# SA1502: Element should not be on a single line +dotnet_diagnostic.SA1502.severity = none + +# SA1515: Single-line comment should be preceded by blank line +dotnet_diagnostic.SA1515.severity = none + +# SA1516: Elements should be separated by blank line +dotnet_diagnostic.SA1516.severity = none + +# SA1600: Elements should be documented +dotnet_diagnostic.SA1600.severity = silent + +# SA1601: Partial elements should be documented +dotnet_diagnostic.SA1601.severity = silent + +# SA1649: File name should match first type name +dotnet_diagnostic.SA1649.severity = none + +# IDE0051: Remove unused private members +dotnet_diagnostic.IDE0051.severity = none + +# CS1591: Missing XML comment for publicly visible type or member +dotnet_diagnostic.CS1591.severity = silent + +# CA1822: Mark members as static +dotnet_diagnostic.CA1822.severity = silent diff --git a/samples/GettingStarted.cs b/samples/GettingStarted.cs new file mode 100644 index 0000000..a794d4e --- /dev/null +++ b/samples/GettingStarted.cs @@ -0,0 +1,36 @@ +// Copyright (c) Andrew Arnott. All rights reserved. +// Licensed under the Microsoft Public License (Ms-PL). See LICENSE.txt file in the project root for full license information. + +using System.Runtime.InteropServices; +using System.Runtime.Versioning; +using System.Security.Cryptography; +using Xunit; + +public class GettingStarted +{ + #region RuntimeCheck + [SkippableFact] + public void RuntimeCheck() + { + Skip.IfNot(Environment.GetEnvironmentVariable("RunThisTest") == "true"); + } + #endregion + + #region ThrownExceptions + [SkippableFact(typeof(NotSupportedException), typeof(NotImplementedException))] + public void TestFunctionalityWhichIsNotSupportedOnSomePlatforms() + { + // Test functionality. If it throws any of the exceptions listed in the attribute, + // a skip result is reported instead of a failure. + } + #endregion + + #region OSCheck + [SkippableFact, SupportedOSPlatform("Windows")] + public void TestCngKey() + { + var key = CngKey.Create(CngAlgorithm.Rsa); + Assert.NotNull(key); + } + #endregion +} diff --git a/samples/Samples.csproj b/samples/Samples.csproj new file mode 100644 index 0000000..b0484bb --- /dev/null +++ b/samples/Samples.csproj @@ -0,0 +1,18 @@ + + + + net9.0 + false + + + + + + + + + + + + + diff --git a/src/Xunit.SkippableFact/README.md b/src/Xunit.SkippableFact/README.md new file mode 100644 index 0000000..fd6f3b1 --- /dev/null +++ b/src/Xunit.SkippableFact/README.md @@ -0,0 +1,8 @@ +# Xunit.SkippableFact + +This library allows for Xunit tests that can determine during execution that they should report a "skipped" result. +This can be useful when a precondition is not satisfied, or the test is over functionality that does not exist on the platform being tested. + +Use `[SkippableFact]` or `[SkippableTheory]` to make a test skippable. + +[Learn more at our documentation site](https://aarnott.github.io/Xunit.SkippableFact/).