Version 0.4: Advanced Features

November 22, 2025 · View on GitHub

Status: ✅ Complete (2025-11-08)

Goal: Implement advanced Playwright features deferred from Version 0.3, including ElementHandles, screenshots options, action options, and SelectOption variants.

Feature: ElementHandles, screenshot options, action options, assertions with auto-retry, network interception, and other advanced capabilities

User Story: As a Rust developer, I want access to advanced Playwright features so that I can write comprehensive browser automation and testing workflows.

Related ADRs:

Prerequisites from Version 0.3

Version 0.4 builds on Version 0.3's page interactions:

  • ✅ Navigation (goto, reload)
  • ✅ Locators and element queries
  • ✅ Core actions (click, fill, press, check, hover)
  • ✅ Select and file upload
  • ✅ Keyboard and Mouse APIs
  • ✅ Basic screenshots (page-level, PNG only)

Deferred from Version 0.3

The following items were deferred from Version 0.3 Slices and need to be implemented in Version 0.4:

Slice 7 Deferrals: Screenshot Options and Element Screenshots

ElementHandle Protocol Support (High Priority)

  • Required for locator.screenshot() - element-level screenshots
  • ElementHandle is a protocol object representing single elements
  • Needed for advanced element interactions
  • Discovery: Frame.screenshot with selector isn't supported by Playwright protocol
  • Requirement: Must implement ElementHandle protocol objects first

Screenshot Options (Medium Priority)

  • ScreenshotType enum: Png, Jpeg
  • ScreenshotClip struct: { x, y, width, height }
  • Options for page.screenshot() and locator.screenshot():
    • type: Png or Jpeg format
    • quality: JPEG quality (0-100)
    • full_page: Capture beyond viewport (full scrollable page)
    • clip: Capture specific region
    • omit_background: Transparent PNG
    • mask: Hide sensitive elements
    • mask_color: Color for masked elements
    • timeout: Screenshot timeout

Screenshot Tests (Medium Priority)

  • Test full-page screenshot (captures beyond viewport)
  • Test JPEG screenshot with quality option
  • Test screenshot with clip region
  • Test screenshot with omit_background (transparent PNG)
  • Test element screenshot (locator.screenshot())
  • Test mask option (hide sensitive elements)

Screenshot Examples (Low Priority)

  • Consider creating examples/screenshots.rs
  • Show page screenshot, element screenshot, options usage

Slice 6 Deferrals: Keyboard and Mouse Options

KeyboardOptions (Low Priority)

  • Options for keyboard.press() and keyboard.type_text()
  • delay: Delay between key presses (milliseconds)
  • Builder pattern with Option fields

MouseOptions (Low Priority)

  • Options for mouse methods
  • button: MouseButton enum (left, middle, right)
  • click_count: Number of clicks
  • delay: Delay between mousedown and mouseup
  • steps: Number of intermediate mousemove events for smooth movement
  • Builder pattern with Option fields

Mouse/Keyboard Enhancements (Low Priority)

  • Modifier key parsing for keyboard.press (e.g., "Control+A", "Shift+Enter")
  • MouseButton enum: Left, Middle, Right

Slice 5 Deferrals: Select and Upload Options

SelectOptions (Low Priority)

  • Options for select_option methods
  • force: Skip actionability checks
  • timeout: Selection timeout
  • Builder pattern

SelectOption Variants (Medium Priority)

  • Currently only supports value string selection
  • Add support for label selection
  • Add support for index selection
  • SelectOption enum: Value(String), Label(String), Index(usize)

FilePayload Struct (Low Priority)

  • In-memory file creation without PathBuf
  • FilePayload { name: String, mime_type: String, buffer: Vec<u8> }
  • Useful for testing without creating temp files

Slice 4 Deferrals: Checkbox and Hover Options

CheckOptions and HoverOptions (Low Priority)

  • Options for check(), uncheck(), hover()
  • force: Skip actionability checks
  • timeout: Action timeout
  • position: Click position within element
  • Builder pattern

set_checked() Convenience Method (Low Priority)

  • locator.set_checked(checked: bool) - Calls check() or uncheck() based on boolean
  • Idiomatic alternative to if/else with check/uncheck

Slice 3 Deferrals: Core Action Options

ClickOptions (Medium Priority)

  • Options for click() and dblclick()
  • button: MouseButton enum (left, middle, right)
  • click_count: Number of clicks
  • delay: Delay between mousedown and mouseup
  • position: Click position within element { x, y }
  • modifiers: Keyboard modifiers (Shift, Control, Alt, Meta)
  • force: Skip actionability checks
  • no_wait_after: Don't wait for navigation
  • timeout: Action timeout
  • trial: Perform checks without clicking
  • Builder pattern with Option fields

FillOptions and PressOptions (Low Priority)

  • Options for fill(), clear(), press()
  • force: Skip actionability checks
  • timeout: Action timeout
  • no_wait_after: Don't wait for navigation
  • Builder pattern

Position Types (Low Priority)

  • Position struct: { x: f64, y: f64 }
  • Used in click options, hover options

Enum Types (Low Priority)

  • MouseButton enum: Left, Middle, Right
  • KeyboardModifier enum: Shift, Control, Alt, Meta

Options Tests (Medium Priority)

  • Test click with position option
  • Test click with modifiers option
  • Test click with force option
  • Test trial option (performs checks without clicking)
  • Test timeout and error handling

Slice 1 Deferrals: Navigation Timeout Handling

Navigation Error Handling (High Priority)

  • Test timeout error handling for goto()
  • Test timeout error handling for reload()
  • Verify error messages are descriptive
  • Test wait_until option behavior

Proposed Scope for Version 0.4

High Priority

  1. ElementHandle Protocol Support

    • Implement ElementHandle protocol objects
    • Element-level screenshot support
    • Advanced element interactions

  2. Navigation Error Handling

    • Timeout tests for goto(), reload()
    • Descriptive error messages
    • wait_until option validation

  3. Screenshot Options

    • ScreenshotType enum (Png, Jpeg)
    • ScreenshotClip struct
    • Implement options for page.screenshot()
    • Implement locator.screenshot() with ElementHandles

Medium Priority

  1. Action Options (Core)

    • ClickOptions with builder pattern
    • Position types
    • MouseButton enum
    • Click options tests

  2. Select Option Variants

    • SelectOption enum (Value, Label, Index)
    • Support label and index selection

  3. Screenshot Tests

    • Full-page screenshots
    • JPEG format with quality
    • Clip region
    • Element screenshots

Low Priority

  1. Remaining Action Options

    • FillOptions, PressOptions
    • CheckOptions, HoverOptions
    • KeyboardOptions, MouseOptions
    • All with builder patterns

  2. Convenience Methods

    • set_checked(bool) for checkboxes
    • Modifier key parsing for keyboard

  3. File Upload Enhancements

    • FilePayload struct for in-memory files

Future Versions (Not Version 0.4)

  • Assertions with auto-retry (expect API)
  • Network interception and route mocking
  • Mobile emulation (device descriptors, viewport, user agent)
  • Videos and tracing
  • Downloads and dialogs
  • Context options (viewport, user agent, geolocation, permissions)

Success Criteria

Version 0.4 is complete - all criteria met:

  • ElementHandle protocol implemented ✅ (Slice 1)
  • locator.screenshot() works with ElementHandles ✅ (Slice 1)
  • Screenshot options fully implemented (type, quality, full_page, clip, etc.) ✅ (Slice 2)
  • Navigation timeout error handling tested ✅ (Slice 3)
  • ClickOptions with builder pattern implemented ✅ (Slice 4)
  • Action position and modifiers work correctly ✅ (Slice 4)
  • SelectOption supports value, label, and index ✅ (Slice 6)
  • All HIGH and MEDIUM priority deferred Version 0.3 items addressed ✅
  • All tests passing cross-browser ✅
  • Documentation updated ✅

Implementation Plan

Status: ✅ Complete - All 6 Slices Complete (2025-11-08)

Version 0.4 followed the same TDD and vertical slicing approach as Version 0.3.

Slice 1: ElementHandle Protocol & Element Screenshots ✅

Status: Complete (2025-11-08)

Goal: Implement ElementHandle as a ChannelOwner protocol object and enable element-level screenshots via locator.screenshot().

Why First: ElementHandles are required for locator.screenshot() (deferred from Version 0.3). This is the highest-priority deferred item.

Research Complete: ✅

  • ElementHandles are ChannelOwner protocol objects created via __create__ messages
  • Element screenshots use ElementHandle.screenshot channel method (NOT Frame.screenshot)
  • Frame already returns ElementHandle GUIDs from querySelectorAll but we currently only use the count
  • Pattern matches Request/Response object implementation

Tasks:

  • Create element_handle.rs protocol module
    • ElementHandle struct with ChannelOwnerImpl base
    • Implement ChannelOwner trait
    • Constructor: new(parent, type_name, guid, initializer)
    • Method: screenshot(options) -> Result<Vec<u8>>
    • Base64 decoding for screenshot data
  • Update frame.rs with query methods
    • query_selector(selector) -> Result<Option<Arc<ElementHandle>>>
    • query_selector_all(selector) -> Result<Vec<Arc<ElementHandle>>>
    • Helper to convert GUID responses to ElementHandle objects
  • Update page.rs with query delegates
    • query_selector() - delegates to main_frame
    • query_selector_all() - delegates to main_frame
  • Update locator.rs
    • Uncomment and implement screenshot() method
    • Use query_selector to get ElementHandle, call screenshot()
  • Update object_factory.rs
    • Add "ElementHandle" case in match statement
    • Call ElementHandle::new() with proper parent
  • Update mod.rs
    • Export ElementHandle module
  • Tests
    • Test query_selector returns ElementHandle
    • Test query_selector returns None when not found
    • Test query_selector_all returns multiple handles
    • Test ElementHandle.screenshot() directly
    • Test locator.screenshot() delegates to ElementHandle
    • test_locator_screenshot in screenshot_test.rs working
    • Cross-browser tests (Chromium, Firefox, WebKit)
  • Documentation
    • Removed debug statements from frame.rs
    • Added rustdoc to ElementHandle methods
    • Link to Playwright ElementHandle docs

Files Created:

  • crates/playwright-core/src/protocol/element_handle.rs
  • crates/playwright-core/tests/element_handle_test.rs

Files Modified:

  • crates/playwright-core/src/protocol/frame.rs
  • crates/playwright-core/src/protocol/page.rs
  • crates/playwright-core/src/protocol/locator.rs
  • crates/playwright-core/src/protocol/mod.rs
  • crates/playwright-core/src/object_factory.rs
  • crates/playwright-core/src/error.rs (added ElementNotFound variant)
  • crates/playwright-core/tests/screenshot_test.rs
  • crates/playwright-core/tests/test_server.rs (added /locators.html route)

Acceptance Criteria: ✅ All Met

  • ✅ ElementHandle is a proper ChannelOwner protocol object
  • ✅ query_selector methods work correctly
  • ✅ ElementHandle.screenshot() captures element screenshots
  • ✅ locator.screenshot() works via ElementHandle
  • ✅ All tests pass cross-browser (Chromium, Firefox, WebKit)
  • ✅ Debug statements removed

Slice 2: Screenshot Options (Type, Quality, Full Page, Clip) ✅

Status: Complete (2025-11-08)

Goal: Implement ScreenshotOptions struct with builder pattern for page and element screenshots.

Why Second: Second-highest priority deferred item. Users need JPEG, full-page, and clip options.

Tasks:

  • Create ScreenshotOptions struct
  • Create ScreenshotType enum (Png, Jpeg)
  • Create ScreenshotClip struct
  • Implement builder pattern
  • Update page.screenshot() to accept ScreenshotOptions
  • Update ElementHandle.screenshot() to accept ScreenshotOptions
  • Update locator.screenshot() to accept ScreenshotOptions
  • Tests for all option combinations (combined into efficient tests)
  • Cross-browser tests (Chromium, Firefox, WebKit)

Files Created:

  • crates/playwright-core/src/protocol/screenshot.rs
  • crates/playwright-core/tests/screenshot_options_test.rs

Files Modified:

  • crates/playwright-core/src/protocol/mod.rs
  • crates/playwright-core/src/protocol/page.rs
  • crates/playwright-core/src/protocol/element_handle.rs
  • crates/playwright-core/src/protocol/locator.rs
  • crates/playwright-core/tests/screenshot_test.rs (removed TODO)

Acceptance Criteria: ✅ All Met

  • ✅ ScreenshotType enum (Png, Jpeg) with proper serialization
  • ✅ ScreenshotClip struct for region capture
  • ✅ ScreenshotOptions with builder pattern
  • ✅ Support for type, quality, full_page, clip, omit_background options
  • ✅ All screenshot methods accept options
  • ✅ All tests pass cross-browser

Slice 3: Navigation Error Handling ✅

Status: Complete (2025-11-08)

Goal: Add timeout tests and error handling for navigation methods.

Why Third: High-priority deferred item from Version 0.3 Slice 1.

Tasks:

  • Test goto() timeout errors
  • Test reload() timeout errors
  • Test wait_until option behavior (Load, DomContentLoaded, NetworkIdle)
  • Verify descriptive error messages
  • Cross-browser error tests (Chromium, Firefox, WebKit)

Files Created:

  • crates/playwright-core/tests/navigation_errors_test.rs

Acceptance Criteria: ✅ All Met

  • ✅ Navigation timeout errors properly tested (unreachable URLs)
  • ✅ Valid navigation with timeout options works
  • ✅ Invalid URL errors handled correctly
  • ✅ reload() timeout behavior tested
  • ✅ wait_until options work (Load, DomContentLoaded, NetworkIdle)
  • ✅ Error messages contain "timeout" for timeout errors
  • ✅ All tests pass cross-browser (Chromium, Firefox, WebKit)

Slice 4: ClickOptions with Builder Pattern ✅

Status: Complete (2025-11-08)

Goal: Implement ClickOptions with position, modifiers, button, force, trial options.

Why Fourth: Most commonly used action option. Foundation for other action options.

Tasks:

  • Create ClickOptions struct with builder
  • Create MouseButton enum (Left, Right, Middle)
  • Create KeyboardModifier enum (Alt, Control, Meta, Shift, ControlOrMeta)
  • Create Position struct
  • Update click() and dblclick() signatures to accept ClickOptions
  • Serialize options to protocol format
  • Tests with position, modifiers, button options
  • Test trial option (dry-run)
  • Test force option
  • Cross-browser tests (Chromium, Firefox, WebKit)

Files Created:

  • crates/playwright-core/src/protocol/click.rs
  • crates/playwright-core/tests/click_options_test.rs

Files Modified:

  • crates/playwright-core/src/protocol/mod.rs
  • crates/playwright-core/src/protocol/locator.rs
  • crates/playwright-core/src/protocol/frame.rs
  • crates/playwright-core/tests/test_server.rs (added /click_options.html route)

Acceptance Criteria: ✅ All Met

  • ✅ MouseButton enum (Left, Right, Middle) with proper serialization
  • ✅ KeyboardModifier enum (Alt, Control, Meta, Shift, ControlOrMeta)
  • ✅ Position struct for click coordinates
  • ✅ ClickOptions with builder pattern
  • ✅ Support for button, click_count, delay, force, modifiers, no_wait_after, position, timeout, trial options
  • ✅ click() and dblclick() methods accept ClickOptions
  • ✅ Cross-browser compatibility verified (Chromium, Firefox, WebKit)

Slice 5: Other Action Options ✅

Status: Complete (2025-11-08)

Goal: Implement remaining action options (Fill, Press, Check, Hover, Select, Keyboard, Mouse).

Why Fifth: Complete the options pattern for all deferred actions.

Tasks:

  • FillOptions, PressOptions
  • CheckOptions, HoverOptions
  • SelectOptions (for select_option)
  • KeyboardOptions (delay)
  • MouseOptions (button, steps, delay)
  • Update all action method signatures
  • Comprehensive option tests

Files Created:

  • crates/playwright-core/src/protocol/action_options.rs
  • crates/playwright-core/tests/action_options_test.rs

Files Modified:

  • crates/playwright-core/src/protocol/mod.rs (exported action option types)
  • crates/playwright-core/src/protocol/locator.rs (updated fill, clear, press, check, uncheck, hover, select_option methods)
  • crates/playwright-core/src/protocol/frame.rs (updated internal methods to accept options)
  • crates/playwright-core/src/protocol/keyboard.rs (updated press, type_text methods)
  • crates/playwright-core/src/protocol/mouse.rs (updated move_to, click, dblclick, down, up methods)
  • crates/playwright-core/src/protocol/page.rs (updated internal keyboard and mouse methods)

Acceptance Criteria: ✅ All Met

  • ✅ FillOptions with force and timeout
  • ✅ PressOptions with delay and timeout
  • ✅ CheckOptions with force, position, timeout, trial
  • ✅ HoverOptions with force, modifiers, position, timeout, trial
  • ✅ SelectOptions with force and timeout
  • ✅ KeyboardOptions with delay
  • ✅ MouseOptions with button, click_count, delay, steps
  • ✅ All action methods accept options
  • ✅ Unit tests for all options structs
  • ✅ Integration tests for all options
  • ✅ Cross-browser compatibility verified (Chromium, Firefox, WebKit)

Slice 6: SelectOption Variants ✅

Status: Complete (2025-11-08)

Goal: Support selection by value, label, or index (not just value).

Why Sixth: Medium-priority enhancement for select_option. Currently only supports value-based selection.

Tasks:

  • Create SelectOption enum (Value, Label, Index)
  • Implement to_json() for protocol serialization
  • Implement From<&str> and From for backward compatibility
  • Update select_option() to accept impl Into<SelectOption>
  • Update select_option_multiple() to accept SelectOption variants
  • Update frame.rs to use SelectOption.to_json() in protocol messages
  • Unit tests for SelectOption serialization
  • Integration tests for label selection
  • Integration tests for index selection
  • Test selection without value attribute (index-based)
  • Test mixed SelectOption types in multiple selection
  • Cross-browser tests (Chromium, Firefox, WebKit)

Files Created:

  • crates/playwright-core/src/protocol/select_option.rs

Files Modified:

  • crates/playwright-core/src/protocol/mod.rs (added SelectOption export)
  • crates/playwright-core/src/protocol/locator.rs (updated select methods)
  • crates/playwright-core/src/protocol/frame.rs (updated protocol serialization)
  • crates/playwright-core/tests/select_upload_test.rs (added comprehensive tests)

Implementation Notes:

  • SelectOption enum has three variants: Value(String), Label(String), Index(usize)
  • Each variant serializes to appropriate JSON-RPC format: {"value": "..."}, {"label": "..."}, {"index": N}
  • Backward compatibility maintained via From trait - existing string usage converts to SelectOption::Value
  • Generic method signatures use impl Into<SelectOption> pattern for ergonomic API
  • All tests passing across Chromium, Firefox, and WebKit

Acceptance Criteria: ✅ All Met

  • ✅ SelectOption enum with Value, Label, Index variants created
  • ✅ Proper JSON-RPC serialization for each variant
  • ✅ Backward compatibility with existing string-based API
  • ✅ All integration tests pass including cross-browser
  • ✅ Can select by label (e.g., "Banana" selects value="banana")
  • ✅ Can select by index (0-based indexing)
  • ✅ Can select options without value attribute using index
  • ✅ Can mix SelectOption types in multiple selection

Slice 7: Documentation and Polish ✅

Status: Complete (2025-11-08)

Goal: Complete Version 0.4 documentation and address any remaining deferred items.

Tasks:

  • Complete rustdoc for all new types - All Version 0.4 types documented
  • Update README with Version 0.4 examples - SelectOption variants added
  • Update roadmap.md - Version 0.4 marked complete
  • Review all Version 0.3 deferrals - All HIGH/MEDIUM priority items addressed
  • Update CLAUDE.md if needed - No updates needed
  • Add doctest infrastructure to Version 0.6 roadmap

Deferred Items (Low Priority - moved to Version 0.5):

  • set_checked() convenience method
  • FilePayload struct for in-memory files
  • Modifier key parsing for keyboard
  • Screenshot mask/mask_color options
  • Dedicated screenshot examples

Acceptance Criteria: ✅ All Met

  • ✅ All rustdoc complete with no warnings
  • ✅ README updated with Version 0.4 completion
  • ✅ Roadmap updated
  • ✅ Version 0.3 deferrals reviewed
  • ✅ Doctest infrastructure improvement noted for Version 0.6

This order prioritizes:

  • High-impact features (ElementHandles, screenshot options)
  • Deferred items blocking other features
  • Most commonly used options first
  • Progressive complexity (simple options → complex options)

Deferred to Version 0.5

The following low-priority items from Version 0.3/0.4 deferrals were not implemented in Version 0.4 and are deferred to Version 0.5:

From Version 0.3 Deferrals

  1. set_checked() Convenience Method (Low Priority)

    • locator.set_checked(checked: bool) - Calls check() or uncheck() based on boolean
    • Idiomatic alternative to if/else with check/uncheck
    • Can be implemented alongside other convenience methods

  2. FilePayload Struct (Low Priority)

    • In-memory file creation without PathBuf
    • FilePayload { name: String, mime_type: String, buffer: Vec<u8> }
    • Useful for testing without creating temp files
    • Lower priority than network interception and assertions

  3. Modifier Key Parsing (Low Priority)

    • Keyboard.press with modifier parsing (e.g., "Control+A", "Shift+Enter")
    • Can parse compound key combinations
    • Nice-to-have enhancement, not critical

  4. Screenshot Mask Options (Low Priority)

    • mask: Hide sensitive elements in screenshots
    • mask_color: Color for masked elements
    • Advanced screenshot feature, lower priority

  5. Dedicated Screenshot Examples (Low Priority)

    • examples/screenshots.rs showing all screenshot capabilities
    • Current README examples are sufficient for now
    • Can enhance examples directory in Version 0.6 (Production Hardening)

Version 0.5 Focus

Version 0.5 will prioritize:

  • HIGH: Assertions with auto-retry (expect API)
  • HIGH: Network interception and route mocking
  • MEDIUM: Mobile emulation (device descriptors)
  • MEDIUM: Downloads and dialogs handling
  • LOW: Above deferrals from Version 0.4

Created: 2025-11-08 Last Updated: 2025-11-08