feat: add button to detach from session without termination (#2641)

* feat: add button to detach from session without termination

* docs: add docs for detach button

* address copilot comment

* docs: add emphasis that the session is retained

Author: eglitise

app/common/public/locales/en/translation.json

@@ -321,5 +321,6 @@
   "Import from File": "Import from File",
   "useMjpegStream": "Use MJPEG Stream",
   "useScreenshotApi": "Use Screenshot API",
-  "Box Model": "Box Model"
+  "Box Model": "Box Model",
+  "detachFromSession": "Detach from Session"
 }

app/common/renderer/actions/SessionBuilder.js

@@ -991,7 +991,7 @@ export function bindWindowClose() {
       let {driver} = getState().inspector;
       if (driver) {
         try {
-          const action = quitSession('Window closed');
+          const action = quitSession();
           await action(dispatch, getState);
         } finally {
           driver = null;

app/common/renderer/actions/SessionInspector.js

@@ -263,7 +263,7 @@ export function restartSession(error, params) {
       title: i18n.t('RestartSessionMessage'),
       duration: 3,
     });
-    const quitSes = quitSession('Window closed');
+    const quitSes = quitSession();
     const newSes = newSession(getState().builder.caps);
     const getPageSrc = applyClientMethod({methodName: 'getPageSource'});
     const storeSessionSet = storeSessionSettings();
@@ -298,14 +298,16 @@ export function setExpandedPaths(paths) {
 /**
  * Quit the session and go back to the new session window
  */
-export function quitSession(reason, killedByUser = true) {
+export function quitSession({reason, manualQuit = true, detachOnly = false} = {}) {
   return async (dispatch, getState) => {
     const killAction = killKeepAliveLoop();
     killAction(dispatch, getState);
-    const applyAction = applyClientMethod({methodName: 'deleteSession'});
-    await applyAction(dispatch, getState);
+    if (!detachOnly) {
+      const applyAction = applyClientMethod({methodName: 'deleteSession'});
+      await applyAction(dispatch, getState);
+    }
     dispatch({type: QUIT_SESSION_DONE});
-    if (!killedByUser) {
+    if (!manualQuit) {
       showError(new Error(reason || i18n.t('Session has been terminated')), {secs: 0});
     }
   };

app/common/renderer/components/SessionInspector/Header/HeaderButtons.jsx

@@ -7,6 +7,7 @@ import {
   IconMessageChatbot,
   IconPlayerPause,
   IconPlayerPlay,
+  IconPlugConnectedX,
   IconRecycle,
   IconRefresh,
   IconSearch,
@@ -38,7 +39,7 @@ const HeaderButtons = (props) => {
     showLocatorTestModal,
     showSiriCommandModal,
     applyClientMethod,
-    quitCurrentSession,
+    quitSessionAndReturn,
     driver,
     contexts,
     currentContext,
@@ -231,10 +232,19 @@ const HeaderButtons = (props) => {
     </Space.Compact>
   );
 
-  const quitSessionButton = (
-    <Tooltip title={t('Quit Session')}>
-      <Button id="btnClose" icon={<IconX size={18} />} onClick={quitCurrentSession} />
-    </Tooltip>
+  const quitControls = (
+    <Space.Compact>
+      <Tooltip title={t('detachFromSession')}>
+        <Button
+          id="btnDetach"
+          icon={<IconPlugConnectedX size={18} />}
+          onClick={() => quitSessionAndReturn({detachOnly: true})}
+        />
+      </Tooltip>
+      <Tooltip title={t('Quit Session')}>
+        <Button id="btnClose" icon={<IconX size={18} />} onClick={quitSessionAndReturn} />
+      </Tooltip>
+    </Space.Compact>
   );
 
   const sessionReloadButton = (
@@ -255,7 +265,7 @@ const HeaderButtons = (props) => {
         {appModeControls}
         {generalControls}
         {sessionReloadButton}
-        {quitSessionButton}
+        {quitControls}
       </Space>
       <Divider />
     </div>

app/common/renderer/components/SessionInspector/SessionInspector.jsx

@@ -188,9 +188,9 @@ const Inspector = (props) => {
     applyClientMethod({methodName: 'getPageSource'});
   };
 
-  const quitCurrentSession = useCallback(
-    async (reason, killedByUser = true) => {
-      await quitSession(reason, killedByUser);
+  const quitSessionAndReturn = useCallback(
+    async ({reason, manualQuit = true, detachOnly = false} = {}) => {
+      await quitSession({reason, manualQuit, detachOnly});
       navigate('/session', {replace: true});
     },
     [navigate, quitSession],
@@ -245,7 +245,7 @@ const Inspector = (props) => {
       // Create timeout only once while prompt is visible
       if (!sessionExpiryTimeoutRef.current) {
         sessionExpiryTimeoutRef.current = setTimeout(() => {
-          quitCurrentSession(t('Session closed due to inactivity'), false);
+          quitSessionAndReturn({reason: t('Session closed due to inactivity'), manualQuit: false});
         }, SESSION_EXPIRY_PROMPT_TIMEOUT);
         setUserWaitTimeout(sessionExpiryTimeoutRef.current);
       }
@@ -255,7 +255,7 @@ const Inspector = (props) => {
       sessionExpiryTimeoutRef.current = null;
       setUserWaitTimeout(null);
     }
-  }, [quitCurrentSession, setUserWaitTimeout, showKeepAlivePrompt, t]);
+  }, [quitSessionAndReturn, setUserWaitTimeout, showKeepAlivePrompt, t]);
 
   const screenShotControls = (
     <div className={styles.screenshotControls}>
@@ -379,13 +379,13 @@ const Inspector = (props) => {
 
   return (
     <div className={styles.inspectorContainer}>
-      <HeaderButtons quitCurrentSession={quitCurrentSession} {...props} />
+      <HeaderButtons quitSessionAndReturn={quitSessionAndReturn} {...props} />
       {main}
       <Modal
         title={t('Session Inactive')}
         open={showKeepAlivePrompt}
         onOk={() => keepSessionAlive()}
-        onCancel={() => quitCurrentSession()}
+        onCancel={() => quitSessionAndReturn()}
         okText={t('Keep Session Running')}
         cancelText={t('Quit Session')}
       >

docs/assets/images/session-inspector.png

@@ -129,8 +129,18 @@ session (selecting an element, interacting with the screenshot, searching for el
 that returns a failed response. Since such a response is not guaranteed to be caused by a
 disconnected device, this functionality is disabled by default.
 
+## Detach from Session
+
+![Detach Button](./assets/images/header/detach-button.png)
+
+This button disconnects the Inspector from the active session and returns to the
+[Session Builder](../session-builder/index.md), but the session itself ^^is not deleted^^, and
+^^remains running^^ on the Appium server. This approach may be useful if you are attaching to an
+existing session mid-test and want to resume the test afterwards, or if you want to reuse the
+session later.
+
 ## Quit Session
 
 ![Quit Button](./assets/images/header/quit-button.png)
 
-This button quits the Inspector session and returns to the [Session Builder](../session-builder/index.md).
+This button deletes the active session and returns to the Session Builder.