@webex/internal-plugin-mercury 3.9.0 → 3.10.0-multi-llms.1

package/test/unit/spec/mercury.js

@@ -75,6 +75,8 @@ describe('plugin-mercury', () => {
       webex.internal.services = {
         convertUrlToPriorityHostUrl: sinon.stub().returns(Promise.resolve('ws://example-2.com')),
         markFailedUrl: sinon.stub().returns(Promise.resolve()),
+        switchActiveClusterIds: sinon.stub(),
+        invalidateCache: sinon.stub(),
       };
       webex.internal.metrics.submitClientMetrics = sinon.stub();
       webex.internal.newMetrics.callDiagnosticMetrics.setMercuryConnectedStatus = sinon.stub();
@@ -97,9 +99,32 @@ describe('plugin-mercury', () => {
       });
 
       mercury = webex.internal.mercury;
+      mercury.defaultSessionId = 'mercury-default-session';
     });
 
-    afterEach(() => {
+    afterEach(async () => {
+      // Clean up Mercury connections and internal state
+      if (mercury) {
+        try {
+          await mercury.disconnectAll();
+        } catch (e) {
+          // Ignore cleanup errors
+        }
+        // Clear any remaining connection promises
+        if (mercury._connectPromises) {
+          mercury._connectPromises.clear();
+        }
+      }
+
+      // Ensure mock socket is properly closed
+      if (mockWebSocket && typeof mockWebSocket.close === 'function') {
+        try {
+          mockWebSocket.close();
+        } catch (e) {
+          // Ignore cleanup errors
+        }
+      }
+
       if (socketOpenStub) {
         socketOpenStub.restore();
       }
@@ -107,6 +132,9 @@ describe('plugin-mercury', () => {
       if (Socket.getWebSocketConstructor.restore) {
         Socket.getWebSocketConstructor.restore();
       }
+
+      // Small delay to ensure all async operations complete
+      await new Promise(resolve => setTimeout(resolve, 10));
     });
 
     describe('#listen()', () => {
@@ -162,7 +190,6 @@ describe('plugin-mercury', () => {
             },
           },
         };
-
         assert.isFalse(mercury.connected, 'Mercury is not connected');
         assert.isTrue(mercury.connecting, 'Mercury is connecting');
         mockWebSocket.open();
@@ -191,6 +218,67 @@ describe('plugin-mercury', () => {
           sinon.restore();
         });
       });
+      it('Mercury emit event:ActiveClusterStatusEvent, call services switchActiveClusterIds', () => {
+        const promise = mercury.connect();
+        const activeClusterEventEnvelope = {
+          data: {
+            activeClusters: {
+              wdm: 'wdm-cluster-id.com',
+            },
+          },
+        };
+        mockWebSocket.open();
+
+        return promise.then(() => {
+          mercury._emit('event:ActiveClusterStatusEvent', activeClusterEventEnvelope);
+          assert.calledOnceWithExactly(
+            webex.internal.services.switchActiveClusterIds,
+            activeClusterEventEnvelope.data.activeClusters
+          );
+          sinon.restore();
+        });
+      });
+      it('Mercury emit event:ActiveClusterStatusEvent with no data, not call services switchActiveClusterIds', () => {
+        webex.internal.feature.updateFeature = sinon.stub();
+        const promise = mercury.connect();
+        const envelope = {};
+
+        return promise.then(() => {
+          mercury._emit('event:ActiveClusterStatusEvent', envelope);
+          assert.notCalled(webex.internal.services.switchActiveClusterIds);
+          sinon.restore();
+        });
+      });
+      it('Mercury emit event:u2c.cache-invalidation, call services invalidateCache', () => {
+        const promise = mercury.connect();
+        const u2cInvalidateEventEnvelope = {
+          data: {
+            timestamp: '1759289614',
+          },
+        };
+
+        mockWebSocket.open();
+
+        return promise.then(() => {
+          mercury._emit('event:u2c.cache-invalidation', u2cInvalidateEventEnvelope);
+          assert.calledOnceWithExactly(
+            webex.internal.services.invalidateCache,
+            u2cInvalidateEventEnvelope.data.timestamp
+          );
+          sinon.restore();
+        });
+      });
+      it('Mercury emit event:u2c.cache-invalidation with no data, not call services switchActiveClusterIds', () => {
+        webex.internal.feature.updateFeature = sinon.stub();
+        const promise = mercury.connect();
+        const envelope = {};
+
+        return promise.then(() => {
+          mercury._emit('event:u2c.cache-invalidation', envelope);
+          assert.notCalled(webex.internal.services.invalidateCache);
+          sinon.restore();
+        });
+      });
 
       describe('when `maxRetries` is set', () => {
         const check = () => {
@@ -436,9 +524,13 @@ describe('plugin-mercury', () => {
 
         // skipping due to apparent bug with lolex in all browsers but Chrome.
         skipInBrowser(it)('does not continue attempting to connect', () => {
-          mercury.connect();
+          const promise = mercury.connect();
+
+          // Wait for the connection to be established before proceeding
+          mockWebSocket.open();
 
-          return promiseTick(2)
+          return promise.then(() =>
+            promiseTick(2)
             .then(() => {
               clock.tick(6 * webex.internal.mercury.config.backoffTimeReset);
 
@@ -446,7 +538,8 @@ describe('plugin-mercury', () => {
             })
             .then(() => {
               assert.calledOnce(Socket.prototype.open);
-            });
+              })
+          );
         });
       });
 
@@ -521,11 +614,11 @@ describe('plugin-mercury', () => {
     });
 
     describe('#logout()', () => {
-      it('calls disconnect and logs', () => {
+      it('calls disconnectAll and logs', () => {
         sinon.stub(mercury.logger, 'info');
-        sinon.stub(mercury, 'disconnect');
+        sinon.stub(mercury, 'disconnectAll');
         mercury.logout();
-        assert.called(mercury.disconnect);
+        assert.called(mercury.disconnectAll);
         assert.calledTwice(mercury.logger.info);
 
         assert.calledWith(mercury.logger.info.getCall(0), 'Mercury: logout() called');
@@ -537,24 +630,24 @@ describe('plugin-mercury', () => {
       });
 
       it('uses the config.beforeLogoutOptionsCloseReason to disconnect and will send code 3050 for logout', () => {
-        sinon.stub(mercury, 'disconnect');
+        sinon.stub(mercury, 'disconnectAll');
         mercury.config.beforeLogoutOptionsCloseReason = 'done (permanent)';
         mercury.logout();
-        assert.calledWith(mercury.disconnect, {code: 3050, reason: 'done (permanent)'});
+        assert.calledWith(mercury.disconnectAll, {code: 3050, reason: 'done (permanent)'});
       });
 
       it('uses the config.beforeLogoutOptionsCloseReason to disconnect and will send code 3050 for logout if the reason is different than standard', () => {
-        sinon.stub(mercury, 'disconnect');
+        sinon.stub(mercury, 'disconnectAll');
         mercury.config.beforeLogoutOptionsCloseReason = 'test';
         mercury.logout();
-        assert.calledWith(mercury.disconnect, {code: 3050, reason: 'test'});
+        assert.calledWith(mercury.disconnectAll, {code: 3050, reason: 'test'});
       });
 
       it('uses the config.beforeLogoutOptionsCloseReason to disconnect and will send undefined for logout if the reason is same as standard', () => {
-        sinon.stub(mercury, 'disconnect');
+        sinon.stub(mercury, 'disconnectAll');
         mercury.config.beforeLogoutOptionsCloseReason = 'done (forced)';
         mercury.logout();
-        assert.calledWith(mercury.disconnect, undefined);
+        assert.calledWith(mercury.disconnectAll, undefined);
       });
     });
 
@@ -660,12 +753,12 @@ describe('plugin-mercury', () => {
           return promiseTick(webex.internal.mercury.config.backoffTimeReset).then(() => {
             // By this time backoffCall and mercury socket should be defined by the
             // 'connect' call
-            assert.isDefined(mercury.backoffCall, 'Mercury backoffCall is not defined');
+            assert.isDefined(mercury.backoffCalls.get('mercury-default-session'), 'Mercury backoffCall is not defined');
             assert.isDefined(mercury.socket, 'Mercury socket is not defined');
             // Calling disconnect will abort the backoffCall, close the socket, and
             // reject the connect
             mercury.disconnect();
-            assert.isUndefined(mercury.backoffCall, 'Mercury backoffCall is still defined');
+            assert.isUndefined(mercury.backoffCalls.get('mercury-default-session'), 'Mercury backoffCall is still defined');
             // The socket will never be unset (which seems bad)
             assert.isDefined(mercury.socket, 'Mercury socket is not defined');
 
@@ -683,15 +776,15 @@ describe('plugin-mercury', () => {
 
           let reason;
 
-          mercury.backoffCall = undefined;
-          mercury._attemptConnection('ws://example.com', (_reason) => {
+          mercury.backoffCalls.clear();
+          mercury._attemptConnection('ws://example.com', 'mercury-default-session',(_reason) => {
             reason = _reason;
           });
 
           return promiseTick(webex.internal.mercury.config.backoffTimeReset).then(() => {
             assert.equal(
               reason.message,
-              'Mercury: prevent socket open when backoffCall no longer defined'
+              `Mercury: prevent socket open when backoffCall no longer defined for ${mercury.defaultSessionId}`
             );
           });
         });
@@ -713,7 +806,7 @@ describe('plugin-mercury', () => {
             return assert.isRejected(promise).then((error) => {
               const lastError = mercury.getLastError();
 
-              assert.equal(error.message, 'Mercury Connection Aborted');
+              assert.equal(error.message, `Mercury Connection Aborted for ${mercury.defaultSessionId}`);
               assert.isDefined(lastError);
               assert.equal(lastError, realError);
             });
@@ -807,7 +900,7 @@ describe('plugin-mercury', () => {
           },
         };
         assert.isUndefined(mercury.mercuryTimeOffset);
-        mercury._setTimeOffset(event);
+        mercury._setTimeOffset('mercury-default-session', event);
         assert.isDefined(mercury.mercuryTimeOffset);
         assert.isTrue(mercury.mercuryTimeOffset > 0);
       });
@@ -817,7 +910,7 @@ describe('plugin-mercury', () => {
             wsWriteTimestamp: Date.now() + 60000,
           },
         };
-        mercury._setTimeOffset(event);
+        mercury._setTimeOffset('mercury-default-session', event);
         assert.isTrue(mercury.mercuryTimeOffset < 0);
       });
       it('handles invalid wsWriteTimestamp', () => {
@@ -828,7 +921,7 @@ describe('plugin-mercury', () => {
               wsWriteTimestamp: invalidTimestamp,
             },
           };
-          mercury._setTimeOffset(event);
+          mercury._setTimeOffset('mercury-default-session', event);
           assert.isUndefined(mercury.mercuryTimeOffset);
         });
       });
@@ -922,5 +1015,626 @@ describe('plugin-mercury', () => {
         });
       });
     });
+
+    describe('shutdown protocol', () => {
+      describe('#_handleImminentShutdown()', () => {
+        let connectWithBackoffStub;
+
+        beforeEach(() => {
+          mercury.connected = true;
+          mercury.socket = {
+            url: 'ws://old-socket.com',
+            removeAllListeners: sinon.stub(),
+          };
+          connectWithBackoffStub = sinon.stub(mercury, '_connectWithBackoff');
+          connectWithBackoffStub.returns(Promise.resolve());
+          sinon.stub(mercury, '_emit');
+        });
+
+        afterEach(() => {
+          connectWithBackoffStub.restore();
+          mercury._emit.restore();
+        });
+
+        it('should be idempotent - no-op if already in progress', () => {
+          mercury._shutdownSwitchoverInProgress = true;
+
+          mercury._handleImminentShutdown();
+
+          assert.notCalled(connectWithBackoffStub);
+        });
+
+        it('should set switchover flags when called', () => {
+          mercury._handleImminentShutdown();
+
+          assert.isTrue(mercury._shutdownSwitchoverInProgress);
+          assert.isDefined(mercury._shutdownSwitchoverId);
+        });
+
+        it('should call _connectWithBackoff with correct parameters', (done) => {
+          mercury._handleImminentShutdown();
+
+          process.nextTick(() => {
+            assert.calledOnce(connectWithBackoffStub);
+            const callArgs = connectWithBackoffStub.firstCall.args;
+            assert.isUndefined(callArgs[0]); // webSocketUrl
+            assert.isObject(callArgs[1]); // context
+            assert.isTrue(callArgs[1].isShutdownSwitchover);
+            done();
+          });
+        });
+
+        it('should handle exceptions during switchover', () => {
+          connectWithBackoffStub.restore();
+          sinon.stub(mercury, '_connectWithBackoff').throws(new Error('Connection failed'));
+
+          mercury._handleImminentShutdown();
+
+          assert.isFalse(mercury._shutdownSwitchoverInProgress);
+        });
+      });
+
+      describe('#_onmessage() with shutdown message', () => {
+        beforeEach(() => {
+          sinon.stub(mercury, '_handleImminentShutdown');
+          sinon.stub(mercury, '_emit');
+          sinon.stub(mercury, '_setTimeOffset');
+        });
+
+        afterEach(() => {
+          mercury._handleImminentShutdown.restore();
+          mercury._emit.restore();
+          mercury._setTimeOffset.restore();
+        });
+
+        it('should trigger _handleImminentShutdown on shutdown message', () => {
+          const shutdownEvent = {
+            data: {
+              type: 'shutdown',
+            },
+          };
+
+          const result = mercury._onmessage(shutdownEvent);
+
+          assert.calledOnce(mercury._handleImminentShutdown);
+          assert.calledWith(mercury._emit, 'event:mercury_shutdown_imminent', shutdownEvent.data);
+          assert.instanceOf(result, Promise);
+        });
+
+        it('should handle shutdown message without additional data gracefully', () => {
+          const shutdownEvent = {
+            data: {
+              type: 'shutdown',
+            },
+          };
+
+          mercury._onmessage(shutdownEvent);
+
+          assert.calledOnce(mercury._handleImminentShutdown);
+        });
+
+        it('should not trigger shutdown handling for non-shutdown messages', () => {
+          const regularEvent = {
+            data: {
+              type: 'regular',
+              data: {
+                eventType: 'conversation.activity',
+              },
+            },
+          };
+
+          mercury._onmessage(regularEvent);
+
+          assert.notCalled(mercury._handleImminentShutdown);
+        });
+      });
+
+      describe('#_onclose() with code 4001 (shutdown replacement)', () => {
+        let mockSocket, anotherSocket;
+
+        beforeEach(() => {
+          mockSocket = {
+            url: 'ws://active-socket.com',
+            removeAllListeners: sinon.stub(),
+          };
+          anotherSocket = {
+            url: 'ws://old-socket.com',
+            removeAllListeners: sinon.stub(),
+          };
+          mercury.socket = mockSocket;
+          mercury.connected = true;
+          sinon.stub(mercury, '_emit');
+          sinon.stub(mercury, '_reconnect');
+          sinon.stub(mercury, 'unset');
+        });
+
+        afterEach(() => {
+          mercury._emit.restore();
+          mercury._reconnect.restore();
+          mercury.unset.restore();
+        });
+
+        it('should handle active socket close with 4001 - permanent failure', () => {
+          const closeEvent = {
+            code: 4001,
+            reason: 'replaced during shutdown',
+          };
+
+          mercury._onclose(closeEvent, mockSocket);
+
+          assert.calledWith(mercury._emit, 'offline.permanent', closeEvent);
+          assert.notCalled(mercury._reconnect); // No reconnect for 4001 on active socket
+          assert.isFalse(mercury.connected);
+        });
+
+        it('should handle non-active socket close with 4001 - no reconnect needed', () => {
+          const closeEvent = {
+            code: 4001,
+            reason: 'replaced during shutdown',
+          };
+
+          mercury._onclose(closeEvent, anotherSocket);
+
+          assert.calledWith(mercury._emit, 'offline.replaced', closeEvent);
+          assert.notCalled(mercury._reconnect);
+          assert.isTrue(mercury.connected); // Should remain connected
+          assert.notCalled(mercury.unset);
+        });
+
+        it('should distinguish between active and non-active socket closes', () => {
+          const closeEvent = {
+            code: 4001,
+            reason: 'replaced during shutdown',
+          };
+
+          // Test non-active socket
+          mercury._onclose(closeEvent, anotherSocket);
+          assert.calledWith(mercury._emit, 'offline.replaced', closeEvent);
+
+          // Reset the spy call history
+          mercury._emit.resetHistory();
+
+          // Test active socket
+          mercury._onclose(closeEvent, mockSocket);
+          assert.calledWith(mercury._emit, 'offline.permanent', closeEvent);
+        });
+
+        it('should handle missing sourceSocket parameter (treats as non-active)', () => {
+          const closeEvent = {
+            code: 4001,
+            reason: 'replaced during shutdown',
+          };
+
+          mercury._onclose(closeEvent); // No sourceSocket parameter
+
+          // With simplified logic, undefined !== this.socket, so isActiveSocket = false
+          assert.calledWith(mercury._emit, 'offline.replaced', closeEvent);
+          assert.notCalled(mercury._reconnect);
+        });
+
+        it('should clean up event listeners from non-active socket when it closes', () => {
+          const closeEvent = {
+            code: 4001,
+            reason: 'replaced during shutdown',
+          };
+
+          // Close non-active socket (not the active one)
+          mercury._onclose(closeEvent, anotherSocket);
+
+          // Verify listeners were removed from the old socket
+          // The _onclose method checks if sourceSocket !== this.socket (non-active)
+          // and then calls removeAllListeners in the else branch
+          assert.calledOnce(anotherSocket.removeAllListeners);
+        });
+
+        it('should not clean up listeners from active socket listeners until close handler runs', () => {
+          const closeEvent = {
+            code: 4001,
+            reason: 'replaced during shutdown',
+          };
+
+          // Close active socket
+          mercury._onclose(closeEvent, mockSocket);
+
+          // Verify listeners were removed from active socket
+          assert.calledOnce(mockSocket.removeAllListeners);
+        });
+      });
+
+      describe('shutdown switchover with retry logic', () => {
+        let connectWithBackoffStub;
+
+        beforeEach(() => {
+          mercury.connected = true;
+          mercury.socket = {
+            url: 'ws://old-socket.com',
+            removeAllListeners: sinon.stub(),
+          };
+          connectWithBackoffStub = sinon.stub(mercury, '_connectWithBackoff');
+          sinon.stub(mercury, '_emit');
+        });
+
+        afterEach(() => {
+          connectWithBackoffStub.restore();
+          mercury._emit.restore();
+        });
+
+        it('should call _connectWithBackoff with shutdown switchover context', (done) => {
+          connectWithBackoffStub.returns(Promise.resolve());
+
+          mercury._handleImminentShutdown();
+
+          // Give it a tick for the async call to happen
+          process.nextTick(() => {
+            assert.calledOnce(connectWithBackoffStub);
+            const callArgs = connectWithBackoffStub.firstCall.args;
+
+            assert.isUndefined(callArgs[0]); // webSocketUrl is undefined
+            assert.isObject(callArgs[1]); // context object
+            assert.isTrue(callArgs[1].isShutdownSwitchover);
+            assert.isObject(callArgs[1].attemptOptions);
+            assert.isTrue(callArgs[1].attemptOptions.isShutdownSwitchover);
+            done();
+          });
+        });
+
+        it('should set _shutdownSwitchoverInProgress flag during switchover', () => {
+          connectWithBackoffStub.returns(new Promise(() => {})); // Never resolves
+
+          mercury._handleImminentShutdown();
+
+          assert.isTrue(mercury._shutdownSwitchoverInProgress);
+        });
+
+        it('should emit success event when switchover completes', async () => {
+          // We need to actually call the onSuccess callback to trigger the event
+          connectWithBackoffStub.callsFake((url, context) => {
+            // Simulate successful connection by calling onSuccess
+            if (context && context.attemptOptions && context.attemptOptions.onSuccess) {
+              const mockSocket = {url: 'ws://new-socket.com'};
+              context.attemptOptions.onSuccess(mockSocket, 'ws://new-socket.com');
+            }
+            return Promise.resolve();
+          });
+
+          mercury._handleImminentShutdown();
+
+          // Wait for async operations
+          await promiseTick(50);
+
+          const emitCalls = mercury._emit.getCalls();
+          const hasCompleteEvent = emitCalls.some(
+            (call) => call.args[0] === 'event:mercury_shutdown_switchover_complete'
+          );
+
+          assert.isTrue(hasCompleteEvent, 'Should emit switchover complete event');
+        });
+
+        it('should emit failure event when switchover exhausts retries', async () => {
+          const testError = new Error('Connection failed');
+
+          connectWithBackoffStub.returns(Promise.reject(testError));
+
+          mercury._handleImminentShutdown();
+          await promiseTick(50);
+
+          // Check if failure event was emitted
+          const emitCalls = mercury._emit.getCalls();
+          const hasFailureEvent = emitCalls.some(
+            (call) =>
+              call.args[0] === 'event:mercury_shutdown_switchover_failed' &&
+              call.args[1] &&
+              call.args[1].reason === testError
+          );
+
+          assert.isTrue(hasFailureEvent, 'Should emit switchover failed event');
+        });
+
+        it('should allow old socket to be closed by server after switchover failure', async () => {
+          connectWithBackoffStub.returns(Promise.reject(new Error('Failed')));
+
+          mercury._handleImminentShutdown();
+          await promiseTick(50);
+
+          // Old socket should not be closed immediately - server will close it
+          assert.equal(mercury.socket.removeAllListeners.callCount, 0);
+        });
+      });
+
+      describe('#_prepareAndOpenSocket()', () => {
+        let mockSocket, prepareUrlStub, getUserTokenStub;
+
+        beforeEach(() => {
+          mockSocket = {
+            open: sinon.stub().returns(Promise.resolve()),
+          };
+          prepareUrlStub = sinon
+            .stub(mercury, '_prepareUrl')
+            .returns(Promise.resolve('ws://example.com'));
+          getUserTokenStub = webex.credentials.getUserToken;
+          getUserTokenStub.returns(
+            Promise.resolve({
+              toString: () => 'mock-token',
+            })
+          );
+        });
+
+        afterEach(() => {
+          prepareUrlStub.restore();
+        });
+
+        it('should prepare URL and get user token', async () => {
+          await mercury._prepareAndOpenSocket(mockSocket, 'ws://test.com', false);
+
+          assert.calledOnce(prepareUrlStub);
+          assert.calledWith(prepareUrlStub, 'ws://test.com');
+          assert.calledOnce(getUserTokenStub);
+        });
+
+        it('should open socket with correct options for normal connection', async () => {
+          await mercury._prepareAndOpenSocket(mockSocket, undefined, false);
+
+          assert.calledOnce(mockSocket.open);
+          const callArgs = mockSocket.open.firstCall.args;
+
+          assert.equal(callArgs[0], 'ws://example.com');
+          assert.isObject(callArgs[1]);
+          assert.equal(callArgs[1].token, 'mock-token');
+          assert.isDefined(callArgs[1].forceCloseDelay);
+          assert.isDefined(callArgs[1].pingInterval);
+          assert.isDefined(callArgs[1].pongTimeout);
+        });
+
+        it('should log with correct prefix for normal connection', async () => {
+          await mercury._prepareAndOpenSocket(mockSocket, undefined, false);
+
+          // The method should complete successfully - we're testing it runs without error
+          // Actual log message verification is complex due to existing stubs in parent scope
+          assert.calledOnce(mockSocket.open);
+        });
+
+        it('should log with shutdown prefix for shutdown connection', async () => {
+          await mercury._prepareAndOpenSocket(mockSocket, undefined, true);
+
+          // The method should complete successfully with shutdown flag
+          assert.calledOnce(mockSocket.open);
+        });
+
+        it('should merge custom mercury options when provided', async () => {
+          webex.config.defaultMercuryOptions = {
+            customOption: 'test-value',
+            pingInterval: 99999,
+          };
+
+          await mercury._prepareAndOpenSocket(mockSocket, undefined, false);
+
+          const callArgs = mockSocket.open.firstCall.args;
+
+          assert.equal(callArgs[1].customOption, 'test-value');
+          assert.equal(callArgs[1].pingInterval, 99999); // Custom value overrides default
+        });
+
+        it('should return the webSocketUrl after opening', async () => {
+          const result = await mercury._prepareAndOpenSocket(mockSocket, undefined, false);
+
+          assert.equal(result, 'ws://example.com');
+        });
+
+        it('should handle errors during socket open', async () => {
+          mockSocket.open.returns(Promise.reject(new Error('Open failed')));
+
+          try {
+            await mercury._prepareAndOpenSocket(mockSocket, undefined, false);
+            assert.fail('Should have thrown an error');
+          } catch (err) {
+            assert.equal(err.message, 'Open failed');
+          }
+        });
+      });
+
+      describe('#_attemptConnection() with shutdown switchover', () => {
+        let mockSocket, prepareAndOpenSocketStub, callback;
+
+        beforeEach(() => {
+          mockSocket = {
+            url: 'ws://test.com',
+          };
+          prepareAndOpenSocketStub = sinon
+            .stub(mercury, '_prepareAndOpenSocket')
+            .returns(Promise.resolve('ws://new-socket.com'));
+          callback = sinon.stub();
+          mercury._shutdownSwitchoverBackoffCall = {}; // Mock backoff call
+          mercury.socket = mockSocket;
+          mercury.connected = true;
+          sinon.stub(mercury, '_emit');
+          sinon.stub(mercury, '_attachSocketEventListeners');
+        });
+
+        afterEach(() => {
+          prepareAndOpenSocketStub.restore();
+          mercury._emit.restore();
+          mercury._attachSocketEventListeners.restore();
+        });
+
+        it('should not set socket reference before opening for shutdown switchover', async () => {
+          const originalSocket = mercury.socket;
+
+          await mercury._attemptConnection('ws://test.com', callback, {
+            isShutdownSwitchover: true,
+            onSuccess: (newSocket, url) => {
+              // During onSuccess, verify original socket is still set
+              // (socket swap happens inside onSuccess callback in _handleImminentShutdown)
+              assert.equal(mercury.socket, originalSocket);
+            },
+          });
+
+          // After onSuccess, socket should still be original since we only swap in _handleImminentShutdown
+          assert.equal(mercury.socket, originalSocket);
+        });
+
+        it('should call onSuccess callback with new socket and URL for shutdown', async () => {
+          const onSuccessStub = sinon.stub();
+
+          await mercury._attemptConnection('ws://test.com', callback, {
+            isShutdownSwitchover: true,
+            onSuccess: onSuccessStub,
+          });
+
+          assert.calledOnce(onSuccessStub);
+          assert.equal(onSuccessStub.firstCall.args[1], 'ws://new-socket.com');
+        });
+
+        it('should emit shutdown switchover complete event', async () => {
+          const oldSocket = mercury.socket;
+
+          await mercury._attemptConnection('ws://test.com', callback, {
+            isShutdownSwitchover: true,
+            onSuccess: (newSocket, url) => {
+              // Simulate the onSuccess callback behavior
+              mercury.socket = newSocket;
+              mercury.connected = true;
+              mercury._emit('event:mercury_shutdown_switchover_complete', {url});
+            },
+          });
+
+          assert.calledWith(
+            mercury._emit,
+            'event:mercury_shutdown_switchover_complete',
+            sinon.match.has('url', 'ws://new-socket.com')
+          );
+        });
+
+        it('should use simpler error handling for shutdown switchover failures', async () => {
+          prepareAndOpenSocketStub.returns(Promise.reject(new Error('Connection failed')));
+
+          try {
+            await mercury._attemptConnection('ws://test.com', callback, {
+              isShutdownSwitchover: true,
+            });
+          } catch (err) {
+            // Error should be caught and passed to callback
+          }
+
+          // Should call callback with error for retry
+          assert.calledOnce(callback);
+          assert.instanceOf(callback.firstCall.args[0], Error);
+        });
+
+        it('should check _shutdownSwitchoverBackoffCall for shutdown connections', () => {
+          mercury._shutdownSwitchoverBackoffCall = undefined;
+
+          const result = mercury._attemptConnection('ws://test.com', callback, {
+            isShutdownSwitchover: true,
+          });
+
+          return result.catch((err) => {
+            assert.instanceOf(err, Error);
+            assert.match(err.message, /switchover backoff call/);
+          });
+        });
+      });
+
+      describe('#_connectWithBackoff() with shutdown switchover', () => {
+        // Note: These tests verify the parameterization logic without running real backoff timers
+        // to avoid test hangs. The backoff mechanism itself is tested in other test suites.
+
+        it('should use shutdown-specific parameters when called', () => {
+          // Stub _connectWithBackoff to prevent real execution
+          const connectWithBackoffStub = sinon
+            .stub(mercury, '_connectWithBackoff')
+            .returns(Promise.resolve());
+
+          mercury._handleImminentShutdown();
+
+          // Verify it was called with shutdown context
+          assert.calledOnce(connectWithBackoffStub);
+          const callArgs = connectWithBackoffStub.firstCall.args;
+          assert.isObject(callArgs[1]); // context
+          assert.isTrue(callArgs[1].isShutdownSwitchover);
+
+          connectWithBackoffStub.restore();
+        });
+
+        it('should pass shutdown switchover options to _attemptConnection', () => {
+          // Stub _attemptConnection to verify it receives correct options
+          const attemptStub = sinon.stub(mercury, '_attemptConnection');
+          attemptStub.callsFake((url, callback) => {
+            // Immediately succeed
+            callback();
+          });
+
+          // Call _connectWithBackoff with shutdown context
+          const context = {
+            isShutdownSwitchover: true,
+            attemptOptions: {
+              isShutdownSwitchover: true,
+              onSuccess: () => {},
+            },
+          };
+
+          // Start the backoff
+          const promise = mercury._connectWithBackoff(undefined, context);
+
+          // Check that _attemptConnection was called with shutdown options
+          return promise.then(() => {
+            assert.calledOnce(attemptStub);
+            const callArgs = attemptStub.firstCall.args;
+            assert.isObject(callArgs[2]); // options parameter
+            assert.isTrue(callArgs[2].isShutdownSwitchover);
+
+            attemptStub.restore();
+          });
+        });
+
+        it('should set and clear state flags appropriately', () => {
+          // Stub to prevent actual connection
+          sinon.stub(mercury, '_attemptConnection').callsFake((url, callback) => callback());
+
+          mercury._shutdownSwitchoverInProgress = true;
+
+          const promise = mercury._connectWithBackoff(undefined, {
+            isShutdownSwitchover: true,
+            attemptOptions: {isShutdownSwitchover: true, onSuccess: () => {}},
+          });
+
+          return promise.then(() => {
+            // Should be cleared after completion
+            assert.isFalse(mercury._shutdownSwitchoverInProgress);
+            mercury._attemptConnection.restore();
+          });
+        });
+      });
+
+      describe('#disconnect() with shutdown switchover in progress', () => {
+        let abortStub;
+
+        beforeEach(() => {
+          mercury.socket = {
+            close: sinon.stub().returns(Promise.resolve()),
+            removeAllListeners: sinon.stub(),
+          };
+          abortStub = sinon.stub();
+          mercury._shutdownSwitchoverBackoffCall = {
+            abort: abortStub,
+          };
+        });
+
+        it('should abort shutdown switchover backoff call on disconnect', async () => {
+          await mercury.disconnect();
+
+          assert.calledOnce(abortStub);
+        });
+
+        it('should handle disconnect when no switchover is in progress', async () => {
+          mercury._shutdownSwitchoverBackoffCall = undefined;
+
+          // Should not throw
+          await mercury.disconnect();
+
+          // Should still close the socket
+          assert.calledOnce(mercury.socket.close);
+        });
+      });
+    });
   });
 });