hex1b: Skill for Claude Code

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"));
    }
}