Use when the user asks about Playwright APIs, selectors, assertions, or patterns for E2E or functional tests. Triggers on questions like "how to click a button in Playwright", "Playwright locator", "page.waitFor", "expect toBeVisible", "Playwright test fixtures", or E2E test patterns.
Instrucciones de origen · Vista previa de solo lectura
name
playwright
description
Use when the user asks about Playwright APIs, selectors, assertions, or patterns for E2E or functional tests. Triggers on questions like "how to click a button in Playwright", "Playwright locator", "page.waitFor", "expect toBeVisible", "Playwright test fixtures", or E2E test patterns.
This skill helps look up Playwright APIs, patterns, and best practices for writing E2E and
functional (webview) tests in this project.
Important: Electron Context
This project runs Playwright against Electron (VS Code), not a browser. This fundamentally
changes how many standard Playwright patterns apply:
No URL navigation: page.goto() doesn't apply — you interact with VS Code's DOM directly
No browser.newPage(): The page comes from electronApp.firstWindow(), not a browser context
Dialog stubbing required: Native OS dialogs can't be interacted with — use
electron-playwright-helpers (stubAllDialogs, stubMultipleDialogs) instead
Webview iframe nesting: Webview content lives inside double-nested iframes — the Webview
page object abstracts this as .contentFrame().locator("iframe").contentFrame()
Single worker only: Tests share a sidecar port and cannot parallelize
Context menus: Require VS Code setting since Playwright can't
interact with OS-native menus
"window.menuStyle": "custom"
Standard Playwright best practices for test writing still apply: Page Object Model, fixtures,
utility functions, resilient locators, auto-waiting, and avoiding waitForTimeout(). Just be aware
that browser-specific APIs (navigation, multiple tabs, browser contexts) often don't translate to
Electron.
Project Test Architecture
Two Test Levels
Level
Location
Context
Run Command
E2E
tests/e2e/specs/*.spec.ts
Full Electron (VS Code) launch
npx gulp e2e
Functional
src/webview/*.spec.ts
Headless browser (no Electron/VS Code)
npx gulp functional
E2E tests launch VS Code as an Electron app and interact with the full extension. The Electron
context section above applies here — browser-specific Playwright APIs often don't translate.
Functional tests render VS Code webview HTML templates in a headless browser using rollwright
(Rollup + Playwright). They test webview UI logic — form validation, data bindings, custom elements
— in isolation, without launching VS Code or the extension. Standard Playwright browser APIs
apply here since the test context is a real browser page. Each spec reads its HTML template from
src/webview/*.html, bundles the associated TypeScript via Rollup plugins, and renders the result.
Functional tests have their own src/webview/baseTest.ts (extending rollwright's test base with
coverage config) — not the E2E baseTest.ts.
Page Object Model (POM)
All E2E tests use page objects under tests/e2e/objects/. Always extend or reuse existing page
objects rather than writing raw locator logic in test files. Browse the directory to discover
available page objects — key subdirectories are views/, views/viewItems/, webviews/,
quickInputs/, notifications/, and editor/.
Custom Fixtures (baseTest.ts)
E2E tests import test from tests/e2e/baseTest.ts (not from @playwright/test). This provides
custom fixtures for Electron app launch, connection setup/teardown, topic lifecycle, and more. Read
the file for available fixtures and their types.
Usage pattern:
import { test } from"../baseTest";
import { ConnectionType } from"../types/connection";
test.use({ connectionType: ConnectionType.Ccloud });
test.use({ topicConfig: { name: "my-test-topic" } });
test("my test", async ({ page, connectionItem, topic }) => {
// connectionItem and topic are automatically set up and torn down
});
Test Tags
Tags are used instead of conditionals for filtering test dimensions. See tests/e2e/tags.ts for
available tags. Run by tag: npx gulp e2e -t "@smoke"
Utility Functions
Reuse utility functions from tests/e2e/utils/ for common operations (connection setup, VS Code
commands, settings, sidebar navigation, message production, etc.). Browse the directory before
writing new helpers.
Sources
Playwright Documentation
The official Playwright docs at https://playwright.dev/:
Section
Entry Point
Use For
Writing Tests
/docs/writing-tests
Test structure, actions, assertions
Actions
/docs/input
Clicking, typing, selecting, uploading
Assertions
/docs/test-assertions
expect API, auto-retrying assertions
Locators
/docs/locators
Finding elements, selector strategies
Page Object Model
/docs/pom
Page class pattern (used in E2E tests)
Auto-waiting
/docs/actionability
How Playwright waits for elements
Test Fixtures
/docs/test-fixtures
Shared setup, custom fixtures
Test Configuration
/docs/test-configuration
playwright.config.ts options
Parallelism
/docs/test-parallel
Parallel vs serial test execution
Timeouts
/docs/test-timeouts
Test, action, navigation timeouts
Best Practices
/docs/best-practices
Official recommended patterns
Electron
/docs/api/class-electron
Electron-specific API (launch, etc.)
API Reference
Key class references for detailed method signatures:
Class
URL
Use For
ElectronApplication
/docs/api/class-electron
Electron app launch, window access
Page
/docs/api/class-page
Window interaction, evaluation
Locator
/docs/api/class-locator
Element interaction and querying
Expect (assertions)
/docs/api/class-locatorassertions
toBeVisible, toHaveText, etc.
FrameLocator
/docs/api/class-framelocator
iframe interaction (webview nesting)
Test
/docs/api/class-test
test(), test.describe(), hooks
TestInfo
/docs/api/class-testinfo
Test metadata, annotations, attachments
All URLs are relative to https://playwright.dev.
Process
1. Understand the Question Context
Determine whether the user needs:
API reference: Exact method signatures, options, return values
Selector help: How to locate elements in VS Code's DOM
Test patterns: Structuring tests, using fixtures, extending page objects
Best practices: Official and project-specific conventions
2. Check Project Conventions First
Before fetching external docs, review the project's testing conventions.
For E2E tests (tests/e2e/):
Import test from ../baseTest (not @playwright/test) to get custom fixtures
Use Page Object Model — extend existing page objects in tests/e2e/objects/
Use test.use() for parameterized tests (connectionType, topicConfig)
Use test tags from tests/e2e/tags.ts — no conditionals within tests
Use utility functions from tests/e2e/utils/ for common operations
Run with npx gulp e2e or npx gulp e2e -t "test name"
For functional tests (src/webview/*.spec.ts):
Import test from src/webview/baseTest (extends rollwright, not the E2E baseTest)
Standard headless browser context — no Electron, no VS Code runtime
Tests render VS Code webview HTML templates in isolation via Rollup plugins
Standard Playwright browser APIs apply (locators, assertions, page interaction)
Run with npx gulp functional
3. Fetch Documentation
For API questions, fetch the relevant class or guide page:
WebFetch: https://playwright.dev/docs/api/class-locator
Prompt: "Find the API documentation for [specific method like locator.click, locator.fill, etc.]"
For Electron-specific questions, start with the Electron API page:
WebFetch: https://playwright.dev/docs/api/class-electron
Prompt: "Find the Electron API documentation for [launch options, window access, etc.]"
For pattern/guide questions, fetch the relevant guide page:
WebFetch: https://playwright.dev/docs/best-practices
Prompt: "Find the best practices for [specific topic like selectors, waiting, etc.]"
Navigation strategy:
Start with the most relevant guide or API page
Look for links to related content in the fetched page
Fetch additional pages as needed for complete answers
Prefer guide pages for "how to" questions, API pages for "what does X do" questions
For newer features or migration questions, supplement with a web search:
WebSearch: "playwright locator filter hasText example"
WebSearch: "playwright electron launch VS Code extension test"
4. Look at Existing Test Examples
When the user needs pattern guidance, look at how the project uses Playwright:
# E2E test files
Glob: tests/e2e/specs/*.spec.ts
# Functional test files
Glob: src/webview/**/*.spec.ts
# Page Object Model classes
Glob: tests/e2e/objects/**/*.ts
# Utility functions
Glob: tests/e2e/utils/*.ts
Read relevant test files to show project-specific patterns alongside official docs.
5. Search for Specific APIs
When the user asks about a specific API (e.g., locator.click(), expect().toBeVisible()):
Fetch the relevant API class page
Search for the specific method or property
Extract the API signature with description, parameters, and examples
Cross-reference with project usage if applicable
Note any Electron-specific caveats if the API behaves differently outside a browser
When answering, include the API signature, a code example adapted to project patterns, and any
Electron-specific caveats.
Electron-Specific Patterns
Webview Iframe Access
VS Code webviews are double-nested iframes. The Webview page object handles this:
// in Webview base class:getwebview() {
returnthis.locator.contentFrame().locator("iframe").contentFrame();
}
// then access content inside the webview:this.webview.locator(".my-element");
Always check project page objects first — most VS Code UI elements already have page objects.
Extend existing classes rather than duplicating locator logic in tests
Import test from baseTest — not from @playwright/test — to get the custom Electron
fixtures (electronApp, page, connectionItem, topic, etc.)
Use test.use() for parameterization — set connectionType and topicConfig per describe
block rather than using conditionals, which violate ESLint rules
Prefer getByRole, getByText, getByLabel over CSS selectors — they're more resilient and
accessible. CSS selectors are acceptable for VS Code's internal DOM structure (e.g.,
.monaco-workbench, [role="treeitem"]) where semantic selectors aren't available
Playwright auto-waiting handles most timing — discourage explicit waitForTimeout() as it
creates flaky tests. Use expect().toBeVisible() or locator.waitFor() instead
Webview content requires iframe traversal — use the Webview base class's .webview getter
to access content inside webview panels
Dialog stubbing is automatic — the electronApp fixture calls stubAllDialogs() by default.
Override with stubDialog() or stubMultipleDialogs() for specific return values
Context menus need custom menu style — Playwright can't interact with OS-native context menus.
The project sets "window.menuStyle": "custom" via configureVSCodeSettings() before using
rightClickContextMenuAction()
Traces are collected on failure — the electronApp fixture automatically captures and
attaches Playwright traces for failed tests. No manual trace setup needed in test code
Playwright docs are well-organized by topic — fetch the specific guide or API class page rather
than broad searches
