updated docs

Author: egil

docs/api/index.md

@@ -1,2 +1,3 @@
-# PLACEHOLDER
-TODO: Add .NET projects to the *src* folder and run `docfx` to generate **REAL** *API Documentation*!
+# bUnit References
+
+TODO: write intro

docs/docfx.json

@@ -3,7 +3,11 @@
     {
       "src": [
         {
-          "files": [ "bunit.csproj" ],
+          "files": [
+            "bunit.core/bunit.core.csproj",
+            "bunit.web/bunit.web.csproj",
+            "bunit.xunit/bunit.xunit.csproj"
+          ],
           "exclude": [ "**/bin/**", "**/obj/**" ],
           "src": "../src"
         }
@@ -65,7 +69,8 @@
       "_appTitle": "bUnit",
       "_description": "bUnit is a unit testing library for Blazor Components. You can easily define components under test in C# or Razor syntax and verify outcome using semantic HTML diffing/comparison logic. You can interact with and inspect components, trigger event handlers, provide cascading values, inject services, mock IJsRuntime, and perform snapshot testing.",
       "_enableSearch": true,
-      "_appLogoPath": "/images/blazor-logo.png"
+      "_appLogoPath": "/images/blazor-logo.png",
+      "_disableBreadcrumb": true
     },
     "postProcessors": [],
     "markdownEngineName": "markdig",

docs/docs/csharp-based-testing.md

@@ -172,8 +172,8 @@ public class ComponentTest : TestContext // implements the ITestContext interfac
 
 See the page [Mocking JsRuntime](/docs/mocking-jsruntime.html) for more details mock.
 
-**Further reading:**
+## Further reading:
 
 - [Semantic HTML markup comparison](/docs/semantic-html-markup-comparison.html)
 - [Mocking JsRuntime](/docs/mocking-jsruntime.html)
-- [C# test examples](/docs/csharp-test-examples.html)
+- [C# test examples in the sample project](https://github.com/egil/bunit/tree/master/sample/tests/Tests)

docs/docs/csharp-test-examples.md

@@ -1,5 +1,7 @@
 # C# test examples
 
+> **WARNING:** These examples are somewhat outdated. Some content in here might still apply:
+
 In the following examples, the terminology **component under test** (abbreviated CUT) is used to mean the component that is the target of the test. The examples below use the `Shouldly` assertion library as well. If you prefer not to use that just replace the assertions with the ones from your own favorite assertion library.
 
 All examples can be found in the [Tests](https://github.com/egil/razor-components-testing-library/tree/master/sample/tests/Tests) folder in the [Sample project](https://github.com/egil/razor-components-testing-library/tree/master/sample/).

docs/docs/index.md

@@ -8,28 +8,30 @@ The sections below takes you through each of the steps you need to get started:
 
 First you need a test project to store your component tests inside. Depending on what general purpose unit testing framework you prefer, you have a few options:
 
-- [Creating a new bUnit and xUnit test project](creating-a-new-bunit-xunit-project.html)
-- [Creating a new bUnit and NUnit test project](creating-a-new-bunit-nunit-project.html)
-- [Creating a new bUnit and MSTest test project](creating-a-new-bunit-mstest-project.html)
+- [Creating a new bUnit and xUnit test project](/docs/creating-a-new-bunit-xunit-project.html)
+- [Creating a new bUnit and NUnit test project](/docs/creating-a-new-bunit-nunit-project.html)
+- [Creating a new bUnit and MSTest test project](/docs/creating-a-new-bunit-mstest-project.html)
 
 ## The basics of testing Blazor components
 
 To test a component, you first have to render it with parameters, cascading values, and services passed into it. Then, you need access to the component's instance and the markup it has produced, so you can inspect and interact with both.
 
 There are three different ways of doing this in bUnit:
 
-1. [**C# based tests**](csharp-based-testing.html)  
+1. [**C# based tests**](/docs/csharp-based-testing.html)  
    With C# based tests, you write all your testing logic in C# files, i.e. like regular unit tests.
-2. [**Razor based tests**](razor-based-testing.html)  
+2. [**Razor based tests**](/docs/razor-based-testing.html)  
    With Razor based tests, you write tests in `.razor` files, which allows you to declare, in Razor syntax, the component under test and other markup fragments you need. You still write your assertions via C# in the .razor file, inside `@code {...}` blocks.
-3. [**Snapshot tests**](snapshot-testing.html)  
+3. [**Snapshot tests**](/docs/snapshot-testing.html)  
    Snapshot tests are written in `.razor` files. A test contains a definition of an input markup/component and the expected output markup. The library will then automatically perform an semantic HTML comparison. Very little C# is needed in this, usually only to configure services.
 
-To learn more, read the [Basics of Blazor component testing](basics-of-blazor-component-testing.html) page.
+To learn more, read the [Basics of Blazor component testing](/docs/basics-of-blazor-component-testing.html) page.
 
 ## Examples
 
 To see examples of how to work assert and manipulate a rendered component, go to the following pages:
 
-- [C# test examples](/docs/csharp-test-examples.html)
-- [Razor test examples](/docs/razor-test-examples.html)
+- [C# test examples in the sample project](https://github.com/egil/bunit/tree/master/sample/tests/Tests)
+- [Razor based test examples in the sample project](https://github.com/egil/bunit/tree/master/sample/tests/RazorTestComponents)
+- [Snapshot test examples in the sample project](https://github.com/egil/bunit/tree/master/sample/tests/SnapshotTests)
+

docs/docs/razor-based-testing.md

@@ -1,32 +1,12 @@
 # Razor-based testing
 
-This pages documents how to do Blazor/Razor component testing from `.razor` files.
-
-Before you get started, make sure you have read the [Getting started](/docs/getting-started.html) page and in particular the [Basics of Blazor component testing](/docs/basics-of-blazor-component-testing.html) section. It wont take long, and it will ensure you get a good start at component testing.
-
-> **NOTE:** This feature is _EXPERIMENTAL_ and syntax and API will likely changed. Here are a few limitations to be aware of at the moment:
->
-> - The xUnit test runner can detect and execute tests in Razor test components, but is not able to distinguish the individual `<Fixture>`'s from each other. They are all executed together, one at the time. The solution is planned, see the [related issue](https://github.com/egil/razor-components-testing-library/issues/4) for details.
-> - Go to the [Contribute](/docs/contribute) page for info on how to provide feedback and suggestions.
-
-> **TIP:** Working with and asserting against the rendered component and its output is covered on the [Working with rendered components and fragments](/docs/working-with-rendered-components-and-fragments.html) page.
-
-**Content:**
-
-- [Creating a new Razor test component](#creating-a-new-razor-test-component)
-- [Defining tests/fixtures in test components](#defining-testsfixtures-in-test-components)
-- [Executing test cases](#executing-test-cases)
+> **WARNINIG**: This feature is only supported when using bUnit with xUNit. NUnit and MSTest is planned.
 
-**Further reading:**
-
-- [Working with rendered components and fragments](/docs/working-with-rendered-components-and-fragments.html)
-- [Semantic HTML markup comparison](/docs/semantic-html-markup-comparison.html)
-- [Mocking JsRuntime](/docs/mocking-jsruntime.html)
-- [Razor test examples](/docs/razor-test-examples.html)
+This pages documents how to do Blazor/Razor component testing from `.razor` files.
 
 ## Creating a new Razor test component
 
-To create Razor based tests, we need to create test components. All test components must inherit from `TestComponentBase`, e.g. by adding `@inherits TestComponentBase` to the top of your .razor file. The `TestComponentBase` contains all the logic for rendering components and correctly dispose of renderers, components, and HTML parsers after each test.
+To create Razor based tests, we need to create Blazor test components. All test components must inherit from `TestComponentBase`, e.g. by adding `@inherits TestComponentBase` to the top of your .razor file.
 
 For example:
 
@@ -49,14 +29,12 @@ For example:
 You will also need to import a few namespaces to make asserting and mocking possible. They are best placed in an `_Imports.razor` file next to your Razor test components, e.g.:
 
 ```cshtml
-@using Microsoft.AspNetCore.Components.Web
-@using Microsoft.Extensions.DependencyInjection
 @using Bunit
 @using Bunit.Mocking.JSInterop
 @using Xunit
 ```
 
-> **NOTE:** The `_Imports.razor` has already been created for you if you are using the [Blazor test project template](/docs/creating-a-new-test-project.html).
+> **NOTE:** The `_Imports.razor` has already been created for you if you are using the [Blazor test project template](/docs/creating-a-new-bunit-xunit-project.html).
 
 ## Defining tests/fixtures in test components
 
@@ -65,13 +43,12 @@ When you have a Razor test component created, its time to add test cases/fixture
 Lets look at what options we have by setting up an empty test case, first the code:
 
 ```cshtml
-<Fixture Description="MyComponent renders as expected" @* Optional - description is shown in error message if test fails *@
-         Setup="Setup" @* Optional - method called first *@
-         SetupAsync="SetupAsync" @* Optional - method called after Setup *@
-         Test="Test1" @*  Optional - method called after Setup/SetupAsync *@
-         TestAsync="Test1Async" @*  Optional - method called after Test *@
-         Tests="new Action[]{ Test2, Test3 }"> @*  Optional - methods are called after Test/TestAsync, one at the time *@
-         TestsAsync="new Func<Task>[]{ Test2Async, Test3Async }"> @*  Optional - methods are called after Tests, one at the time *@
+<Fixture Description="MyComponent renders as expected"
+         Timeout="1000" 
+         Skip="Reason to skip the test"
+         Setup="Setup
+         SetupAsync="SetupAsync"
+         Test="Test1" @* or *@ TestAsync="Test1Async">
   <ComponentUnderTest>
     <MyComponent />
   </ComponentUnderTest>
@@ -85,56 +62,38 @@ Lets look at what options we have by setting up an empty test case, first the co
 @code {
   // Called first if present when added to the Setup parameter
   // on a <Fixture> component (can be named anything)
-  void Setup()
+  void Setup(Fixture fixture)
   {
     // Add services and do other setup work in this method.
-    Services.AddMockJsRuntime();
+    fixture.Services.AddMockJsRuntime();
   }
 
   // Called after Setup if present when added to the Setup parameter
   // on a <Fixture> component (can be named anything)
-  Task SetupAsync() => Task.CompletedTask;
+  Task SetupAsync(Fixture fixture) => Task.CompletedTask;
 
   // Called after Setup when added to the Test parameter to a
   // <Fixture> component (can be named anything)
-  void Test1()
+  void Test1(Fixture fixture)
   {
     // Renders a MyComponent component and assigns the result to
     // a cut variable. CUT is short for Component Under Test.
-    IRenderedComponent<MyComponent> cut = GetComponentUnderTest<MyComponent>();
+    IRenderedComponent<MyComponent> cut = fixture.GetComponentUnderTest<MyComponent>();
 
     // Renders the markup in the "first" fragment by calling GetFragment without an id.
-    IRenderedFragment firstFragment = GetFragment();
+    IRenderedFragment firstFragment = fixture.GetFragment();
 
     // Renders the markup in the "first" fragment by calling GetFragment with an id.
-    IRenderedFragment alsoFirstFragment = GetFragment("first");
+    IRenderedFragment alsoFirstFragment = fixture.GetFragment("first");
 
     // Both first fragments refers to the same instance.
     Assert.Equal(firstFragment, alsoFirstFragment);
 
     // Renders a MyOtherComponent component defined in the second fragment.
-    IRenderedComponent<MyOtherComponent> myOtherComponent = GetFragment<MyOtherComponent>("second");
+    IRenderedComponent<MyOtherComponent> myOtherComponent = fixture.GetFragment<MyOtherComponent>("second");
   }
 
-  Task Test1Async() => Task.CompletedTask;
-
-  // Called after Test when added to the Tests parameter to a
-  // <Fixture> component (can be named anything). Methods in
-  // the Tests parameter is called in the order they are present in the
-  // array.
-  void Test2()
-  {
-    // do more testing on CUT, f1 and f2 by retriving them.
-  }
-
-  void Test3()
-  {
-    // do more testing on CUT, f1 and f2 by retriving them.
-  }
-
-  Task Test2Async() => Task.CompletedTask;
-
-  Task Test3Async() => Task.CompletedTask;
+  Task Test1Async(Fixture fixture) => Task.CompletedTask;
 }
 ```
 
@@ -144,13 +103,12 @@ The code above works as follows:
 
   1. `Setup`
   2. `SetupAsync`
-  3. `Test`
-  4. `TestAsync`
-  5. `Tests`, one at the time, in the order they appear in the array.
-  6. `TestsAsync`, one at the time, in the order they appear in the array.
+  3. `Test` or `TestAsync`
 
-- The `Description` parameter on the `<Fixture>` element is displayed in the test runners error window if the test fails.
+- If the `Description` parameter is present, it is used as the name of the test in the Test Explorer and is displayed in the test runners error window if the test fails.
 - It is inside child component `<ComponentUnderTest>` where you declare the component under test.
+- If the `Timeout` parameter is specified, the test will timeout after the specified time, in milliseconds.
+- If `Skip` parameter is specified, the test is skipped and the reason is printed in the test output.
 - Any markup or component fragments that is needed for the test can be declared inside the optional `<Fragment>` components. The `Id` parameter is optional, and only needed if you have more than one.
 
 - To render and get the component under test or any of the fragments, use the `GetComponentUnderTest<TComponent>()` method, where `TComponent` is the type of the component you have defined under the `<ComponentUnderTest>` element.
@@ -163,4 +121,8 @@ The code above works as follows:
 
 Since Blazor test component use xUnit under the hood as a test runner, you execute your tests them in exactly the same way as you would normal xUnit unit tests, i.e. by running `dotnet test` from the console or running the tests through the Test Explorer in Visual Studio.
 
-Do note the current limitations mentioned at the top of the page.
+## Further reading:
+
+- [Semantic HTML markup comparison](/docs/semantic-html-markup-comparison.html)
+- [Mocking JsRuntime](/docs/mocking-jsruntime.html)
+- [Razor based test examples in the sample project](https://github.com/egil/bunit/tree/master/sample/tests/RazorTestComponents)

docs/docs/razor-test-examples.md

@@ -1,12 +1,14 @@
 # Razor test examples
 
+> **WARNING:** These examples are somewhat outdated. Some content in here might still apply:
+
 In the following examples, the terminology **component under test** (abbreviated CUT) is used to mean the component that is the target of the test. The examples below use the `Shouldly` assertion library as well. If you prefer not to use that just replace the assertions with the ones from your own favorite assertion library.
 
-All examples can be found in the [Tests](https://github.com/egil/razor-components-testing-library/tree/master/sample/tests/Tests) folder in the [Sample project](https://github.com/egil/razor-components-testing-library/tree/master/sample/).
+All examples can be found in the [Tests](https://github.com/egil/bunit/tree/master/sample/tests/Tests) folder in the [Sample project](https://github.com/egil/bunit/tree/master/sample/).
 
 ## Examples
 
-Here is a few examples that demonstrate how Razor test components can be used. More can be found in the [sample/tests/RazorComponentTests](https://github.com/egil/razor-components-testing-library/tree/master/sample/tests/RazorComponentTests) samples folder.
+Here is a few examples that demonstrate how Razor test components can be used. More can be found in the [sample/tests/RazorComponentTests](https://github.com/egil/bunit/tree/master/sample/tests/RazorComponentTests) samples folder.
 
 ```cshtml
 <Fixture Test="ThemedButtonUsesNamedCascadingValue">
@@ -30,7 +32,7 @@ Here is a few examples that demonstrate how Razor test components can be used. M
 }
 ```
 
-This example shows how [ThemedElement.razor](https://github.com/egil/razor-components-testing-library/tree/master/sample/src/Components/ThemedElement.razor) can be tested with cascading values.
+This example shows how [ThemedElement.razor](https://github.com/egil/bunit/tree/master/sample/src/Components/ThemedElement.razor) can be tested with cascading values.
 
 ```cshtml
 <Fixture Test=MarkupPassedViaChildContent>
@@ -53,9 +55,9 @@ This example shows how [ThemedElement.razor](https://github.com/egil/razor-compo
 }
 ```
 
-This example shows how [ThemedButton.razor](https://github.com/egil/razor-components-testing-library/tree/master/sample/src/Components/ThemedButton.razor) can be tested with with child content, and how a `<Fragment>` can be used to specify the expected output.
+This example shows how [ThemedButton.razor](https://github.com/egil/bunit/tree/master/sample/src/Components/ThemedButton.razor) can be tested with with child content, and how a `<Fragment>` can be used to specify the expected output.
 
-Lets look at a more complex example, a test of the [TodoList.razor](https://github.com/egil/razor-components-testing-library/tree/master/sample/src/Pages/TodoList.razor) component:
+Lets look at a more complex example, a test of the [TodoList.razor](https://github.com/egil/bunit/tree/master/sample/src/Pages/TodoList.razor) component:
 
 ```cshtml
 <Fixture Setup="() => Services.AddMockJsRuntime()"

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

@@ -6,13 +6,6 @@ On this page we will go through how the comparison works, and what options you h
 
 > **NOTE:** The semantic HTML comparison is available in all three test types, but is always used in the Snapshot test type.
 
-**Content:**
-
-- [Why semantic comparison is needed for stable tests](#why-semantic-comparison-is-needed-for-stable-tests)
-- [Customizing the comparison process](#customizing-the-comparison-process)
-- [Verifying output from components](#verifying-output-from-components)
-- [Different ways of getting the differences](#different-ways-of-getting-the-differences)
-
 ## Why semantic comparison is needed for stable tests
 
 Just performing string comparison of two strings containing HTML markup can break quite easily, _even_ if the two markup strings are semantically equivalent. Some changes that can cause a regular string comparison to fail are: