Release Notes - v0.8.0¶

Session management and testing SDK release with CLI/MCP parity for assertions and verifications.

Highlights¶

Live Session Mode Foundation

This release adds the SDK foundation for live session mode, where a browser stays open and multiple CLI commands or MCP tools can reuse the same session. This enables:

AI assistant + human collaboration with shared browser
Interactive debugging with persistent browser state
Session persistence across CLI invocations

SDK Assertion and Verification Methods

Testing capabilities have been moved from MCP-only to the core SDK, enabling both CLI and MCP to use the same underlying methods:

Page-level assertions: AssertText, AssertElement, AssertURL
Element verifications: VerifyValue, VerifyText, VerifyVisible, etc.
Locator generation with multiple strategies

MCP Batch Execution and HTTP Request Tools

New MCP tools for AI agent workflows:

http_request - Make authenticated HTTP requests in browser context
batch_execute - Execute multiple operations in a single call (15+ supported tools)
js_evaluate now supports max_result_size for result truncation

CLI Test Commands

Full CLI parity with MCP testing tools:

# Assertions
w3pilot test assert-text "Welcome"
w3pilot test assert-element "#login"
w3pilot test assert-url "**/dashboard"

# Verifications
w3pilot test verify-value "#email" "user@example.com"
w3pilot test verify-text ".heading" "Welcome"
w3pilot test verify-visible "#modal"
w3pilot test verify-enabled "#submit"

# Locator generation
w3pilot test generate-locator "#submit" --strategy xpath

New Features¶

Session Management Package¶

New session package provides shared browser session management:

import "github.com/plexusone/w3pilot/session"

// Create a session manager
mgr := session.NewManager(session.Config{
    Headless:      false,
    AutoReconnect: true,
})

// Get browser (launches if needed, reconnects if possible)
pilot, err := mgr.Pilot(ctx)

// Detach without closing browser
mgr.Detach()

// Later: reconnect to the same session
pilot, err = mgr.Pilot(ctx)

// When done: close browser and cleanup
mgr.Close(ctx)

Session Types¶

session.Manager - Manages browser lifecycle with persistence
session.Config - Configuration options (headless, timeout, auto-reconnect)
session.Info - Persisted session data (WebSocket URL, ports, PIDs)
session.Status - Connection status (disconnected, connected, reconnecting)

Session Persistence¶

Session info is persisted to ~/.w3pilot/session.json:

{
  "websocket_url": "ws://localhost:9222",
  "clicker_port": 9222,
  "cdp_port": 9223,
  "headless": false,
  "clicker_pid": 12345,
  "launched_at": "2026-03-29T10:00:00Z"
}

MCP Tools for AI Agents¶

New tools to improve AI agent workflows with reduced latency and better ergonomics.

HTTP Request Tool¶

Make authenticated HTTP requests using the browser's session cookies:

{
  "tool": "http_request",
  "arguments": {
    "url": "https://api.example.com/data",
    "method": "POST",
    "headers": {"X-Custom": "value"},
    "body": "{\"key\": \"value\"}",
    "content_type": "application/json"
  }
}

Batch Execute Tool¶

Execute multiple operations in a single MCP call to reduce round-trip latency:

{
  "tool": "batch_execute",
  "arguments": {
    "steps": [
      {"tool": "page_navigate", "args": {"url": "https://example.com"}},
      {"tool": "element_fill", "args": {"selector": "#username", "value": "user"}},
      {"tool": "element_fill", "args": {"selector": "#password", "value": "pass"}},
      {"tool": "element_click", "args": {"selector": "#login"}}
    ],
    "stop_on_error": true
  }
}

Supported tools in batch: page_navigate, page_go_back, page_go_forward, page_reload, page_get_title, page_get_url, page_screenshot, element_click, element_fill, element_type, element_get_text, js_evaluate, wait_for_selector, wait_for_load, http_request.

Result Truncation¶

js_evaluate now supports max_result_size to prevent large results from consuming tokens:

{
  "tool": "js_evaluate",
  "arguments": {
    "script": "document.body.innerHTML",
    "max_result_size": 4096
  }
}

Browser Reconnection¶

New Connect function allows connecting to an existing browser:

// Connect to existing clicker instance
pilot, err := w3pilot.Connect(ctx, "ws://localhost:9222")

// Access clicker process info
if clicker := pilot.Clicker(); clicker != nil {
    fmt.Printf("Port: %d\n", clicker.Port())
    fmt.Printf("PID: %d\n", clicker.Process().Pid)
}

API Additions¶

Session Package¶

Type/Function	Description
`session.NewManager(config)`	Create session manager
`session.DefaultConfig()`	Get default configuration
`session.Save(path, info)`	Persist session to file
`session.Load(path)`	Load session from file
`session.Clear(path)`	Remove session file
`session.Exists(path)`	Check if session file exists

Manager Methods¶

Method	Description
`Pilot(ctx)`	Get browser (launch/reconnect as needed)
`LaunchIfNeeded(ctx)`	Launch browser if not connected
`IsConnected()`	Check connection status
`State()`	Get current session state
`Detach()`	Disconnect without closing browser
`Close(ctx)`	Close browser and cleanup
`Refresh(ctx)`	Update persisted session info

Pilot Additions¶

Method	Description
`Connect(ctx, wsURL)`	Connect to existing browser
`Pilot.Clicker()`	Access clicker process
`ClickerProcess.Process()`	Access underlying os.Process

Assertion Methods¶

Method	Description
`Pilot.AssertText(ctx, text, opts)`	Assert text exists on page
`Pilot.AssertElement(ctx, selector, opts)`	Assert element exists
`Pilot.AssertURL(ctx, pattern, opts)`	Assert URL matches pattern
`Pilot.GenerateLocator(ctx, selector, opts)`	Generate robust locator

Element Verification Methods¶

Method	Description
`Element.VerifyValue(ctx, expected)`	Verify input value matches
`Element.VerifyText(ctx, expected, opts)`	Verify element text matches
`Element.VerifyVisible(ctx)`	Verify element is visible
`Element.VerifyHidden(ctx)`	Verify element is hidden
`Element.VerifyEnabled(ctx)`	Verify element is enabled
`Element.VerifyDisabled(ctx)`	Verify element is disabled
`Element.VerifyChecked(ctx)`	Verify checkbox/radio is checked
`Element.VerifyUnchecked(ctx)`	Verify checkbox/radio is unchecked

CLI Test Commands¶

Command	Description
`test assert-text <text>`	Assert text exists on page
`test assert-element <selector>`	Assert element exists
`test assert-url <pattern>`	Assert URL matches pattern
`test verify-value <selector> <expected>`	Verify input value
`test verify-text <selector> <expected>`	Verify element text
`test verify-visible <selector>`	Verify element visible
`test verify-hidden <selector>`	Verify element hidden
`test verify-enabled <selector>`	Verify element enabled
`test verify-disabled <selector>`	Verify element disabled
`test verify-checked <selector>`	Verify checkbox checked
`test verify-unchecked <selector>`	Verify checkbox unchecked
`test generate-locator <selector>`	Generate robust locator

New MCP Tools¶

Tool	Description
`http_request`	Make authenticated HTTP requests in browser context
`batch_execute`	Execute multiple operations in a single MCP call

MCP Tool Updates¶

Tool	Update
`js_evaluate`	Added `max_result_size` parameter for result truncation

Bug Fixes¶

IIFE Evaluation: Fixed js_evaluate returning null for async IIFEs like (async () => { return await fetch(...) })(). The SDK now detects IIFE patterns and uses expression syntax to preserve return values.
State Operations Fallback: Fixed state_save and state_load failing on some browser contexts by adding fallback to standard BiDi commands when vibium-specific commands are unavailable.

Coming Next¶

The CLI commands for live session mode will be added in a future release:

w3pilot session start - Launch browser and keep session alive
w3pilot session attach - Attach to existing session
w3pilot session detach - Detach without closing browser
w3pilot session stop - Close browser and end session

Breaking Changes¶

None. All changes are backwards compatible.

Installation¶

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