Getting Started

This guide will help you get up and running with Playwriter in just a few minutes.

Installation

Add playwriter to your list of dependencies in mix.exs:

def deps do
  [
    {:playwriter, "~> 0.1.0"}
  ]
end

Then fetch dependencies:

mix deps.get

Choose Your Mode

Playwriter supports three modes of operation:

Quick Start: Local Mode

For headless browser automation on your local machine:

# One-time setup: install Playwright
mix playwriter.setup

Then in your code:

{:ok, html} = Playwriter.fetch_html("https://example.com")

Quick Start: Windows Mode (WSL to Windows)

Recommended for WSL users. See visible browsers on your Windows desktop:

1. One-time setup (installs Playwright on Windows):

powershell.exe -ExecutionPolicy Bypass -File priv/scripts/start_server.ps1 -Install

2. Use from Elixir:

{:ok, html} = Playwriter.fetch_html("https://example.com", mode: :windows)

A browser window will open on Windows!

Running Examples

# Local mode (headless)
mix run examples/fetch_html.exs --local

# Windows mode (visible browser on Windows)
mix run examples/windows_mode.exs

Available examples:

• examples/fetch_html.exs - Fetch HTML content
• examples/screenshot.exs - Take screenshots
• examples/interaction.exs - Form filling and clicking
• examples/windows_mode.exs - WSL-to-Windows demo

Setup Commands

Local Mode Setup

# Install Playwright and Chromium
mix playwriter.setup

# Install a different browser
mix playwriter.setup --browser firefox

# Install all browsers
mix playwriter.setup --browser all

Windows Mode Setup

On Windows, you need Node.js and Playwright installed in %TEMP%\playwriter-server:

# From WSL - runs setup on Windows
powershell.exe -ExecutionPolicy Bypass -File priv/scripts/start_server.ps1 -Install

Or manually on Windows:

# Install Node.js (if not already installed)
winget install OpenJS.NodeJS.LTS

# Create and setup server directory
cd $env:TEMP
mkdir playwriter-server
cd playwriter-server
npm init -y
npm install playwright
npx playwright install chromium

Your First Script

Fetching HTML

# Local mode (default, headless)
{:ok, html} = Playwriter.fetch_html("https://example.com")

# Windows mode (visible on Windows desktop)
{:ok, html} = Playwriter.fetch_html("https://example.com", mode: :windows)

IO.puts("Got #{byte_size(html)} bytes of HTML")

Taking Screenshots

# Local (headless)
{:ok, png_data} = Playwriter.screenshot("https://example.com")
File.write!("screenshot.png", png_data)

# Windows (visible)
{:ok, png_data} = Playwriter.screenshot("https://example.com", mode: :windows)
File.write!("screenshot.png", png_data)

Interactive Sessions

For complex workflows, use with_browser/2:

{:ok, result} = Playwriter.with_browser([mode: :windows], fn ctx ->
  # Navigate
  :ok = Playwriter.goto(ctx, "https://example.com")

  # Click a link
  :ok = Playwriter.click(ctx, "a")

  # Get content
  {:ok, html} = Playwriter.content(ctx)
  html
end)

The browser is automatically closed when the function completes, even if an error occurs.

Configuration Options

All functions accept options to customize behavior:

Playwriter.fetch_html("https://example.com",
  mode: :windows,         # :local, :windows, or :remote
  headless: false,        # show browser window (local mode only)
  browser_type: :chromium,# :chromium, :firefox, :webkit (local mode)
  timeout: 60_000         # milliseconds
)

Troubleshooting

"Playwright executable not found"

Run the setup task:

mix playwriter.setup

"Timeout waiting for transport" (Windows mode)

Ensure Playwright is installed on Windows:

powershell.exe -ExecutionPolicy Bypass -File priv/scripts/start_server.ps1 -Install

"Cannot find module 'playwright'" (Windows mode)

Manually install on Windows:

cd $env:TEMP\playwriter-server
npm install playwright
npx playwright install chromium

Next Steps

• Architecture Overview - Understand how Playwriter works
• Function Reference - Complete function documentation
• Transport Layer - Learn about local, windows, and remote transports
• WSL-Windows Integration - Detailed Windows mode setup
• Examples - Real-world usage examples
• Troubleshooting - Common issues and fixes