feat(keep-browser): keep browser alive after end of tests

* feat(keep-browser): keep browser alive after end of tests

* feat(standalone): attach browser for standalone api

* feat(standalone): attach browser for standalone api #1

* feat(standalone): kill driver process

* feat(standalone): kill driver process by pid

* feat(standalone): kill driver process by pid

* feat(standalone): add tests

* feat(standalone): add tests 2

* feat(standalone): add tests 3

---------

Co-authored-by: rocketraccoon <rocketraccoon@yandex-team.ru>

Author: sonic16x

docs/debugging.md

@@ -7,3 +7,62 @@ Testpalne supports [OpenTelemetry](https://opentelemetry.io) standard for tracin
 
 You can use `traceparent` to trace the execution of individual tests.
 
+### Keep Browser for Debugging
+
+Testplane provides CLI options to keep browser sessions alive after test completion for debugging purposes. This feature has two main use cases:
+
+1. **Local debugging**: After test fails, you can still interact with the browser and see what's wrong
+2. **AI agents integration**: Let AI agents run tests to perform complex logic (e.g. custom authentication), then attach to browser via MCP and perform additional actions
+
+#### Why not REPL?
+
+While REPL mode pauses test execution for interactive debugging, keep-browser options preserve the final browser state after tests finish. For AI agents, it's much easier to say "write test with the same beforeEach as in this file and run it to prepare browser" rather than forcing AI to use REPL interactively.
+
+#### `--keep-browser`
+
+Keep browser session alive after test completion for debugging.
+
+```bash
+npx testplane --keep-browser --browser chrome tests/login.test.js
+```
+
+#### `--keep-browser-on-fail`
+
+Keep browser session alive only when test fails for debugging.
+
+```bash
+npx testplane --keep-browser-on-fail --browser chrome tests/login.test.js
+```
+
+**Note**: These options work only when running a single test in a single browser.
+
+#### Session Information
+
+When a browser is kept alive, Testplane outputs a message with session information for programmatic access:
+
+```
+Testplane run has finished, but the browser won't be closed, because you passed the --keep-browser argument.
+You may attach to this browser using the following capabilities:
+{
+    "sessionId": "abc123...",
+    "capabilities": {
+        "browserName": "chrome",
+        "debuggerAddress": "127.0.0.1:9222"
+    },
+    "sessionOptions": {
+        "hostname": "127.0.0.1",
+        "port": 4444,
+        "path": "/wd/hub",
+        "protocol": "http"
+    }
+}
+```
+
+#### Attaching to Kept Session
+
+You can use the outputted session information to attach to the kept browser through:
+
+- **MCP (Model Context Protocol)** tools that support WebDriver session attachment
+- **CDP (Chrome DevTools Protocol)** using the `debuggerAddress` from capabilities
+- **Direct WebDriver** connection using the session ID and connection details
+- **Custom automation tools** that can reuse existing browser sessions 

src/browser-installer/chrome/index.ts

@@ -7,13 +7,14 @@ import { getMilestone } from "../utils";
 import { installChrome, resolveLatestChromeVersion } from "./browser";
 import { installChromeDriver } from "./driver";
 import { isUbuntu, getUbuntuLinkerEnv } from "../ubuntu-packages";
+import RuntimeConfig from "../../config/runtime-config";
 
 export { installChrome, resolveLatestChromeVersion, installChromeDriver };
 
 export const runChromeDriver = async (
     chromeVersion: string,
     { debug = false } = {},
-): Promise<{ gridUrl: string; process: ChildProcess; port: number }> => {
+): Promise<{ gridUrl: string; process: ChildProcess; port: number; kill: () => void }> => {
     const [chromeDriverPath, randomPort, chromeDriverEnv] = await Promise.all([
         installChromeDriver(chromeVersion),
         getPort(),
@@ -22,9 +23,12 @@ export const runChromeDriver = async (
             .then(extraEnv => (extraEnv ? { ...process.env, ...extraEnv } : process.env)),
     ]);
 
+    const runtimeConfig = RuntimeConfig.getInstance();
+    const keepBrowserModeEnabled = runtimeConfig.keepBrowserMode?.enabled;
+
     const chromeDriver = spawn(chromeDriverPath, [`--port=${randomPort}`, debug ? `--verbose` : "--silent"], {
         windowsHide: true,
-        detached: false,
+        detached: keepBrowserModeEnabled || false,
         env: chromeDriverEnv,
     });
 
@@ -34,7 +38,9 @@ export const runChromeDriver = async (
 
     const gridUrl = `http://127.0.0.1:${randomPort}`;
 
-    process.once("exit", () => chromeDriver.kill());
+    if (!keepBrowserModeEnabled) {
+        process.once("exit", () => chromeDriver.kill());
+    }
 
     await waitPort({
         port: randomPort,
@@ -43,5 +49,10 @@ export const runChromeDriver = async (
         interval: DRIVER_WAIT_INTERVAL,
     });
 
-    return { gridUrl, process: chromeDriver, port: randomPort };
+    return {
+        gridUrl,
+        process: chromeDriver,
+        port: randomPort,
+        kill: () => chromeDriver.kill(),
+    };
 };

src/browser-installer/edge/index.ts

@@ -4,19 +4,23 @@ import getPort from "get-port";
 import waitPort from "wait-port";
 import { pipeLogsWithPrefix } from "../../dev-server/utils";
 import { DRIVER_WAIT_INTERVAL, DRIVER_WAIT_TIMEOUT } from "../constants";
+import RuntimeConfig from "../../config/runtime-config";
 
 export { resolveEdgeVersion } from "./browser";
 export { installEdgeDriver };
 
 export const runEdgeDriver = async (
     edgeVersion: string,
     { debug = false }: { debug?: boolean } = {},
-): Promise<{ gridUrl: string; process: ChildProcess; port: number }> => {
+): Promise<{ gridUrl: string; process: ChildProcess; port: number; kill: () => void }> => {
     const [edgeDriverPath, randomPort] = await Promise.all([installEdgeDriver(edgeVersion), getPort()]);
 
+    const runtimeConfig = RuntimeConfig.getInstance();
+    const keepBrowserModeEnabled = runtimeConfig.keepBrowserMode?.enabled;
+
     const edgeDriver = spawn(edgeDriverPath, [`--port=${randomPort}`, debug ? `--verbose` : "--silent"], {
         windowsHide: true,
-        detached: false,
+        detached: keepBrowserModeEnabled || false,
     });
 
     if (debug) {
@@ -25,7 +29,9 @@ export const runEdgeDriver = async (
 
     const gridUrl = `http://127.0.0.1:${randomPort}`;
 
-    process.once("exit", () => edgeDriver.kill());
+    if (!keepBrowserModeEnabled) {
+        process.once("exit", () => edgeDriver.kill());
+    }
 
     await waitPort({
         port: randomPort,
@@ -34,5 +40,5 @@ export const runEdgeDriver = async (
         interval: DRIVER_WAIT_INTERVAL,
     });
 
-    return { gridUrl, process: edgeDriver, port: randomPort };
+    return { gridUrl, process: edgeDriver, port: randomPort, kill: () => edgeDriver.kill() };
 };

src/browser-installer/firefox/index.ts

@@ -7,13 +7,14 @@ import { installLatestGeckoDriver } from "./driver";
 import { pipeLogsWithPrefix } from "../../dev-server/utils";
 import { DRIVER_WAIT_INTERVAL, DRIVER_WAIT_TIMEOUT } from "../constants";
 import { getUbuntuLinkerEnv, isUbuntu } from "../ubuntu-packages";
+import RuntimeConfig from "../../config/runtime-config";
 
 export { installFirefox, resolveLatestFirefoxVersion, installLatestGeckoDriver };
 
 export const runGeckoDriver = async (
     firefoxVersion: string,
     { debug = false } = {},
-): Promise<{ gridUrl: string; process: ChildProcess; port: number }> => {
+): Promise<{ gridUrl: string; process: ChildProcess; port: number; kill: () => void }> => {
     const [geckoDriverPath, randomPort, geckoDriverEnv] = await Promise.all([
         installLatestGeckoDriver(firefoxVersion),
         getPort(),
@@ -22,13 +23,16 @@ export const runGeckoDriver = async (
             .then(extraEnv => (extraEnv ? { ...process.env, ...extraEnv } : process.env)),
     ]);
 
+    const runtimeConfig = RuntimeConfig.getInstance();
+    const keepBrowserModeEnabled = runtimeConfig.keepBrowserMode?.enabled;
+
     const geckoDriver = await startGeckoDriver({
         customGeckoDriverPath: geckoDriverPath,
         port: randomPort,
         log: debug ? "debug" : "fatal",
         spawnOpts: {
             windowsHide: true,
-            detached: false,
+            detached: keepBrowserModeEnabled || false,
             env: geckoDriverEnv,
         },
     });
@@ -39,7 +43,9 @@ export const runGeckoDriver = async (
 
     const gridUrl = `http://127.0.0.1:${randomPort}`;
 
-    process.once("exit", () => geckoDriver.kill());
+    if (!keepBrowserModeEnabled) {
+        process.once("exit", () => geckoDriver.kill());
+    }
 
     await waitPort({
         port: randomPort,
@@ -48,5 +54,5 @@ export const runGeckoDriver = async (
         interval: DRIVER_WAIT_INTERVAL,
     });
 
-    return { gridUrl, process: geckoDriver, port: randomPort };
+    return { gridUrl, process: geckoDriver, port: randomPort, kill: () => geckoDriver.kill() };
 };

src/browser-installer/safari/index.ts

@@ -3,19 +3,24 @@ import getPort from "get-port";
 import waitPort from "wait-port";
 import { pipeLogsWithPrefix } from "../../dev-server/utils";
 import { DRIVER_WAIT_INTERVAL, DRIVER_WAIT_TIMEOUT, SAFARIDRIVER_PATH } from "../constants";
+import RuntimeConfig from "../../config/runtime-config";
 
 export { resolveSafariVersion } from "./browser";
 
 export const runSafariDriver = async ({ debug = false }: { debug?: boolean } = {}): Promise<{
     gridUrl: string;
     process: ChildProcess;
     port: number;
+    kill: () => void;
 }> => {
     const randomPort = await getPort();
 
+    const runtimeConfig = RuntimeConfig.getInstance();
+    const keepBrowserModeEnabled = runtimeConfig.keepBrowserMode?.enabled;
+
     const safariDriver = spawn(SAFARIDRIVER_PATH, [`--port=${randomPort}`], {
         windowsHide: true,
-        detached: false,
+        detached: keepBrowserModeEnabled || false,
     });
 
     if (debug) {
@@ -24,7 +29,9 @@ export const runSafariDriver = async ({ debug = false }: { debug?: boolean } = {
 
     const gridUrl = `http://127.0.0.1:${randomPort}`;
 
-    process.once("exit", () => safariDriver.kill());
+    if (!keepBrowserModeEnabled) {
+        process.once("exit", () => safariDriver.kill());
+    }
 
     await waitPort({
         port: randomPort,
@@ -33,5 +40,5 @@ export const runSafariDriver = async ({ debug = false }: { debug?: boolean } = {
         interval: DRIVER_WAIT_INTERVAL,
     });
 
-    return { gridUrl, process: safariDriver, port: randomPort };
+    return { gridUrl, process: safariDriver, port: randomPort, kill: () => safariDriver.kill() };
 };

src/browser-pool/webdriver-pool.ts

@@ -5,7 +5,7 @@ import type { SupportedBrowser } from "../browser-installer";
 type BrowserVersion = string;
 type Port = string;
 type ChildProcessWithStatus = { process: ChildProcess; gridUrl: string; isBusy: boolean };
-export type WdProcess = { gridUrl: string; free: () => void; kill: () => void };
+export type WdProcess = { gridUrl: string; free: () => void; kill: () => void; getPid: () => number | undefined };
 
 export class WebdriverPool {
     private driverProcess: Map<SupportedBrowser, Map<BrowserVersion, Record<Port, ChildProcessWithStatus>>>;
@@ -45,6 +45,7 @@ export class WebdriverPool {
                     gridUrl: wdProcesses[port].gridUrl,
                     free: () => this.freeWebdriver(port),
                     kill: () => this.killWebdriver(browserNameNormalized, browserVersionNormalized, port),
+                    getPid: () => wdProcesses[port].process.pid,
                 };
             }
         }
@@ -98,6 +99,7 @@ export class WebdriverPool {
             gridUrl: driver.gridUrl,
             free: () => this.freeWebdriver(String(driver.port)),
             kill: () => this.killWebdriver(browserName, browserVersion, String(driver.port)),
+            getPid: () => driver.process.pid,
         };
     }
 }

src/browser/browser.ts

@@ -39,6 +39,7 @@ export type BrowserState = {
     testXReqId?: string;
     traceparent?: string;
     isBroken?: boolean;
+    isLastTestFailed?: boolean;
 };
 
 export type CustomCommand = { name: string; elementScope: boolean };
@@ -76,6 +77,7 @@ export class Browser {
         this._state = {
             ...opts.state,
             isBroken: false,
+            isLastTestFailed: false,
         };
         this._customCommands = new Set();
         this._wdPool = opts.wdPool;

src/browser/existing-browser.ts

@@ -16,17 +16,11 @@ import { Config } from "../config";
 import { Image, Rect } from "../image";
 import type { CalibrationResult, Calibrator } from "./calibrator";
 import { NEW_ISSUE_LINK } from "../constants/help";
-import type { Options } from "@testplane/wdio-types";
 import { runWithoutHistory } from "./history";
+import type { SessionOptions } from "./types";
 
 const OPTIONAL_SESSION_OPTS = ["transformRequest", "transformResponse"];
 
-interface SessionOptions {
-    sessionId: string;
-    sessionCaps?: WebdriverIO.Capabilities;
-    sessionOpts?: Options.WebdriverIO & { capabilities: WebdriverIO.Capabilities };
-}
-
 interface PrepareScreenshotOpts {
     disableAnimation?: boolean;
     // TODO: specify the rest of the options

src/browser/new-browser.ts

@@ -103,6 +103,14 @@ export class NewBrowser extends Browser {
         }
     }
 
+    getDriverPid(): number | undefined {
+        if (this._wdProcess) {
+            return this._wdProcess.getPid();
+        }
+
+        return undefined;
+    }
+
     protected async _createSession(): Promise<WebdriverIO.Browser> {
         const sessionOpts = await this._getSessionOpts();
 

src/browser/standalone/attachToBrowser.ts

@@ -0,0 +1,60 @@
+import { Config } from "../../config";
+import { ExistingBrowser } from "./../existing-browser";
+import { Calibrator } from "./../calibrator";
+import { AsyncEmitter } from "../../events";
+import { BrowserName, type W3CBrowserName, type SessionOptions } from "./../types";
+import { getNormalizedBrowserName } from "../../utils/browser";
+
+export async function attachToBrowser(session: SessionOptions): Promise<WebdriverIO.Browser> {
+    const browserName = session.sessionCaps?.browserName || BrowserName.CHROME;
+    const normalizedBrowserName = getNormalizedBrowserName(browserName) as W3CBrowserName;
+
+    if (!normalizedBrowserName) {
+        throw new Error(
+            [
+                `Running browser "${browserName}" is unsupported`,
+                `Supported browsers: "chrome", "firefox", "safari", "edge"`,
+            ].join("\n"),
+        );
+    }
+
+    const browserConfig = {
+        desiredCapabilities: {
+            browserName,
+        },
+    };
+
+    const config = new Config({
+        browsers: {
+            [browserName]: browserConfig,
+        },
+    });
+
+    if (!process.env.WDIO_LOG_LEVEL) {
+        process.env.WDIO_LOG_LEVEL = config.system.debug ? "trace" : "error";
+    }
+
+    const emitter = new AsyncEmitter();
+
+    const existingBrowser = new ExistingBrowser(config, {
+        id: browserName,
+        version: session.sessionCaps?.browserVersion,
+        emitter,
+        state: {},
+    });
+
+    const calibrator = new Calibrator();
+
+    await existingBrowser.init(session, calibrator);
+
+    existingBrowser.publicAPI.overwriteCommand("deleteSession", async originalCommand => {
+        await originalCommand({ shutdownDriver: true });
+
+        // force kill driver process by pid, because { shutdownDriver: true } in prev command doesn't work :(
+        if (session.driverPid) {
+            process.kill(session.driverPid, 9);
+        }
+    });
+
+    return existingBrowser.publicAPI;
+}