Implementation:Webdriverio Webdriverio DeleteSession Command

Overview

The deleteSession() method is the concrete tool provided by the WebdriverIO library for terminating a WebDriver browser session. It sends a DELETE request to the WebDriver endpoint and handles all associated cleanup including WebSocket connections, driver processes, and logging.

Description

The deleteSession() method sends a DELETE request to the WebDriver endpoint to terminate the current session. It performs a comprehensive cleanup sequence:

1. Sends the protocol command: Issues DELETE /session/{sessionId} to the WebDriver server.
2. Closes the BiDi WebSocket: If a WebDriver BiDi connection was established, the _bidiHandler is closed, terminating the WebSocket.
3. Kills the driver process: Optionally shuts down the underlying WebDriver server process (chromedriver, geckodriver, etc.) based on the shutdownDriver parameter. The driver PID is tracked via the wdio:driverPID capability.
4. Clears logger streams: Flushes and closes log handlers associated with the session (only in non-worker mode).
5. Aborts pending requests: Any in-flight protocol commands for this session are aborted via the session abort listener mechanism, preventing them from timing out.

The command is generated via the protocol command factory in packages/webdriver/src/command.ts, which wraps the W3C WebDriver protocol definition with parameter validation, logging, and event emission.

Source Location

Property	Value
Repository	https://github.com/webdriverio/webdriverio
Protocol Command Generator	packages/webdriver/src/command.ts, L17-219
Session Cleanup Logic	packages/webdriver/src/command.ts, L190-209
WebDriver Class	packages/webdriver/src/index.ts, L19-100

Signature

browser.deleteSession(
    params?: {
        shutdownDriver?: boolean
    }
): Promise<void>

Import

// Available as a method on the browser instance returned by remote()
import { remote } from 'webdriverio'

const browser = await remote({ capabilities: { browserName: 'chrome' } })
// ... use browser ...
await browser.deleteSession()

Inputs

Parameter	Type	Required	Description
params	object	No	Optional configuration object for session deletion.
params.shutdownDriver	boolean	No	Whether to also shut down the driver server process (e.g., chromedriver, geckodriver). Defaults to true. Set to false when you want to keep the driver running for session reuse or when managed externally.

Implicit inputs:

• An active browser session with a valid sessionId.
• The browser instance must have been created via remote() or the testrunner.

Outputs

Return Type	Description
Promise<void>	Resolves when the session has been terminated and all resources freed. The browser process is closed, the session ID is invalidated, and the driver process is optionally shut down.

Side effects:

• The browser window/tab is closed.
• The session ID becomes invalid -- any further commands will throw "invalid session id" errors.
• The WebDriver BiDi WebSocket connection (if any) is closed.
• The driver process (if managed by WebdriverIO) is terminated.
• Pending protocol commands for this session are aborted.
• Logger streams are cleared.

Usage Example

import { remote } from 'webdriverio'

const browser = await remote({
    capabilities: { browserName: 'chrome' }
})

try {
    await browser.url('https://webdriver.io')
    const title = await browser.getTitle()
    console.log('Title:', title)
} catch (err) {
    console.error('Test failed:', err.message)
} finally {
    // Always clean up the session, even on error
    await browser.deleteSession()
}

With driver shutdown control:

// Keep the driver process running (useful for session reuse)
await browser.deleteSession({ shutdownDriver: false })

// Shut down everything (default behavior)
await browser.deleteSession({ shutdownDriver: true })

Internal Flow

The internal execution flow when deleteSession() is called:

1. The protocol command factory (command.ts) constructs the DELETE /session/{sessionId} request.
2. An abort signal is created for the request, linked to the session abort listener.
3. The command is logged: COMMAND deleteSession().
4. The HTTP DELETE request is sent to the WebDriver server.
5. Upon successful response:
   • The BiDi handler (_bidiHandler) is closed if present.
   • killDriverProcess() is called with the capabilities and the shutdownDriver flag.
   • logger.clearLogger() is called in non-worker mode.
   • The session abort listeners for this session ID are triggered, aborting any in-flight requests.
6. The result event is emitted: { command: 'deleteSession', ... }.
7. The promise resolves.

Related Pages

• implements Principle:Webdriverio_Webdriverio_Session_Cleanup - The Session Cleanup principle that this command implements.
• Environment:Webdriverio_Webdriverio_Browser_Driver_Environment