Headless WebView Testing

AuroraView provides multiple strategies for running WebView tests in headless/CI environments.

Overview

Mode	Platform	Use Case	Pros	Cons
Playwright	All	UI testing, CI	Fast, reliable, cross-platform	Not real WebView
Xvfb	Linux	Integration testing	Real WebView	Linux only
WebView2 CDP	Windows	WebView2 testing	Real WebView2	Windows only

Quick Start

Playwright Mode (Recommended)

from auroraview.testing.headless_webview import HeadlessWebView

with HeadlessWebView.playwright() as webview:
    webview.goto("https://example.com")
    webview.click("#button")
    assert webview.text("#result") == "Success"

Use Microsoft Edge channel on Windows (optional)

This improves compatibility coverage with WebView2/Edge behavior while still staying fully headless.

# Prefer system Edge for Playwright on Windows
$env:AURORAVIEW_PLAYWRIGHT_CHANNEL = "msedge"

from auroraview.testing.headless_webview import HeadlessWebView

with HeadlessWebView.playwright(channel="msedge") as webview:
    webview.load_html("<h1>Hello Edge</h1>")
    assert webview.text("h1") == "Hello Edge"

Auto-Detection Mode

from auroraview.testing.headless_webview import HeadlessWebView

# Automatically selects the best mode for current environment
with HeadlessWebView.auto() as webview:
    webview.goto("https://example.com")

Installation

Playwright (All Platforms)

pip install playwright
playwright install chromium

Xvfb (Linux)

# Debian/Ubuntu
sudo apt-get install xvfb

# Fedora/CentOS
sudo dnf install xorg-x11-server-Xvfb

# Arch Linux
sudo pacman -S xorg-server-xvfb

Pytest Integration

Using Fixtures

# conftest.py
pytest_plugins = ["auroraview.testing.pytest_plugin"]

# test_example.py
import pytest

@pytest.mark.webview
def test_button_click(headless_webview):
    headless_webview.load_html("<button id='btn'>Click</button>")
    headless_webview.click("#btn")

@pytest.mark.playwright
def test_with_playwright(playwright_webview):
    playwright_webview.goto("https://example.com")
    assert playwright_webview.text("h1") == "Example Domain"

Available Fixtures

Fixture	Description
headless_webview	Auto-detected mode
playwright_webview	Playwright mode
xvfb_webview	Xvfb mode (Linux)
webview2_cdp_webview	WebView2 CDP mode
playwright_browser	Session-scoped browser
playwright_page	Function-scoped page

CI/CD Configuration

GitHub Actions

name: WebView Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      # Linux: Install Xvfb and WebKitGTK
      - name: Install Linux dependencies
        if: runner.os == 'Linux'
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            xvfb \
            libwebkit2gtk-4.1-dev \
            libgtk-3-dev

      # Install Playwright
      - name: Install Playwright
        run: |
          pip install playwright
          playwright install chromium

      # Install package
      - name: Install package
        run: pip install -e ".[test]"

      # Run tests with Playwright (all platforms)
      - name: Run Playwright tests
        run: pytest tests/ -m playwright -v

      # Run tests with Xvfb (Linux only)
      - name: Run Xvfb tests (Linux)
        if: runner.os == 'Linux'
        run: xvfb-run pytest tests/ -m xvfb -v

Using xvfb-run

On Linux CI, use xvfb-run to run tests in a virtual display:

# Run all tests
xvfb-run pytest tests/

# Run specific test file
xvfb-run pytest tests/test_webview.py

# With custom display settings
xvfb-run --server-args="-screen 0 1920x1080x24" pytest tests/

WebView2 CDP Testing

Starting WebView2 with CDP

Set the environment variable before starting your WebView2 application:

# PowerShell
$env:WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS = "--remote-debugging-port=9222"

# Bash
export WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS="--remote-debugging-port=9222"

Connecting to WebView2

from auroraview.testing.headless_webview import HeadlessWebView

# Connect to running WebView2 instance
with HeadlessWebView.webview2_cdp("http://localhost:9222") as webview:
    webview.goto("https://example.com")

Environment Variable

Set WEBVIEW2_CDP_URL to auto-connect:

export WEBVIEW2_CDP_URL="http://localhost:9222"

# Auto-detection will use WebView2 CDP
with HeadlessWebView.auto() as webview:
    webview.goto("https://example.com")

Advanced Usage

Custom Options

from auroraview.testing.headless_webview import HeadlessWebView, HeadlessOptions

options = HeadlessOptions(
    timeout=60.0,
    width=1920,
    height=1080,
    inject_bridge=True,
    screenshot_on_failure=True,
    screenshot_dir="test-artifacts",
    slow_mo=100,  # Slow down for debugging
)

webview = HeadlessWebView.playwright(
    timeout=options.timeout,
    width=options.width,
    height=options.height,
)

Direct Playwright Access

from auroraview.testing.headless_webview import HeadlessWebView

with HeadlessWebView.playwright() as webview:
    # Access underlying Playwright page
    page = webview.page

    # Use full Playwright API
    page.locator("#button").click()
    page.wait_for_load_state("networkidle")
    page.screenshot(path="screenshot.png")

Testing AuroraView Bridge

with HeadlessWebView.playwright(inject_bridge=True) as webview:
    webview.load_html("<div id='app'></div>")

    # Test bridge is injected
    result = webview.evaluate("window.auroraview._testMode")
    assert result == True

    # Test bridge API
    result = webview.evaluate("typeof window.auroraview.call")
    assert result == "function"

Troubleshooting

Playwright Issues

# Reinstall browsers
playwright install --force chromium

# Check installation
playwright --version

Xvfb Issues

# Check if Xvfb is running
ps aux | grep Xvfb

# Start Xvfb manually
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99

# Run tests
pytest tests/

WebView2 CDP Issues

# Check if CDP port is open
Test-NetConnection -ComputerName localhost -Port 9222

# List available targets
curl http://localhost:9222/json

References

• Tauri WebDriver CI Guide
• Playwright Documentation
• Xvfb Manual
• Chrome DevTools Protocol