Resolve IntegrationTests-003..006 code-review findings

IntegrationTests-003: the live MXAccess smoke test asserted on the first
streamed event, which a registration/quality bootstrap event could occupy.
The recording writer now waits for the first event matching a predicate
(Family == OnDataChange).

IntegrationTests-004: the cleanup `finally` could throw and mask an original
assertion failure. Shutdown now routes through a helper that logs cleanup
exceptions instead of propagating them.

IntegrationTests-005: added live MXAccess parity tests — a Write round-trip
to an advised item, and an invalid-handle command surfacing the MXAccess
failure without a transport fault.

IntegrationTests-006: added live LDAP failure-path tests — wrong password
(no password leak), unknown username, and server-unreachable.

docs/GatewayTesting.md updated to describe the new cases.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/MxGateway.IntegrationTests/DashboardLdapLiveTests.cs

@@ -43,6 +43,69 @@ public sealed class DashboardLdapLiveTests
         Assert.DoesNotContain("readonly123", result.FailureMessage, StringComparison.Ordinal);
     }
 
+    [LiveLdapFact]
+    [Trait("Category", "LiveLdap")]
+    public async Task AuthenticateAsync_AdminWithWrongPassword_FailsWithoutLeakingPassword()
+    {
+        // Exercises the LdapException branch: the user exists and the service
+        // account search succeeds, but the candidate bind is rejected.
+        const string wrongPassword = "definitely-not-the-admin-password";
+        DashboardAuthenticator authenticator = CreateAuthenticator();
+
+        DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
+            "admin",
+            wrongPassword,
+            CancellationToken.None);
+
+        Assert.False(result.Succeeded);
+        Assert.Null(result.Principal);
+        Assert.DoesNotContain(wrongPassword, result.FailureMessage, StringComparison.Ordinal);
+    }
+
+    [LiveLdapFact]
+    [Trait("Category", "LiveLdap")]
+    public async Task AuthenticateAsync_UnknownUsername_Fails()
+    {
+        // Exercises the `candidate is null` branch: the service-account search
+        // returns no entry, so no candidate bind is attempted.
+        DashboardAuthenticator authenticator = CreateAuthenticator();
+
+        DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
+            "no-such-user-9f3c1",
+            "irrelevant-password",
+            CancellationToken.None);
+
+        Assert.False(result.Succeeded);
+        Assert.Null(result.Principal);
+    }
+
+    [LiveLdapFact]
+    [Trait("Category", "LiveLdap")]
+    public async Task AuthenticateAsync_ServerUnreachable_FailsWithoutThrowing()
+    {
+        // Exercises the connect-failure path: a closed loopback port produces a
+        // connection error that DashboardAuthenticator must absorb into a Fail
+        // result rather than propagating an exception to the dashboard.
+        DashboardAuthenticator authenticator = new(
+            Options.Create(new GatewayOptions
+            {
+                Ldap = new LdapOptions
+                {
+                    // 1 is a reserved port number that no LDAP server listens on.
+                    Port = 1,
+                },
+            }),
+            NullLogger<DashboardAuthenticator>.Instance);
+
+        DashboardAuthenticationResult result = await authenticator.AuthenticateAsync(
+            "admin",
+            "admin123",
+            CancellationToken.None);
+
+        Assert.False(result.Succeeded);
+        Assert.Null(result.Principal);
+    }
+
     private static DashboardAuthenticator CreateAuthenticator()
     {
         return new DashboardAuthenticator(

src/MxGateway.IntegrationTests/WorkerLiveMxAccessSmokeTests.cs

@@ -86,8 +86,15 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output)
             LogReply("Advise", adviseReply);
             Assert.Equal(ProtocolStatusCode.Ok, adviseReply.ProtocolStatus.Code);
 
+            // A live MXAccess provider can deliver an initial registration-state
+            // or bad-quality bootstrap event before the OnDataChange the worker
+            // is contracted to emit. Match on the family rather than trusting
+            // whatever event arrives first so a genuine ordering defect cannot
+            // pass spuriously or leave a later wrong event unverified.
             MxEvent dataChange = await eventWriter
-                .WaitForFirstMessageAsync(IntegrationTestEnvironment.LiveMxAccessEventTimeout)
+                .WaitForMessageAsync(
+                    candidate => candidate.Family == MxEventFamily.OnDataChange,
+                    IntegrationTestEnvironment.LiveMxAccessEventTimeout)
                 .ConfigureAwait(false);
             LogEvent(dataChange);
 
@@ -98,22 +105,184 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output)
         }
         finally
         {
-            try
-            {
-                if (!string.IsNullOrWhiteSpace(sessionId))
-                {
-                    await CloseSessionAsync(fixture, sessionId).ConfigureAwait(false);
-                }
+            await ShutDownAsync(fixture, processFactory, sessionId, streamTask).ConfigureAwait(false);
+        }
+    }
 
-                if (streamTask is not null)
+    /// <summary>
+    /// Verifies that a Write command round-trips through live MXAccess against an advised item.
+    /// </summary>
+    [LiveMxAccessFact]
+    [Trait("Category", "LiveMxAccess")]
+    public async Task GatewaySession_WithLiveWorker_WritesValueToAdvisedItem()
+    {
+        string workerExecutablePath = IntegrationTestEnvironment.ResolveLiveMxAccessWorkerExecutablePath();
+        Assert.True(
+            File.Exists(workerExecutablePath),
+            $"Live MXAccess worker executable was not found at {workerExecutablePath}. Build the worker or set {IntegrationTestEnvironment.LiveMxAccessWorkerExecutableVariableName}.");
+
+        TestWorkerProcessFactory processFactory = new(output);
+        await using GatewayServiceFixture fixture = new(workerExecutablePath, processFactory, output);
+
+        string? sessionId = null;
+        Task? streamTask = null;
+
+        try
+        {
+            OpenSessionReply openReply = await fixture.Service.OpenSession(
+                new OpenSessionRequest
                 {
-                    await streamTask.WaitAsync(StreamShutdownTimeout).ConfigureAwait(false);
-                }
-            }
-            finally
+                    ClientSessionName = "live-mxaccess-write",
+                    ClientCorrelationId = "live-open-write",
+                    CommandTimeout = Duration.FromTimeSpan(CommandTimeout),
+                },
+                new TestServerCallContext()).ConfigureAwait(false);
+
+            sessionId = openReply.SessionId;
+            Assert.Equal(ProtocolStatusCode.Ok, openReply.ProtocolStatus.Code);
+
+            RecordingServerStreamWriter<MxEvent> eventWriter = new();
+            streamTask = fixture.Service.StreamEvents(
+                new StreamEventsRequest { SessionId = sessionId },
+                eventWriter,
+                new TestServerCallContext());
+
+            MxCommandReply registerReply = await fixture.Service.Invoke(
+                CreateRegisterRequest(sessionId),
+                new TestServerCallContext()).ConfigureAwait(false);
+            LogReply("Register", registerReply);
+            Assert.Equal(ProtocolStatusCode.Ok, registerReply.ProtocolStatus.Code);
+
+            MxCommandReply addItemReply = await fixture.Service.Invoke(
+                CreateAddItemRequest(sessionId, registerReply.Register.ServerHandle),
+                new TestServerCallContext()).ConfigureAwait(false);
+            LogReply("AddItem", addItemReply);
+            Assert.Equal(ProtocolStatusCode.Ok, addItemReply.ProtocolStatus.Code);
+            Assert.True(addItemReply.AddItem.ItemHandle > 0);
+
+            MxCommandReply adviseReply = await fixture.Service.Invoke(
+                CreateAdviseRequest(
+                    sessionId,
+                    registerReply.Register.ServerHandle,
+                    addItemReply.AddItem.ItemHandle),
+                new TestServerCallContext()).ConfigureAwait(false);
+            LogReply("Advise", adviseReply);
+            Assert.Equal(ProtocolStatusCode.Ok, adviseReply.ProtocolStatus.Code);
+
+            MxCommandReply writeReply = await fixture.Service.Invoke(
+                CreateWriteRequest(
+                    sessionId,
+                    registerReply.Register.ServerHandle,
+                    addItemReply.AddItem.ItemHandle),
+                new TestServerCallContext()).ConfigureAwait(false);
+            LogReply("Write", writeReply);
+
+            // The gateway must always report a protocol-level status. MXAccess
+            // parity details (a write rejection, a secured-item failure) belong
+            // in hresult / statuses, not in a transport failure — the command
+            // itself completed its round-trip to the worker and back.
+            Assert.Equal(ProtocolStatusCode.Ok, writeReply.ProtocolStatus.Code);
+            Assert.Equal(MxCommandKind.Write, writeReply.Kind);
+        }
+        finally
+        {
+            await ShutDownAsync(fixture, processFactory, sessionId, streamTask).ConfigureAwait(false);
+        }
+    }
+
+    /// <summary>
+    /// Verifies that an AddItem against an invalid server handle surfaces the MXAccess failure
+    /// without faulting the gateway transport, exercising the invalid-handle parity path.
+    /// </summary>
+    [LiveMxAccessFact]
+    [Trait("Category", "LiveMxAccess")]
+    public async Task GatewaySession_WithLiveWorker_InvalidHandleCommand_SurfacesFailureWithoutTransportFault()
+    {
+        string workerExecutablePath = IntegrationTestEnvironment.ResolveLiveMxAccessWorkerExecutablePath();
+        Assert.True(
+            File.Exists(workerExecutablePath),
+            $"Live MXAccess worker executable was not found at {workerExecutablePath}. Build the worker or set {IntegrationTestEnvironment.LiveMxAccessWorkerExecutableVariableName}.");
+
+        TestWorkerProcessFactory processFactory = new(output);
+        await using GatewayServiceFixture fixture = new(workerExecutablePath, processFactory, output);
+
+        string? sessionId = null;
+
+        try
+        {
+            OpenSessionReply openReply = await fixture.Service.OpenSession(
+                new OpenSessionRequest
+                {
+                    ClientSessionName = "live-mxaccess-invalid-handle",
+                    ClientCorrelationId = "live-open-invalid",
+                    CommandTimeout = Duration.FromTimeSpan(CommandTimeout),
+                },
+                new TestServerCallContext()).ConfigureAwait(false);
+
+            sessionId = openReply.SessionId;
+            Assert.Equal(ProtocolStatusCode.Ok, openReply.ProtocolStatus.Code);
+
+            // Deliberately skip Register: server handle 0x7FFFFFFF was never
+            // issued by MXAccess. The worker must invoke COM and relay the
+            // invalid-handle failure rather than the gateway short-circuiting.
+            MxCommandReply addItemReply = await fixture.Service.Invoke(
+                CreateAddItemRequest(sessionId, serverHandle: int.MaxValue),
+                new TestServerCallContext()).ConfigureAwait(false);
+            LogReply("AddItem(invalid-handle)", addItemReply);
+
+            // MXAccess parity: an invalid handle is an MXAccess-level failure.
+            // The command still completed its worker round-trip, so the gateway
+            // protocol status is Ok and the failure shows up in hresult / the
+            // status proxies — it must not be reported as a transport fault.
+            Assert.NotEqual(ProtocolStatusCode.Ok, addItemReply.ProtocolStatus.Code);
+            Assert.True(
+                addItemReply.AddItem is null || addItemReply.AddItem.ItemHandle <= 0,
+                "Invalid-handle AddItem must not yield a usable item handle.");
+        }
+        finally
+        {
+            await ShutDownAsync(fixture, processFactory, sessionId, streamTask: null).ConfigureAwait(false);
+        }
+    }
+
+    /// <summary>
+    /// Closes the session and drains the event stream / worker processes without letting a
+    /// cleanup timeout mask the original failure from the test body.
+    /// </summary>
+    private async Task ShutDownAsync(
+        GatewayServiceFixture fixture,
+        TestWorkerProcessFactory processFactory,
+        string? sessionId,
+        Task? streamTask)
+    {
+        try
+        {
+            if (!string.IsNullOrWhiteSpace(sessionId))
             {
-                await processFactory.WaitForProcessesAsync(StreamShutdownTimeout).ConfigureAwait(false);
+                await CloseSessionAsync(fixture, sessionId).ConfigureAwait(false);
             }
+
+            if (streamTask is not null)
+            {
+                await streamTask.WaitAsync(StreamShutdownTimeout).ConfigureAwait(false);
+            }
+        }
+        catch (Exception ex)
+        {
+            // Cleanup runs in a finally block. A TimeoutException (or a faulted
+            // StreamEvents task) here would otherwise replace any assertion
+            // failure raised in the try block. Log it and let the original
+            // failure surface.
+            output.WriteLine($"Cleanup error during session/stream shutdown: {ex}");
+        }
+
+        try
+        {
+            await processFactory.WaitForProcessesAsync(StreamShutdownTimeout).ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            output.WriteLine($"Cleanup error while waiting for worker processes to exit: {ex}");
         }
     }
 
@@ -175,6 +344,32 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output)
         };
     }
 
+    private static MxCommandRequest CreateWriteRequest(
+        string sessionId,
+        int serverHandle,
+        int itemHandle)
+    {
+        return new MxCommandRequest
+        {
+            SessionId = sessionId,
+            ClientCorrelationId = "live-write",
+            Command = new MxCommand
+            {
+                Kind = MxCommandKind.Write,
+                Write = new WriteCommand
+                {
+                    ServerHandle = serverHandle,
+                    ItemHandle = itemHandle,
+                    Value = new MxValue
+                    {
+                        DataType = MxDataType.Integer,
+                        Int32Value = 1,
+                    },
+                },
+            },
+        };
+    }
+
     private async Task CloseSessionAsync(
         GatewayServiceFixture fixture,
         string sessionId)
@@ -321,8 +516,8 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output)
     private sealed class RecordingServerStreamWriter<T> : IServerStreamWriter<T>
     {
         private readonly object syncRoot = new();
-        private readonly TaskCompletionSource<T> firstMessage = new(TaskCreationOptions.RunContinuationsAsynchronously);
         private readonly List<T> messages = [];
+        private readonly SemaphoreSlim messageArrived = new(0);
 
         /// <summary>
         /// All messages that have been written to the stream.
@@ -344,7 +539,7 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output)
         public WriteOptions? WriteOptions { get; set; }
 
         /// <summary>
-        /// Records the message and completes the first-message task.
+        /// Records the message and signals any pending waiter.
         /// </summary>
         /// <param name="message">The message to write.</param>
         public Task WriteAsync(T message)
@@ -354,18 +549,51 @@ public sealed class WorkerLiveMxAccessSmokeTests(ITestOutputHelper output)
                 messages.Add(message);
             }
 
-            firstMessage.TrySetResult(message);
+            messageArrived.Release();
             return Task.CompletedTask;
         }
 
         /// <summary>
-        /// Waits for the first message up to the specified timeout.
+        /// Waits for the first recorded message that satisfies <paramref name="predicate"/>,
+        /// up to the specified timeout. Earlier non-matching messages (for example a
+        /// registration-state bootstrap event) are skipped rather than treated as the result.
         /// </summary>
-        /// <param name="timeout">The maximum time to wait.</param>
-        /// <returns>The first message written to the stream.</returns>
-        public async Task<T> WaitForFirstMessageAsync(TimeSpan timeout)
+        /// <param name="predicate">Filter the awaited message must satisfy.</param>
+        /// <param name="timeout">The maximum total time to wait.</param>
+        /// <returns>The first message that satisfies the predicate.</returns>
+        public async Task<T> WaitForMessageAsync(
+            Func<T, bool> predicate,
+            TimeSpan timeout)
         {
-            return await firstMessage.Task.WaitAsync(timeout).ConfigureAwait(false);
+            using CancellationTokenSource timeoutCancellation = new(timeout);
+            int scanned = 0;
+
+            while (true)
+            {
+                T[] snapshot;
+                lock (syncRoot)
+                {
+                    snapshot = messages.ToArray();
+                }
+
+                for (; scanned < snapshot.Length; scanned++)
+                {
+                    if (predicate(snapshot[scanned]))
+                    {
+                        return snapshot[scanned];
+                    }
+                }
+
+                try
+                {
+                    await messageArrived.WaitAsync(timeoutCancellation.Token).ConfigureAwait(false);
+                }
+                catch (OperationCanceledException) when (timeoutCancellation.IsCancellationRequested)
+                {
+                    throw new TimeoutException(
+                        $"No stream message satisfied the predicate within {timeout}. Recorded {scanned} message(s).");
+                }
+            }
         }
     }