Skip to content

Commit 1a0f3bf

Browse files
egilegil
committed
Docs: improved semantic html comparison page
1 parent 12dd487 commit 1a0f3bf

3 files changed

Lines changed: 93 additions & 89 deletions

File tree

‎docs/samples/tests/razor/SemanticHtmlTest.razor‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
@inherits TestComponentBase
2+
3+
<Fixture Test="Test1">
4+
<ComponentUnderTest>
5+
<Heading />
6+
</ComponentUnderTest>
7+
<Fragment>
8+
<h3 id:regex="heading-\d{4}" required>
9+
Heading text
10+
<small diff:ignore></small>
11+
</h3>
12+
</Fragment>
13+
14+
@code {
15+
void Test1(Fixture fixture)
16+
{
17+
// Arrange - Gets the Heading component
18+
var cut = fixture.GetComponentUnderTest<Heading>();
19+
20+
// Assert
21+
// Here we get expected HTML from the Fragment element above.
22+
var expectedHtml = fixture.GetFragment();
23+
24+
// Here we use the HTML diffing library to assert that the rendered HTML
25+
// from CUT is semantically the same as the expected HTML string above.
26+
cut.MarkupMatches(expectedHtml);
27+
}
28+
}
29+
</Fixture>
30+
31+
<SnapshotTest>
32+
<TestInput>
33+
<Heading />
34+
</TestInput>
35+
<ExpectedOutput>
36+
<h3 id:regex="heading-\d{4}" required>
37+
Heading text
38+
<small diff:ignore></small>
39+
</h3>
40+
</ExpectedOutput>
41+
</SnapshotTest>

‎docs/samples/tests/xunit/SemanticHtmlTest.cs‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
using Xunit;
2+
using Bunit;
3+
using System.Collections.Generic;
4+
using Microsoft.AspNetCore.Components;
5+
using Microsoft.AspNetCore.Components.Web;
6+
7+
using static Bunit.ComponentParameterFactory;
8+
9+
namespace Bunit.Docs.Samples
10+
{
11+
public class SemanticHtmlTest
12+
{
13+
[Fact]
14+
public void InitialHtmlIsCorrect()
15+
{
16+
// Arrange - renders the Heading component
17+
using var ctx = new TestContext();
18+
var cut = ctx.RenderComponent<Heading>();
19+
20+
// Assert
21+
// Here we specify expected HTML from CUT.
22+
var expectedHtml = @"<h3 id:regex=""heading-\d{4}"" required>
23+
Heading text
24+
<small diff:ignore></small>
25+
</h3>";
26+
27+
// Here we use the HTML diffing library to assert that the rendered HTML
28+
// from CUT is semantically the same as the expected HTML string above.
29+
cut.MarkupMatches(expectedHtml);
30+
}
31+
}
32+
}

‎docs/site/docs/verification/semantic-html-comparison.md‎

Lines changed: 20 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,14 @@ uid: semantic-html-comparison
33
title: Customizing the Semantic HTML Comparison
44
---
55

6-
# Semantic HTML markup comparison
6+
# Customizing the Semantic HTML Comparison
77

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

1010
On this page we will go through how the comparison works, and what options you have to affect the comparison process.
1111

12-
> **NOTE:** The semantic HTML comparison is available in both C# and Razor tests with the <xref:Bunit.Fixture> component, and is always used in Razor tests with the <xref:Bunit.SnapshotTest> component.
12+
> [!NOTE]
13+
> The semantic HTML comparison is available in both C# and Razor tests with the <xref:Bunit.Fixture> component, and is always used in Razor tests with the <xref:Bunit.SnapshotTest> component.
1314
1415
## Why semantic comparison is needed for stable tests
1516

@@ -24,7 +25,7 @@ Just performing string comparison of two strings containing HTML markup can brea
2425

2526
The [AngleSharp Diffing](https://github.com/AngleSharp/AngleSharp.Diffing/) library handles all those cases, so your tests are more stable.
2627

27-
## Customizing the Semantic HTML Comparison
28+
## Customizing Options
2829

2930
The [AngleSharp Diffing](https://github.com/AngleSharp/AngleSharp.Diffing/) library also allows us to customize the comparison process, by added special attributes to the _"control" markup_, i.e. the expected markup we want to use in verification.
3031

@@ -58,7 +59,8 @@ There are the customization options you have available to you:
5859
</header>
5960
```
6061

61-
**NOTE:** The default for `<pre>` and `<script>` elements is the `Preserve` option. To change that, use the `diff:whitespace` attribute, for example:
62+
> [!NOTE]
63+
> The default for `<pre>` and `<script>` elements is the `Preserve` option. To change that, use the `diff:whitespace` attribute, for example:
6264
6365
```html
6466
<pre diff:whitespace="RemoveWhitespaceNodes">...</pre>
@@ -90,96 +92,25 @@ There are the customization options you have available to you:
9092
<h1 title:regex="Heading-\d{4}">...</h1>
9193
```
9294

93-
**NOTE:** The attribute modifiers `:ignoreCase` and `:regex` can be combined, for example as: `attr:ignoreCase:regex="FOO-\d{4}"`
95+
> [!NOTE]
96+
> The attribute modifiers `:ignoreCase` and `:regex` can be combined, for example as: `attr:ignoreCase:regex="FOO-\d{4}"`
9497
95-
## Verifying Output from Components
98+
## Examples
9699

97-
To verify the rendered output of a component (i.e. in the from of a `IRenderedFragment`), we have the various `MarkupMatches()` methods we can use.
100+
To verify the rendered output of a component, we have the `MarkupMatches()` methods we can use.
98101

99102
If for example we have a component, `<Heading>`, that renders the following markup:
100103

101-
```html
102-
<h3 id="heading-1337" required>
103-
Heading text
104-
<small class="text-muted mark">Secondary text</small>
105-
</h3>
106-
```
104+
[!code-html[Heading.razor](../../../samples/components/Heading.razor)]
107105

108106
If we want to verify the markup is rendered correctly, and for example use RegEx to verify the `id` attribute (it might be generated) and ignore the `<small>` element, we can do it like this in C# based tests:
109107

110-
```csharp
111-
[Fact]
112-
public void InitialHtmlIsCorrect()
113-
{
114-
// Arrange - renders the Heading component
115-
var cut = RenderComponent<Heading>();
116-
117-
// Assert
118-
// Here we specify expected HTML from CUT.
119-
var expectedHtml = @"<h3 id:regex=""heading-\d{4}"" required>
120-
Heading text
121-
<small diff:ignore></small>
122-
</h3>";
123-
124-
// Here we use the HTML diffing library to assert that the rendered HTML
125-
// from CUT is semantically the same as the expected HTML string above.
126-
cut.MarkupMatches(expectedHtml);
127-
}
128-
```
129-
130-
In a Razor based test, the example looks like this:
131-
132-
```cshtml
133-
<Fixture Test="Test1">
134-
<ComponentUnderTest>
135-
<Heading />
136-
</ComponentUnderTest>
137-
</Fixture>
138-
@code {
139-
void Test1(IRazorTestContext context)
140-
{
141-
// Arrange - Gets the Heading component
142-
var cut = context.GetComponentUnderTest<Heading>();
143-
144-
// Assert
145-
// Here we specify expected HTML from CUT.
146-
var expectedHtml = @"<h3 id:regex=""heading-\d{4}"" required>
147-
Heading text
148-
<small diff:ignore></small>
149-
</h3>";
150-
151-
// Here we use the HTML diffing library to assert that the rendered HTML
152-
// from CUT is semantically the same as the expected HTML string above.
153-
cut.MarkupMatches(expectedHtml);
154-
}
155-
}
156-
```
157-
158-
In a Snapshot test, the example looks like this:
159-
160-
```html
161-
<SnapshotTest Description="Helpful description of the test case">
162-
<TestInput>
163-
<Heading />
164-
</TestInput>
165-
<ExpectedOutput>
166-
<h3 id:regex="heading-\d{4}" required>
167-
Heading text
168-
<small diff:ignore></small>
169-
</h3>
170-
</ExpectedOutput>
171-
</SnapshotTest>
172-
```
173-
174-
## Different ways of getting the differences
175-
176-
This section is coming soon. For now, see examples on the [C# test examples](/docs/CSharp-test-examples.html) page where the methods are demonstrated. Look for examples using these methods:
177-
178-
- `CompareTo`
179-
- `MarkupMatches`
180-
- `GetChangesSinceFirstRender`
181-
- `SaveSnapshot` and `GetChangesSinceSnapshot`
182-
- `ShouldHaveSingleTextChange`
183-
- `ShouldHaveSingleChange`
184-
- `ShouldBeAddition`
185-
- `ShouldBeRemoval`
108+
[!code-csharp[SemanticHtmlTest.cs](../../../samples/tests/xunit/SemanticHtmlTest.cs#L16-L29)]
109+
110+
In a Razor based test, using the `<Fixture>` test type, the example looks like this:
111+
112+
[!code-html[SemanticHtmlTest.razor](../../../samples/tests/razor/SemanticHtmlTest.razor.cs#L3-L29)]
113+
114+
In a Razor based test, using the `<SnapshotTest>` test type, the example looks like this:
115+
116+
[!code-html[SemanticHtmlTest.razor](../../../samples/tests/razor/SemanticHtmlTest.razor.cs#L31-L41)]

0 commit comments

Comments
 (0)