Docs: Verify Markup page first parts

egil · egil · commit b5199f99856e · 2020-06-24T22:48:54.000Z
diff --git a/docs/samples/components/FancyTable.razor b/docs/samples/components/FancyTable.razor
@@ -0,0 +1,13 @@
+<table>
+  <caption>Lorem lipsum captium</caption>
+  <tbody>
+    <tr>
+      <td style="white-space:nowrap">Foo</td>
+      <td>Bar</td>
+    </tr>
+    <tr>
+      <td style="white-space:nowrap">Baz</td>
+      <td>Boo</td>
+    </tr>
+  </tbody>
+</table>
diff --git a/docs/samples/components/Heading.razor b/docs/samples/components/Heading.razor
@@ -1,4 +1,6 @@
 <h3 id="heading-1337" required>
   Heading text
-  <small class="text-muted mark">Secondary text</small>
+  <small class="text-muted mark">
+    Secondary text
+  </small>
 </h3>
diff --git a/docs/samples/tests/xunit/VerifyMarkupExamples.cs b/docs/samples/tests/xunit/VerifyMarkupExamples.cs
@@ -0,0 +1,74 @@
+using Xunit;
+using Bunit;
+using System.Collections.Generic;
+using Microsoft.AspNetCore.Components;
+using Microsoft.AspNetCore.Components.Web;
+
+using static Bunit.ComponentParameterFactory;
+
+namespace Bunit.Docs.Samples
+{
+  public class VerifyMarkupExamples
+  {
+    [Fact]
+    public void RawMarkupVerify()
+    {
+      using var ctx = new TestContext();
+
+      var cut = ctx.RenderComponent<HelloWorld>();
+
+      var renderedMarkup = cut.Markup;
+      Assert.Equal("<h1>Hello world from Blazor</h1>", renderedMarkup);
+    }
+
+    [Fact]
+    public void MarkupMatchesOnRenderedFragment()
+    {
+      using var ctx = new TestContext();
+
+      var cut = ctx.RenderComponent<Heading>();
+
+      cut.MarkupMatches(@"<h3 id=""heading-1337"" required>
+                            Heading text
+                            <small class=""mark text-muted"">Secondary text</small>
+                          </h3>");
+    }
+
+    [Fact]
+    public void MarkupMatchesOnNode()
+    {
+      using var ctx = new TestContext();
+
+      var cut = ctx.RenderComponent<Heading>();
+
+      var smallElm = cut.Find("small");
+      smallElm.MarkupMatches(@"<small class=""mark text-muted"">Secondary text</small>");
+    }
+
+    [Fact]
+    public void MarkupMatchesOnTextNode()
+    {
+      using var ctx = new TestContext();
+
+      var cut = ctx.RenderComponent<Heading>();
+
+      var smallElmText = cut.Find("small").TextContent;
+      smallElmText.MarkupMatches("Secondary text");
+    }
+
+    [Fact]
+    public void FindAndFindAll()
+    {
+      using var ctx = new TestContext();
+
+      var cut = ctx.RenderComponent<FancyTable>();
+
+      var tableCaption = cut.Find("caption");
+      var tableCells = cut.FindAll("td:first-child");
+
+      Assert.Empty(tableCaption.Attributes);
+      Assert.Equal(2, tableCells.Count);
+      Assert.All(tableCells, td => td.HasAttribute("style"));
+    }
+  }
+}
diff --git a/docs/site/docs/verification/index.md b/docs/site/docs/verification/index.md
@@ -5,4 +5,9 @@ title: Verifying Output from a Component Under Test
 
 # Verifying Output from a Component Under Test
 
-providing a toc with descriptions of each topic
+These section covers the different ways to verify the result of a test scenario:
+
+- **<xref:verify-markup>:** This covers the different ways bUnit enables verification and assertions against the rendered markup from a component.
+- **<xref:verify-component-state>:** This covers how to inspect instance of the component under test.
+- **<xref:semantic-html-comparison>:** This covers how to customize the semantic HTML/markup comparer included in bUnit, for more stable tests.
+- **<xref:async-assertion>:** This covers how to create stable tests in an asynchronous world.
diff --git a/docs/site/docs/verification/semantic-html-comparison.md b/docs/site/docs/verification/semantic-html-comparison.md
@@ -101,16 +101,16 @@ To verify the rendered output of a component, we have the `MarkupMatches()` meth
 
 If for example we have a component, `<Heading>`, that renders the following markup:
 
-[!code-html[Heading.razor](../../../samples/components/Heading.razor)]
+[!code-razor[Heading.razor](../../../samples/components/Heading.razor)]
 
 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:
 
 [!code-csharp[SemanticHtmlTest.cs](../../../samples/tests/xunit/SemanticHtmlTest.cs#L16-L29)]
 
 In a Razor based test, using the `<Fixture>` test type, the example looks like this:
 
-[!code-html[SemanticHtmlTest.razor](../../../samples/tests/razor/SemanticHtmlTest.razor#L3-L30)]
+[!code-razor[SemanticHtmlTest.razor](../../../samples/tests/razor/SemanticHtmlTest.razor#L3-L30)]
 
 In a Razor based test, using the `<SnapshotTest>` test type, the example looks like this:
 
-[!code-html[SemanticHtmlTest.razor](../../../samples/tests/razor/SemanticHtmlTest.razor#L32-L42)]
+[!code-razor[SemanticHtmlTest.razor](../../../samples/tests/razor/SemanticHtmlTest.razor#L32-L42)]
diff --git a/docs/site/docs/verification/verify-component-state.md b/docs/site/docs/verification/verify-component-state.md
@@ -11,3 +11,4 @@ Show Instance prop
 
 Warn against setting props directly
 
+FindComponent/FindComponents
diff --git a/docs/site/docs/verification/verify-markup.md b/docs/site/docs/verification/verify-markup.md
@@ -1,32 +1,129 @@
 ---
 uid: verify-markup
-title: Verifying the Rendered Markup from a Component Under Test
+title: Verifying Markup from a Component
 ---
 
-# Verifying the Rendered Markup from a Component Under Test
+# Verifying Markup from a Component
 
-Describe how markup is available.
+When a component is rendered in a test, the result is a <xref:Bunit.IRenderedFragment> or a <xref:Bunit.IRenderedComponent`1>. Through these it is possible to access the rendered markup (HTML) of the component, and in the case of <xref:Bunit.IRenderedComponent`1>, the instance of the component. 
 
-List properties in renderedfragment for accessing rendered markup.
+> [!NOTE]
+> An <xref:Bunit.IRenderedComponent`1> inherits from <xref:Bunit.IRenderedFragment>. This page will only show how a <xref:Bunit.IRenderedFragment> is used. <xref:Bunit.IRenderedComponent`1> is covered on the <xref:verify-component-state> page.
 
-Mention AngleSharp and the complete DOM api.
+This page cover the following **verification approaches**:
 
-## Finding DOM Nodes
+- Basic verification of raw markup.
+- Semantic comparison of markup.
+- Inspecting the individual DOM nodes in the DOM tree.
+- Diffing of markup between renders.
 
-### Refreshable Find Queries
+The following sections will cover each of these.
 
-## Useful DOM Properties and Methods for Asserting 
+## Basic Verification of Raw Markup
 
-## Diffing DOM Nodes
+To access the rendered markup of a component, just use the <xref:Bunit.IRenderedFragment.Markup> property on <xref:Bunit.IRenderedFragment>. It holds the *raw* HTML from the component as a `string`. 
 
-- Since first render
-- since snapshot
-- Assertion helpers for List of IDiff
+To get the markup as a string, do the following:
+
+[!code-csharp[](../../../samples/tests/xunit/VerifyMarkupExamples.cs?start=16&end=21&highlight=5)]
+
+You can perform standard string assertions against the markup string, e.g. like checking if it contains a value or is empty.
+
+> [!WARNING]
+> Be aware that all indentions and whitespace in your components (`.razor` files) are included in the rendered markup, so it is often wise to normalize the markup string a little, e.g. via the string `Trim()` method, to make the tests more stable. Otherwise a change to the formatting in your components might break the tests when it does not need to.
 
 ## Semantic Comparison of Markup
 
-- MarkupMatches
-- Make case for semantic comparison
-- Show use cases
+Working with raw markup only works well with very simple output, and even then, you have to sanitize it to get stable tests. A much better approach is to use the semantic HTML comparer that comes with bUnit.
+
+### How does the Semantic HTML Comparer Work?
+
+The comparer takes two HTML fragments (e.g. in the form of a C# string) as input, and returns `true` if both HTML fragments will result in the same visual rendered output in a web browser, otherwise it returns `false`.
+
+For example, a web browser will render this HTML:
+
+```html
+<span>Foo Bar</span>
+```
+
+Exactly the same as this HTML:
+
+```html
+<span>
+  Foo Bar
+</span>
+```
+
+That is why it makes sense to allow tests to pass, _even_ when the rendered HTML markup is not entire identical to the expected HTML, from a normal string comparer perspective.
+
+bUnit's semantic HTML comparer safely ignores things like insignificant whitespace and the order of attributes on elements, and many more things. **This leads to much more stable tests, as e.g. a reformatted component doesn't break it's tests because insignificant whitespace changes.**
+
+### The MarkupMatches() Method
+
+The HTML comparer can be easily accessed through `MarkupMatches()` extension methods, available in places that represents HTML fragments in bUnit, i.e. on <xref:Bunit.IRenderedFragment> and the `INode` and `INodeList` types.
+
+In the following examples, the `<Heading>` component listed below will be used as the component under test.
+
+[!code-razor[Heading.razor](../../../samples/components/Heading.razor)]
+
+To use the `MarkupMatches()` method to perform a semantic comparison of the output of the `<Heading>` component, through its <xref:Bunit.IRenderedFragment>, do the following:
+
+[!code-csharp[](../../../samples/tests/xunit/VerifyMarkupExamples.cs?start=27&end=34&highlight=5-9)]
+
+The highlighted line shows the call to the `MarkupMatches()` method. This test passes even though the insignificant whitespace is not exactly the same between the expected HTML string and the raw markup produced by the `<Heading>` component. It even works when the CSS class-list is not in the same order on the `<small>` element.
+
+The `MarkupMatches()` method is also available on `INode` and `INodeList` types, for example:
+
+[!code-csharp[](../../../samples/tests/xunit/VerifyMarkupExamples.cs?start=40&end=45&highlight=5-6)]
+
+Here we use the `Find(string cssSelector)` method to find the `<small>` element, and only verify it and it's content and attributes.
+
+> [!TIP]
+> Working with `Find()`, `FindAll()`, `INode` and `INodeList` is covered later on this page.
+
+Text content can also be verified with the `MarkupMatches()` method, e.g. the text inside the `<small>` element. It has the advantage over regular string comparison that it removes insignificant whitespace in the text automatically, even between words, where a normal string `Trim()` method isn't enough. For example:
 
-Ref to customizing markup matches
+[!code-csharp[](../../../samples/tests/xunit/VerifyMarkupExamples.cs?start=51&end=56&highlight=5)]
+
+The semantic HTML comparer can be customized to make a test case even more stable and easier to maintain. It is e.g. possible to ignore an element or attribute during comparison, or provide an regular expression to the comparer when comparing a specific element or attribute, to make the comparer work with generated data. Learn more about the customizations options on the <xref:semantic-html-comparison> page.
+
+## Inspecting DOM Nodes
+
+The rendered markup from a component is available as a DOM nodes through the <xref:Bunit.IRenderedFragment.Nodes> property on <xref:Bunit.IRenderedFragment>, as well as the `Find(string cssSelector)` and `FindAll(string cssSelector)` extension methods on <xref:Bunit.IRenderedFragment>.
+
+The <xref:Bunit.IRenderedFragment.Nodes> property and the `FindAll()` method returns an [AngleSharp](https://anglesharp.github.io/) `INodeList` type, and the `Find()` method returns an [AngleSharp](https://anglesharp.github.io/) `IElement` type. 
+
+The DOM API in AngleSharp follows the W3C DOM API specifications and gives you the same results as state of the art browsers implementation of the DOM API in JavaScript does. Besides the official DOM API, AngleSharp and bUnit adds some useful extension methods on top. This makes working with DOM nodes convenient.
+
+### Finding Nodes with the Find() and FindAll() methods
+
+Users of the famous JavaScript framework [jQuery](https://jquery.com/) will recognize the two methods [`Find(string cssSelector)`](xref:Bunit.RenderedFragmentExtensions.Find(Bunit.IRenderedFragment,System.String)) and [`FindAll(string cssSelector)`](xref:Bunit.RenderedFragmentExtensions.FindAll(Bunit.IRenderedFragment,System.String,System.Boolean)). 
+
+- [`Find(string cssSelector)`](xref:Bunit.RenderedFragmentExtensions.Find(Bunit.IRenderedFragment,System.String)) takes a "CSS selector" as input and returns an `IElement` as output, or throws an exception if non is found.
+- [`FindAll(string cssSelector)`](xref:Bunit.RenderedFragmentExtensions.FindAll(Bunit.IRenderedFragment,System.String,System.Boolean)) takes a "CSS selector" as input a list of `IElement` elements.
+
+Let's see some examples of using the [`Find(string cssSelector)`](xref:Bunit.RenderedFragmentExtensions.Find(Bunit.IRenderedFragment,System.String)) and [`FindAll(string cssSelector)`](xref:Bunit.RenderedFragmentExtensions.FindAll(Bunit.IRenderedFragment,System.String,System.Boolean)) methods to query the `<FanyTable>` component listed below.
+
+[!code-razor[FanyTable.razor](../../../samples/components/FanyTable.razor)]
+
+To find the `<caption>` element and the first `<td>` elements in each row, do the following:
+
+[!code-csharp[](../../../samples/tests/xunit/VerifyMarkupExamples.cs?start=62&end=67&highlight=5-6)]
+
+Once you have one or more elements, you verify against them by e.g. inspecting their properties through the DOM API. For example:
+
+[!code-csharp[](../../../samples/tests/xunit/VerifyMarkupExamples.cs?start=69&end=71)]
+
+
+
+
+
+#### Refreshable FindAll() Queries
+
+### Useful DOM Properties and Methods for Asserting 
+
+## Diffing DOM Nodes
+
+- Since first render
+- since snapshot
+- Assertion helpers for List of IDiff
diff --git a/docs/site/templates/bunit/partials/scripts.tmpl.partial b/docs/site/templates/bunit/partials/scripts.tmpl.partial
@@ -1,5 +1,9 @@
 {{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}}
 
 <script type="text/javascript" src="{{_rel}}styles/docfx.vendor.js"></script>
+<script type="text/javascript" src="{{_rel}}styles/cshtml-razor.js"></script>
+<script>
+  hljs.registerLanguage('cshtml-razor', window.hljsDefineCshtmlRazor);
+</script>
 <script type="text/javascript" src="{{_rel}}styles/docfx.js"></script>
 <script type="text/javascript" src="{{_rel}}styles/main.js"></script>
diff --git a/docs/site/templates/bunit/styles/cshtml-razor.js b/docs/site/templates/bunit/styles/cshtml-razor.js
diff --git a/docs/site/templates/bunit/styles/docfx.vendor.css b/docs/site/templates/bunit/styles/docfx.vendor.css
diff --git a/docs/site/templates/bunit/styles/docfx.vendor.js b/docs/site/templates/bunit/styles/docfx.vendor.js

Original file line number	Diff line number	Diff line change
`@@ -11,3 +11,4 @@ Show Instance prop`
`11`	`11`
`12`	`12`	`Warn against setting props directly`
`13`	`13`
	`14`	`+FindComponent/FindComponents`