Enhance MAUI test infrastructure and refactor tests

- Added `InternalsVisibleTo` for `IntegrationTests` in the project file.
- Enhanced `IntegrationTestBase` with methods to initialize MAUI apps.
- Introduced `TestMauiProgram` for test-specific MAUI app configuration.
- Added `MockApplication` to support headless testing scenarios.
- Documented testing patterns and limitations in `TESTING_PATTERN.md`.
- Improved test cleanup documentation in `TEST_CLEANUP_SUMMARY.md`.
- Refactored `ErrorHandlingTests`, `GoBackAsyncTests`, and `ShellNavigationTests`:
  - Removed invalid tests and mock-based setups.
  - Focused on testing navigation logic and route building.
  - Added `TestNavigation` to simulate `INavigation` behavior.
- Ensured no production code changes were made to accommodate tests.

Author: matt-goldman

src/Plugin.Maui.SmartNavigation/Plugin.Maui.SmartNavigation.csproj

@@ -16,6 +16,7 @@
 
   <ItemGroup>
 	<InternalsVisibleTo Include="Plugin.Maui.SmartNavigation.MopupsExtensions" />
+	<InternalsVisibleTo Include="Plugin.Maui.SmartNavigation.IntegrationTests" />
   </ItemGroup>
 
 	<ItemGroup>

tests/Plugin.Maui.SmartNavigation.IntegrationTests/Infrastructure/IntegrationTestBase.cs

@@ -7,6 +7,8 @@ public abstract class IntegrationTestBase : IDisposable
 {
     protected IServiceProvider ServiceProvider { get; private set; }
     protected IServiceCollection Services { get; private set; }
+    protected MauiApp? MauiApp { get; private set; }
+    protected Application? App { get; private set; }
 
     protected IntegrationTestBase()
     {
@@ -24,6 +26,50 @@ protected virtual void SetupServices(IServiceCollection services)
         // Derived classes can override to add their own services
     }
 
+    /// <summary>
+    /// Initializes a MAUI application for testing using the host builder pattern.
+    /// This properly initializes the MAUI infrastructure including DI, handlers, etc.
+    /// </summary>
+    /// <param name="mainPage">Optional main page to use. If null, a default page is created.</param>
+    protected void InitializeMauiApp(Page? mainPage = null)
+    {
+        MauiApp = TestMauiProgram.CreateMauiApp(mainPage);
+        App = MauiApp.Services.GetRequiredService<IApplication>() as Application;
+
+        if (App != null)
+        {
+            Application.Current = App;
+        }
+    }
+
+    /// <summary>
+    /// Initializes a MAUI application with Shell for testing Shell-based navigation.
+    /// </summary>
+    protected void InitializeMauiAppWithShell()
+    {
+        MauiApp = TestMauiProgram.CreateMauiAppWithShell();
+        App = MauiApp.Services.GetRequiredService<IApplication>() as Application;
+
+        if (App != null)
+        {
+            Application.Current = App;
+        }
+    }
+
+    /// <summary>
+    /// Initializes a MAUI application with a regular page for testing non-Shell navigation.
+    /// </summary>
+    protected void InitializeMauiAppWithPage()
+    {
+        MauiApp = TestMauiProgram.CreateMauiAppWithPage();
+        App = MauiApp.Services.GetRequiredService<IApplication>() as Application;
+
+        if (App != null)
+        {
+            Application.Current = App;
+        }
+    }
+
     public void Dispose()
     {
         Dispose(true);
@@ -38,6 +84,14 @@ protected virtual void Dispose(bool disposing)
             {
                 disposable.Dispose();
             }
+
+            // Clean up MAUI app
+            if (MauiApp != null)
+            {
+                Application.Current = null;
+                // MauiApp doesn't implement IDisposable, but we should clean up the reference
+                MauiApp = null;
+            }
         }
     }
 }

tests/Plugin.Maui.SmartNavigation.IntegrationTests/Infrastructure/TestMauiProgram.cs

@@ -0,0 +1,68 @@
+using Microsoft.Extensions.Logging;
+using Plugin.Maui.SmartNavigation.IntegrationTests.Mocks;
+
+namespace Plugin.Maui.SmartNavigation.IntegrationTests.Infrastructure;
+
+/// <summary>
+/// Provides a MAUI host builder for integration tests, similar to platform-specific entry points.
+/// This allows tests to work with a properly initialized MAUI application without requiring
+/// platform-specific UI infrastructure.
+/// </summary>
+public static class TestMauiProgram
+{
+    /// <summary>
+    /// Creates and configures a MauiApp instance for testing purposes.
+    /// This mirrors the pattern used in platform entry points (AppDelegate, MainApplication, etc.)
+    /// but uses test doubles instead of real UI components.
+    /// </summary>
+    /// <param name="mainPage">Optional main page to use for the application. If null, a default Page is created.</param>
+    /// <returns>A configured MauiApp instance suitable for integration testing.</returns>
+    public static MauiApp CreateMauiApp(Page? mainPage = null)
+    {
+        var builder = MauiApp.CreateBuilder();
+        
+        builder
+            .UseMauiApp<MockApplication>()
+            .ConfigureFonts(fonts =>
+            {
+                // Fonts typically required for MAUI, even in headless tests
+                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
+                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
+            });
+
+        // Configure the main page if provided
+        if (mainPage != null)
+        {
+            builder.Services.AddSingleton(mainPage);
+        }
+
+        // Add test-specific services here as needed
+        // builder.Services.AddTransient<IMyService, MyTestService>();
+
+#if DEBUG
+        builder.Logging.SetMinimumLevel(LogLevel.Trace);
+#endif
+
+        return builder.Build();
+    }
+
+    /// <summary>
+    /// Creates a MauiApp configured for Shell navigation testing.
+    /// </summary>
+    /// <returns>A configured MauiApp instance with Shell as the main page.</returns>
+    public static MauiApp CreateMauiAppWithShell()
+    {
+        var shell = new Shell();
+        return CreateMauiApp(shell);
+    }
+
+    /// <summary>
+    /// Creates a MauiApp configured for non-Shell navigation testing.
+    /// </summary>
+    /// <returns>A configured MauiApp instance with a regular Page as the main page.</returns>
+    public static MauiApp CreateMauiAppWithPage()
+    {
+        var page = new ContentPage { Title = "Test Page" };
+        return CreateMauiApp(page);
+    }
+}

tests/Plugin.Maui.SmartNavigation.IntegrationTests/Mocks/MockApplication.cs

@@ -0,0 +1,39 @@
+namespace Plugin.Maui.SmartNavigation.IntegrationTests.Mocks;
+
+/// <summary>
+/// Mock application for testing that can be used with MauiApp.CreateBuilder().UseMauiApp&lt;MockApplication&gt;()
+/// </summary>
+public class MockApplication : Application
+{
+    private Page? _mainPage;
+
+    /// <summary>
+    /// Default constructor required for MauiApp builder pattern
+    /// </summary>
+    public MockApplication()
+    {
+    }
+
+    /// <summary>
+    /// Constructor for direct instantiation in tests (legacy pattern)
+    /// </summary>
+    public MockApplication(Page page) : this()
+    {
+        _mainPage = page;
+    }
+
+    /// <summary>
+    /// Sets the main page to be used when creating windows
+    /// </summary>
+    public void SetMainPage(Page page)
+    {
+        _mainPage = page;
+    }
+
+    protected override Window CreateWindow(IActivationState? activationState)
+    {
+        // Use the configured main page, or create a default one if not set
+        var page = _mainPage ?? new ContentPage { Title = "Mock Page" };
+        return new Window(page);
+    }
+}

tests/Plugin.Maui.SmartNavigation.IntegrationTests/TESTING_PATTERN.md

@@ -0,0 +1,143 @@
+# MAUI Application Testing Pattern - Solution Documentation
+
+## Problem
+Integration tests needed to work with MAUI Application instances to test navigation scenarios, but creating testable Application/Window instances was failing because:
+1. Directly instantiating `Application` and calling `ActivateWindow()` doesn't populate the `Windows` collection
+2. The `Windows` collection requires platform-specific infrastructure that's not available in headless unit tests
+3. Previous attempts to mock or workaround this led to "testing the test" rather than testing actual code
+
+## Solution: MauiApp Host Builder Pattern
+
+The solution mirrors how platform entry points (AppDelegate on iOS, MainApplication on Android, etc.) initialize MAUI applications. These entry points call `CreateMauiApp()` which returns a properly configured `MauiApp` instance with:
+- Fully initialized dependency injection container
+- Service registrations
+- MAUI handlers and infrastructure
+- Properly configured Application instance
+
+## Implementation
+
+### 1. TestMauiProgram (Infrastructure/TestMauiProgram.cs)
+```csharp
+public static class TestMauiProgram
+{
+    public static MauiApp CreateMauiApp(Page? mainPage = null)
+    {
+        var builder = MauiApp.CreateBuilder();
+        builder.UseMauiApp<MockApplication>()
+               .ConfigureFonts(/*...*/);
+        // Configure services as needed
+        return builder.Build();
+    }
+}
+```
+
+This provides test-specific variants:
+- `CreateMauiApp()` - Generic with optional page
+- `CreateMauiAppWithShell()` - Pre-configured with Shell
+- `CreateMauiAppWithPage()` - Pre-configured with ContentPage
+
+### 2. Updated MockApplication (Mocks/MockApplication.cs)
+```csharp
+public class MockApplication : Application
+{
+    // Parameterless constructor required for host builder
+    public MockApplication() { }
+    
+    // Optional legacy constructor for backward compatibility
+    public MockApplication(Page page) : this() { /*...*/ }
+    
+    protected override Window CreateWindow(IActivationState? activationState)
+    {
+        // Returns window with configured page
+    }
+}
+```
+
+Key change: Added parameterless constructor to support `UseMauiApp<MockApplication>()` pattern.
+
+### 3. Enhanced IntegrationTestBase (Infrastructure/IntegrationTestBase.cs)
+```csharp
+public abstract class IntegrationTestBase : IDisposable
+{
+    protected MauiApp? MauiApp { get; private set; }
+    protected Application? App { get; private set; }
+    
+    protected void InitializeMauiApp(Page? mainPage = null)
+    {
+        MauiApp = TestMauiProgram.CreateMauiApp(mainPage);
+        App = MauiApp.Services.GetRequiredService<IApplication>() as Application;
+        Application.Current = App;
+    }
+    
+    // Similar methods for Shell and Page variants
+}
+```
+
+## Usage Pattern
+
+### In Test Methods:
+```csharp
+[Fact]
+public void MyNavigationTest()
+{
+    // Arrange - Initialize MAUI app
+    InitializeMauiAppWithPage();  // or InitializeMauiAppWithShell()
+    
+    // Application.Current is now properly set
+    Application.Current.ShouldNotBeNull();
+    
+    // Get services from DI container
+    var navService = MauiApp.Services.GetRequiredService<INavigationService>();
+    
+    // Act & Assert - test actual plugin code
+    // ...
+}
+```
+
+## Benefits
+
+1. **Proper Initialization**: Application is initialized through the same path as production code
+2. **DI Container**: Full access to service provider for resolving dependencies
+3. **No Platform Dependencies**: Works in headless test environment
+4. **Matches Production**: Same pattern as platform entry points
+5. **Testable**: Can inject test services and mocks into the builder
+6. **Extensible**: Easy to add configuration for different test scenarios
+
+## Current Limitations
+
+- Windows collection may still be empty in headless environment (platform activation required)
+- UI-specific handlers and features may not be available
+- Platform-specific lifecycle events won't fire
+
+## For UI-Level Testing
+
+For tests that require actual platform UI handlers, window management, or lifecycle events, use:
+- Xamarin.UITest / Appium for full UI automation
+- Platform-specific test frameworks (XCTest, Espresso, etc.)
+
+This pattern is ideal for:
+- Navigation service logic
+- Dependency injection
+- Service layer testing
+- Business logic that interacts with MAUI infrastructure
+
+## Future Error Handling Tests
+
+With this pattern, real error handling tests can now be written:
+
+```csharp
+[Fact]
+public async Task NavigateToUnregisteredRoute_ShouldThrowInvalidOperationException()
+{
+    // Arrange
+    InitializeMauiAppWithShell();
+    var navigationService = MauiApp.Services.GetRequiredService<ISmartNavigationService>();
+    
+    // Act & Assert - testing ACTUAL plugin code
+    var ex = await Should.ThrowAsync<InvalidOperationException>(() =>
+        navigationService.GoToAsync("unregistered/route"));
+    ex.Message.ShouldContain("not registered");
+}
+```
+
+This tests real navigation service behavior, not mock setup code.