Principle:Webdriverio Webdriverio ESLint Rules
| Knowledge Sources | |
|---|---|
| Domains | Linting, Test_Quality |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
Enforcing best practices and catching common mistakes in browser automation test code through static analysis rules.
Description
Browser automation test code is prone to subtle bugs that pass linting with generic rules but cause flaky or incorrect test behavior. ESLint Rules for browser automation define domain-specific static analysis checks that catch these issues at development time, before tests are even executed. These rules target patterns unique to the automation domain: forgetting to await asynchronous assertions (which silently passes regardless of the actual result), leaving debug breakpoints in committed code (which halts CI/CD pipelines indefinitely), and leaving pause statements that block test execution. Each rule analyzes the abstract syntax tree (AST) of test source files to detect prohibited patterns and reports actionable error messages with fix suggestions.
Usage
This principle applies when teams author browser automation tests and want to prevent common mistakes from reaching CI/CD or production test suites. It is the right choice for enforcing team-wide coding standards in test code, catching async/await mistakes that are invisible at runtime until they cause false positives, and preventing debug artifacts from being committed. It integrates into standard development workflows through IDE plugins and pre-commit hooks.
Theoretical Basis
Each lint rule implements a visitor pattern over the AST, targeting specific node types and analyzing their context:
- Await-expect rule: Detects
expect()calls on browser commands that are not preceded byawait. Browser command assertions return promises; withoutawait, the assertion's promise is created but never awaited, so the test passes regardless of the actual value:
// AST visitor pseudocode
function visitCallExpression(node):
if node.callee.name == "expect":
parent = node.parent
if parent is ExpressionStatement:
// Check if the expression is awaited
if not isAwaited(parent):
report(node, "Expected 'await' before 'expect' on async matcher")
// Detects: expect(browser.getTitle()).toBe("Home")
// Suggests: await expect(browser.getTitle()).toBe("Home")
- No-debug rule: Detects calls to
browser.debug()which launches an interactive REPL that halts test execution. This is useful during development but must never be committed:
function visitCallExpression(node):
if isMemberCall(node, "browser", "debug"):
report(node, "Unexpected browser.debug() call - remove before committing")
- No-pause rule: Detects calls to
browser.pause()with no arguments or with excessively long durations, which indicate forgotten debugging pauses rather than intentional waits:
function visitCallExpression(node):
if isMemberCall(node, "browser", "pause"):
if node.arguments is empty:
report(node, "Unexpected browser.pause() without duration")
else if getDuration(node.arguments[0]) > threshold:
report(node, "Suspiciously long pause duration - use waitUntil instead")
The rules follow ESLint's rule metadata convention, providing machine-readable severity levels, fix functions for auto-correction where safe, and documentation URLs for detailed explanations of why each pattern is problematic.