Principle:Webdriverio Webdriverio WebDriver Error Handling

Overview

WebDriver Error Handling is a strategy for catching, classifying, and recovering from errors encountered during browser automation. Proper error handling is critical for writing robust, non-flaky tests. The W3C WebDriver specification defines a standardized set of error codes that all implementations must follow.

Description

WebDriver Error Handling deals with managing the various error conditions that arise during automated browser interaction. These errors can originate from multiple sources:

• Protocol errors: The WebDriver server returns an error response (e.g., element not found, session expired).
• Network errors: The connection to the WebDriver server fails (e.g., timeout, connection refused).
• Script errors: JavaScript executed in the browser throws an exception.
• Timing errors: An element is not yet available or has become stale between commands.

Common error categories include:

Error Code	Description	Typical Cause
no such element	The element could not be found on the page.	The selector does not match any DOM node, or the page has not finished loading.
stale element reference	The element reference is no longer valid.	The DOM was modified (e.g., by a navigation or dynamic update) after the element was located.
element not interactable	The element exists but cannot be interacted with.	The element is hidden, disabled, or covered by another element.
timeout	An operation did not complete within the allotted time.	Page load, script execution, or implicit wait exceeded the configured timeout.
invalid session id	The session ID is not recognized.	The session was deleted or never created, or a network interruption occurred.
javascript error	JavaScript execution in the browser raised an exception.	The script passed to execute() or executeAsync() threw an error.
no such window	The target window or tab no longer exists.	The window was closed by user action or another automation command.
invalid selector	The provided selector is syntactically invalid.	Malformed CSS selector or XPath expression.

Proper error handling is critical for writing robust, non-flaky tests. It involves:

• Try/catch/finally blocks: Wrapping automation code to catch and handle errors gracefully.
• Wait strategies: Using implicit or explicit waits to handle timing-dependent element availability.
• Retry mechanisms: Automatically retrying failed commands for transient errors.
• Error classification: Distinguishing between recoverable errors (e.g., stale element) and fatal errors (e.g., invalid session).
• Diagnostic capture: Taking screenshots and logging on failure for debugging.

Usage

Use error handling in every standalone script (via try/catch/finally) and in test hooks for retries and diagnostics. Especially important when dealing with dynamic web pages where element availability is timing-dependent.

When to use:

• In every standalone automation script -- always wrap in try/catch/finally.
• When interacting with dynamic or asynchronously-loaded content.
• When writing retry logic for flaky selectors.
• In test framework hooks (afterEach, onError) for diagnostic capture.
• When dealing with multiple browser windows or tabs that may close unexpectedly.

Error handling patterns:

• Defensive waiting: Use waitUntil(), waitForExist(), waitForDisplayed() before interacting with elements.
• Catch-and-retry: Catch stale element errors and re-fetch the element before retrying the action.
• Graceful degradation: Catch non-critical errors and continue with reduced functionality.
• Always-cleanup: Use finally blocks to ensure deleteSession() is called regardless of test outcome.

Theoretical Basis

The W3C WebDriver specification defines error responses with a standard JSON body containing three fields:

• error (string): A predefined error code string (e.g., "no such element", "stale element reference").
• message (string): A human-readable description of what went wrong.
• stacktrace (string): An implementation-defined stack trace for the error.

The HTTP response status codes map to error categories:

HTTP Status	Error Codes
400 Bad Request	invalid argument, invalid selector, no such alert
404 Not Found	no such element, no such window, no such frame, invalid session id
500 Internal Server Error	javascript error, stale element reference, element not interactable, timeout

Robust automation wraps commands in try/catch, uses waits (implicit/explicit) to handle timing, and implements retry strategies for transient failures. The specification is defined in W3C WebDriver: Errors.

Related Pages

Implementation:Webdriverio_Webdriverio_Error_Handling_Pattern

• implemented_by Implementation:Webdriverio_Webdriverio_Error_Handling_Pattern - The error handling classes and patterns that concretely implement WebDriver error handling in WebdriverIO.
• Heuristic:Webdriverio_Webdriverio_Stale_Element_Auto_Refetch
• Heuristic:Webdriverio_Webdriverio_Exponential_Backoff_Retry