Locator Doctor

Your Playwright locator failed. Here's why.

Locator Doctor automatically turns a Playwright failure in VS Code's integrated terminal into a concise, evidence-based debugging diagnosis.

Problem

Playwright errors contain useful details, but locator and timing failures are often difficult to interpret while debugging a test. Locator Doctor identifies the failure type, extracts its locator and source location when available, and separates what the error proves from plausible next things to check.

Features

• Automatically diagnoses a failed Playwright command from VS Code's integrated terminal
• Detects Playwright projects from a config file or @playwright/test
• Parses locator timeouts, missing locators, strict-mode failures, visibility/detachment, expectations, navigation, and network failures
• Extracts locators and a small, local source window around the reported line
• Shows a theme-aware, secure diagnosis panel with Copy Fix, Copy Diagnosis, and Analyze Again
• Includes an offline deterministic diagnosis provider; the provider boundary is ready for a configured AI provider

Example

Given:

locator.click: Timeout 5000ms exceeded.
waiting for getByRole('button', { name: 'Checkout' })

Locator Doctor reports that Playwright waited five seconds for that button and presents likely (not asserted) causes, such as an accessible-name change or an application state that has not rendered the button.

Installation

Install Locator Doctor from the VS Code Extensions view, then reload VS Code if prompted. No setup, API key, terminal command, or configuration is required.

Usage

1. Open a Playwright project in VS Code.
2. Run a Playwright test that fails in VS Code's integrated terminal.
3. Locator Doctor opens its diagnosis panel as soon as it recognizes the failure output.

Automatic terminal analysis requires VS Code terminal shell integration, which is enabled by default in supported shells such as zsh, bash, and PowerShell.

If needed, the Command Palette also includes Locator Doctor: Analyze Last Test Failure for a saved Playwright report or log.

AI and privacy

V0.1 runs its included local provider offline. No API key is included and no repository content is sent anywhere. The future AI-provider interface accepts only structured failure data, a small source window near the failure, detected prior actions, and lightweight project metadata. It is designed so an added provider can use this minimum context rather than the whole repository.

Architecture

failure artifact → parser → locator/source context analysis → provider → secure Webview panel

The parser, source-context reader, locator analyzer, diagnosis validation, and provider are independent TypeScript modules so automatic failure detection, trace analysis, and remote providers can be added without changing the UI workflow.

Roadmap

• V0.1 — Failure diagnosis
• V0.2 — Automatic failure detection
• V0.3 — DOM/accessibility-tree analysis
• V0.4 — Locator health analysis
• V0.5 — Apply Fix
• V0.6 — Playwright trace analysis
• V0.7 — Flaky test detection
• V1.0 — Full Playwright debugging assistant