From 266f03daef4bb3cbe5d36e159fbef5c1960346a2 Mon Sep 17 00:00:00 2001 From: tznind Date: Thu, 20 Mar 2025 08:39:46 +0000 Subject: [PATCH] Xmldoc --- TerminalGuiFluentTesting/GuiTestContext.cs | 108 +++++++++++++++--- .../TerminalGuiFluentTesting.csproj | 1 + TerminalGuiFluentTesting/V2TestDriver.cs | 9 +- .../FluentTests/BasicFluentAssertionTests.cs | 5 +- .../V2/MainLoopCoordinatorTests.cs | 4 +- 5 files changed, 105 insertions(+), 22 deletions(-) diff --git a/TerminalGuiFluentTesting/GuiTestContext.cs b/TerminalGuiFluentTesting/GuiTestContext.cs index 5b4c697d9..9a1195df8 100644 --- a/TerminalGuiFluentTesting/GuiTestContext.cs +++ b/TerminalGuiFluentTesting/GuiTestContext.cs @@ -5,6 +5,10 @@ using Terminal.Gui.ConsoleDrivers; namespace TerminalGuiFluentTesting; +/// +/// Fluent API context for testing a Terminal.Gui application. Create +/// an instance using static class. +/// public class GuiTestContext : IDisposable { private readonly CancellationTokenSource _cts = new (); @@ -130,7 +134,9 @@ public class GuiTestContext : IDisposable return this; } - // Cleanup to avoid state bleed between tests + /// + /// Cleanup to avoid state bleed between tests + /// public void Dispose () { Stop (); @@ -164,6 +170,12 @@ public class GuiTestContext : IDisposable return this; } + /// + /// Simulates changing the console size e.g. by resizing window in your operating system + /// + /// new Width for the console. + /// new Height for the console. + /// public GuiTestContext ResizeConsole (int width, int height) { _output.Size = new (width, height); @@ -181,6 +193,11 @@ public class GuiTestContext : IDisposable return WaitIteration (); } + /// + /// Writes all Terminal.Gui engine logs collected so far to the + /// + /// + /// public GuiTestContext WriteOutLogs (TextWriter writer) { writer.WriteLine (_logsSb.ToString ()); @@ -188,6 +205,12 @@ public class GuiTestContext : IDisposable return WaitIteration (); } + /// + /// Waits until the end of the current iteration of the main loop. Optionally + /// running a given action on the UI thread at that time. + /// + /// + /// public GuiTestContext WaitIteration (Action? a = null) { a ??= () => { }; @@ -212,6 +235,12 @@ public class GuiTestContext : IDisposable return this; } + /// + /// Performs the supplied immediately. + /// Enables running commands without breaking the Fluent API calls. + /// + /// + /// public GuiTestContext Then (Action doAction) { doAction (); @@ -219,8 +248,24 @@ public class GuiTestContext : IDisposable return this; } + /// + /// Simulates a right click at the given screen coordinates on the current driver. + /// This is a raw input event that goes through entire processing pipeline as though + /// user had pressed the mouse button physically. + /// + /// 0 indexed screen coordinates + /// 0 indexed screen coordinates + /// public GuiTestContext RightClick (int screenX, int screenY) { return Click (WindowsConsole.ButtonState.Button3Pressed, screenX, screenY); } + /// + /// Simulates a left click at the given screen coordinates on the current driver. + /// This is a raw input event that goes through entire processing pipeline as though + /// user had pressed the mouse button physically. + /// + /// 0 indexed screen coordinates + /// 0 indexed screen coordinates + /// public GuiTestContext LeftClick (int screenX, int screenY) { return Click (WindowsConsole.ButtonState.Button1Pressed, screenX, screenY); } private GuiTestContext Click (WindowsConsole.ButtonState btn, int screenX, int screenY) @@ -297,7 +342,11 @@ public class GuiTestContext : IDisposable return this; } - + /// + /// Simulates the Right cursor key + /// + /// + /// public GuiTestContext Right () { switch (_driver) @@ -319,6 +368,11 @@ public class GuiTestContext : IDisposable return this; } + /// + /// Simulates the Left cursor key + /// + /// + /// public GuiTestContext Left () { switch (_driver) @@ -340,6 +394,11 @@ public class GuiTestContext : IDisposable return this; } + /// + /// Simulates the up cursor key + /// + /// + /// public GuiTestContext Up () { switch (_driver) @@ -361,6 +420,11 @@ public class GuiTestContext : IDisposable return this; } + /// + /// Simulates pressing the Return/Enter (newline) key. + /// + /// + /// public GuiTestContext Enter () { switch (_driver) @@ -386,6 +450,31 @@ public class GuiTestContext : IDisposable return this; } + /// + /// Registers a right click handler on the added view (or root view) that + /// will open the supplied . + /// + /// + /// + /// + public GuiTestContext WithContextMenu (ContextMenu ctx, MenuBarItem menuItems) + { + LastView.MouseEvent += (s, e) => + { + if (e.Flags.HasFlag (MouseFlags.Button3Clicked)) + { + ctx.Show (menuItems); + } + }; + + return this; + } + + /// + /// The last view added (e.g. with ) or the root/current top. + /// + public View LastView => _lastView ?? Application.Top ?? throw new ("Could not determine which view to add to"); + /// /// Send a full windows OS key including both down and up. /// @@ -459,19 +548,4 @@ public class GuiTestContext : IDisposable WaitIteration (); } - - public GuiTestContext WithContextMenu (ContextMenu ctx, MenuBarItem menuItems) - { - LastView.MouseEvent += (s, e) => - { - if (e.Flags.HasFlag (MouseFlags.Button3Clicked)) - { - ctx.Show (menuItems); - } - }; - - return this; - } - - public View LastView => _lastView ?? Application.Top ?? throw new ("Could not determine which view to add to"); } diff --git a/TerminalGuiFluentTesting/TerminalGuiFluentTesting.csproj b/TerminalGuiFluentTesting/TerminalGuiFluentTesting.csproj index 6694b9386..21dc13b4d 100644 --- a/TerminalGuiFluentTesting/TerminalGuiFluentTesting.csproj +++ b/TerminalGuiFluentTesting/TerminalGuiFluentTesting.csproj @@ -4,6 +4,7 @@ net8.0 enable enable + bin\$(Configuration)\$(AssemblyName).xml diff --git a/TerminalGuiFluentTesting/V2TestDriver.cs b/TerminalGuiFluentTesting/V2TestDriver.cs index 5560a1c82..2366bee0c 100644 --- a/TerminalGuiFluentTesting/V2TestDriver.cs +++ b/TerminalGuiFluentTesting/V2TestDriver.cs @@ -7,10 +7,17 @@ using System.Threading.Tasks; namespace TerminalGuiFluentTesting; /// -/// Which v2 driver should be used +/// Which v2 driver simulation should be used /// public enum V2TestDriver { + /// + /// The v2 windows driver with simulation I/O but core driver classes + /// V2Win, + + /// + /// The v2 net driver with simulation I/O but core driver classes + /// V2Net } diff --git a/Tests/IntegrationTests/FluentTests/BasicFluentAssertionTests.cs b/Tests/IntegrationTests/FluentTests/BasicFluentAssertionTests.cs index d5cfcb1d2..345d7acc1 100644 --- a/Tests/IntegrationTests/FluentTests/BasicFluentAssertionTests.cs +++ b/Tests/IntegrationTests/FluentTests/BasicFluentAssertionTests.cs @@ -50,9 +50,10 @@ public class BasicFluentAssertionTests using GuiTestContext c = With.A (40, 10, d) .Add (lbl) - .Then (() => Assert.Equal (lbl.Frame.Width, 38)) // Window has 2 border + .Then (() => Assert.Equal (38, lbl.Frame.Width)) // Window has 2 border .ResizeConsole (20, 20) - .Then (() => Assert.Equal (lbl.Frame.Width, 18)) + .Then (() => Assert.Equal (18, lbl.Frame.Width)) + .WriteOutLogs (_out) .Stop (); } diff --git a/Tests/UnitTests/ConsoleDrivers/V2/MainLoopCoordinatorTests.cs b/Tests/UnitTests/ConsoleDrivers/V2/MainLoopCoordinatorTests.cs index d678c93e9..4c2a32e6f 100644 --- a/Tests/UnitTests/ConsoleDrivers/V2/MainLoopCoordinatorTests.cs +++ b/Tests/UnitTests/ConsoleDrivers/V2/MainLoopCoordinatorTests.cs @@ -6,7 +6,7 @@ namespace UnitTests.ConsoleDrivers.V2; public class MainLoopCoordinatorTests { [Fact] - public void TestMainLoopCoordinator_InputCrashes_ExceptionSurfacesMainThread () + public async Task TestMainLoopCoordinator_InputCrashes_ExceptionSurfacesMainThread () { var mockLogger = new Mock (); @@ -26,7 +26,7 @@ public class MainLoopCoordinatorTests // StartAsync boots the main loop and the input thread. But if the input class bombs // on startup it is important that the exception surface at the call site and not lost - var ex = Assert.ThrowsAsync(c.StartAsync).Result; + var ex = await Assert.ThrowsAsync(c.StartAsync); Assert.Equal ("Crash on boot", ex.InnerExceptions [0].Message);