DodoSSH/tests/DodoSSH.Client.App.Layout.Tests/LayoutHarness.cs

using System.Globalization;
using Avalonia;
using Avalonia.Controls;
using Avalonia.Headless;
using Avalonia.Threading;
using Avalonia.VisualTree;

namespace DodoSSH.Client.App.Layout.Tests;

/// <summary>
/// Lays out real XAML at a real size and reports anything a user could not click.
/// </summary>
/// <remarks>
/// <para>
/// The defect this exists for is a control arranged past the edge of its container. It is invisible to every
/// other suite here — no other test loads a <c>.axaml</c> — and this window has shipped it once, when the
/// setup screens rendered sliced with their buttons unreachable at the default width.
/// </para>
/// <para>
/// A control inside a <see cref="ScrollViewer"/> is exempt, and that exemption is load-bearing rather than a
/// convenience: a list longer than its viewport is the normal case, and treating a row scrolled out of sight
/// as a defect would make this harness cry wolf on every populated list. What is left after the exemption is
/// the class of thing that has no way to come back into view.
/// </para>
/// </remarks>
internal static class LayoutHarness
{
    /// <summary>The window's own declared minimum, which is the size that has to work.</summary>
    /// <remarks>
    /// Taken from <c>MainWindow.axaml</c>'s <c>MinWidth</c>/<c>MinHeight</c> by hand. A test asserts these
    /// two constants still match the XAML, so the harness cannot quietly start measuring a window larger
    /// than the one a user is allowed to drag to.
    /// </remarks>
    internal const double MinimumWidth = 880;

    /// <inheritdoc cref="MinimumWidth" />
    internal const double MinimumHeight = 560;

    /// <summary>The host sidebar's fixed width, from the hosts screen's <c>ColumnDefinitions</c>.</summary>
    internal const double HostSidebarWidth = 268;

    /// <summary>The nav rail's fixed width, from <c>NavRail.axaml</c>.</summary>
    internal const double NavRailWidth = 54;

    /// <summary>
    /// What the titlebar and the status bar take off the window before any screen gets a pixel.
    /// </summary>
    /// <remarks>
    /// Both are fixed heights declared in their own markup — 38 and 24 — rather than shapes that grow with
    /// their contents, which is what makes stating them here honest. Two tests hold the two controls to
    /// those numbers, so the budget below cannot drift away from what the window actually leaves.
    /// </remarks>
    internal const double TitleBarHeight = 38;

    /// <inheritdoc cref="TitleBarHeight" />
    internal const double StatusBarHeight = 24;

    /// <summary>The height a screen actually gets at the window's minimum.</summary>
    internal static double ScreenHeight => MinimumHeight - TitleBarHeight - StatusBarHeight;

    /// <summary>The width a full-width screen gets, once the nav rail has taken its column.</summary>
    internal static double ScreenWidth => MinimumWidth - NavRailWidth;

    private static readonly HeadlessUnitTestSession Session =
        HeadlessUnitTestSession.GetOrStartForAssembly(typeof(LayoutHarness).Assembly);

    /// <summary>
    /// Runs one body on Avalonia's dispatcher thread.
    /// </summary>
    /// <remarks>
    /// Everything that touches a control has to happen here. The session owns the thread and the
    /// application, so this is also what serialises the suite — Avalonia's platform is process-global and
    /// two tests laying out windows at once would share one dispatcher.
    /// </remarks>
    internal static Task OnTheUiThreadAsync(Action body, CancellationToken cancellationToken) =>
        Session.Dispatch(body, cancellationToken);

    /// <summary>Shows a window at a given size and lets layout finish.</summary>
    internal static void Settle(Window window, double width, double height)
    {
        ArgumentNullException.ThrowIfNull(window);

        window.Width = width;
        window.Height = height;

        // None, because a headless window still reserves space for decorations it does not draw, and the
        // budget being measured is the client area the application actually gets.
        window.WindowDecorations = WindowDecorations.None;

        window.Show();

        // Show() queues layout rather than performing it. Without this the tree is measured but not
        // arranged, and every Bounds read below would be a zero rectangle — which would make this harness
        // report the whole window as unreachable, or worse, report nothing at all.
        Dispatcher.UIThread.RunJobs();
        window.UpdateLayout();
    }

    /// <summary>Wraps a control in a host window sized to the application's minimum.</summary>
    internal static Window HostAtMinimumSize(Control content, double width, double height)
    {
        var window = new Window { Content = content };
        Settle(window, width, height);
        return window;
    }

    /// <summary>
    /// Every interactive control that is laid out where it cannot be used, described for a failure message.
    /// </summary>
    /// <remarks>
    /// Returns descriptions rather than controls because the value of this harness is entirely in what it
    /// says when it fails: "something is clipped" sends the reader back to a 500-line XAML file, while
    /// "Button 'Save' at 8,486 486x32 falls outside 820x520" names the control and the edge it crossed.
    /// </remarks>
    internal static IReadOnlyList<string> Unreachable(Window window)
    {
        ArgumentNullException.ThrowIfNull(window);

        var client = new Rect(window.ClientSize);
        var found = new List<string>();

        foreach (var control in window.GetVisualDescendants().OfType<Control>())
        {
            if (Fault(control, client, window) is { } fault)
            {
                found.Add(fault);
            }
        }

        return found;
    }

    private static string? Fault(Control control, Rect client, Visual window)
    {
        if (!IsInteractive(control) || !control.IsEffectivelyVisible || IsScrollable(control))
        {
            return null;
        }

        if (control.TranslatePoint(default, window) is not { } origin)
        {
            return null;
        }

        var box = new Rect(origin, control.Bounds.Size);

        // Zero size is a defect for a control the theme gives a height to and a normal state for one sized by
        // its content: an empty list is zero pixels tall and correct, a squashed button is neither. Learned
        // from this firing on KeyList in a vault with no keys in it.
        if (control is not ListBox && (box.Width <= 0 || box.Height <= 0))
        {
            return Describe(control, box, client, "was arranged with no size");
        }

        return client.Contains(box) ? null : Describe(control, box, client, "falls outside the window");
    }

    /// <remarks>
    /// The controls a user has to be able to reach. A clipped <see cref="TextBlock"/> is a cosmetic problem
    /// and a clipped <see cref="Button"/> is a dead end, so only the second kind is worth failing a build
    /// over — and keeping the list short is what stops this harness from becoming a pixel-diff nobody
    /// trusts.
    /// </remarks>
    private static bool IsInteractive(Control control) =>
        control is Button or TextBox or CheckBox or ComboBox or NumericUpDown or ListBox;

    private static bool IsScrollable(Control control) =>
        control.GetVisualAncestors().OfType<ScrollViewer>().Any();

    private static string Describe(Control control, Rect box, Rect client, string fault)
    {
        var name = control.Name is { Length: > 0 } named ? $" '{named}'" : Label(control);

        return string.Create(
            CultureInfo.InvariantCulture,
            $"{control.GetType().Name}{name} {fault}: {Format(box)} is not inside {Format(client)}");
    }

    /// <remarks>
    /// A button's caption, because "Save" identifies the control to a reader far better than its position
    /// in a visual tree does.
    /// </remarks>
    private static string Label(Control control) => control switch
    {
        Button { Content: string caption } => $" '{caption}'",
        TextBox { PlaceholderText: { Length: > 0 } placeholder } => $" (placeholder '{placeholder}')",
        _ => string.Empty,
    };

    private static string Format(Rect rect) => string.Create(
        CultureInfo.InvariantCulture,
        $"{rect.X:0.#},{rect.Y:0.#} {rect.Width:0.#}x{rect.Height:0.#}");
}