Skip to content

Commit 7ab0c10

Browse files
AArnottAArnott
committed
Build up the docfx site and create a package README
1 parent 2965bfa commit 7ab0c10

File tree

9 files changed

+180
-29
lines changed

9 files changed

+180
-29
lines changed

‎README.md

Lines changed: 15 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -4,57 +4,49 @@ Xunit.SkippableFact
44
[![GitHub Actions status](https://github.com/aarnott/Library.Template/workflows/CI/badge.svg)](https://github.com/AArnott/Xunit.SkippableFact/actions/workflows/build.yml)
55
[![NuGet package](https://img.shields.io/nuget/v/xunit.skippablefact.svg)](https://nuget.org/packages/xunit.skippablefact)
66

7-
This project allows for Xunit tests that can determine during execution
8-
that they should report a "skipped" result. This can be useful when
9-
a precondition is not satisfied, or the test is over functionality that
10-
does not exist on the platform being tested.
7+
This project allows for Xunit tests that can determine during execution that they should report a "skipped" result.
8+
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.
119

1210
## Installation
1311

1412
This project is available as a [NuGet package][NuPkg]
1513

16-
## Example
14+
## Usage
15+
16+
[Learn more at our documentation site](https://aarnott.github.io/Xunit.SkippableFact/).
17+
18+
Below is a sampling of uses.
19+
20+
Skip based on a runtime check:
1721

1822
```csharp
1923
[SkippableFact]
20-
public void SomeTestForWindowsOnly()
24+
public void SomeMoodyTest()
2125
{
22-
Skip.IfNot(Environment.IsWindows);
23-
24-
// Test Windows only functionality.
26+
Skip.IfNot(InTheMood);
2527
}
2628
```
2729

28-
You can also automatically report tests as skipped based on specific exception types.
29-
This is particularly useful when the test runs against multiple target frameworks and
30-
your library is not expected to be implemented in some of them. For example:
30+
Skip based on a thrown exception:
3131

3232
```csharp
33-
[SkippableFact(typeof(NotSupportedException), typeof(NotImplementedException))]
33+
[SkippableFact(typeof(NotSupportedException))]
3434
public void TestFunctionalityWhichIsNotSupportedOnSomePlatforms()
3535
{
3636
// Test functionality. If it throws any of the exceptions listed in the attribute,
3737
// a skip result is reported instead of a failure.
3838
}
3939
```
4040

41-
## The `[SupportedOSPlatform]` attribute
42-
43-
Since version 1.5, `Xunit.SkippableFact` understands the `SupportedOSPlatform` attribute to skip tests on unsupported platforms.
41+
Skip based on `SupportedOSPlatformAttribute`:
4442

4543
```csharp
4644
[SkippableFact, SupportedOSPlatform("Windows")]
4745
public void TestCngKey()
4846
{
49-
var key = CngKey.Create(CngAlgorithm.Sha256);
47+
var key = CngKey.Create(CngAlgorithm.Rsa);
5048
Assert.NotNull(key);
5149
}
5250
```
5351

54-
Without `[SupportedOSPlatform("Windows")]` the [CA1416][CA1416] code analysis warning would trigger:
55-
> This call site is reachable on all platforms. 'CngKey. Create(CngAlgorithm)' is only supported on: 'windows'.
56-
57-
Adding `[SupportedOSPlatform("Windows")]` both suppresses this platform compatibility warning and skips the test when running on Linux or macOS.
58-
5952
[NuPkg]: https://www.nuget.org/packages/Xunit.SkippableFact
60-
[CA1416]: https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca1416

‎Xunit.SkippableFact.sln

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Microsoft Visual Studio Solution File, Format Version 12.00
1+
Microsoft Visual Studio Solution File, Format Version 12.00
22
# Visual Studio 15
33
VisualStudioVersion = 15.0.26228.9
44
MinimumVisualStudioVersion = 10.0.40219.1
@@ -22,6 +22,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
2222
EndProject
2323
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Xunit.SkippableFact.Tests", "test\Xunit.SkippableFact.Tests\Xunit.SkippableFact.Tests.csproj", "{B6E55EBE-4D2D-48DE-97AF-6058169B517D}"
2424
EndProject
25+
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Samples", "samples\Samples.csproj", "{115DBEC6-9D00-4070-82C3-C17D3F508EE0}"
26+
EndProject
2527
Global
2628
GlobalSection(SolutionConfigurationPlatforms) = preSolution
2729
Debug|Any CPU = Debug|Any CPU
@@ -36,6 +38,10 @@ Global
3638
{B6E55EBE-4D2D-48DE-97AF-6058169B517D}.Debug|Any CPU.Build.0 = Debug|Any CPU
3739
{B6E55EBE-4D2D-48DE-97AF-6058169B517D}.Release|Any CPU.ActiveCfg = Release|Any CPU
3840
{B6E55EBE-4D2D-48DE-97AF-6058169B517D}.Release|Any CPU.Build.0 = Release|Any CPU
41+
{115DBEC6-9D00-4070-82C3-C17D3F508EE0}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
42+
{115DBEC6-9D00-4070-82C3-C17D3F508EE0}.Debug|Any CPU.Build.0 = Debug|Any CPU
43+
{115DBEC6-9D00-4070-82C3-C17D3F508EE0}.Release|Any CPU.ActiveCfg = Release|Any CPU
44+
{115DBEC6-9D00-4070-82C3-C17D3F508EE0}.Release|Any CPU.Build.0 = Release|Any CPU
3945
EndGlobalSection
4046
GlobalSection(SolutionProperties) = preSolution
4147
HideSolutionNode = FALSE

‎docfx/docs/features.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
11
# Features
22

3-
TODO
3+
* 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.
4+
* 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.
5+
* Support for skipping facts or individual test cases in theories.
6+
* Optionally provide the reason for a test being skipped for inclusion in the test log.

‎docfx/docs/getting-started.md

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,40 @@
55
Consume this library via its NuGet Package.
66
Click on the badge to find its latest version and the instructions for consuming it that best apply to your project.
77

8-
[![NuGet package](https://img.shields.io/nuget/v/Library.svg)](https://nuget.org/packages/Library)
8+
[![NuGet package](https://img.shields.io/nuget/v/Xunit.SkippableFact.svg)](https://nuget.org/packages/Xunit.SkippableFact)
99

1010
## Usage
1111

12-
TODO
12+
Always use the @Xunit.SkippableFactAttribute or @Xunit.SkippableTheoryAttribute on test methods that you want to potentially skip for.
13+
14+
### Conditional runtime skipping
15+
16+
Use methods on the @Xunit.Skip class to skip a test based on some runtime check.
17+
18+
This can be useful when you need to test for specific runtime conditions.
19+
It can also be useful to skip certain test cases in a theory when input combinations are invalid.
20+
21+
[!code-csharp[](../../samples/GettingStarted.cs#RuntimeCheck)]
22+
23+
### Exceptions thrown
24+
25+
You can also automatically report tests as skipped based on specific exception types.
26+
This is particularly useful when the test runs against multiple target frameworks and
27+
your library is not expected to be implemented in some of them. For example:
28+
29+
[!code-csharp[](../../samples/GettingStarted.cs#ThrownExceptions)]
30+
31+
### Supported platforms
32+
33+
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.
34+
35+
[!code-csharp[](../../samples/GettingStarted.cs#OSCheck)]
36+
37+
Without `[SupportedOSPlatform("Windows")]` the [CA1416][CA1416] code analysis warning would trigger:
38+
39+
> This call site is reachable on all platforms. 'CngKey. Create(CngAlgorithm)' is only supported on: 'windows'.
40+
41+
Adding `[SupportedOSPlatform("Windows")]` both suppresses this platform compatibility warning and skips the test when running on Linux or macOS.
42+
43+
[NuPkg]: https://www.nuget.org/packages/Xunit.SkippableFact
44+
[CA1416]: https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca1416

‎docfx/index.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ _layout: landing
44

55
# Overview
66

7-
This is your docfx landing page.
7+
This project allows for Xunit tests that can determine during execution that they should report a "skipped" result.
8+
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.
89

9-
Click "Docs" across the top to get get started.
10+
Click "Docs" across the top to get started.

‎samples/.editorconfig

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
[*.cs]
2+
3+
# SA1123: Do not place regions within elements
4+
dotnet_diagnostic.SA1123.severity = none
5+
6+
# SA1124: Do not use regions
7+
dotnet_diagnostic.SA1124.severity = none
8+
9+
# SA1133: Do not combine attributes
10+
dotnet_diagnostic.SA1133.severity = silent
11+
12+
# SA1200: Using directives should be placed correctly
13+
dotnet_diagnostic.SA1200.severity = none
14+
15+
# SA1201: Elements should appear in the correct order
16+
dotnet_diagnostic.SA1201.severity = silent
17+
18+
# SA1205: Partial elements should declare access
19+
dotnet_diagnostic.SA1205.severity = none
20+
21+
# SA1400: Access modifier should be declared
22+
dotnet_diagnostic.SA1400.severity = none
23+
24+
# SA1402: File may only contains a single type
25+
dotnet_diagnostic.SA1402.severity = none
26+
27+
# SA1403: File may only contain a single namespace
28+
dotnet_diagnostic.SA1403.severity = none
29+
30+
# SA1502: Element should not be on a single line
31+
dotnet_diagnostic.SA1502.severity = none
32+
33+
# SA1515: Single-line comment should be preceded by blank line
34+
dotnet_diagnostic.SA1515.severity = none
35+
36+
# SA1516: Elements should be separated by blank line
37+
dotnet_diagnostic.SA1516.severity = none
38+
39+
# SA1600: Elements should be documented
40+
dotnet_diagnostic.SA1600.severity = silent
41+
42+
# SA1601: Partial elements should be documented
43+
dotnet_diagnostic.SA1601.severity = silent
44+
45+
# SA1649: File name should match first type name
46+
dotnet_diagnostic.SA1649.severity = none
47+
48+
# IDE0051: Remove unused private members
49+
dotnet_diagnostic.IDE0051.severity = none
50+
51+
# CS1591: Missing XML comment for publicly visible type or member
52+
dotnet_diagnostic.CS1591.severity = silent
53+
54+
# CA1822: Mark members as static
55+
dotnet_diagnostic.CA1822.severity = silent

‎samples/GettingStarted.cs

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// Copyright (c) Andrew Arnott. All rights reserved.
2+
// Licensed under the Microsoft Public License (Ms-PL). See LICENSE.txt file in the project root for full license information.
3+
4+
using System.Runtime.InteropServices;
5+
using System.Runtime.Versioning;
6+
using System.Security.Cryptography;
7+
using Xunit;
8+
9+
public class GettingStarted
10+
{
11+
#region RuntimeCheck
12+
[SkippableFact]
13+
public void RuntimeCheck()
14+
{
15+
Skip.IfNot(Environment.GetEnvironmentVariable("RunThisTest") == "true");
16+
}
17+
#endregion
18+
19+
#region ThrownExceptions
20+
[SkippableFact(typeof(NotSupportedException), typeof(NotImplementedException))]
21+
public void TestFunctionalityWhichIsNotSupportedOnSomePlatforms()
22+
{
23+
// Test functionality. If it throws any of the exceptions listed in the attribute,
24+
// a skip result is reported instead of a failure.
25+
}
26+
#endregion
27+
28+
#region OSCheck
29+
[SkippableFact, SupportedOSPlatform("Windows")]
30+
public void TestCngKey()
31+
{
32+
var key = CngKey.Create(CngAlgorithm.Rsa);
33+
Assert.NotNull(key);
34+
}
35+
#endregion
36+
}

‎samples/Samples.csproj

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<Project Sdk="Microsoft.NET.Sdk">
2+
3+
<PropertyGroup>
4+
<TargetFramework>net9.0</TargetFramework>
5+
<IsPackable>false</IsPackable>
6+
</PropertyGroup>
7+
8+
<ItemGroup>
9+
<ProjectReference Include="..\src\Xunit.SkippableFact\Xunit.SkippableFact.csproj" />
10+
</ItemGroup>
11+
12+
<ItemGroup>
13+
<PackageReference Include="Microsoft.NET.Test.Sdk" />
14+
<PackageReference Include="xunit" />
15+
<PackageReference Include="xunit.runner.visualstudio" />
16+
</ItemGroup>
17+
18+
</Project>

‎src/Xunit.SkippableFact/README.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Xunit.SkippableFact
2+
3+
This library allows for Xunit tests that can determine during execution that they should report a "skipped" result.
4+
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.
5+
6+
Use `[SkippableFact]` or `[SkippableTheory]` to make a test skippable.
7+
8+
[Learn more at our documentation site](https://aarnott.github.io/Xunit.SkippableFact/).

0 commit comments

Comments
 (0)