bUnit version 2

[egil]

bUnit version 2

I want to start a discussion of where we should take bUnit version 2, what the high-level goals are, and what the API changes we are planning should be.

High-level goals

Remove unnecessary abstractions

Some abstractions were put in place to support other things like MobileBlazorBindings. It still makes sense to have a core lib, i.e. bunit.core, since 3rd parties can take a dependency on that if they want to provide extensions to the core types like ITestContext or IRenderedFragment.

Simplify core types and make them extensible instead

For example, remove support for SaveSnapshot, GetChangesSinceSnapshot, and GetChangesSinceFirstRender from IRenderedFragment and instead make the functionality possible through custom IRenderedFragment subtypes, that users can use if they want that functionality.

Rename types and interfaces that overlap with over libraries and Blazor's types

For example: Rename TestContext to BunitContext to avoid conflict with MSTest and NUnit's TestContext type. Another example is renaming TestRenderer to BunitRenderer.

Renaming some test doubles, e.g. FakeNavigationManager to BunitNavigationManager. That allows us to evolve and change bUnits navigation manager without breaking with specific test conventions.

To align with Blazor's API, we could align with the concept of RootComponents and rename TestContext.RenderTree to TestContext.RootComponents.

100% deterministic testing

This includes:

• Using a synchronization context/dispatcher to ensure test code does not run concurrently with the renderer unless desired by the user.
• Switch to async versions of render and event dispatch methods.
• Make WaitFor methods async

One renderer per (root) render

Currently, the TestContext creates one TestRenderer and uses that for all calls to TestContext.Render method calls. Instead, the TestContext should be considered a "configuration hub" where users can set up services, root components, and JSInterop, and then each root/initial render call gets a unique renderer.

This will align more with how Blazor works, i.e. one renderer per "application", and will allow future scenarios more easily, such as enabling predictable "Shallow Render", e.g. a render that only renders the component at the top of the component tree.

The downside is additional overhead for tests that calls Render multiple times. However, the expectation is that almost all tests only perform one render call anyway, so that actual impact is likely going to be negligible.

Open question: Should the TestServiceProvider be shared?

Public API changes

Here are the current suggestions for changes to the public API.

If the list grows too large, we could consider providing a bunit.compat package that maps between the v1 and v2 APIs.

AngleSharpWrappers

The purpose of the wrappers is to allow users to keep a reference to one element between renders, and if it changes, not having to query/find it again, but see the updates directly in the already referenced element.

Recent changes in the AngleSharp library enable us to achieve a similar result and allow us to add additional metadata to elements and perhaps nodes too. The key seems to be the introduction to factories that AngleSharp uses to create elements, and the ability to replace the factories.

With changes to BunitHtmlParser, we can potentially improve the user experience of the DOM node users are accessing. This could be through creating custom BunitHtmlElement types, that have additional functionality needed in bUnit tests, e.g.:

• Attach event handlers to elements
• Keep a reference on elements to the IRenderedComponent that created them

Below are some rough experiments with using IElementFactory:

// Registers a custom element factory.
// Something similar can be done with Document.
var config = Configuration
    .Default
    .WithOnly<IElementFactory<Document, HtmlElement>>(new BunitElementFactory());

// Set up the browser context that is needed for
// parsing raw markup.
var context = BrowsingContext.New(config);
var parseOptions = new HtmlParserOptions
{
    IsKeepingSourceReferences = true,
};
var htmlParser = new HtmlParser(parseOptions, context);
var parseContextDoc = await context
    .GetFactory<IDocumentFactory>()
    .CreateAsync(
        context,
            new CreateDocumentOptions(
                VirtualResponse.Create(static _ => { })),
        CancellationToken.None);

var parseContextElement = parseContextDoc.Body ?? throw new Exception("BODY IS NULL");

// Calling the html parser will cause the BunitElementFactory to be called
var res1 = htmlParser.ParseFragment("<h1>foo</h1>", parseContextElement);

internal class BunitElementFactory : IElementFactory<Document, HtmlElement>
{
    public HtmlElement Create(Document document, string localName, string? prefix = null, NodeFlags flags = NodeFlags.None)
    {
        // TODO: return bUnit version of elements that contains additional meta data
        throw new NotImplementedException();
    }
}

bunit.core

WIP!

The outline of a replacement for TestContext/TestContextBase.
The idea here is to simplify the render methods to three options, a basic one that takes the simplest form, a RenderFragment, and one
that exposes the render fragment/parameter builder version currently called RenderComponent. I do not want to carry over the other variants of RenderComponent, because I see very little usefulness in them and they were just kept around to avoid breaking changes.

I include both a generic and none-generic version of the Render method that takes a RenderFragment. It's not a great solution, but it also feels redundant for users that write tests in .razor files and want to just pass in @<MyComp /> to the Render method to also have to specify the component name as a generic.

public class BunitContext
{
  public BunitServiceProvider Services { get; }
  public BunitJSInterop JSInterop { get; }
  public RootRenderTree RootComponents { get; }
  public ComponentFactoryCollection ComponentFactories { get; }	
  public Task<IRenderedComponent<IComponent>> RenderAsync(RenderFragment renderFragment);
  public Task<IRenderedComponent<TComponent>> RenderAsync<TComponent>(RenderFragment renderFragment);
  public Task<IRenderedComponent<TComponent>> RenderAsync<TComponent>(Action<ComponentParameterCollectionBuilder<TComponent>>? parameterCollectionBuilder = null);
  protected virtual void BuildRenderTree(Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder builder) { }
}

Usage of BunitContext:

var ctx = new BunitContext();

// RenderAsync methods
IRenderedComponent<IComponent> cut = await ctx.RenderAsync(@<Foo />);
IRenderedComponent<Foo> cut = await ctx.RenderAsync<Foo>(@<Foo />);
IRenderedComponent<Foo> cut = await ctx.RenderAsync<Foo>();

// RenderAsync methods with parameters
IRenderedComponent<IComponent> cut = await ctx.RenderAsync(@<Bar Name="baz" />);
IRenderedComponent<Bar> cut = await ctx.RenderAsync<Bar>(@<Bar Name="baz" />);
IRenderedComponent<Bar> cut = await ctx.RenderAsync<Bar>(ps => ps.Add(p => p.Name, "baz"));

I would like to get away from having both IRenderedFragment and IRenderedComponent. We actually never return an IRenderedComponent, when we're just rendering a component without knowing its type, it's just a RenderedComponent<IComponent> that is returned. I think I like better just to be explicit about it, and then users can inspect the result with their debugger and perhaps figure out that they can get the Instance of their component.

Instead of having SetParametersAndRender and Render methods, I think it's just as good to just have a RenderAsync methods that users can pass new parameters to via an optional parameter builder.

The OnAfterRender methods are a bit inspired by the similarly named method on ComponentBase. The idea with these methods is that a user can pass in an action/callback, that is invoked every time the component completes a render cycle. So this is a very low-level version of the "wait for" methods we currently have, and the methods should serve as the base for the more high-level "wait for assertion"/"wait for element" methods, as well as custom logic such as saving snapshots/state between renders for advanced diffing/assertion scenarios.

The OnAfterRender API idea is pretty fresh. Not sure if it could lead to memory leaks since there is no way to "unregister" the actions. Perhaps a different pattern is needed if this is a concern.

public interface IRenderedComponent<TComponent> where TComponent : IComponent
{
  public int RenderCount { get; }
  public bool IsDisposed { get; }
  public int ComponentId { get; }
  public TComponent Instance { get; }
  public string Markup { get; }
  public INodeList Nodes { get; }
  
  public Task RenderAsync(Action<ComponentParameterCollectionBuilder<TComponent>>? parameterCollectionBuilder = null);
  
  public void OnAfterRender(Action<IRenderedComponent<TComponent>> afterRenderAction);
  public void OnAfterRender(Func<IRenderedComponent<TComponent>, Task> afterRenderActionAsync);
}

Whenever a IRenderedComponent<T> is created, this factory should be used by the BunitRenderer. It will allow 3rd parties to provide a custom IRenderedComponent<T> type, which they can add custom logic to, such as the SaveSnapshot/GetChangesSinceSnapshot feature in v1. That should also make it possible for us to move to an AngleSharp
renderer version at some point.

public interface IRenderedComponentFactory
{
  IRenderedComponent<TComponent> Create<TComponent>(TComponent component, INodeList nodes) where TComponent : IComponent;
}

public class BunitRenderer
{
  public BunitRenderer(IRenderedComponentFactory renderedComponentFactory)
  {
  }
}

bunit.web

TODO

bunit.web.testcomponents

Remove project and subtypes completely.

[linkdotnet]

Simplify core types and make them extensible instead

I do like to simplify those parts. One thing we could tackle and review is the abstraction levels we are currently having in bUnit.
Especially those 4 types:

• IRenderFragmentBase
• IRenderFragment
• IRenderedComponentBase
• IRenderedComponent

The most probable type a user is facing is either IRenderFragment or IRenderedComponent (which makes the "base" interface type quite obsolete - from a user point of view. Maybe for extensibility that can be important).

If we take that further both interfaces (IRenderFragment and IRenderedComponent) do get implemented by the same internal type. So having only exposing interface overall should be fine enough.

[egil]

Agreed.

The background for splitting them up originally was to keep web-specific things out of bunit.core, so the core didn't have any dependencies on things specific to HTML/AngleSharp, and perhaps create a bunit.mobile variant. However, since MBB never took off, it looks like an unneeded effort.

I would even go so far as to say that we can keep only the IRenderedComponent<T>. Sometimes the T is unknown and will fall back to just IComponent, but that's OK too.

[linkdotnet]

AngleSharpWrappers

I really like the factory concept of AngleSharp. If we have the same objects updating "themselves" a lot of assertions might get easier overall without wrapping them in types.

With that, we could even think of removing GetChangesSinceSnapshot and friends from the IRenderFragment and having them separately in their own class to decouple what IRenderFragment should do.

var cut = await RenderAsync<MyComp>();
var snapshot = new SnapshotComparer(cut); // or SnapshotComparer.Default.Get(cut);
...
snapshot.GetChangesSinceLastRender().HasSomeChanges(); 

If we also have a factory model here, the user can extent the behavior. For example, we could have a snapshot compare that ignores certain aspects (like MarkupMatches ignores certain things if told so).

[egil]

I really like the factory concept of AngleSharp. If we have the same objects updating "themselves" a lot of assertions might get easier overall without wrapping them in types.

That is what AngleSharpWrappers provide currently. The Find(cssSelector) sets up the updating mechanism that does this currently. I think it can be made more elegant though by using the AngleSharp element factories. Another change in AngleSharp is that the implementations of IHtmlElement in AngleSharp are no longer internal, which means we can much easier extend them.

With that, we could even think of removing GetChangesSinceSnapshot and friends from the IRenderFragment and having them separately in their own class to decouple what IRenderFragment should do.

var cut = await RenderAsync<MyComp>();
var snapshot = new SnapshotComparer(cut); // or SnapshotComparer.Default.Get(cut);
...
snapshot.GetChangesSinceLastRender().HasSomeChanges(); 

If we also have a factory model here, the user can extent the behavior. For example, we could have a snapshot compare that ignores certain aspects (like MarkupMatches ignores certain things if told so).

That is my plan (to remove the snapshot-related stuff), but to enable something like that again through extensions, we need the IRenderedComponentFactory idea I talk about above. This is essential, as far as I can see, because that will enable an implementation of the IRenderedComponent<T> type to capture the state immediately after the first render of a component before the component gets a chance to re-render.

Your example with a SnapshotComparer above won't be able to give that guarantee.

[linkdotnet]

Yeah my example might not be able in the state it is (besides making FirstRenderMarkup internal :D).
But I guess we got the idea.