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.md
• references/website-analysis/<target>/website-analysis.md
• references/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:

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:

1. Extract the full body of the it() block matching testName
2. Identify all enclosing describe() blocks (tests can be nested — outer describe hooks apply)
3. Identify all Mocha hooks in scope: before, beforeEach, after, afterEach at every nesting level — these run around the failing test and may be relevant
4. 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 deep
• before / after run once per describe block
• beforeEach / 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 sent
• DATA <payload> — the command’s parameters
• RESULT <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:

1. Load them in filename / timestamp order — earlier snapshots show DOM state before the failure
2. For the failure-time snapshot: check whether selectors from page objects are present in the HTML, have the expected attributes, text, and state
3. CSS selectors can be matched structurally against the HTML. XPath requires understanding document hierarchy.
4. 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.

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.

Expect / Assertions

Assertions use expect-webdriverio. A failing assertion means the element or browser was in the wrong state at that moment.

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.