Changelog

Copy Markdown View Source

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.1.0] - 2026-02-03

Changed

  • Complete architecture redesign with clean, modular transport abstraction
  • New dependency: built on playwright_ex (~> 0.3.2) instead of alpha playwright
  • Transport abstraction via Playwriter.Transport.Behaviour
  • Session management via Playwriter.Browser.Session GenServer
  • Remote transport disabled due to WSL2 Hyper-V firewall blocking WebSockets
  • Playwright path changed from deps/playwright_ex to deps/playwright/priv/static
  • mix playwriter.setup now installs to correct playwright dependency location
  • GenServer call timeouts increased throughout for reliability
  • Screenshot handling now properly decodes base64 from playwright_ex
  • Server scripts bind to 0.0.0.0 for WSL2 accessibility
  • PowerShell commands now use -ExecutionPolicy Bypass flag

Added

  • WindowsCmd transport (Playwriter.Transport.WindowsCmd):
    • Runs Playwright directly on Windows via PowerShell stdin/stdout
    • Bypasses all WSL2 networking and firewall issues
    • No server setup required, just npm install playwright on Windows
    • Use with mode: :windows option
  • Transport layer modules:
    • Playwriter.Transport.Local wraps playwright_ex for local automation
    • Playwriter.Transport.WindowsCmd for WSL-to-Windows via PowerShell
    • Playwriter.Transport factory with auto-detection
  • Server discovery and health checks:
    • Playwriter.Server.Discovery for automatic endpoint detection
    • Playwriter.Server.Health for availability monitoring
  • Public API functions:
    • Playwriter.with_browser/2 for composable sessions with cleanup
    • Playwriter.fetch_html/2, screenshot/2 convenience functions
    • Playwriter.goto/3, content/1, click/3, fill/4 context operations
  • Windows server scripts in priv/scripts/
  • Working examples in examples/ directory:
    • fetch_html.exs, screenshot.exs, interaction.exs
    • windows_browser.exs, windows_mode.exs, test_windows_cmd.exs
  • Test suite with 47 tests using Supertester patterns

Added Documentation

  • Testing guide (guides/testing.md):
    • Test categories and tags explained
    • Running unit, integration, and Windows server tests
    • Prerequisites for each test type
    • CI configuration guidance
    • Writing tests with proper tags
  • Examples README (examples/README.md):
    • All available examples with descriptions
    • CLI flags (--local, --remote, --endpoint, --headless)
    • Mode auto-detection behavior
    • Writing custom scripts
    • Troubleshooting tips
  • Complete guide system:
    • Getting Started, Architecture, Transport Layer
    • WSL-Windows Integration, Function Reference
    • Examples, Troubleshooting
  • HexDocs configuration with grouped modules and guide hierarchy
  • Professional hexagonal SVG logo

Removed

  • Old Playwriter.Fetcher module (replaced by Session)
  • Old Playwriter.WindowsBrowserAdapter (replaced by transports)
  • Old Playwriter.WindowsBrowserDirect (experimental)
  • Old Playwriter.CLI (simplified, to be re-added)
  • Dependency on alpha playwright library
  • Remote transport WebSocket implementation (non-functional in WSL2)

Fixed

  • Screenshot binary handling with proper base64 decoding
  • Timeout issues in browser operations
  • PowerShell execution policy blocking script execution
  • Server not accepting connections from WSL2

Cleanup

  • Removed 44 unused files from root directory
  • Clean root: LICENSE, CHANGELOG.md, README.md only
  • Development scripts consolidated in priv/scripts/
  • Added screenshot.png to .gitignore

Technical

  • Zero compiler warnings
  • Credo strict: no issues
  • Dialyzer clean
  • All unit tests passing

[0.0.2] - 2025-07-04

Added

  • Architecture Diagrams: Comprehensive Mermaid diagrams documenting system architecture
  • Visual Documentation: Added diagrams.md with 10 detailed diagrams covering:
    • High-Level Architecture overview
    • WSL-to-Windows Bridge Flow
    • Component Interaction patterns
    • WebSocket Connection Workflow
    • Browser Launch Strategies
    • Data Flow visualization
    • Error Handling Flow
    • Chrome Profile Integration
    • Security Considerations
    • Performance Optimization strategies

Changed

  • Documentation: Enhanced Hex.pm documentation package with visual diagrams
  • Styling: All Mermaid diagrams now use consistent black font color (#000) for better readability
  • HexDocs: Added native Mermaid diagram rendering support with automatic dark/light theme switching

[0.0.1] - 2025-07-04

Added

Core Features

  • Cross-Platform Browser Automation: Complete Elixir application for browser automation using Playwright
  • WSL-to-Windows Integration: Advanced WebSocket-based bridge for controlling Windows browsers from WSL
  • Headed Browser Support: True visible browser windows (not just headless automation)
  • Multi-Port Discovery: Robust server discovery across multiple ports and network interfaces
  • Chrome Profile Integration: Support for enumerating and accessing Windows Chrome profiles

CLI Interface

  • Flexible Command System: Multiple operation modes with pattern matching
  • Local Browser Automation: Standard Playwright automation in headless/headed modes
  • Windows Browser Commands: --windows-browser and --windows-firefox options
  • Profile Management: --list-profiles command for Chrome profile enumeration
  • Authentication Demo: --auth mode with custom headers and cookies

Core Modules

  • Playwriter.Fetcher: Core HTML fetching logic with dual-mode browser management
  • Playwriter.WindowsBrowserAdapter: WSL-Windows WebSocket bridge with network discovery
  • Playwriter.WindowsBrowserDirect: Alternative direct browser control methods
  • Playwriter.CLI: Command-line interface with comprehensive argument parsing

Windows Integration Scripts

  • start_true_headed_server.sh: Launch headed Playwright server on Windows
  • kill_playwright.ps1: Clean termination of all Playwright processes
  • list_chrome_profiles.ps1: Enumerate available Chrome profiles on Windows
  • start_chromium.ps1: Launch Playwright's Chromium with custom profile setup

Network & Discovery

  • Multi-Endpoint Discovery: Automatic WSL gateway IP detection and fallback
  • Port Scanning: Intelligent port discovery with prioritization
  • Connection Validation: Server health checking and endpoint verification
  • Error Recovery: Graceful handling of network failures and timeouts

Documentation

  • Comprehensive README: Detailed developer documentation with architecture diagrams
  • Code Examples: Usage examples for both CLI and programmatic access
  • Troubleshooting Guide: Extensive troubleshooting section with common issues
  • Architecture Documentation: Deep-dive into cross-platform integration

Technical Details

Architecture Innovations

  • WebSocket Bridge: Solves WSL-Windows network boundary challenges
  • Headed Server Architecture: Uses launchServer({headless: false}) instead of run-server
  • Profile Discovery: PowerShell-based Chrome profile enumeration
  • Process Management: Clean startup, shutdown, and cleanup utilities

Supported Platforms

  • WSL2: Primary development and testing environment
  • Windows: Target platform for browser automation
  • Linux: Native support for local browser automation

Browser Support

  • Chromium: Primary browser with full feature support
  • Chrome: Profile integration and Windows-specific features
  • Firefox: Basic support through Windows integration

Dependencies

  • Elixir: 1.14+ compatibility
  • Playwright: 1.49.1-alpha.2 (Elixir port)
  • Node.js: Required on Windows for Playwright server
  • PowerShell: Used for Windows automation scripts

Known Limitations

Current Constraints

  • Profile Support: Limited to default Chromium profile due to server architecture
  • Single Server: One server per port limits concurrent browser sessions
  • Manual Management: User must start/stop servers manually
  • Network Dependency: Requires stable WSL-Windows networking

Security Considerations

  • Unencrypted WebSocket: Uses ws:// not wss:// connections
  • No Authentication: WebSocket connections have no authentication
  • Process Privileges: Runs with user-level privileges

Future Roadmap

Planned Enhancements

  • Profile-Aware Servers: Launch servers with specific Chrome profile arguments
  • Server Pool Management: Multiple servers for concurrent operations
  • Enhanced Error Recovery: Automatic server restart and reconnection
  • Chrome Extension Support: Install and manage browser extensions
  • Session Persistence: Save and restore complete browser sessions

Architecture Improvements

  • Service-Based Architecture: Windows service for permanent server management
  • Load Balancing: Distribute requests across multiple browser instances
  • Health Monitoring: Server health checks and automatic failover
  • Configuration Management: Profile and server configuration via config files

Credits

Acknowledgments

  • Playwright - The browser automation framework
  • Playwright for Elixir - The Elixir implementation
  • Elixir - The programming language
  • WSL team at Microsoft for cross-platform development capabilities