Skip to content

Commit 007a767

Browse files
egilegil
committed
Updates to docs
1 parent b7c6062 commit 007a767

16 files changed

Lines changed: 208 additions & 20 deletions

File tree

‎docs/docs.csproj‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,26 @@
1-
<Project Sdk="Microsoft.NET.Sdk">
1+
<Project Sdk="Microsoft.NET.Sdk.Razor">
22

33
<PropertyGroup>
4-
<TargetFramework>netstandard2.0</TargetFramework>
4+
<TargetFramework>netcoreapp3.1</TargetFramework>
5+
<RazorLangVersion>3.0</RazorLangVersion>
56
</PropertyGroup>
67

7-
<ItemGroup>
8+
<ItemGroup>
9+
<PackageReference Include="Microsoft.AspNetCore.Components" Version="3.1.4" />
10+
<PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="3.1.4" />
11+
<PackageReference Include="xunit" Version="2.4.1" />
12+
<PackageReference Include="nunit" Version="3.12.0" />
13+
<PackageReference Include="MSTest.TestFramework" Version="2.1.0" />
814
<PackageReference Include="docfx.console" Version="2.50.0">
915
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
1016
<PrivateAssets>all</PrivateAssets>
1117
</PackageReference>
1218
</ItemGroup>
1319

20+
<ItemGroup>
21+
<ProjectReference Include="..\src\bunit.core\bunit.core.csproj" />
22+
<ProjectReference Include="..\src\bunit.web\bunit.web.csproj" />
23+
<ProjectReference Include="..\src\bunit.xunit\bunit.xunit.csproj" />
24+
</ItemGroup>
25+
1426
</Project>

docs/docs/create-test-project.md renamed to docs/docs/getting-started/create-test-project.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ To create a project for testing you Blazor components that uses either of three
1515

1616
1. Create a new xUnit/NUnit/MSTest testing project
1717
2. Add bUnit to the test project
18-
3. Change project type to `Microsoft.NET.Sdk.Razor`
18+
3. Configure project settings
1919
4. Add the test project to your solution
2020

2121
These steps look like this from the `dotnet` CLI:
@@ -74,9 +74,11 @@ dotnet add package bunit.web --version #{VERSION}#
7474

7575
***
7676

77-
**3. Change project type to `Microsoft.NET.Sdk.Razor`**
77+
**3. Configure project settings**
7878

79-
Changing the project type to `Microsoft.NET.Sdk.Razor` is done by changing first section of the test project's `.csproj` file to look like this:
79+
Then you need to change a few project settings, in particular we need to change the project's SDK to `Microsoft.NET.Sdk.Razor`, remember to set `RazorLangVersion` to `3.0`, and set the `<TargetFramework>` to `netcoreapp3.1`, since bUnit builds on `.netstandard 2.1`.
80+
81+
To do so, change the first part of the test project's `.csproj` file to look like this.:
8082

8183
```xml
8284
<Project Sdk="Microsoft.NET.Sdk.Razor">
@@ -86,12 +88,11 @@ Changing the project type to `Microsoft.NET.Sdk.Razor` is done by changing first
8688
<RazorLangVersion>3.0</RazorLangVersion>
8789
</PropertyGroup>
8890

89-
...
91+
...
9092

9193
</Project>
9294
```
9395

94-
9596
**4. Add the test project to your solution**
9697

9798
Then you need to add your test project to your solution (`.sln`) and add a reference between your test project and component project:
@@ -224,4 +225,5 @@ dotnet add <NAME OF COMPONENT PROJECT>.csproj reference <NAME OF TEST PROJECT>.c
224225

225226
## Further reading
226227

227-
- [Miscellaneous bUnit testing tips](/docs/misc-test-tips.html)
228+
- <xref:writing-first-csharp-test>
229+
- <xref:misc-test-tips>

docs/docs/index.md renamed to docs/docs/getting-started/getting-started.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
uid: getting-started
3+
title: Getting started with bUnit
4+
---
5+
16
# Getting started with bUnit
27

38
To get started writing tests for your Blazor components, you first need to set up a test project. Then you can start writing your tests, using either C# or Razor syntax.

docs/docs/misc-test-tips.md renamed to docs/docs/getting-started/misc-test-tips.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
---
2+
uid: misc-test-tips
23
title: Miscellaneous bUnit testing tips
34
---
45

‎docs/docs/getting-started/writing-first-csharp-test.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
uid: writing-first-csharp-test
3+
title: Writing the first C# test
4+
---
5+
6+
# Writing the first C# test
7+
8+
Testing Blazor components is a different from testing regular C# classes: Blazor components are *rendered*, they have the *Blazor component life-cycle*, during which we can *provide input* to them and where they *produce output*.
9+
10+
**bUnit** enables you to render the component you want to test, pass in parameters to it, inject services into it, and access the rendered component instance and the markup it has produced.
11+
12+
Rendering a component happens through bUnit's <xref:Bunit.TestContext>, and the result of the rendering, a <xref:Bunit.IRenderedComponent`1>, provides access to the component instance, and the markup produced by the component.
13+
14+
## Rendering a component
15+
16+
Lets see a simple example, where we test the following `HelloWorld` component:
17+
18+
[!code-cshtml[HelloWorld.razor](../../samples/Components/HelloWorld.razor)]
19+
20+
# [xUnit](#tab/xunit)
21+
22+
[!code-csharp[HelloWorldTest.cs](../../samples/tests/xunit/HelloWorldTest.cs)]
23+
24+
# [NUnit](#tab/nunit)
25+
26+
[!code-csharp[HelloWorldTest.cs](../../samples/tests/nunit/HelloWorldTest.cs)]
27+
28+
> [!NOTE]
29+
> `TestContext` is an ambiguous reference between `<xref:Bunit.TestContext>` and `NUnit.Framework.TestContext`, so you have to specify the `Bunit` namespace when referencing `<xref:Bunit.TestContext>` to resolve the ambiguity for the compiler. Alternatively, you can give bUnit's <xref:Bunit.TestContext> a different name during import, e.g.: `using BunitTestContext = Bunit.TestContext;`
30+
31+
# [MSTest](#tab/mstest)
32+
33+
[!code-csharp[HelloWorldTest.cs](../../samples/tests/mstest/HelloWorldTest.cs)]
34+
35+
> [!NOTE]
36+
> `TestContext` is an ambiguous reference between `<xref:Bunit.TestContext>` and `Microsoft.VisualStudio.TestTools.UnitTesting.TestContext`, so you have to specify the `Bunit` namespace when referencing `<xref:Bunit.TestContext>` to resolve the ambiguity for the compiler. Alternatively, you can give bUnit's <xref:Bunit.TestContext> a different name during import, e.g.:
37+
> `using BunitTestContext = Bunit.TestContext;`
38+
39+
***
40+
41+
In this test, we do the following:
42+
43+
1. New up the disposable <xref:Bunit.TestContext>, and assign it using `using var` syntax, to avoid unnecessary indention.
44+
2. Render the `HelloWorld` component using <xref:Bunit.TestContext>, which we do through the <xref:Bunit.TestContext.RenderComponent``1(Bunit.Rendering.ComponentParameter[])> method.
45+
3. Verify the rendered markup from the `HelloWorld` component using the <xref:Bunit.MarkupMatchesAssertExtensions.MarkupMatches(Bunit.IRenderedFragment,System.String,System.String)> method, which performs a semantic comparison of the expected markup with the rendered markup.
46+
47+
> [!TIP]
48+
> Learn more about how the semantic HTML/markup comparison in bUnit work, and how to customize it on the <xref:semantic-html-comparison> page.
49+

docs/docs/semantic-html-markup-comparison.md renamed to docs/docs/semantic-html-comparison.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
uid: semantic-html-comparison
3+
title: Semantic HTML markup comparison
4+
---
5+
16
# Semantic HTML markup comparison
27

38
This library includes comparison and assert helpers that uses the [AngleSharp Diffing](https://github.com/AngleSharp/AngleSharp.Diffing/) library to perform semantic HTML comparison.

‎docs/docs/toc.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
1-
# [Getting Started](index.md)
2-
# [Create a test project](xref:create-test-project)
3-
# [Basics of Blazor component testing](basics-of-blazor-component-testing.md)
1+
# [Getting Started](xref:getting-started)
2+
## [Create a test project](xref:create-test-project)
3+
## [Writing the first C# test](xref:writing-first-csharp-test)
4+
## [Miscellaneous bUnit testing tips](xref:misc-test-tips)
45
# [C# based testing](csharp-based-testing.md)
56
# [Razor based testing](razor-based-testing.md)
67
# [Snapshot testing](snapshot-testing.md)
7-
# [Semantic HTML markup comparison](semantic-html-markup-comparison.md)
8+
# [Semantic HTML markup comparison](xref:semantic-html-comparison)
89
# [Mocking JsRuntime](mocking-jsruntime.md)
9-
# [Miscellaneous bUnit testing tips](/docs/misc-test-tips.md)
1010
# [Tutorials and Presentations](tutorials-and-presentations.md)
1111
# [Contribute](contribute.md)

‎docs/index.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
uid: home
3+
title: bUnit - a testing library for Blazor components
4+
---
5+
16
[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/egil/bunit/CI?logo=github&style=flat-square)](https://github.com/egil/bunit/actions?query=workflow%3ACI)
27
[![GitHub tag (latest SemVer pre-release)](https://img.shields.io/github/v/tag/egil/bunit?include_prereleases&logo=github&style=flat-square)](https://github.com/egil/bunit/releases)
38
[![Nuget](https://img.shields.io/nuget/dt/bunit?logo=nuget&style=flat-square)](https://www.nuget.org/packages/bunit/)
@@ -39,7 +44,7 @@ public void CounterShouldIncrementWhenClicked()
3944
}
4045
```
4146

42-
**Go to [Documentation](/docs) to learn more.**
47+
**Go to [Documentation](xref:getting-started) to learn more.**
4348

4449
### NuGet downloads
4550

‎docs/samples/components/HelloWorld.razor‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<h1>Hello world from Blazor</h1>

‎docs/samples/components/_Imports.razor‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
@namespace Docs.Components
2+
@using Microsoft.AspNetCore.Components.Web

0 commit comments

Comments
 (0)