Created docs toc and outlined some docs

egil · egil · commit 7a67b5f6530a · 2020-05-22T22:08:27.000Z
diff --git a/docs/.editorconfig b/docs/.editorconfig
@@ -23,10 +23,10 @@ tab_size = 2
 tab_size = 2
 
 [*.{ps1,psm1}]
-tab_size = 4
+tab_size = 2
 
 [*.sh]
-tab_size = 4
+tab_size = 2
 end_of_line = lf
 
 [*.{yml,yaml,md}]
@@ -37,6 +37,7 @@ tab_size = 2
 trim_trailing_whitespace = false
 
 [*.{cs,razor}]
+tab_size = 2
 dotnet_diagnostic.BL0001.severity = none
 dotnet_diagnostic.BL0002.severity = none
 dotnet_diagnostic.BL0003.severity = none
diff --git a/docs/docs/getting-started/create-test-project.md b/docs/docs/getting-started/create-test-project.md
@@ -22,7 +22,7 @@ These steps look like this from the `dotnet` CLI:
 
 **1. Create a new test project**
 
-Use the following command:
+Use the following command (click on the tab that for the test framework you would like to use):
 
 # [xUnit](#tab/xunit)
 
diff --git a/docs/docs/getting-started/index.md b/docs/docs/getting-started/index.md
diff --git a/docs/docs/getting-started/writing-razor-tests.md b/docs/docs/getting-started/writing-razor-tests.md
@@ -5,11 +5,16 @@ title: Writing tests in Razor syntax for Blazor components
 
 # Writing tests in Razor syntax for Blazor components
 
-A test for a Blazor component can be written in a Blazor component, using a mix of Razor and C# syntax. The advantage of this is the familiarity in declaring the component under test, and other HTML or Razor fragments that will be used in the test, in Razor and HTML markup. This is especially useful when testing components that takes a lot of parameters and child content as input.
-
 > [!WARNING]
 > Razor tests are currently only compatible with using xUnit as the general purpose testing framework.
 
+A test for a Blazor component can be written in a Blazor component, using a mix of Razor and C# syntax. The advantage of this is the familiarity in declaring the component under test, and other HTML or Razor fragments that will be used in the test, in Razor and HTML markup. This is especially useful when testing components that takes a lot of parameters and child content as input.
+
+> [!TIP]
+> Tests declared inside Blazor test components can be discovered and invoked individually, and will show up in e.g. Visual Studio's Test Explorer. 
+> 
+> However, they will _not_ show up before the Blazor test component has been compiled into C# by the Blazor compiler, and if there are compile-errors from the Blazor compiler, they might appear to come and go in the Test Explorer.
+
 ## Create a test specific `_Imports.razor` file
 
 Razor tests are written in Blazor test components. To make our life's a little easier, let's first set up a `_Imports.razor` file, with the using statements we are going to be using throughout our tests. Simply add the following `_Imports.razor` to the root folder where you will be placing your Blazor test components:
diff --git a/docs/docs/input/passing-parameters-to-components.md b/docs/docs/input/passing-parameters-to-components.md
diff --git a/docs/docs/misc-test-tips.md b/docs/docs/misc-test-tips.md
@@ -37,6 +37,10 @@ A neat trick, which will limit the `import` statements needed in your test proje
 </PropertyGroup>
 ```
 
+## Capture logs from ILogger in test output
+
+TODO: Document XunitLogger and XunitLoggerFactory
+
 ## Make copy/paste of HTML easier
 
 When writing C# based tests, you sometime want to copy/paste some HTML into C# strings from e.g. a Razor file. This is tedious to do manually as you have to escape the quotes and other special characters. The extension, [SmartPaster2019](https://marketplace.visualstudio.com/items?itemName=martinw.SmartPaster2013), allows us to copy strings where any character that needs to be escaped will be automatically.
diff --git a/docs/docs/mocking/index.md b/docs/docs/mocking/index.md
@@ -0,0 +1,12 @@
+﻿---
+uid: mocking
+title: Mocking component dependencies
+---
+
+# Mocking component dependencies
+
+intro
+
+Mention Moq, JustMock, say nothing special required.
+
+Read more points to specific mocking guides for Blazor.
diff --git a/docs/docs/mocking/mocking-auth.md b/docs/docs/mocking/mocking-auth.md
@@ -0,0 +1,8 @@
+﻿---
+uid: mocking-auth
+title: Mocking Blazor's Authorization
+---
+
+# Mocking Blazor's Authorization
+
+https://github.com/egil/bunit/issues/135
diff --git a/docs/docs/mocking/mocking-httpclient.md b/docs/docs/mocking/mocking-httpclient.md
@@ -0,0 +1,8 @@
+﻿---
+uid: mocking-httpclient
+title: Mocking HttpClient
+---
+
+# Mocking `HttpClient`
+
+TODO - https://github.com/egil/bunit/issues/61
diff --git a/docs/docs/mocking/mocking-ijsruntime.md b/docs/docs/mocking/mocking-ijsruntime.md
@@ -1,5 +1,12 @@
-# Mocking IJsRuntime
+---
+uid: mocking-ijsruntime
+title: Mocking Blazor's IJSRuntime
+---
+
+# Mocking Blazor's `IJSRuntime`
 
 This page is on the todo list.
 
 To see examples of how to mock the JsRuntime, go to the [C# test examples](/docs/csharp-test-examples.html#testing-components-that-use-on-ijsruntime) page.
+
+- TODO: https://github.com/egil/bunit/issues/67
diff --git a/docs/docs/mocking/mocking-localizer.md b/docs/docs/mocking/mocking-localizer.md
@@ -0,0 +1,6 @@
+﻿---
+uid: mocking-localizer
+title: Mocking localization via IStringLocalizer
+---
+
+# Mocking localization via `IStringLocalizer`
diff --git a/docs/docs/mocking/mocking-navigation-manager.md b/docs/docs/mocking/mocking-navigation-manager.md
@@ -0,0 +1,6 @@
+﻿---
+uid: mocking-navigation-manager
+title: Mocking Blazor's Navigation Manager
+---
+
+# Mocking Blazor's `NavigationManager`
diff --git a/docs/docs/providing-input/configure-3rd-party-libs.md b/docs/docs/providing-input/configure-3rd-party-libs.md
@@ -0,0 +1,14 @@
+﻿---
+uid: configure-3rd-party-libs
+title: How to test components that use 3rd party libraries
+---
+
+# How to test components that use 3rd party libraries
+
+General introduction about what is usually required: Mimic setup guide from lib in test.
+
+Talk about following section containing specific instructions for 3rd parter libraries.
+
+Add how to for test setup of tests that use Telerik, SyncFusion, etc. libraries. They often have IJsRuntime or other services that needs mocking or setup, before a test can run.
+
+The how to should be as minimal as possible, preferably with links to vendors own documentation, so we do not have to keep it up to date if the vendor changes something in their library.
diff --git a/docs/docs/providing-input/inject-services-into-components.md b/docs/docs/providing-input/inject-services-into-components.md
diff --git a/docs/docs/providing-input/passing-parameters-to-components.md b/docs/docs/providing-input/passing-parameters-to-components.md
@@ -0,0 +1,32 @@
+﻿---
+uid: passing-parameters-to-components
+title: How to pass parameters to a component under test
+---
+
+# Passing parameters to a component under test
+
+Describe factory methods and builder.
+
+Highlight blazor test components only need this for re-renders through SetParametersAndRender, which alternatively can be done by just mutating a field captured by a parameter.
+
+## Component specific parameters
+
+Show same cases for factory and builder using tabs.
+
+### EventCallback
+
+### Child content
+
+### RenderFragment
+
+### Templates
+
+### Unmatched parameters
+
+## Cascading value parameters
+
+## How to render component inside other components
+
+## Further reading
+
+- <xref:inject-services-into-components>
diff --git a/docs/docs/providing-input/trigger-event-handlers.md b/docs/docs/providing-input/trigger-event-handlers.md
diff --git a/docs/docs/providing-input/trigger-renders.md b/docs/docs/providing-input/trigger-renders.md
@@ -0,0 +1,8 @@
+﻿---
+uid: trigger-renders
+title: Triggering a render life-cycle on a component
+---
+
+# Triggering a render life-cycle on a component
+
+Describe how to trigger an explicit render life-cycle through the IRenderedComponent Render, SetParametersAndRender, and InvokeAsync methods.
diff --git a/docs/docs/toc.md b/docs/docs/toc.md
@@ -1,14 +1,29 @@
-# [Getting Started](xref:getting-started)
+# [Getting started](xref:getting-started)
 ## [Create a test project](xref:create-test-project)
 ## [Writing tests in C#](xref:writing-csharp-tests)
 ## [Writing tests in Razor syntax](xref:writing-razor-tests)
 ## [Fixture test options](xref:fixture-options)
 ## [SnapshotTest options](xref:snapshot-options)
-# [C# based testing](csharp-based-testing.md)
-# [Razor based testing](razor-based-testing.md)
-# [Snapshot testing](snapshot-testing.md)
-# [Semantic HTML markup comparison](xref:semantic-html-comparison)
-# [Mocking JsRuntime](mocking-jsruntime.md)
+
+# [Providing input](xref:passing-parameters-to-components)
+## [Pass parameters and cascading values](xref:passing-parameters-to-components)
+## [Inject services](xref:inject-services-into-components)
+## [Trigger event handlers](xref:trigger-event-handlers)
+## [Trigger renders](xref:trigger-renders)
+## [Configure 3rd party libraries](xref:configure-3rd-party-libs)
+
+# [Verifying output](xref:verify-markup)
+## [Verify markup](xref:verify-markup)
+## [Verify component state](xref:verify-component-state)
+## [Semantic HTML markup comparison](xref:semantic-html-comparison)
+
+# [Mocking](xref:mocking)
+## [Mocking authorization](xref:mocking-auth)
+## [Mocking HttpClient](xref:mocking-httpclient)
+## [Mocking IJsRuntime](xref:mocking-ijsruntime)
+## [Mocking localization](xref:mocking-localizer)
+## [Mocking NavigationManager](xref:mocking-navigation-manager)
+
 # [Miscellaneous bUnit testing tips](xref:misc-test-tips)
 # [Tutorials and Presentations](tutorials-and-presentations.md)
 # [Contribute](contribute.md)
diff --git a/docs/docs/verification/semantic-html-comparison.md b/docs/docs/verification/semantic-html-comparison.md
@@ -1,6 +1,6 @@
 ---
 uid: semantic-html-comparison
-title: Semantic HTML markup comparison
+title: Customizing the semantic HTML comparison
 ---
 
 # Semantic HTML markup comparison
@@ -9,7 +9,7 @@ This library includes comparison and assert helpers that uses the [AngleSharp Di
 
 On this page we will go through how the comparison works, and what options you have to affect the comparison process.
 
-> **NOTE:** The semantic HTML comparison is available in all three test types, but is always used in the Snapshot test type.
+> **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.
 
 ## Why semantic comparison is needed for stable tests
 
diff --git a/docs/docs/verification/verify-component-state.md b/docs/docs/verification/verify-component-state.md
@@ -5,4 +5,9 @@ title: How to verify the state of a component under test
 
 # Verifying the state of a component under test
 
-TODO!
+Describe IRenderedComponent interface
+
+Show Instance prop
+
+Warn against setting props directly
+
diff --git a/docs/docs/verification/verify-markup.md b/docs/docs/verification/verify-markup.md
@@ -5,4 +5,27 @@ title: How to verify the rendered markup from a component under test
 
 # Verifying the rendered markup from a component under test
 
-TODO!
+Describe how markup is available.
+
+List properties in renderedfragment for accessing rendered markup.
+
+Mention AngleSharp and the complete DOM api.
+
+## Finding DOM nodes
+
+### Refreshable find queries
+
+## Useful DOM properties and methods for asserting 
+
+## Diffing DOM nodes
+
+- Since first render
+- since snapshot
+- Assertion helpers for List of IDiff
+
+## MarkupMatches
+
+- Make case for semantic comparison
+- Show use cases
+
+Ref to customizing markup matches
diff --git a/docs/samples/components/Heading.razor b/docs/samples/components/Heading.razor
@@ -0,0 +1,4 @@
+<h3 id="heading-1337" required>
+  Heading text
+  <small class="text-muted mark">Secondary text</small>
+</h3>
