Skip to content

Commit a88b812

Browse files
coenmcoenm
authored
Added markdown readme files to nuget packages (#24)
1 parent 4f12b48 commit a88b812

24 files changed

Lines changed: 362 additions & 14 deletions

‎.azuredevops/Pipelines/build.yaml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,9 @@ stages:
3838
value: 39ce9363-a308-4580-8610-ee11f4953539/01001223-8651-4b73-a7ca-ba27c3e10a3c
3939

4040
steps:
41+
- script: git submodule update --init --recursive
42+
displayName: Update git submodules
43+
4144
- task: UseDotNet@2
4245
displayName: "Use dotnet sdk 2.1.x"
4346
inputs:
@@ -90,6 +93,13 @@ stages:
9093
errorActionPreference: 'silentlyContinue'
9194
ignoreLASTEXITCODE: true
9295

96+
# regenerate markdowns without links (in order to generate markdown to be included in nuget package)
97+
- pwsh: |
98+
dotnet tool install --tool-path . MarkdownSnippets.Tool
99+
./mdsnippets --omit-snippet-links true
100+
displayName: Re-generate markdown without links
101+
name: mdsnippets
102+
93103
- task: DotNetCoreCLI@2
94104
displayName: DotNet Restore
95105
inputs:

‎.azuredevops/Pipelines/publish.yaml‎

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -69,11 +69,4 @@ stages:
6969
command: push
7070
packagesToPush: '$(Pipeline.Workspace)/CI/packages/*.nupkg;!$(Pipeline.Workspace)/**/*.symbols.nupkg'
7171
nuGetFeedType: external
72-
publishFeedCredentials: nuget.org
73-
# - task: NuGetCommand@2
74-
# displayName: NuGet push snupkg
75-
# inputs:
76-
# command: push
77-
# packagesToPush: '$(Pipeline.Workspace)/CI/packages/*.snupkg'
78-
# nuGetFeedType: external
79-
# publishFeedCredentials: nuget.org
72+
publishFeedCredentials: nuget.org

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ public async Task LoadAsStream()
6161
<a id='snippet-loadastestfile'></a>
6262
```cs
6363
[Fact]
64-
public async Task LoadAsTestFile()
64+
public async Task LoadAsTestFileWithJson()
6565
{
6666
// You can also load the test file as a TestFile object.
6767
TestFile testFile = EasyTestFile.Load();
@@ -76,7 +76,7 @@ public async Task LoadAsTestFile()
7676
string text = await testFile.AsText();
7777
}
7878
```
79-
<sup><a href='/tests/EasyTestFile.Xunit.Tests/Samples/UnitTestClass.cs#L39-L55' title='Snippet source file'>snippet source</a> | <a href='#snippet-loadastestfile' title='Start of snippet'>anchor</a></sup>
79+
<sup><a href='/tests/EasyTestFile.Xunit.Tests/Samples/UnitTestClass.cs#L75-L91' title='Snippet source file'>snippet source</a> | <a href='#snippet-loadastestfile' title='Start of snippet'>anchor</a></sup>
8080
<!-- endSnippet -->
8181

8282

‎src/Directory.Build.props‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@
2424
</PropertyGroup>
2525

2626
<ItemGroup>
27-
<PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.0.0" PrivateAssets="all" Condition="$(Configuration) == 'Release'" />
28-
<PackageReference Include="Nerdbank.GitVersioning" Version="3.4.240" PrivateAssets="all" />
27+
<PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.0.0" PrivateAssets="all" Condition="$(Configuration) == 'Release'" />
28+
<PackageReference Include="Nerdbank.GitVersioning" Version="3.4.240" PrivateAssets="all" />
2929
</ItemGroup>
3030

3131
<ItemGroup>

‎src/EasyTestFile.Json/EasyTestFile.Json.csproj‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
<PackageId>EasyTestFile.NewtonsoftJson</PackageId>
66
<PackageTags>EasyTestFile;UnitTests;IntegrationTests;Json</PackageTags>
77
<Description>EasyTestFile NewtonsoftJson extension making it easy to read files as objects.</Description>
8+
<PackageReadmeFile>PackageDescription.md</PackageReadmeFile>
89
</PropertyGroup>
910

1011
<ItemGroup>
@@ -14,4 +15,8 @@
1415
<ItemGroup>
1516
<ProjectReference Include="..\EasyTestFile\EasyTestFile.csproj" PrivateAssets="None" />
1617
</ItemGroup>
18+
19+
<ItemGroup>
20+
<None Include="$(MSBuildThisFileDirectory)\PackageDescription.md" Pack="true" PackagePath="$(PackageReadmeFile)" Visible="false" />
21+
</ItemGroup>
1722
</Project>

‎src/EasyTestFile.Json/PackageDescription.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# EasyTestFile
2+
3+
EasyTestFile is a library that simplifies the creation and usage of testfiles in unittests.
4+
Testfiles (like text, json, xml, binary, jpg, etc. etc.) are named based on the class and method name, are created if not exist, and are embedded as resource making sure the execution of the test is deterministic and do not rely on untracked files etc.
5+
6+
# EasyTestFile.Json
7+
8+
This package contains extension method(s) to deserialize TestFiles using json.
9+
10+
<!-- snippet: LoadJson -->
11+
<a id='snippet-loadjson'></a>
12+
```cs
13+
[Fact] // or [Test]
14+
public async Task JsonTestFile()
15+
{
16+
// load testfile
17+
var settings = new EasyTestFileSettings();
18+
settings.UseExtension("json");
19+
TestFile testFile = EasyTestFile.Load(settings);
20+
21+
// deserialize testfile using Newtonsoft Json.
22+
Person person = await testFile.AsObjectUsingNewtonsoft<Person>();
23+
24+
// do something with person object
25+
// i.e. sut.Process(person);
26+
}
27+
28+
public class Person
29+
{
30+
public string Name { get; set; }
31+
}
32+
```
33+
<sup><a href='/tests/EasyTestFile.Xunit.Tests/Samples/UnitTestClass.cs#L36-L56' title='Snippet source file'>snippet source</a> | <a href='#snippet-loadjson' title='Start of snippet'>anchor</a></sup>
34+
<!-- endSnippet -->

‎src/EasyTestFile.Nunit/EasyTestFile.Nunit.csproj‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
<PackageId>EasyTestFile.NUnit</PackageId>
66
<PackageTags>EasyTestFile;UnitTests;IntegrationTests;NUnit</PackageTags>
77
<Description>Enables EasyTestFile when writing test using NUnit.</Description>
8+
<PackageReadmeFile>PackageDescription.md</PackageReadmeFile>
89
</PropertyGroup>
910

1011
<ItemGroup>
@@ -14,4 +15,8 @@
1415
<ItemGroup>
1516
<ProjectReference Include="..\EasyTestFile\EasyTestFile.csproj" PrivateAssets="None" />
1617
</ItemGroup>
18+
19+
<ItemGroup>
20+
<None Include="$(MSBuildThisFileDirectory)\PackageDescription.md" Pack="true" PackagePath="$(PackageReadmeFile)" Visible="false" />
21+
</ItemGroup>
1722
</Project>

‎src/EasyTestFile.Nunit/PackageDescription.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# EasyTestFile
2+
3+
EasyTestFile is a library that simplifies the creation and usage of testfiles in unittests.
4+
Testfiles (like text, json, xml, binary, jpg, etc. etc.) are named based on the class and method name, are created if not exist, and are embedded as resource making sure the execution of the test is deterministic and do not rely on untracked files etc.
5+
6+
# EasyTestFile.Nunit
7+
8+
This package is required when your project uses NUnit for unittesting. No setup is required.
9+
10+
## Samples
11+
12+
<!-- snippet: NunitLoadAsText -->
13+
<a id='snippet-nunitloadastext'></a>
14+
```cs
15+
[Test]
16+
public async Task LoadAsText()
17+
{
18+
// Executing this test for the first time will create an empty testfile and throw an exception.
19+
// Executing this test for the second time, this statement will read the testfile
20+
// and returns the content as a string.
21+
string text = await EasyTestFile.LoadAsText();
22+
23+
// and do whatever you want
24+
}
25+
```
26+
<sup><a href='/tests/EasyTestFile.Nunit.Tests/Samples/UnitTestClass.cs#L11-L22' title='Snippet source file'>snippet source</a> | <a href='#snippet-nunitloadastext' title='Start of snippet'>anchor</a></sup>
27+
<!-- endSnippet -->
28+
29+
<!-- snippet: NunitLoadAsStream -->
30+
<a id='snippet-nunitloadasstream'></a>
31+
```cs
32+
[Test]
33+
public async Task LoadAsStream()
34+
{
35+
// You can also load the testfile content as a stream.
36+
Stream stream = await EasyTestFile.LoadAsStream();
37+
38+
}
39+
```
40+
<sup><a href='/tests/EasyTestFile.Nunit.Tests/Samples/UnitTestClass.cs#L24-L32' title='Snippet source file'>snippet source</a> | <a href='#snippet-nunitloadasstream' title='Start of snippet'>anchor</a></sup>
41+
<!-- endSnippet -->
42+
43+
Or load the TestFile object first
44+
45+
<!-- snippet: NunitLoadAsTestFileBasic -->
46+
<a id='snippet-nunitloadastestfilebasic'></a>
47+
```cs
48+
[Test]
49+
public async Task LoadAsTestFile()
50+
{
51+
// You can also load the test file as a TestFile object.
52+
TestFile testFile = EasyTestFile.Load();
53+
54+
// then you can load the content as a stream
55+
Stream stream = testFile.AsStream();
56+
57+
// or like
58+
string text = await testFile.AsText();
59+
}
60+
```
61+
<sup><a href='/tests/EasyTestFile.Nunit.Tests/Samples/UnitTestClass.cs#L58-L71' title='Snippet source file'>snippet source</a> | <a href='#snippet-nunitloadastestfilebasic' title='Start of snippet'>anchor</a></sup>
62+
<!-- endSnippet -->
63+

‎src/EasyTestFile.Xunit/EasyTestFile.Xunit.csproj‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
<PackageId>EasyTestFile.XUnit</PackageId>
66
<PackageTags>EasyTestFile;UnitTests;IntegrationTests;XUnit</PackageTags>
77
<Description>Enables EasyTestFile when writing test using XUnit.</Description>
8+
<PackageReadmeFile>PackageDescription.md</PackageReadmeFile>
89
</PropertyGroup>
910

1011
<ItemGroup>
@@ -16,4 +17,8 @@
1617
<ItemGroup>
1718
<ProjectReference Include="..\EasyTestFile\EasyTestFile.csproj" PrivateAssets="None" />
1819
</ItemGroup>
20+
21+
<ItemGroup>
22+
<None Include="$(MSBuildThisFileDirectory)\PackageDescription.md" Pack="true" PackagePath="$(PackageReadmeFile)" Visible="false" />
23+
</ItemGroup>
1924
</Project>

‎src/EasyTestFile.Xunit/PackageDescription.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# EasyTestFile
2+
3+
EasyTestFile is a library that simplifies the creation and usage of testfiles in unittests.
4+
Testfiles (like text, json, xml, binary, jpg, etc. etc.) are named based on the class and method name, are created if not exist, and are embedded as resource making sure the execution of the test is deterministic and do not rely on untracked files etc.
5+
6+
# EasyTestFile.Nunit
7+
8+
This package is required when your project uses NUnit for unittesting. Make sure your test class is annotated with the attribute `[EasyTestFileXunit.UsesEasyTestFile]`.
9+
10+
## Attribute usage
11+
<!-- snippet: XUnitAttributeUsage -->
12+
<a id='snippet-xunitattributeusage'></a>
13+
```cs
14+
[UsesEasyTestFile]
15+
public class TestClass1
16+
{
17+
// The attribute is required when using XUnit.
18+
}
19+
```
20+
<sup><a href='/tests/EasyTestFile.Xunit.Tests/Samples/Samples.cs#L6-L12' title='Snippet source file'>snippet source</a> | <a href='#snippet-xunitattributeusage' title='Start of snippet'>anchor</a></sup>
21+
<!-- endSnippet -->
22+
23+
## Usage
24+
25+
Default options to load as text or load as stream:
26+
27+
<!-- snippet: LoadAsText -->
28+
<a id='snippet-loadastext'></a>
29+
```cs
30+
[Fact]
31+
public async Task LoadAsText()
32+
{
33+
// Executing this test for the first time will create an empty testfile and throw an exception.
34+
// Executing this test for the second time, this statement will read the testfile
35+
// and returns the content as a string.
36+
string text = await EasyTestFile.LoadAsText();
37+
38+
// and do whatever you want
39+
}
40+
```
41+
<sup><a href='/tests/EasyTestFile.Xunit.Tests/Samples/UnitTestClass.cs#L12-L23' title='Snippet source file'>snippet source</a> | <a href='#snippet-loadastext' title='Start of snippet'>anchor</a></sup>
42+
<!-- endSnippet -->
43+
44+
<!-- snippet: LoadAsStream -->
45+
<a id='snippet-loadasstream'></a>
46+
```cs
47+
[Fact]
48+
public async Task LoadAsStream()
49+
{
50+
// You can also load the testfile content as a stream.
51+
Stream stream = await EasyTestFile.LoadAsStream();
52+
53+
}
54+
```
55+
<sup><a href='/tests/EasyTestFile.Xunit.Tests/Samples/UnitTestClass.cs#L25-L33' title='Snippet source file'>snippet source</a> | <a href='#snippet-loadasstream' title='Start of snippet'>anchor</a></sup>
56+
<!-- endSnippet -->
57+
58+
Or load the TestFile object first
59+
60+
<!-- snippet: LoadAsTestFileBasic -->
61+
<a id='snippet-loadastestfilebasic'></a>
62+
```cs
63+
[Fact]
64+
public async Task LoadAsTestFile()
65+
{
66+
// You can also load the test file as a TestFile object.
67+
TestFile testFile = EasyTestFile.Load();
68+
69+
// then you can load the content as a stream
70+
Stream stream = testFile.AsStream();
71+
72+
// or like
73+
string text = await testFile.AsText();
74+
}
75+
```
76+
<sup><a href='/tests/EasyTestFile.Xunit.Tests/Samples/UnitTestClass.cs#L59-L72' title='Snippet source file'>snippet source</a> | <a href='#snippet-loadastestfilebasic' title='Start of snippet'>anchor</a></sup>
77+
<!-- endSnippet -->

0 commit comments

Comments
 (0)