Principle:Webdriverio Webdriverio Session Cleanup

Overview

Session Cleanup is a protocol operation for terminating a browser session and releasing associated resources. It is the counterpart to session creation and is essential for preventing resource leaks in automated testing environments.

Description

Session Cleanup terminates the active WebDriver session, closing the browser and freeing server-side resources. It is essential for preventing resource leaks in long-running test suites and CI environments. Failing to clean up sessions leads to several critical problems:

Zombie browser processes: Browser instances that continue running without any controlling automation client, consuming CPU and memory.
Exhausted connection pools: WebDriver servers (e.g., Selenium Grid) have finite session capacity. Leaked sessions prevent new tests from running.
Cloud billing overages: Cloud testing providers (BrowserStack, Sauce Labs) charge by session time. Unclosed sessions continue accruing costs.
Port exhaustion: Each browser session binds network ports. Unreleased sessions can exhaust available ports on the host machine.
File handle leaks: Browser processes hold file handles for logs, profiles, and temporary files that are not released until the process terminates.

Session cleanup involves more than just closing the browser window. It encompasses:

Closing the browser process: The browser application is terminated.
Releasing the WebDriver session: The server invalidates the session ID so it can no longer be used.
Shutting down the driver process: Optionally, the WebDriver server process (e.g., chromedriver, geckodriver) is also terminated.
Closing BiDi connections: If a WebDriver BiDi WebSocket connection was established, it is closed.
Clearing logger streams: Log handlers associated with the session are flushed and closed.

Usage

Use Session Cleanup at the end of every standalone script or test lifecycle. In testrunner mode, this is handled automatically by the framework. In standalone mode, always call cleanup in a finally block to ensure cleanup even on error.

When to use:

At the end of every standalone WebdriverIO script
In the finally block of a try/catch/finally wrapper
In afterEach or after hooks in test frameworks
When recovering from fatal errors that require session replacement

When not to use:

In testrunner mode where the framework manages the session lifecycle automatically
When you intend to reuse the session (use reloadSession() instead)

Best practice pattern:

const browser = await remote({ capabilities: { browserName: 'chrome' } })
try {
    // ... automation code ...
} finally {
    await browser.deleteSession()
}

Theoretical Basis

The W3C WebDriver specification defines DELETE /session/{id} as the cleanup command. The protocol behavior is defined as follows:

The client sends an HTTP DELETE request to /session/{sessionId}.
The remote end (WebDriver server) performs the following steps:
1. Closes the current top-level browsing context (the browser window/tab).
2. Terminates the WebDriver session, invalidating the session ID.
3. Releases all server-side resources associated with the session (memory, file handles, ports).
The server responds with a success status (HTTP 200) and an empty JSON body.
After deletion, the session ID is no longer valid. Any subsequent commands using this session ID will receive an "invalid session id" error response.

The protocol specification guarantees that:

Session deletion is idempotent -- deleting an already-deleted session returns an appropriate error but does not cause server failure.
All resources are released synchronously with the response -- by the time the client receives the response, the browser process should be terminated.
The session ID is permanently invalidated -- it cannot be reused or reattached after deletion.

The specification is defined in W3C WebDriver: Delete Session.

implemented_by Implementation:Webdriverio_Webdriverio_DeleteSession_Command - The deleteSession() method that concretely implements session cleanup in WebdriverIO.

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment