@kamox/plugin-vscode

VSCode Extension adapter for KamoX using Playwright. This package enables automated testing, live preview, and UI inspection for VSCode extensions within the KamoX ecosystem.

Installation

This package is usually installed automatically as a dependency of the main kamox CLI. If you are building a custom integration:

npm install @kamox/plugin-vscode

Usage

In your kamox.config.json:

{
  "mode": "vscode",
  "projectPath": ".",
  "port": 3000
}

Or via CLI:

kamox vscode --project-path ./my-vscode-extension

How It Works

KamoX launches VSCode as an Electron app using Playwright's _electron.launch() API with --extensionDevelopmentPath pointing to your extension source. This approach:

• Does not require ChromeDriver — avoids remote debugging port issues
• Isolated user profile — each session uses a unique --user-data-dir to prevent mutex conflicts with any running VSCode instance
• Extension loaded immediately — --extensionDevelopmentPath is a native VSCode feature; no manual installation or junction setup needed

Features

• Automated Launch: Launches VSCode with your extension loaded in development mode ([Extension Development Host] title bar).
• Screenshot Capture: Takes full-window screenshots for visual verification via /check-ui.
• Command Execution: Executes any VSCode command programmatically via /vscode/command.
• File Open: Opens files in the editor via /vscode/open.
• Keyboard & Element Control: Type text, press keys, and click elements via /playwright/keyboard and /playwright/element.
• Output Channel Logs: Reads Extension Host output channels via /vscode/output.
• Notifications: Reads and dismisses notification toasts via /vscode/notifications.
• Status Bar: Reads status bar item text via /vscode/statusbar.
• Activity Bar: Switches between views (Explorer, SCM, etc.) via /vscode/activity-bar.
• Tree View: Lists visible tree view items via /vscode/tree-view/:viewId.
• Problems Panel: Reads diagnostics (errors/warnings) via /vscode/problems.
• Swappable Driver: The internal IVSCodeUIDriver interface allows replacing the Playwright driver with a custom implementation.

VSCode-Specific API Endpoints

| Method | Endpoint | Description | | --- | --- | --- | | POST | /vscode/command | Execute a VSCode command by ID | | GET | /vscode/output | Get text from an Output Channel | | POST | /vscode/open | Open a file in the editor | | GET | /vscode/notifications | Get current notification toasts | | POST | /vscode/notifications/dismiss | Dismiss a notification by message | | GET | /vscode/statusbar | Get status bar item text | | POST | /vscode/activity-bar | Click an Activity Bar view | | GET | /vscode/tree-view/:viewId | List visible tree view items | | POST | /vscode/quick-pick | Select an item from a Quick Pick menu | | GET | /vscode/problems | Get all visible Problems panel markers |

Common Endpoints (Inherited)

| Method | Endpoint | Description | | --- | --- | --- | | GET | /status | Server and extension status | | POST | /rebuild | Run the build command | | POST | /check-ui | Take a screenshot | | GET | /logs | Get Extension Host logs | | POST | /playwright/keyboard | Type text or press a key | | POST | /playwright/element | Click element by CSS selector | | POST | /playwright/wait | Wait for a duration (ms) | | POST | /playwright/reload | Reload the VSCode window | | POST | /playwright/evaluate | Execute JavaScript in the renderer |

/playwright/keyboard — Request Body

{ "action": "type", "text": "hello" }
{ "action": "press", "key": "Enter" }
{ "action": "press", "key": "Control+Shift+P" }
{ "action": "press", "key": "ArrowDown" }

Configuration Options

| Option | CLI Flag | Description | Default | | --- | --- | --- | --- | | projectPath | --project-path | Path to your extension source | . | | vscodePath | --vscode-path | Path to VSCode executable | Auto-detect | | workspacePath | -w, --workspace | Workspace folder to open | None | | buildCommand | -b, --build-command | Build command to run | npm run build | | port | -p, --port | HTTP server port | 3000 |

VSCode Binary Detection Order

1. --vscode-path CLI flag / vscodePath config option
2. ExTester cached VSCode at %TEMP%/test-resources/VSCode-win32-x64-archive/Code.exe
3. User's installed VSCode at %LOCALAPPDATA%/Programs/Microsoft VS Code/Code.exe

Architecture

This plugin uses IVSCodeUIDriver as an abstraction layer over the underlying driver:

VSCodeAdapter (HTTP API logic)
  └── IVSCodeUIDriver (interface)
        └── PlaywrightVSCodeDriver (Playwright _electron.launch() implementation)
              └── ExTesterDriver (legacy, kept for reference)

To inject a custom driver (e.g., for testing):

import { VSCodeAdapter } from '@kamox/plugin-vscode'
import { MyCustomDriver } from './my-driver'

const adapter = new VSCodeAdapter(config, new MyCustomDriver())

Extension Loading Notes

activationEvents

VSCode 1.74+ changed the meaning of "activationEvents": []:

• [] — VSCode infers activation from contributes (e.g., activates only when a contributed command is invoked)
• ["*"] — Eager activation at startup (not recommended for production but useful for testing)

For extensions with onLanguage:xxx activation events, the extension activates only when a file of that language type is opened. If VSCode assigns a different language (e.g., .wire.md shown as Markdown), use the language picker to manually set the language and trigger activation.

Language File Associations

Extensions that contribute custom languages (e.g., "extensions": [".wire.md"]) register their associations automatically when loaded via --extensionDevelopmentPath. However, VSCode's built-in language detection may assign .md files to Markdown first. To change the language mode:

POST /vscode/command {"id":"workbench.action.editor.changeLanguageMode"}
POST /playwright/keyboard {"action":"type","text":"YourLanguageName"}
POST /playwright/keyboard {"action":"press","key":"ArrowDown"}
POST /playwright/keyboard {"action":"press","key":"Enter"}

Limitations

• Mouse actions (/playwright/mouse) are not supported. Use /playwright/element with a CSS selector instead.
• Extension Host process cannot be accessed directly. Commands return after dispatching; return values from vscode.commands.executeCommand() are not retrievable via the API.
• WebView content inspection is limited (Playwright iframe restrictions in Electron).
• LSP features (hover info, completion details, raw diagnostics) are not accessible at the protocol level.