Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
345 lines (244 loc) · 15.5 KB

CONTRIBUTING.md

File metadata and controls

345 lines (244 loc) · 15.5 KB

Contributing to Reactor

Reactor lives at github.com/microsoft/microsoft-ui-reactor. Reactor is an experimental project — the API surface, DSL, and layering are all subject to change as we iterate in the open. Contributions and feedback are welcome from day one.

  • Report a bug or propose a feature: open an issue
  • Ask a question or float an idea: start a discussion
  • Submit a change: open a PR against main — please link the issue it addresses, keep the change focused, and include tests

When filing an issue, include the platform (x64 / ARM64), .NET SDK version, and a minimal repro. For bugs that involve real WinUI controls, a selfhost fixture (see below) is the ideal repro format.

Contributor License Agreement

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Prerequisites

  • .NET 10 SDK
  • Windows App SDK 2.0 — restored automatically from NuGet, no manual install required
  • Visual Studio 2022 (17.8+) or VS Code with C# Dev Kit

Package version: All projects reference Microsoft.WindowsAppSDK 2.0.1 (public NuGet). The version is centralized in Directory.Build.props — update it there to change the version for every project at once.

Building

From the command line

# Restore packages (pulls experimental WinUI 3 from NuGet)
dotnet restore Reactor.slnx

# Build the entire solution (framework, tests, test app, samples)
dotnet build Reactor.slnx

# Build just the framework
dotnet build src/Reactor/Reactor.csproj

From Visual Studio

  1. Open Reactor.slnx in Visual Studio 2022 (17.8+)
  2. Select the x64 or ARM64 platform from the toolbar
  3. Build the solution (Ctrl+Shift+B)

Visual Studio will restore NuGet packages on first load, pulling the experimental Windows App SDK.

Platforms

Library projects (Reactor, Reactor.Interop.WinForms) are architecture-neutral (AnyCPU). Application projects (samples, tests, CLI) target x64 and ARM64.

When building via the solution (dotnet build Reactor.slnx), the platform is selected automatically. When building a single app project directly, pass -p:Platform=x64 (or ARM64):

dotnet build tests/Reactor.Tests -p:Platform=x64
dotnet test  tests/Reactor.Tests -p:Platform=x64

Running tests

Reactor has three test suites. Each lives in its own project, so there are no filters to remember — one command per suite.

# Suite Project Runner What it tests
1 Unit tests/Reactor.Tests xUnit Algorithms, reconciliation, Yoga layout, hooks, D3 — no WinUI window
2 Selftest tests/Reactor.SelfTests MSTest (wraps TAP subprocess) Full reconciler pipeline against real WinUI controls, in-process
3 E2E tests/Reactor.AppTests MSTest + Appium/WinAppDriver Cross-process UIA validation, real user input

Three commands

# 1. Unit
dotnet test tests/Reactor.Tests

# 2. Selftest (in-process WinUI, ~10s; no filter needed)
dotnet test tests/Reactor.SelfTests

# 3. E2E (requires WinAppDriver)
dotnet test tests/Reactor.AppTests

# All three
dotnet test tests/Reactor.Tests && dotnet test tests/Reactor.SelfTests && dotnet test tests/Reactor.AppTests

Both Reactor.SelfTests and Reactor.AppTests declare a ProjectReference to Reactor.AppTests.Host with ReferenceOutputAssembly="false", so dotnet test rebuilds the Host first. No stale binaries.

When to write which test

If you're testing… Write a…
An algorithm, pure function, record equality, hook bookkeeping, D3 math — anything that doesn't need a WinUI window Unit test in tests/Reactor.Tests/
How an element mounts/updates against a real WinUI control, layout math against real Yoga+XAML, reconciler behavior end-to-end, assertions via VisualTreeHelper Selftest fixture in tests/Reactor.AppTests.Host/SelfTest/Fixtures/ (registered in SelfTestFixtureRegistry, wrapped by a [TestMethod] in SelfTestBatch)
Real user input (clicks, keystrokes, tab navigation), UIA properties as seen by assistive tech, cross-process behavior, XAML Island interop E2E test in tests/Reactor.AppTests/Tests/

Rule of thumb: start with a unit test. Drop to selftest only when you need a live control. Reach for E2E only when you need cross-process UIA — E2E is the slowest and flakiest tier.

1. Unit tests (tests/Reactor.Tests) — xUnit

xUnit tests covering framework internals without a WinUI window: element creation, reconciliation algorithms (LIS, keyed/positional), Yoga layout, localization, property hashing, control pooling, hooks, D3 charting math.

When to run: after any code change. Fast, no prerequisites beyond the .NET SDK.

dotnet test tests/Reactor.Tests

# Run a specific test class
dotnet test tests/Reactor.Tests --filter "FullyQualifiedName~ReconcilerMountUpdateTests"

2. Selftest (tests/Reactor.SelfTests) — MSTest + TAP

In-process checks that run inside a real WinUI window at CPU speed. Each fixture (in tests/Reactor.AppTests.Host/SelfTest/Fixtures/) mounts UI via ReactorHost, runs assertions through VisualTreeHelper, and emits TAP to stdout. SelfTestBatch launches the Host subprocess, parses TAP, and maps each fixture to a [TestMethod] so MSTest reports them individually. This is the only way to test the reconciler end-to-end against real WinUI controls.

When to run: after reconciler, control mount/update, or any UI-related changes.

dotnet test tests/Reactor.SelfTests

For faster iteration with raw TAP output, you can bypass MSTest and run the Host directly:

# Raw TAP output
dotnet run --project tests/Reactor.AppTests.Host -- --self-test

# Filter by fixture name prefix
dotnet run --project tests/Reactor.AppTests.Host -- --self-test --filter "Flex"

3. E2E tests (tests/Reactor.AppTests) — MSTest + WinAppDriver

End-to-end tests that use Appium/WinAppDriver to simulate real user input (clicks, keyboard, tab navigation) through the cross-process UI Automation pipeline. These verify the full input → render → output path and validate that UIA properties are visible to assistive technology.

When to run: before shipping. Slow, and requires WinAppDriver.

E2E test classes (across two host apps):

Class Host What it tests
InteractiveTests WinUI Counter clicks, observable mutation
AccessibilityTests WinUI WCAG property validation via UIA
AccessibilityInteractionTests WinUI Keyboard nav, live regions, headings, semantic panels
EventHandlerTests WinUI OnTapped, OnSizeChanged, OnPointerPressed, OnKeyDown, UseReducer
DataGridTests WinUI Click-to-edit, keyboard commit
WinFormsInteropTests WinForms XAML Island rendering, tab navigation, UIA across boundaries 
dotnet test tests/Reactor.AppTests

# A specific class
dotnet test tests/Reactor.AppTests --filter "ClassName=Reactor.AppTests.Tests.AccessibilityTests"

Requires: WinAppDriver installed at C:\Program Files (x86)\Windows Application Driver\WinAppDriver.exe. Unit and selftest runs don't need it.

WinForms tests also require Reactor.WinFormsTests.Host to build. It launches a separate WinForms app with a XAML Island.

Code coverage

The canonical coverage metric is unit + selftest merged. Run both and merge:

# (install once: dotnet tool install -g dotnet-coverage)

# --- Unit tests ---
dotnet build tests/Reactor.Tests -c Debug -p:Optimize=false -p:DebugType=portable
dotnet-coverage collect -s coverage.settings.xml \
  --output unit.cobertura.xml --output-format cobertura \
  -- dotnet test tests/Reactor.Tests --no-build

# --- Selftest ---
# Step 1: Rebuild with explicit Debug settings (required for instrumentation)
dotnet build src/Reactor                      -c Debug -p:Optimize=false -p:DebugType=portable --no-incremental
dotnet build tests/Reactor.AppTests.Host      -c Debug -p:Optimize=false -p:DebugType=portable --no-incremental

# Step 2: Instrument Reactor.dll statically
#         (dynamic instrumentation skips referenced assemblies)
dotnet-coverage instrument \
  "tests/Reactor.AppTests.Host/bin/$(RuntimeIdentifier)/Debug/net10.0-windows10.0.22621.0/Reactor.dll" \
  -s coverage.settings.xml

# Step 3: Collect
dotnet-coverage collect -s coverage.settings.xml \
  --output selftest.cobertura.xml --output-format cobertura \
  -- dotnet run --project tests/Reactor.AppTests.Host --no-build -- --self-test

# --- Merge ---
dotnet-coverage merge unit.cobertura.xml selftest.cobertura.xml \
  --output merged.cobertura.xml --output-format cobertura

Replace $(RuntimeIdentifier) with ARM64 or x64, or omit the platform segment if you used the default platform from Directory.Build.props. The coverage.settings.xml file in the repo root controls which modules are included and excludes generated code (obj/, *.g.cs) and test-host scaffolding exercised only by the Appium/E2E runner.

Running the demo app

The interactive demo app exercises every built-in control:

dotnet run --project samples/Reactor.TestApp

Project layout

src/Reactor/                      Core framework library
  Core/
    Component.cs                  Base Component class, hook methods
    Element.cs                    40+ virtual element record types
    RenderContext.cs              Hook state storage, effect tracking
    Reconciler.cs                 Tree diff orchestration
    Reconciler.Mount.cs           Mount handlers for each element type
    Reconciler.Update.cs          Update handlers for each element type
    ChildReconciler.cs            Keyed child list reconciliation
    ElementPool.cs                Control reuse pool
    PropValueRegistry.cs          Property value caching/hashing
  Elements/
    Dsl.cs                        200+ static factory methods (TextBlock, Button, VStack, Flex, etc.)
    ElementExtensions.cs          Fluent modifiers (.Bold(), .Margin(), .Width(), etc.)
    FlexExtensions.cs             .Flex() attached property modifier for flex children
  Flex/
    FlexPanel.cs                  CSS Flexbox panel backed by Yoga layout engine
  Yoga/
    YogaAlgorithm.cs              Pure C# port of Meta's Yoga layout algorithm
    YogaNode.cs                   Yoga node tree structure
    YogaStyle.cs                  Style properties (direction, justify, align, etc.)
    YogaEnums.cs                  Yoga enum types (YogaFlexDirection, YogaJustify, etc.)
  Hosting/
    ReactorApp.cs                 Static entry point — ReactorApp.Run<T>()
    ReactorHost.cs                Render loop, state batching, dispatcher scheduling
    ReactorHostControl.cs         Embeddable host for existing WinUI apps
    HotReloadService.cs           .NET Hot Reload integration for Visual Studio
src/Reactor.Cli/                  CLI scaffolding tool
tests/
  Reactor.Tests/                  1. Unit tests — xUnit (no UI window; includes D3 charting tests)
  Reactor.SelfTests/              2. Selftest runner — MSTest wrapper that subprocess-launches the Host and parses TAP
  Reactor.AppTests.Host/          2. Host app — hosts selftest fixtures and the Appium fixture navigator
  Reactor.AppTests/               3. E2E tests — MSTest + Appium/WinAppDriver
  stress_perf/                    Performance benchmarks
samples/
  Reactor.TestApp/                Interactive control showcase / demo app
  apps/                           Sample apps (wordpuzzle, ductfiles, regedit, etc.)
  TodoApp/                        Todo app sample

How to add a new element type

Adding a new WinUI control to Reactor requires changes in four places (plus optional modifiers and tests).

1. Define the element record (src/Reactor/Core/Element.cs)

public record MyControlElement(
    string Label,
    Action? OnClick = null
) : Element;

2. Add a DSL factory method (src/Reactor/Elements/Dsl.cs)

public static MyControlElement MyControl(string label, Action? onClick = null)
    => new(label, onClick);

3. Add a mount handler (src/Reactor/Core/Reconciler.Mount.cs)

private FrameworkElement MountMyControl(MyControlElement el)
{
    var control = new WinUI.MyControl();
    control.Label = el.Label;
    if (el.OnClick != null)
    {
        SetElementTag(control, el);
        control.Click += (s, _) => GetElementTag<MyControlElement>(s)?.OnClick?.Invoke();
    }
    return control;
}

Register it in the mount dispatch switch in Mount().

4. Add an update handler (src/Reactor/Core/Reconciler.Update.cs)

private void UpdateMyControl(WinUI.MyControl control, MyControlElement old, MyControlElement @new)
{
    if (old.Label != @new.Label) control.Label = @new.Label;
    SetElementTag(control, @new);
}

Register it in the update dispatch switch in Update().

5. (Optional) Add modifiers (src/Reactor/Elements/ElementExtensions.cs)

If the control has properties that make sense as fluent modifiers, add extension methods.

6. Add tests

Add unit tests in tests/Reactor.Tests/ for element creation, mount, and update. If the control has user-facing behavior, add a selfhost fixture in tests/Reactor.AppTests.Host/SelfTest/Fixtures/.

How to add a new hook

Hooks live in src/Reactor/Core/Component.cs (public API) and src/Reactor/Core/RenderContext.cs (implementation).

  1. Add the hook method to Component (delegates to RenderContext)
  2. Implement the logic in RenderContext, using GetOrCreateHook<T>() to manage state
  3. Follow the convention: hooks must be called in the same order every render, no conditional calls
  4. Add tests in tests/Reactor.Tests/

Code style

  • Elements are immutable records. Use with expressions for variations.
  • Hooks follow React conventions. Same order every render, no conditional hooks.
  • Factory methods over constructors. TextBlock("hello") not new TextBlockElement("hello").
  • Fluent modifiers for layout. .Margin(16).Bold() not constructor parameters.
  • Tag-based event dispatch. Event handlers are wired once at mount; the current element is stored in Tag so handlers always read the latest closure.
  • No XAML. Everything is C#.

Hot reload

Reactor supports .NET Hot Reload via HotReloadService.cs. When you edit code in Visual Studio and save, the framework re-renders with your changes while preserving hook state. No special setup needed — it hooks into the standard MetadataUpdateHandler mechanism.