Writing Unit Tests

Writing Unit Tests Skill

This skill provides guidelines for AI agents writing unit tests for the Hex1b TUI library. It outlines the preferred testing approach, patterns, and anti-patterns to avoid. Tests use MSTest 4 with MSTest.Sdk/4.2.3, OutputType=Exe, and Microsoft.Testing.Platform (MTP). global.json configures dotnet test to use MTP; test projects can also run in executable mode with dotnet run --project tests/SomeProject/.

Core Philosophy

1. Prefer full terminal stack testing - Use Hex1bTerminal.CreateBuilder() to create complete terminal environments
2. Use .WithHex1bApp() for TUI functionality tests - This wires up the full app lifecycle
3. Keep tests simple and linear - Avoid excessive abstractions; repeating patterns are beneficial for AI agents
4. Assert on visual behavior - Use CellPatternSearcher and color assertions for render verification
5. Update this skill when discovering new patterns - Build the body of knowledge as part of PRs

When to Use Full Stack vs Isolation

Standard Test Structure

Full Stack Integration Test

Test files import Microsoft.VisualStudio.TestTools.UnitTesting. The Hex1b.Testing namespace is global-using'd via Directory.Build.props for helpers such as TestSeq. For test output, add public TestContext TestContext { get; set; } = null!; and call TestContext.WriteLine(...). Suppressed MSTest analyzers are MSTEST0014, MSTEST0030, MSTEST0032, and MSTEST0057.

This is the preferred pattern for most tests:

using Microsoft.VisualStudio.TestTools.UnitTesting;

[TestClass]
public class WidgetNameTests
{
    [TestMethod]
    public async Task WidgetName_Scenario_ExpectedBehavior()
    {
        // Arrange - Build the terminal with the app
        await using var terminal = Hex1bTerminal.CreateBuilder()
            .WithHex1bApp((app, options) => ctx => new VStackWidget([
                new TextBlockWidget("Hello"),
                new ButtonWidget("Click Me")
            ]))
            .WithHeadless()
            .WithDimensions(80, 24)
            .Build();

        // Act & Assert - Use input sequencer with WaitUntil
        var snapshot = await new Hex1bTerminalInputSequenceBuilder()
            .WaitUntil(s => s.ContainsText("Hello"), TimeSpan.FromSeconds(2), "initial render")
            .Down()  // Navigate to button
            .WaitUntil(s => s.ContainsText("> Click Me"), TimeSpan.FromSeconds(2), "button focused")
            .Capture("focused-button")
            .Ctrl().Key(Hex1bKey.C)
            .Build()
            .ApplyWithCaptureAsync(terminal, TestContext.Current.CancellationToken);

        // Assert (often redundant if WaitUntil already verified)
        Assert.IsTrue(snapshot.ContainsText("> Click Me"));
    }
}

Key Elements

1. await using var terminal - Ensures proper disposal
2. .WithHeadless() - No actual terminal output (CI-safe)
3. .WithDimensions(80, 24) - Explicit terminal size
4. WaitUntil before assertions - Prevents timing issues
5. .Capture("name") - Saves SVG/HTML for debugging
6. Ctrl().Key(Hex1bKey.C) - Clean exit

Input Sequencing Patterns

Basic Navigation

await new Hex1bTerminalInputSequenceBuilder()
    .WaitUntil(s => s.ContainsText("Item 1"), TimeSpan.FromSeconds(2), "list rendered")
    .Down()
    .WaitUntil(s => s.ContainsText("> Item 2"), TimeSpan.FromSeconds(2), "moved to item 2")
    .Down()
    .WaitUntil(s => s.ContainsText("> Item 3"), TimeSpan.FromSeconds(2), "moved to item 3")
    .Capture("navigation-result")
    .Ctrl().Key(Hex1bKey.C)
    .Build()
    .ApplyWithCaptureAsync(terminal, TestContext.Current.CancellationToken);

Text Input

await new Hex1bTerminalInputSequenceBuilder()
    .WaitUntil(s => s.ContainsText("Name:"), TimeSpan.FromSeconds(2), "form rendered")
    .Type("John Doe")
    .WaitUntil(s => s.ContainsText("John Doe"), TimeSpan.FromSeconds(2), "text entered")
    .Capture("text-input")
    .Ctrl().Key(Hex1bKey.C)
    .Build()
    .ApplyWithCaptureAsync(terminal, TestContext.Current.CancellationToken);

Keyboard Shortcuts

await new Hex1bTerminalInputSequenceBuilder()
    .WaitUntil(s => s.ContainsText("Ready"), TimeSpan.FromSeconds(2), "app ready")
    .Ctrl().Key(Hex1bKey.S)  // Ctrl+S
    .WaitUntil(s => s.ContainsText("Saved"), TimeSpan.FromSeconds(2), "save completed")
    .Capture("after-save")
    .Ctrl().Key(Hex1bKey.C)
    .Build()
    .ApplyWithCaptureAsync(terminal, TestContext.Current.CancellationToken);

Visual Assertion Patterns

Using CellPatternSearcher

For precise cell-level assertions:

// Find a specific character
var pattern = new CellPatternSearcher().Find('█');
var result = pattern.Search(snapshot);
Assert.IsTrue(result.HasMatches);
Assert.AreEqual(expectedX, result.First!.Start.X);

// Find with regex pattern
var pattern = new CellPatternSearcher().FindPattern(@"Count:\s*\d+");
var result = pattern.Search(snapshot);
Assert.IsTrue(result.HasMatches);

// Find with predicate
var pattern = new CellPatternSearcher()
    .Find(ctx => char.IsDigit(ctx.Cell.Character[0]));
var result = pattern.Search(snapshot);
Assert.AreEqual(3, result.Count);

Color Assertions

For verifying themed/styled output:

// Check if any cell has a specific background color
Assert.IsTrue(snapshot.HasBackgroundColor(Hex1bColor.FromRgb(0, 100, 200)),
    "Button should have blue background");

// Check if any cell has a specific foreground color
Assert.IsTrue(snapshot.HasForegroundColor(Hex1bColor.FromRgb(255, 255, 255)),
    "Text should be white");

// Get color at specific position
var bgColor = snapshot.GetBackgroundColor(10, 5);
Assert.AreEqual(Hex1bColor.FromRgb(255, 0, 0), bgColor);

// Check uniform row background
Assert.IsTrue(snapshot.HasUniformBackgroundColor(0, Hex1bColor.FromRgb(50, 50, 50)),
    "Header row should have dark background");

Available Color Extension Methods

Anti-Patterns to Avoid

📘 See the test-fixer skill for detailed diagnosis and fixes when tests become flaky.

❌ Insufficient WaitUntil Conditions (Partial Render)

// BROKEN: Waits for partial content, but rest of screen may not be rendered
await new Hex1bTerminalInputSequenceBuilder()
    .WaitUntil(s => s.ContainsText("Header"), TimeSpan.FromSeconds(2))  // ❌ Only checks header
    .Capture("screen")
    .Build()
    .ApplyAsync(terminal, ct);

// Assertion on footer may fail - it wasn't part of the WaitUntil!
Assert.IsTrue(snapshot.ContainsText("Footer"));

Problem: Rendering is inherently async. Finding "Header" doesn't guarantee "Footer" has rendered yet. This is especially problematic when testing other terminal frameworks (like Spectre Console) which may drop input if they're not ready to receive it.

Fix: Over-specify the WaitUntil condition to ensure everything you need is present:

// ✅ Wait for ALL content you'll assert on
await new Hex1bTerminalInputSequenceBuilder()
    .WaitUntil(s => s.ContainsText("Header") && s.ContainsText("Footer"), 
               TimeSpan.FromSeconds(2), "full screen rendered")
    .Capture("screen")
    .Build()
    .ApplyAsync(terminal, ct);

Guideline: If you're going to assert on specific screen content, include it in the WaitUntil condition. Don't assume the rest of the screen is ready just because one part appeared.

❌ Snapshot After Exit

// BROKEN: Snapshot taken AFTER Ctrl+C clears the buffer
var snapshot = await new Hex1bTerminalInputSequenceBuilder()
    .WaitUntil(s => s.ContainsText("Hello"), TimeSpan.FromSeconds(2))
    .Capture("final")
    .Ctrl().Key(Hex1bKey.C)  // Buffer may be cleared before snapshot!
    .Build()
    .ApplyWithCaptureAsync(terminal, ct);

Assert.IsTrue(snapshot.ContainsText("Hello"));  // ❌ May fail on Linux CI

Fix: The WaitUntil already verified the content. If you need to assert, the WaitUntil serves as the assertion.

❌ Missing WaitUntil After Action

// BROKEN: No wait for render after Down()
await new Hex1bTerminalInputSequenceBuilder()
    .WaitUntil(s => s.ContainsText("Item 1"), TimeSpan.FromSeconds(2))
    .Down()
    .Capture("after-down")  // ❌ Render may not be complete!
    .Ctrl().Key(Hex1bKey.C)
    .Build()
    .ApplyAsync(terminal, ct);

Fix: Always add WaitUntil after any action that changes state:

.Down()
.WaitUntil(s => s.ContainsText("> Item 2"), TimeSpan.FromSeconds(2), "moved down")
.Capture("after-down")

❌ Task.Delay for Async Events

// BROKEN: Fixed delay may not be long enough on slow CI
await terminal.SendKeyAsync(Hex1bKey.Enter);
await Task.Delay(100);  // ❌ Arbitrary delay
Assert.IsTrue(eventFired);

Fix: Use TaskCompletionSource to signal completion:

var eventSignal = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);

// In event handler:
eventSignal.TrySetResult();

// In test:
await eventSignal.Task.WaitAsync(TimeSpan.FromSeconds(2), ct);

❌ Over-Abstracted Test Helpers

// AVOID: Too many layers of abstraction
var result = await TestHelpers.CreateTerminalAndRunScenario(
    widgets: WidgetFactory.CreateStandardList(),
    actions: ActionBuilder.NavigateAndSelect(3),
    assertions: AssertionBuilder.SelectedItem("Item 3")
);

Prefer: Simple, linear, self-contained tests. Repetition is acceptable and helps AI agents understand patterns.

Presentation Escape Timeout Tests

Use queued in-memory presentation reads with Hex1bAppWorkloadAdapter. Observe the escape timer's finite ITimer.Change before firing its callback; observing CreateTimer alone is insufficient because it is initially disabled. Keep other timers (such as synchronized output) independent in the controlled provider. For example, Hex1bTerminalTests.PresentationInput_PasteEscapeAcrossTimeout_PreservesLiteralContent queues "\x1b[200~a\x1b", waits for arming, fires expiry, then queues "\rb\x1b[201~z". Read through the post-paste z sentinel before asserting exact completed paste text and no surplus events. This avoids sleeps and makes read-boundary/timeout bugs reproducible. At app level, bind on the focused widget and prove the same Escape binding fires for an ordinary Escape after the paste.

Network Test Fixtures

Let the server reserve its listening port atomically. Random port selection and probing a free port before closing the probe both allow collisions under parallel execution. For Kestrel fixtures, configure options.Listen(IPAddress.Loopback, 0), await app.StartAsync(), then derive client URIs from TestSeq.Single(app.Urls). For example:

var wsUri = new UriBuilder(TestSeq.Single(app.Urls))
{
    Scheme = "ws",
    Path = "/ws/attach"
}.Uri;

Keep the application owned by the fixture before awaiting startup so cleanup can dispose it even if startup fails. Cover independently reachable concurrent servers and listener release; see RemoteTerminalWorkloadAdapterTests. Do not mask port collisions with sleeps, retries, or disabled parallelism.

Scheduler Progress Under Load

For starvation regressions, keep the producer active while asserting input, timer, or shutdown progress. A finite output burst followed by app.Invalidate() can hide a lost wakeup. Use TestWidget.OnRender to place events at a known frame:

var observer = new TestWidget().OnRender(args =>
{
    app.Invalidate(); // Renew on every frame, including while input is pending.
    if (args.RenderCount == 3)
        workload.SendKey(Hex1bKey.A);
});

This fragment assumes captured app and workload references. Pair it with changing visible content so frames actually render, a bounded completion signal, and cancellation in finally. See Hex1bAppSchedulingTests for full examples. Check input ordering with coalescing both enabled and disabled. For exact cadence, use the app's internal FrameTimeProvider with a fake clock, wait for timer registration before advancing it, and assert both the requested delay and elapsed virtual time. A fixed wall-clock tolerance around Task.Delay is not portable across CI runners. Keep real-time full-stack tests alongside deterministic pacing coverage rather than widening timing tolerances. For nested output races, gate later child redraws: their extra notifications can mask a lost first-frame notification. These controlled cases supplement, rather than prove, responsiveness under arbitrary real-world load.

Process Output Completion

Process exit and terminal output consumption are separate events. For a controlled regression, start a StandardProcessWorkloadAdapter and await its exit before constructing a terminal with an already-completed run callback. Gate the first presentation write with a TaskCompletionSource: RunAsync and lifecycle completion must remain pending until the gate is released and both stdout and stderr reach the snapshot. See StandardProcessOutputTests for raw and filtered output, cancellation, and pump-failure cases. Keep ordinary WithProcess tests alongside this ordering test; do not keep a one-shot child alive or wait for visible output before awaiting RunAsync in a drain regression, since that hides the race. For echo/transport tests, use an already-available executable (cmd /d /c echo on Windows, /bin/echo on Unix). Runtime-compiling a temporary C# program with dotnet run puts SDK startup and compilation inside the output deadline.

HMP1 Shutdown Compatibility

Test each endpoint against a scripted peer with pinned numeric frame types, little-endian headers, and literal JSON from the pre-change protocol. Do not use the production codec on the simulated legacy side: otherwise both endpoints can change together and conceal a wire regression. Preserve the existing mandatory ActivityState handshake baseline; these fixtures model the build immediately before the shutdown change, not every historical HMP1 implementation.

See Hmp1ShutdownCompatibilityTests: the server fixture sends a literal ClientHello and Input, gates a large Output write, then independently decodes Output, Output, Exit and EOF without sending acknowledgements. The client fixture feeds Hello, StateSync, ActivityState, split-UTF-8 Output and Exit or EOF, gates presentation, and checks exact final bytes and the snapshot at lifecycle completion. Include premature Exit and truncated final frames to establish that missing content cannot be recovered. Confirm the relevant tests fail when server ordering or client draining is temporarily removed, then restore both safeguards.

Widget Test Dimensions

When writing tests for widgets, consider all the dimensions that affect behavior. Each widget should have tests covering these scenarios:

1. Terminal Size Variations

Widgets must work across different terminal sizes. Use MSTest DataRow for parameterized cases:

[TestMethod]
[DataRow(40, 10)]   // Minimum realistic size
[DataRow(80, 24)]   // Standard terminal
[DataRow(120, 40)]  // Large terminal
[DataRow(200, 60)]  // Very large terminal
public async Task ListWidget_VariousTerminalSizes_RendersCorrectly(int width, int height)
{
    await using var terminal = Hex1bTerminal.CreateBuilder()
        .WithHex1bApp((app, options) => ctx => new ListWidget(["Item 1", "Item 2", "Item 3"]))
        .WithHeadless()
        .WithDimensions(width, height)
        .Build();

    await new Hex1bTerminalInputSequenceBuilder()
        .WaitUntil(s => s.ContainsText("Item 1"), TimeSpan.FromSeconds(2), "list rendered")
        .Capture($"list-{width}x{height}")
        .Ctrl().Key(Hex1bKey.C)
        .Build()
        .ApplyAsync(terminal, TestContext.Current.CancellationToken);
}

Key questions to answer:

• What is the realistic minimum terminal size for this widget?
• Does the widget truncate, scroll, or wrap when space is limited?
• Does the widget expand appropriately in large terminals?
• Are there edge cases at specific sizes?