API reference
Every symbol re-exported from src/index.ts, grouped by the feature area most users look for first. Generated by scripts/gen-api-reference.mjs — do not edit by hand.
Run npm run docs:api to regenerate. CI fails when this file is out of date.
Start with Browser, By / Locator, and the feature guide that matches the job you are automating.
Browser And Pages
Launch browsers, move between pages and frames, handle dialogs, and wait for navigation.
| Symbol | Kind | Summary | Docs |
|---|---|---|---|
Browser | class | — | browser-api |
LaunchOptions | type | Mutually-exclusive browser, Electron, and remote-WebDriver launch configurations. | browser-api |
LoadState | type | When to consider a navigation complete. - 'load' — page load event has fired (default) - 'domcontentloaded' — DOMContentLoaded has fired (faster, no waiting for images/fonts) - 'networkidle' — load + no in-flight requests for 500 ms - 'none' — do not wait; return as soon as the navigation is initiated | browser-api |
Page | class | — | browser-api |
Frame | class | — | browser-api |
Dialog | type | Represents an open browser dialog (alert / confirm / prompt). Passed to handlers registered with browser.onDialog(). | browser-api |
DialogType | type | The type of a browser dialog. | browser-api |
Download | type | A file downloaded during a waitForDownload() call. | browser-api |
Locators And Elements
Find page content with semantic locators and selector helpers.
| Symbol | Kind | Summary | Docs |
|---|---|---|---|
By | class | — | selectors |
Locator | class | — | selectors |
ShadowRootLocator | class | Lazy, explicit search context for one open ShadowRoot. | selectors |
Assertions
Auto-wait for page, locator, and element conditions.
| Symbol | Kind | Summary | Docs |
|---|---|---|---|
AssertionOptions | type | Per-assertion timeout override. | assertions |
DocumentExpectApi | type | Auto-waiting assertions for the current browser page or an explicit Page. | assertions |
ElementExpectApi | type | Auto-waiting assertions for a single resolved element. | assertions |
LocatorExpectApi | type | Auto-waiting assertions for a locator collection and its first element. | assertions |
Input
Drive keyboard, mouse, and low-level key values.
| Symbol | Kind | Summary | Docs |
|---|---|---|---|
Key | const | — | keyboard-mouse |
Keyboard | class | — | keyboard-mouse |
Mouse | class | — | keyboard-mouse |
Contexts And Sessions
Isolate users, manage cookies, and save or restore browser state.
| Symbol | Kind | Summary | Docs |
|---|---|---|---|
BrowserContext | class | — | browser-context |
BrowserContextConfig | type | Per-context options stored at creation time. | browser-context |
BrowserContextHooks | type | Internal hooks the owning {@link Browser } passes to a new context. | browser-context |
ClearCookiesFilter | type | Filter applied to {@link BrowserContext.clearCookies}. | browser-context |
ContextStorageStateOptions | type | Options for {@link BrowserContext.storageState}. | browser-context |
InitScriptHandle | type | A handle returned by {@link BrowserContext.addInitScript}. | browser-context |
RoutePattern | type | Pattern accepted by {@link BrowserContext.route}. Same shape as the browser-level interceptor. | browser-context |
Cookie | type | — | session-management |
CookieInput | type | — | session-management |
SessionState | type | — | session-management |
SessionStateManager | class | — | session-management |
StorageStateOptions | type | — | session-management |
Network
Mock, intercept, observe, and assert browser network traffic.
| Symbol | Kind | Summary | Docs |
|---|---|---|---|
NetworkInterceptor | class | — | network |
MockResponse | type | — | network |
InterceptedRequest | type | — | network |
InterceptedResponse | type | — | network |
Logs And Tracing
Capture console output, JavaScript errors, and trace artifacts.
| Symbol | Kind | Summary | Docs |
|---|---|---|---|
LogMonitor | class | — | browser-logs |
ConsoleMessage | type | — | browser-logs |
JavaScriptError | type | — | browser-logs |
LogMessage | type | — | browser-logs |
TraceStartOptions | type | — | tracing |
TraceStopOptions | type | — | tracing |
TraceScreenshotMode | type | Screenshot mode for tracing. | tracing |
TraceEvent | type | — | tracing |
Emulation And Time
Configure devices, emulation overrides, and deterministic browser time.
| Symbol | Kind | Summary | Docs |
|---|---|---|---|
devices | const | Common mobile device presets | browser-api |
DeviceMetrics | type | Device metrics for custom mobile emulation | browser-api |
DeviceName | type | — | browser-api |
MobileEmulation | type | Mobile emulation configuration | browser-api |
EmulateOptions | type | Options for {@link Browser.emulate}. Every field is independent; only the keys you pass are applied, others stay at their previous value. Passing null for a field clears the override for that field. | browser-api |
Clock | class | Controls the virtual clock inside the browser page. | clock |
ClockInstallOptions | type | Options for {@link Clock.install}. | clock |
ClockTime | type | Accepted forms for a point in time. | clock |
Electron Automation
Launch packaged Electron applications, drive their renderer, and opt in to main-process testing.
| Symbol | Kind | Summary | Docs |
|---|---|---|---|
ElectronLaunchOptions | type | Options for driving an Electron application (see LaunchOptions.electron). | electron |
ElectronService | class | Driver service for automating an Electron application renderer. It uses the chromedriver protocol like ChromeService, but resolves the driver only from Electron-specific configuration, never from system Chrome. | electron |
ElectronServiceOptions | type | Driver-process configuration for {@link ElectronService}. | electron |
ElectronRemote | class | Run code in the Electron main process via browser.electron.executeMain. Named executeMain (not WDIO's execute) so the process boundary is loud: browser.evaluate() is the renderer, executeMain() the main process. | electron |
MainProcessCallback | type | A function evaluated in the Electron main process; receives the electron module. | electron |
ElectronDialogMock | type | A native-dialog replacement returned by browser.electron.mockDialog(). | electron |
ElectronDialogMethod | type | — | electron |
ElectronDialogCall | type | One native-dialog invocation. options excludes the optional parent window. | electron |
ElectronDialogResult | type | — | electron |
ElectronOpenDialogResult | type | Scripted result for Electron's asynchronous dialog.showOpenDialog(). | electron |
ElectronSaveDialogResult | type | Scripted result for Electron's asynchronous dialog.showSaveDialog(). | electron |
ElectronMessageBoxResult | type | Scripted result for Electron's asynchronous dialog.showMessageBox(). | electron |
ElectronMainLogMonitor | class | Buffers and dispatches main-process log entries. Reachable via browser.electron.mainLogs; its public surface mirrors the renderer {@link LogMonitor } so console monitoring reads the same in both processes. | electron |
ElectronMainLog | type | — | electron |
ElectronMainLogHandler | type | — | electron |
ElectronMainLogLevel | type | Normalized level for a main-process log entry. | electron |
Visual Testing
Assert screenshots against baselines with pixel/percentage tolerances and optional anti-alias handling.
| Symbol | Kind | Summary | Docs |
|---|---|---|---|
compareScreenshots | function | Compare two compressed PNG buffers without disk access, browser capture, retries, or throwing on a normal mismatch. Applies the same byte/pixel input limits as the retrying assertion. | visual-testing |
VisualMismatchError | class | Thrown by browser.expectScreenshot() when no screenshot matched the baseline before the timeout. Carries the final actual and diff PNG buffers plus the comparison summary; code is VISUAL_MISMATCH. | visual-testing |
ScreenshotCompareOptions | type | Policies applied to a single buffer-to-buffer comparison. | visual-testing |
ExpectScreenshotOptions | type | Options for the retrying browser.expectScreenshot() assertion. | visual-testing |
VisualScreenshotOptions | type | Mutually exclusive capture scope forwarded to browser.screenshot(). fullPage and selector cannot be combined (enforced by the union here and re-checked at runtime for JavaScript callers). | visual-testing |
VisualComparisonResult | type | Result of one buffer-to-buffer comparison. | visual-testing |
ScreenshotMatchResult | type | Result of a successful browser.expectScreenshot() assertion. | visual-testing |
Accessibility
Run axe-core accessibility checks and inspect violation details.
| Symbol | Kind | Summary | Docs |
|---|---|---|---|
A11y | class | Ergonomic wrapper around axe-core. Obtain instances via the .a11y accessor on Browser, ElementHandle, or Locator — never construct directly. | accessibility |
A11yError | class | Thrown by A11y.check() when violations are found. | accessibility |
A11yImpact | type | Severity buckets reported by axe-core. | accessibility |
A11yOptions | type | — | accessibility |
A11yResult | type | — | accessibility |
A11yShadowSelector | type | axe-core selector path through one or more open shadow boundaries. | accessibility |
A11yTarget | type | A light-DOM selector or axe-core's nested selector path for Shadow DOM. | accessibility |
A11yViolation | type | — | accessibility |
A11yViolationNode | type | — | accessibility |
Errors And Driver Services
Handle stable CraftDriver errors or customize browser driver services.
| Symbol | Kind | Summary | Docs |
|---|---|---|---|
CraftdriverError | class | Base class for every error thrown from the public API. | error-codes |
CraftdriverErrorOptions | type | — | error-codes |
ErrorCode | const | Stable, machine-readable error codes for the public craftdriver API. | error-codes |
ErrorCodeName | type | — | error-codes |
ErrorCodeValue | type | — | error-codes |
ChromeService | class | — | getting-started |
ChromeServiceOptions | type | — | getting-started |
FirefoxService | class | — | getting-started |
FirefoxServiceOptions | type | — | getting-started |
SafariService | class | — | getting-started |
SafariServiceOptions | type | — | getting-started |
Other Exports
Exports that are public but not yet assigned to a feature group.
| Symbol | Kind | Summary | Docs |
|---|---|---|---|
ChromeDriverResolutionInfo | type | — | — |
ElectronMainConnectInfo | type | — | electron |
ElectronMock | type | A replacement for a single electron.<api>.<fn> main-process method, returned by browser.electron.mock(). Records every call, returns a scripted value, and restores the original method on restore() or browser.quit(). | — |
ElectronMockCall | type | One recorded invocation of a mocked Electron main-process method. | — |
ElectronRemoteOptions | type | Extra context ElectronRemote needs beyond the inspector endpoint. | electron |
inspectChromeDriverResolution | function | Resolve the exact ChromeDriver CraftDriver would launch and report both sides of the browser/driver pairing. Intended for benchmark manifests and startup diagnostics; ordinary launches use {@link resolveChromeDriver} and avoid the extra driver --version probe. | — |
PageMatcher | type | Selects a top-level page by url and/or title for {@link Browser.waitForPage}. A string matches as a substring; a RegExp is tested. When both fields are given, both must match. | browser-api |
RemoteAuth | type | — | — |
RemoteWebDriverOptions | type | Options for connecting to any W3C-compatible remote WebDriver endpoint — a self-hosted Selenium Grid, BrowserStack, or another cloud provider. Provider-specific detail (BrowserStack's bstack:options, etc.) is forwarded through capabilities without schema conversion. | — |
SessionStateCookie | type | — | — |
Total exports: 103.