| name | gathering-context |
| description | Use when investigating a failing WebdriverIO test and you need to understand what the test was doing and where it broke. |
Context Gatherer
Reads all available artifacts for a failing WebdriverIO test and returns a structured markdown summary. Called by the Investigator agent — does not diagnose or fix, only gathers and organizes evidence.
Inputs
The Investigator passes a structured failure object:
- testName: string # The it() / describe() title
- specFile: string # Relative path to the spec file
- errorMessage: string # The assertion or exception message
- stackTrace: string # Full stack trace
- logFile?: string # Optional: path to wdio log file
- snapshotDir?: string # Optional: dir where HTML/screenshots/video are saved
Project Context Files
Before scanning from scratch, read project cache files when available:
.webdriverio-skills/project-context.md.webdriverio-skills/project-context.json.webdriverio-skills/custom-rules.mdreferences/website-analysis/<target>/website-analysis.mdreferences/website-analysis/<target>/website-analysis.json
Use cached reporter, service, artifact, and environment details to narrow discovery work.
If files are missing or stale, run managing-project-customizations first.
Target Resolution Rule
When reading references/website-analysis/<target>/..., resolve <target> as:
- lowercase site host from the test URL/baseUrl (e.g.
demo.learnwebdriverio.com)
- if host is unknown, use
unknown-target and continue without blocking
Workflow
Step 1 — Locate Artifacts
Use cached context first, then read wdio.conf.js (or discovered WDIO config files) to resolve:
- Reporters — which are configured (e.g.
allure, junit, spec) and their output directories. Note artifact paths; do not parse report formats.
- Log paths — where WDIO writes its log output.
- Snapshot directories — where screenshots and HTML snapshots are saved on failure (often configured in
afterTest hook via browser.saveScreenshot() and browser.savePDF() / page source capture).
- Video — if a video service (e.g.
wdio-video-reporter) is configured, note the output path.
- Services — list all configured services. Flag any in these categories as a potential failure dimension for the Investigator:
| Service type | Why it matters |
|---|
Visual regression (e.g. wdio-image-comparison-service) | Failure may be a visual diff, not a selector or logic issue |
| Mobile / Appium | Element interaction differs from browser; gestures, native contexts |
| Cloud providers (BrowserStack, Sauce, LambdaTest) | Session timeouts, capability mismatches, remote-specific failures |
selenium-standalone / chromedriver | Driver version mismatch can cause unexpected command failures |
If snapshotDir or logFile were provided in the failure object, use those directly and skip discovery for those paths.
Step 2 — Read the Spec File
Open specFile and:
- Extract the full body of the
it() block matching testName
- Identify all enclosing
describe() blocks (tests can be nested — outer describe hooks apply)
- Identify all Mocha hooks in scope:
before, beforeEach, after, afterEach at every nesting level — these run around the failing test and may be relevant
- Note all
import / require statements — these reveal page object dependencies to traverse in Step 3
If website analysis references exist, use them to quickly map the failing test to:
- likely section/component ownership
- expected critical states for the area
- known auth-gated routes or dependencies
Mocha structure to understand:
describe() blocks scope hooks and can be nested arbitrarily deepbefore / after run once per describe blockbeforeEach / afterEach run around every it() in their scope- All hooks from all enclosing describe levels apply to any given
it()
Step 3 — Traverse Page Object Dependencies
Starting from the imports found in Step 2, recursively follow all import / require statements.
For each page object class found:
- Extract method names and their implementations
- Note every WebdriverIO command used (see Command Reference below)
- Extract every selector passed to
$() or $$() — these are CSS or XPath strings that map directly to DOM elements
Page Object pattern:
Page objects are JavaScript classes that encapsulate selectors and interactions. A method like async clickSubmit() wraps await this.submitBtn.click() where submitBtn is defined as get submitBtn() { return $('#submit-btn') }. Understanding this chain — method → command → selector → DOM element — is essential for correlating failures with HTML snapshots.
Continue recursing until all transitive imports are read. Cross-reference selectors from page objects with the HTML snapshots in Step 5.
Step 4 — Search for Custom Commands
Search the codebase for addCommand to find all custom command definitions.
For each custom command found:
- Note whether it's registered on
browser or element
- Read its full implementation
- If a custom command appears in the failing test or any page object method, treat it as a first-class suspect — read it completely
Custom commands do not appear as named entries in WDIO logs. You will see only the underlying native commands they delegate to. To understand what a custom command was doing at failure time, cross-reference the native command sequence in the logs with the custom command's implementation.
If a custom command calls another custom command, follow the chain completely.
Step 5 — Read Logs
Open the log file (from logFile input or discovered in Step 1).
Filter to lines associated with the failing test. WDIO logs include:
COMMAND <method> <endpoint> — a native browser command being sentDATA <payload> — the command's parametersRESULT <value> — the response from the driver
Match the log's command sequence against the WebdriverIO commands in the spec and page objects to reconstruct what actually executed at runtime. Look for the last successful command before the error appears.
Step 6 — Collect HTML Snapshots
If HTML snapshots exist in the snapshot directory:
- Load them in filename / timestamp order — earlier snapshots show DOM state before the failure
- For the failure-time snapshot: check whether selectors from page objects are present in the HTML, have the expected attributes, text, and state
- CSS selectors can be matched structurally against the HTML. XPath requires understanding document hierarchy.
- Note any elements that are absent, hidden (
display:none, visibility:hidden, aria-hidden), disabled, or have unexpected attribute values
Step 7 — Collect Visual Artifacts
Locate screenshots and video files associated with the test run. Do not attempt to analyze their content — record file paths and timestamps only. The Investigator decides whether to pass them to a vision-capable model.
Include in the summary:
- Screenshot file paths (in timestamp order)
- Video file path (if present)
Command Reference
Use this reference to understand what a failing test was executing. If a command is unfamiliar or you need full parameter details, look it up:
- Element commands:
https://webdriver.io/docs/api/element/<commandName>
- Browser commands:
https://webdriver.io/docs/api/browser/<commandName>
- Expect / assertions:
https://webdriver.io/docs/api/expect-webdriverio
- Full API index:
https://webdriver.io/docs/api
Element Commands
Called on an element object returned by $() or $$(). Operate on a specific DOM node. Failures here relate to that element's state, visibility, or interactability — look at the selector and the DOM snapshot.
| Command | What it does | Common failure modes |
|---|
$('selector') | Find first matching element | Element not in DOM, wrong selector, not yet rendered |
$$('selector') | Find all matching elements | Returns empty array if none match |
click() | Click the element | Element obscured, not interactable, wrong element matched |
setValue(val) | Clear and type into input | Element not an input, not focused, readonly |
addValue(val) | Append to input value | Same as setValue |
getText() | Get visible text content | Element not rendered, text in shadow DOM |
getValue() | Get input value | Element not an input type |
getAttribute(name) | Get DOM attribute | Attribute doesn't exist → returns null |
getCSSProperty(prop) | Get computed CSS value | Useful for checking visibility, color, dimensions |
isDisplayed() | Is element visible? | Returns false if hidden via CSS |
isExisting() | Is element in DOM? | Returns false if not yet rendered |
isClickable() | Is element clickable? | Checks displayed + enabled + in viewport |
isEnabled() | Is form element enabled? | Returns false for disabled inputs/buttons |
isSelected() | Is checkbox/radio selected? | Only for checkboxes and radio buttons |
waitForDisplayed(opts) | Wait until visible | Timeout if element never becomes visible |
waitForExist(opts) | Wait until in DOM | Timeout if element never appears |
waitForClickable(opts) | Wait until clickable | Timeout if never interactable |
selectByVisibleText(text) | Select <option> by label | Text mismatch, not a <select> element |
selectByAttribute(attr, val) | Select <option> by attribute | Attribute value mismatch |
scrollIntoView() | Scroll element into viewport | Needed before click on off-screen elements |
moveTo() | Hover over element | Used for hover-triggered UI |
Browser Commands
Called on the global browser object. Operate at the session or page level. Failures here relate to navigation, page state, or browser context — not element-level issues.
| Command | What it does | Common failure modes |
|---|
browser.url(path) | Navigate to URL or path | Wrong base URL, page load failure |
browser.getUrl() | Get current URL | Useful for asserting navigation succeeded |
browser.getTitle() | Get page title | Page not loaded, wrong page |
browser.refresh() | Reload current page | — |
browser.back() / forward() | Browser history navigation | — |
browser.waitUntil(fn, opts) | Wait for arbitrary condition | Timeout if condition never true; check fn logic |
browser.execute(fn) | Run JS in browser context | JS error in fn, wrong return type |
browser.executeAsync(fn) | Run async JS in browser | Callback never called → timeout |
browser.pause(ms) | Hard wait (avoid if possible) | Masks timing issues rather than fixing them |
browser.keys(keys) | Send keyboard input | Focus not on expected element |
browser.switchToFrame(id) | Switch context to iframe | Wrong frame ID, frame not loaded |
browser.switchToParentFrame() | Return to main frame | Already in main frame |
browser.newWindow(url) | Open new window/tab | — |
browser.switchWindow(handle) | Switch to window by handle/title | Wrong handle, window closed |
browser.acceptAlert() | Accept a browser dialog | No dialog present |
browser.dismissAlert() | Dismiss a browser dialog | No dialog present |
browser.getAlertText() | Get dialog message text | No dialog present |
browser.setCookies(cookies) | Set browser cookies | Wrong domain, malformed cookie |
browser.getCookies() | Get all cookies | — |
browser.deleteCookies() | Delete cookies | — |
browser.saveScreenshot(path) | Save screenshot to file | — |
browser.getPageSource() | Get full page HTML | Useful for snapshot comparison |
Expect / Assertions
Assertions use expect-webdriverio. A failing assertion means the element or browser was in the wrong state at that moment.
| Assertion | What it checks |
|---|
expect(el).toBeDisplayed() | Element is visible |
expect(el).toExist() | Element is in DOM |
expect(el).toBeClickable() | Element is interactable |
expect(el).toBeEnabled() | Form element is not disabled |
expect(el).toBeSelected() | Checkbox/radio is checked |
expect(el).toHaveText(str) | Element text matches |
expect(el).toHaveValue(str) | Input value matches |
expect(el).toHaveAttribute(attr, val) | Attribute has expected value |
expect(el).toHaveClass(name) | Element has CSS class |
expect(el).toHaveURL(str) | Current URL matches (on browser) |
expect(el).toHaveTitle(str) | Page title matches (on browser) |
expect(arr).toHaveLength(n) | Array/collection length |
When an assertion fails, the error message includes the actual vs. expected value. Cross-reference the actual value with the HTML snapshot and logs to understand why the state was wrong.
Output
Return a structured markdown summary to the Investigator:
## Context: <testName>
### Test Flow
Step-by-step reconstruction of what the test was doing,
derived from the spec file, hooks in scope, and page object methods.
### Last Known Good State
What the test had successfully completed just before the failure,
based on log command sequence and intermediate HTML snapshots (if present).
### Point of Failure
- **Error:** <errorMessage>
- **Stack trace:** excerpt pointing to the exact file and line
- **Command:** the WebdriverIO command that failed or produced wrong state
- **Selector involved:** the CSS/XPath selector (if applicable)
- **Page object method:** which method contained the failing command
### DOM State at Failure
Key observations from the HTML snapshot at failure time:
- Was the selector present? Hidden? Disabled?
- Were expected elements missing or in unexpected state?
- Any relevant attribute values or form state?
### Visual Artifacts
- Screenshots: [list of file paths with timestamps, in order]
- Video: [file path if present, otherwise "none"]
- HTML snapshots: [list of file paths in sequence, oldest first]
### Active Services
[List configured services and flag any that may be relevant to the failure]
### Custom Commands Involved
[List any custom commands called in the test flow, with their source location]
### Hypothesis
One or two sentences: the most likely cause of the failure based on the
evidence gathered. Do not speculate beyond what the artifacts support.
