Skip to content

Release Notes - v0.4.0

Semantic selectors, full storage state management, init scripts, and 25+ new MCP tools.

Highlights

AI-native element finding with semantic selectors.

This release adds semantic selectors that find elements by accessibility attributes (role, label, text) instead of brittle CSS selectors. Also includes full storage state management with sessionStorage support, init scripts for pre-page JavaScript injection, and 25+ new MCP tools.

New Features

Semantic Selectors

Find elements by accessibility attributes instead of CSS selectors:

Selector Description Example
role ARIA role button, textbox, link
text Visible text content "Submit", "Learn more"
label Associated label text "Email address"
placeholder Input placeholder "Enter email"
testid data-testid attribute "login-btn"
alt Image alt text "Company logo"
title Element title attribute "Close dialog"
xpath XPath expression "//button[@type='submit']"
near CSS selector of nearby element "#username"

SDK Usage

// Find by ARIA role and text
elem, err := pilot.Find(ctx, "", &w3pilot.FindOptions{
    Role: "button",
    Text: "Submit",
})

// Find by label (for form inputs)
elem, err := pilot.Find(ctx, "", &w3pilot.FindOptions{
    Label: "Email address",
})

// Scoped search within parent element
form, _ := pilot.Find(ctx, "form.signup", nil)
emailInput, _ := form.Find(ctx, "", &w3pilot.FindOptions{
    Label: "Email",
})

MCP Tool Usage

{"name": "click", "arguments": {"role": "button", "text": "Sign In"}}
{"name": "fill", "arguments": {"label": "Email", "value": "user@example.com"}}
{"name": "click", "arguments": {"testid": "submit-btn"}}

Init Scripts

Inject JavaScript that runs before any page scripts on every navigation:

// Mock an API before page loads
err := pilot.AddInitScript(ctx, `
    window.fetch = async (url, opts) => {
        if (url.includes('/api/user')) {
            return { json: () => ({ id: 1, name: 'Test User' }) };
        }
        return originalFetch(url, opts);
    };
`)

CLI flags for script injection:

w3pilot mcp --init-script=./mock-api.js --init-script=./test-helpers.js

Full Storage State

Complete browser state management including sessionStorage:

// Get complete storage state (cookies + localStorage + sessionStorage)
state, err := pilot.StorageState(ctx)

// Restore storage state
err := pilot.SetStorageState(ctx, &savedState)

// Clear all storage
err := pilot.ClearStorage(ctx)

New MCP Tools

25+ new tools organized by category:

Category Tools
Tracing start_trace, stop_trace, start_trace_chunk, stop_trace_chunk, start_trace_group, stop_trace_group
Dialogs handle_dialog, get_dialog
Network get_network_requests, clear_network_requests, route, unroute, route_list, network_state_set
LocalStorage localstorage_get, localstorage_set, localstorage_list, localstorage_delete, localstorage_clear
SessionStorage sessionstorage_get, sessionstorage_set, sessionstorage_list, sessionstorage_delete, sessionstorage_clear
Tabs list_tabs, select_tab, close_tab
Testing verify_value, verify_list_visible, generate_locator, fill_form
Init Scripts add_init_script
Storage clear_storage

Bug Fixes

  • Browser connection stability - Fixed browser connection drops in MCP server by using exec.Command instead of exec.CommandContext for clicker process lifetime

Tests

New integration test suites:

  • Semantic selectors - All selector types, scoped search, element interactions
  • Tracing - Start/stop, chunks, groups, context tracing
  • Storage state - Get/set/clear, round-trip, cookies, multiple origins
  • Init scripts - Basic injection, functions, API mocking, multiple scripts

Installation

go get github.com/plexusone/w3pilot@v0.4.0

Usage Examples

AI-Assisted Form Filling

// Click the login button by its text
{"name": "click", "arguments": {"role": "button", "text": "Log In"}}

// Fill email by label
{"name": "fill", "arguments": {"label": "Email address", "value": "user@example.com"}}

// Fill password by placeholder
{"name": "fill", "arguments": {"placeholder": "Enter password", "value": "secret"}}

// Submit by test ID
{"name": "click", "arguments": {"testid": "submit-btn"}}

Session Persistence

// Save session after login
{"name": "get_storage_state"}

// Restore session on next run
{"name": "set_storage_state", "arguments": {"state": "<saved JSON>"}}

API Mocking for Tests

// Inject mock before page loads
{"name": "add_init_script", "arguments": {"script": "window.fetch = () => Promise.resolve({json: () => ({mocked: true})})"}}

Documentation