updates to docs and samples

egil · egil · commit 9ff70f481701 · 2019-12-15T06:57:21.000Z
diff --git a/docs/razor-examples.md b/docs/razor-examples.md
@@ -2,11 +2,12 @@
 
 The library supports specifying the component under test and other markup/fragments using Razor syntax. The advantage is that we get Visual Studio help writing Razor and HTML, which is a much nicer experience than writing HTML in a string in a C# class/file. This is especially useful for more complex scenarios, where e.g. a component under test has many parameters or complex child contents.
 
-**NOTE:** This feature is _EXPERIMENTAL_ and syntax and API will likely changed.
+**NOTE:** This feature is _EXPERIMENTAL_ and syntax and API will likely changed. See [Contribute](readme.md/#contribute) for info on how to provide feedback and suggestions.
 
 1. [Creating new test component](#creating-new-test-component)
-1. [Defining test cases](#defining-test-cases)
-1. [Known issues](#known-issues)
+2. [Defining test cases](#defining-test-cases)
+3. [Examples](#examples)
+4. [Known issues](#known-issues)
 
 ## Creating new test component
 
@@ -77,7 +78,7 @@ The code above works as follows:
 
 - Inside the `Test` methods you can do all the things you can in C#-based tests, e.g. assert against the CUT. The only difference is that some methods such as `TakeSnapshot()` is not available on the local scope, but through the `IRazorTestContext` object passed to each Test method.
 
-### Examples
+## Examples
 
 Here is a few examples that demonstrate how Razor test components can be used. More can be found in the [samples/tests/RazorComponentTests](../samples/tests/RazorComponentTests) samples folder.
 
diff --git a/docs/snapshot-examples.md b/docs/snapshot-examples.md
@@ -1,3 +1,81 @@
 # Writing Snapshot Tests for Blazor Components
 
-TODO
+The library has basic support for snapshot testing, declared via Razor syntax in Razor files. In snapshot testing, you declare your input (e.g. one or more component under test) and the expected output, and the library will automatically tell you if they do not match.
+
+Notable features that are missing at the moment is the ability to auto-generate the expected output and to trigger updates of expected output.
+
+**NOTE:** This feature is _EXPERIMENTAL_ and syntax and API will likely changed. See [Contribute](readme.md/#contribute) for info on how to provide feedback and suggestions.
+
+1. [Creating new snapshot test component](#creating-new-snapshot-test-component)
+2. [Defining snapshot test cases](#defining-snapshot-test-cases)
+3. [Examples](#examples)
+4. [Known issues](#known-issues)
+
+## Creating new snapshot test component
+
+To create Razor-based snapshot tests, we need to create snapshot test components.
+
+All snapshot test components must inherit from `TestComponentBase`, e.g. by adding `@inherits TestComponentBase` to the top of your .razor file.
+
+**Tip:** In the folder you keep your Razor-based snapshot tests, add a `_Imports.razor` file, and put `@inherits TestComponentBase` into that as well as any using statements you need. Then all snapshot test components inherits the correct base component by default and have the default imports available.
+
+## Defining snapshot test cases
+
+All you need to define a snapshot test case is the `<SnapshotTest>` component added to a test component, e.g.:
+
+```cshtml
+<SnapshotTest Description="Helpful description of the test case - displayed if test fails"
+              Setup="ctx => ctx.Services.AddMockJsRuntime()">
+    <TestInput><!-- Declare your test input here, e.g. one or more components --></TestInput>
+    <ExpectedOutput><!-- Declare your expected output here --></ExpectedOutput>
+</SnapshotTest>
+```
+
+You can add as many `<SnapshotTest>` components to a test component as you want. Each `<SnapshotTest>` component will go through this life cycle:
+
+1. Create a new test context (of type `ITestContext`).
+2. Call the `Setup` method, if specified, and pass it the test context. Use the `Setup` method to e.g. configure services, like registering a mock `IJsRuntime`.
+3. Render the child content of the `<TestInput>` component and capture its output.
+4. Render the child content of the `<ExpectedOutput>` component and capture its output.
+5. Verify that the two outputs are equal. If they are not, the test will fail with an `HtmlEqualException`.
+
+## Examples
+
+The following example shows how to test the the [TodoList.razor](../sample/src/Pages/TodoList.razor) component:
+
+```cshtml
+@inherits TestComponentBase
+
+<SnapshotTest Description="A todolist with one todo added should render correctly"
+              Setup="ctx => ctx.Services.AddMockJsRuntime()">
+    <TestInput>
+        <TodoList Label="My label" Items=@(new Todo[]{ new Todo{ Id=42, Text="Check out this new thing called Blazor" } })>
+            <ItemsTemplate Context="todo">
+                <TodoItem Todo="todo"></TodoItem>
+            </ItemsTemplate>
+        </TodoList>
+    </TestInput>
+    <ExpectedOutput>
+        <form>
+            <div class="input-group">
+                <input type="text" class="form-control" placeholder="My label" aria-label="My label" value="" />
+                <div class="input-group-append">
+                    <button class="btn btn-secondary" type="submit">Add task</button>
+                </div>
+            </div>
+        </form>
+        <ol class="list-group">
+            <li id:regex="todo-42" class="list-group-item list-group-item-action">
+                <span>Check out this new thing called Blazor</span>
+                <span class="float-right text-danger">(click to complete)</span>
+            </li>
+        </ol>
+    </ExpectedOutput>
+</SnapshotTest>
+```
+
+## Known issues
+
+These are the known issues:
+
+1. The xUnit test runner is not able to distinguish the individual `<SnapshotTest>`'s from each other. So they are all executed together, one at the time. This is less than a problem with snapshot tests than with Razor based tests, since a failing test will have its description printed along with the differences found in the snapshot. The solution is to develop a custom test runner, see [issue #4 - Create custom xUnit test runner/discoverer](/issues/4) for more details.
diff --git a/sample/tests/RazorTestComponents/Components/TodoListTest.razor b/sample/tests/RazorTestComponents/Components/TodoListTest.razor
@@ -2,7 +2,8 @@
 @using Xunit
 
 <Fixture Setup="ctx => ctx.Services.AddMockJsRuntime()"
-         Tests="new Test[]{ EmptyTodoList, SettingLabel, TaskListRendersItemsUsingItemTemplate }">
+         Test="EmptyTodoList"
+         Tests="new Test[]{ SettingLabel, TaskListRendersItemsUsingItemTemplate }">
     <ComponentUnderTest>
         <TodoList>
             <ItemsTemplate>
@@ -31,17 +32,24 @@
 
     void EmptyTodoList(IRazorTestContext context)
     {
+        // Act - get the CUT
         var cut = context.GetComponentUnderTest<TodoList>();
 
-        cut.ShouldBe(context.GetFragment("EmptyTodoListRender"));
+        // Assert - get the expected initial rendered HTML from the fragment 
+        // and use it to verify the initial rendered HTML
+        var expectedInitialRender = context.GetFragment("EmptyTodoListRender");
+        cut.ShouldBe(expectedInitialRender);
     }
 
     void SettingLabel(IRazorTestContext context)
     {
+        // Arrange - get the CUT
         var cut = context.GetComponentUnderTest<TodoList>();
 
+        // Act - update label 
         cut.SetParametersAndRender((nameof(TodoList.Label), "LABEL"));
 
+        // Assert - verifiy that the placeholder and aria-label has changed
         cut.GetChangesSinceFirstRender().ShouldAllBe(
             diff => diff.ShouldBeAttributeChange("placeholder", "LABEL"),
             diff => diff.ShouldBeAttributeChange("aria-label", "LABEL")
@@ -50,14 +58,17 @@
 
     void TaskListRendersItemsUsingItemTemplate(IRazorTestContext context)
     {
+        // Arrange - get the cut and take a snapshot of the current render tree output
         var cut = context.GetComponentUnderTest<TodoList>();
         cut.TakeSnapshot();
 
+        // Act - assign test todo items to the CUT
         cut.SetParametersAndRender((nameof(TodoList.Items), TestItems));
 
+        // Assert - get the diffs since the snapshot and compare to the expected.
         var diffs = cut.GetChangesSinceSnapshot();
-        diffs.ShouldHaveSingleChange()
-        .ShouldBeAddition(context.GetFragment("TodoItemRender"));
+        var expected = context.GetFragment("TodoItemRender");
+        diffs.ShouldHaveSingleChange().ShouldBeAddition(expected);
     }
 }
 
@@ -86,44 +97,55 @@
 
     void OnFirstRenderInputFieldGetsFocus(IRazorTestContext context)
     {
+        // Act
         var cut = context.GetComponentUnderTest<TodoList>();
 
-        // assert that there is a call to document.body.focus.call with a single argument,
+        // Assert that there is a call to document.body.focus.call with a single argument,
         // a reference to the input element.
         jsRtMock.VerifyInvoke("document.body.focus.call")
             .Arguments.Single().ShouldBeElementReferenceTo(cut.Find("input"));
     }
 
     void AfterFirstRenderInputFieldDoesntGetFocusAfterRerenders(IRazorTestContext context)
     {
+        // Arrange
         var cut = context.GetComponentUnderTest<TodoList>();
 
+        // Act
         cut.Render(); // second render
         cut.Render(); // thrid render
         cut.Render(); // ...
         cut.Render();
 
+        // Assert that focus logic only runs on first render (only called 1 time).
         jsRtMock.VerifyInvoke("document.body.focus.call", calledTimes: 1);
     }
 
     void WhenAddTaskFormIsSubmittedWithNoTextOnAddingTodoIsNotCalled(IRazorTestContext context)
     {
+        // Arrange
         var cut = context.GetComponentUnderTest<TodoList>();
 
+        // Act - submit the empty form
         cut.Find("form").Submit();
 
+        // Assert - verify that no task was created
         Assert.Null(createdTodo);
     }
 
     void WhenAddTaskFormIsSubmittedWithTextOnAddingTodoIsCalled(IRazorTestContext context)
     {
+        // Arrange - ensure createdTask is null
         createdTodo = null;
         var cut = context.GetComponentUnderTest<TodoList>();
         var taskValue = "HELLO WORLD TASK";
 
+        // Act - find input field and change its value, then submit the form
         cut.Find("input").Change(taskValue);
         cut.Find("form").Submit();
 
+        // Assert that a new task has been passed to the EventCallback listener and that the 
+        // new task has the expected value
         Assert.NotNull(createdTodo);
         Assert.Equal(taskValue, createdTodo?.Text);
     }
diff --git a/sample/tests/SnapshotTests/TodoListTest.razor b/sample/tests/SnapshotTests/TodoListTest.razor
@@ -19,8 +19,8 @@
             </div>
         </form>
         <ol class="list-group">
-            <li id:regex="todo-[\d]+" class="list-group-item list-group-item-action">
-                <span diff:regex>[\w\d]+</span>
+            <li id:regex="todo-42" class="list-group-item list-group-item-action">
+                <span>Check out this new thing called Blazor</span>
                 <span class="float-right text-danger">(click to complete)</span>
             </li>
         </ol>
