Skip to content

Commit 3ef4017

Browse files
SimonCroppSimonCropp
committed
docs
1 parent e20cbe1 commit 3ef4017

File tree

12 files changed

+257
-20
lines changed

12 files changed

+257
-20
lines changed

‎docs/dangling-files.md

+159
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
<!--
2+
GENERATED FILE - DO NOT EDIT
3+
This file was generated by [MarkdownSnippets](https://github.com/SimonCropp/MarkdownSnippets).
4+
Source File: /docs/mdsource/dangling-files.source.md
5+
To change this file edit the source file and then run MarkdownSnippets.
6+
-->
7+
8+
# Dangling snapshot files
9+
10+
A dangling snapshot file are when `.verified.` file exist with no corresponding test. This can occur when a test, with corresponding test snapshot file(s), is renamed or deleted. The snapshot file are now redundant and noise on the file system and in the solution explorer
11+
12+
13+
## How dangling snapshot checks works
14+
15+
* When each test is executed, any snapshots produced are recorded.
16+
* After all tests are executed, all recorded snapshots are checked against the snapshots that exist on disk
17+
* An exception is thrown if any files:
18+
* exist on disk and do not have a corresponding recorded test
19+
* have casing that does not match the test case
20+
21+
22+
## Experimental
23+
24+
`DanglingSnapshots` is an experimental feature (marked with `[Experimental("VerifyDanglingSnapshots")]`) and is subject to change in minor version.
25+
26+
To use it requires the `VerifyDanglingSnapshots` warning to to be disabled using a `pragma warning disable`:
27+
28+
```
29+
#pragma warning disable VerifyDanglingSnapshots
30+
```
31+
32+
33+
## Only in CI
34+
35+
When running tests locally, it is not possible to detect if all tests are being run, or only a subset. As such `DanglingSnapshots.Run()` will only perform checks when executed on a build server.
36+
37+
38+
## Usage
39+
40+
In the tear-down of a test run (after all test have run), call `DanglingSnapshots.Run()`.
41+
42+
43+
### MSTest
44+
45+
Use the `[AssemblyCleanup]` feature:
46+
47+
<!-- snippet: DanglingSnapshotsMSTestUsage/DanglingSnapshots.cs -->
48+
<a id='snippet-DanglingSnapshotsMSTestUsage/DanglingSnapshots.cs'></a>
49+
```cs
50+
#pragma warning disable VerifyDanglingSnapshots
51+
[TestClass]
52+
public static class Cleanup
53+
{
54+
[AssemblyCleanup]
55+
public static void Run() =>
56+
DanglingSnapshots.Run();
57+
}
58+
```
59+
<sup><a href='/src/DanglingSnapshotsMSTestUsage/DanglingSnapshots.cs#L1-L8' title='Snippet source file'>snippet source</a> | <a href='#snippet-DanglingSnapshotsMSTestUsage/DanglingSnapshots.cs' title='Start of snippet'>anchor</a></sup>
60+
<!-- endSnippet -->
61+
62+
63+
### NUnit
64+
65+
use the `[OneTimeTearDown]` feature:
66+
67+
<!-- snippet: DanglingSnapshotsNUnitUsage/DanglingSnapshots.cs -->
68+
<a id='snippet-DanglingSnapshotsNUnitUsage/DanglingSnapshots.cs'></a>
69+
```cs
70+
#pragma warning disable VerifyDanglingSnapshots
71+
72+
[SetUpFixture]
73+
public static class SetUp
74+
{
75+
[OneTimeTearDown]
76+
public static void Run() =>
77+
DanglingSnapshots.Run();
78+
}
79+
```
80+
<sup><a href='/src/DanglingSnapshotsNUnitUsage/DanglingSnapshots.cs#L1-L9' title='Snippet source file'>snippet source</a> | <a href='#snippet-DanglingSnapshotsNUnitUsage/DanglingSnapshots.cs' title='Start of snippet'>anchor</a></sup>
81+
<!-- endSnippet -->
82+
83+
84+
### XUnit
85+
86+
Define an XUnit collection:
87+
88+
<!-- snippet: DanglingSnapshotsXUnitUsage/DanglingSnapshots.cs -->
89+
<a id='snippet-DanglingSnapshotsXUnitUsage/DanglingSnapshots.cs'></a>
90+
```cs
91+
#pragma warning disable VerifyDanglingSnapshots
92+
93+
[CollectionDefinition(nameof(SharedFixtureCollection))]
94+
public class SharedFixtureCollection :
95+
ICollectionFixture<SharedFixture>;
96+
97+
public sealed class SharedFixture :
98+
IDisposable
99+
{
100+
public void Dispose() =>
101+
DanglingSnapshots.Run();
102+
}
103+
```
104+
<sup><a href='/src/DanglingSnapshotsXunitUsage/DanglingSnapshots.cs#L1-L12' title='Snippet source file'>snippet source</a> | <a href='#snippet-DanglingSnapshotsXUnitUsage/DanglingSnapshots.cs' title='Start of snippet'>anchor</a></sup>
105+
<!-- endSnippet -->
106+
107+
Apply that collection to all tests:
108+
109+
<!-- snippet: XunitDanglingCollection -->
110+
<a id='snippet-XunitDanglingCollection'></a>
111+
```cs
112+
[Collection(nameof(SharedFixtureCollection))]
113+
public class Tests
114+
{
115+
[Fact]
116+
public Task Simple() =>
117+
Verify("Foo");
118+
```
119+
<sup><a href='/src/DanglingSnapshotsXunitUsage/Tests.cs#L1-L8' title='Snippet source file'>snippet source</a> | <a href='#snippet-XunitDanglingCollection' title='Start of snippet'>anchor</a></sup>
120+
<!-- endSnippet -->
121+
122+
123+
### XUnitV3
124+
125+
Define an XUnit collection:
126+
127+
<!-- snippet: DanglingSnapshotsXUnitV3Usage/DanglingSnapshots.cs -->
128+
<a id='snippet-DanglingSnapshotsXUnitV3Usage/DanglingSnapshots.cs'></a>
129+
```cs
130+
#pragma warning disable VerifyDanglingSnapshots
131+
132+
[CollectionDefinition(nameof(SharedFixtureCollection))]
133+
public class SharedFixtureCollection :
134+
ICollectionFixture<SharedFixture>;
135+
136+
public sealed class SharedFixture :
137+
IDisposable
138+
{
139+
public void Dispose() =>
140+
DanglingSnapshots.Run();
141+
}
142+
```
143+
<sup><a href='/src/DanglingSnapshotsXunitV3Usage/DanglingSnapshots.cs#L1-L12' title='Snippet source file'>snippet source</a> | <a href='#snippet-DanglingSnapshotsXUnitV3Usage/DanglingSnapshots.cs' title='Start of snippet'>anchor</a></sup>
144+
<!-- endSnippet -->
145+
146+
Apply that collection to all tests:
147+
148+
<!-- snippet: XunitV3DanglingCollection -->
149+
<a id='snippet-XunitV3DanglingCollection'></a>
150+
```cs
151+
[Collection(nameof(SharedFixtureCollection))]
152+
public class Tests
153+
{
154+
[Fact]
155+
public Task Simple() =>
156+
Verify("Foo");
157+
```
158+
<sup><a href='/src/DanglingSnapshotsXunitV3Usage/Tests.cs#L1-L8' title='Snippet source file'>snippet source</a> | <a href='#snippet-XunitV3DanglingCollection' title='Start of snippet'>anchor</a></sup>
159+
<!-- endSnippet -->

‎docs/mdsource/dangling-files.source.md

+69
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Dangling snapshot files
2+
3+
A dangling snapshot file are when `.verified.` file exist with no corresponding test. This can occur when a test, with corresponding test snapshot file(s), is renamed or deleted. The snapshot file are now redundant and noise on the file system and in the solution explorer
4+
5+
6+
## How dangling snapshot checks works
7+
8+
* When each test is executed, any snapshots produced are recorded.
9+
* After all tests are executed, all recorded snapshots are checked against the snapshots that exist on disk
10+
* An exception is thrown if any files:
11+
* exist on disk and do not have a corresponding recorded test
12+
* have casing that does not match the test case
13+
14+
15+
## Experimental
16+
17+
`DanglingSnapshots` is an experimental feature (marked with `[Experimental("VerifyDanglingSnapshots")]`) and is subject to change in minor version.
18+
19+
To use it requires the `VerifyDanglingSnapshots` warning to to be disabled using a `pragma warning disable`:
20+
21+
```
22+
#pragma warning disable VerifyDanglingSnapshots
23+
```
24+
25+
26+
## Only in CI
27+
28+
When running tests locally, it is not possible to detect if all tests are being run, or only a subset. As such `DanglingSnapshots.Run()` will only perform checks when executed on a build server.
29+
30+
31+
## Usage
32+
33+
In the tear-down of a test run (after all test have run), call `DanglingSnapshots.Run()`.
34+
35+
36+
### MSTest
37+
38+
Use the `[AssemblyCleanup]` feature:
39+
40+
snippet: DanglingSnapshotsMSTestUsage/DanglingSnapshots.cs
41+
42+
43+
### NUnit
44+
45+
use the `[OneTimeTearDown]` feature:
46+
47+
snippet: DanglingSnapshotsNUnitUsage/DanglingSnapshots.cs
48+
49+
50+
### XUnit
51+
52+
Define an XUnit collection:
53+
54+
snippet: DanglingSnapshotsXUnitUsage/DanglingSnapshots.cs
55+
56+
Apply that collection to all tests:
57+
58+
snippet: XunitDanglingCollection
59+
60+
61+
### XUnitV3
62+
63+
Define an XUnit collection:
64+
65+
snippet: DanglingSnapshotsXUnitV3Usage/DanglingSnapshots.cs
66+
67+
Apply that collection to all tests:
68+
69+
snippet: XunitV3DanglingCollection

‎src/DanglingSnapshotsMSTestUsage/DanglingSnapshots.cs

+2-3
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
1-
[TestClass]
1+
#pragma warning disable VerifyDanglingSnapshots
2+
[TestClass]
23
public static class Cleanup
34
{
45
[AssemblyCleanup]
56
public static void Run() =>
6-
#pragma warning disable VerifyDanglingSnapshots
77
DanglingSnapshots.Run();
8-
#pragma warning restore VerifyDanglingSnapshots
98
}

‎src/DanglingSnapshotsMSTestUsage/Tests.cs

-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
[TestClass]
2-
[UsesVerify]
32
public partial class Tests
43
{
54
[TestMethod]

‎src/DanglingSnapshotsNUnitUsage/DanglingSnapshots.cs

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
[SetUpFixture]
2-
static class SetUp
1+
#pragma warning disable VerifyDanglingSnapshots
2+
3+
[SetUpFixture]
4+
public static class SetUp
35
{
46
[OneTimeTearDown]
57
public static void Run() =>
6-
#pragma warning disable VerifyDanglingSnapshots
78
DanglingSnapshots.Run();
8-
#pragma warning restore VerifyDanglingSnapshots
99
}

‎src/DanglingSnapshotsXunitUsage/DanglingSnapshots.cs

+5-4
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
1-
[CollectionDefinition(nameof(SharedFixtureCollection))]
1+
#pragma warning disable VerifyDanglingSnapshots
2+
3+
[CollectionDefinition(nameof(SharedFixtureCollection))]
24
public class SharedFixtureCollection :
35
ICollectionFixture<SharedFixture>;
46

57
public sealed class SharedFixture :
68
IDisposable
79
{
8-
#pragma warning disable VerifyDanglingSnapshots
9-
public void Dispose() => DanglingSnapshots.Run();
10-
#pragma warning restore VerifyDanglingSnapshots
10+
public void Dispose() =>
11+
DanglingSnapshots.Run();
1112
}

‎src/DanglingSnapshotsXunitUsage/Tests.cs

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
1-
[Collection(nameof(SharedFixtureCollection))]
1+
#region XunitDanglingCollection
2+
[Collection(nameof(SharedFixtureCollection))]
23
public class Tests
34
{
45
[Fact]
56
public Task Simple() =>
67
Verify("Foo");
8+
#endregion
79

810
[Fact]
911
public Task IncorrectCase() =>

‎src/DanglingSnapshotsXunitV3Usage/DanglingSnapshots.cs

+5-4
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
1-
[CollectionDefinition(nameof(SharedFixtureCollection))]
1+
#pragma warning disable VerifyDanglingSnapshots
2+
3+
[CollectionDefinition(nameof(SharedFixtureCollection))]
24
public class SharedFixtureCollection :
35
ICollectionFixture<SharedFixture>;
46

57
public sealed class SharedFixture :
68
IDisposable
79
{
8-
#pragma warning disable VerifyDanglingSnapshots
9-
public void Dispose() => DanglingSnapshots.Run();
10-
#pragma warning restore VerifyDanglingSnapshots
10+
public void Dispose() =>
11+
DanglingSnapshots.Run();
1112
}

‎src/DanglingSnapshotsXunitV3Usage/Tests.cs

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
1-
[Collection(nameof(SharedFixtureCollection))]
1+
#region XunitV3DanglingCollection
2+
[Collection(nameof(SharedFixtureCollection))]
23
public class Tests
34
{
45
[Fact]
56
public Task Simple() =>
67
Verify("Foo");
8+
#endregion
79

810
[Fact]
911
public Task IncorrectCase() =>

‎src/Directory.Build.props

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<Project>
33
<PropertyGroup>
4-
<Version>28.14.0-beta.7</Version>
4+
<Version>28.14.0</Version>
55
<NoWarn>CA1822;CS1591;CS0649;xUnit1026;xUnit1013;CS1573;VerifyTestsProjectDir;VerifySetParameters;PolyFillTargetsForNuget;xUnit1051</NoWarn>
66
<ImplicitUsings>enable</ImplicitUsings>
77
<LangVersion>preview</LangVersion>

‎src/VerifyDangling.sln

+6
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DanglingSnapshotsMSTestUsag
4141
EndProject
4242
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DanglingSnapshotsXunitV3Usage", "DanglingSnapshotsXunitV3Usage\DanglingSnapshotsXunitV3Usage.csproj", "{D1C6D798-73B7-48A6-8A04-439C337E2123}"
4343
EndProject
44+
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Verify.MSTest.SourceGenerator", "Verify.MSTest.SourceGenerator\Verify.MSTest.SourceGenerator.csproj", "{F94EA9BA-2C50-48DE-8F73-1356316F5E20}"
45+
EndProject
4446
Global
4547
GlobalSection(SolutionConfigurationPlatforms) = preSolution
4648
Debug|Any CPU = Debug|Any CPU
@@ -103,6 +105,10 @@ Global
103105
{D1C6D798-73B7-48A6-8A04-439C337E2123}.Debug|Any CPU.Build.0 = Debug|Any CPU
104106
{D1C6D798-73B7-48A6-8A04-439C337E2123}.Release|Any CPU.ActiveCfg = Release|Any CPU
105107
{D1C6D798-73B7-48A6-8A04-439C337E2123}.Release|Any CPU.Build.0 = Release|Any CPU
108+
{F94EA9BA-2C50-48DE-8F73-1356316F5E20}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
109+
{F94EA9BA-2C50-48DE-8F73-1356316F5E20}.Debug|Any CPU.Build.0 = Debug|Any CPU
110+
{F94EA9BA-2C50-48DE-8F73-1356316F5E20}.Release|Any CPU.ActiveCfg = Release|Any CPU
111+
{F94EA9BA-2C50-48DE-8F73-1356316F5E20}.Release|Any CPU.Build.0 = Release|Any CPU
106112
EndGlobalSection
107113
GlobalSection(SolutionProperties) = preSolution
108114
HideSolutionNode = FALSE

‎usages/MSTestNugetUsage/Sample.cs

-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
[TestClass]
2-
[UsesVerify]
32
public partial class Sample
43
{
54
[TestMethod]

0 commit comments

Comments
 (0)