Webwright Documentation

Final scripts located at final_runs/run_<id>/final_script.py must follow a specific instrumentation pattern for logging and screenshots:

1. Screenshots: Save to final_runs/run_<id>/screenshots/final_execution_<step>_<action>.png.
2. Logging: Reset and append to final_runs/run_<id>/final_script_log.txt.
3. Final Output: Print the final extracted datum at the end of the log using the format FINAL_RESPONSE: <value>.

Use a log(step, msg) helper to ensure consistency.

import asyncio, os
from pathlib import Path
from playwright.async_api import async_playwright

RUN_DIR = Path(__file__).parent
SCREENSHOTS = RUN_DIR / "screenshots"
SCREENSHOTS.mkdir(parents=True, exist_ok=True)
LOG = RUN_DIR / "final_script_log.txt"
LOG.write_text("")  # reset

def log(step: int, msg: str) -> None:
    line = f"step {step} action: {msg}\n"
    LOG.open("a").write(line)
    print(line, end="")

async def main():
    async with async_playwright() as playwright:
        browser = await playwright.firefox.launch(headless=True)
        context = await browser.new_context(viewport={"width": 1280, "height": 1800})
        page = await context.new_page()

        await page.goto("<START_URL>", wait_until="domcontentloaded")
        await page.screenshot(path=str(SCREENSHOTS / "final_execution_1_open_start_page.png"))
        log(1, "open start page")

        # ... apply CP1, screenshot, log ...
        # ... apply CP2, screenshot, log ...

        # End of run: capture the final datum visibly and in the log
        final_value = "<extracted price / code / winner>"
        with LOG.open("a") as f:
            f.write(f"\nFINAL_RESPONSE: {final_value}\n")

        await browser.close()

asyncio.run(main())

The craft command allows you to parameterize a natural-language web task into a reusable Python CLI tool. The process transforms a specific, concrete task into a script (final_script.py) that can be executed with different arguments via argparse.

Workflow for crafting a tool:

1. Identify parameters: Determine which values (search terms, locations, dates, etc.) should be variable. Keep site-specific constants (start URL, selectors) hard-coded.
2. Create plan.md: Define a # Parameters table with name | type | source phrase | default | allowed/format.
3. Author final_script.py:
   • Place in a new directory: final_runs/run_<id>/.
   • Implement a reusable function (e.g., def search_domain(arg_a, arg_b): ...).
   • Use argparse in the if __name__ == "__main__": block to mirror function arguments.
   • Ensure the script is side-effect-free at import time (no browser/network activity at top-level).
   • The first log line after reset must be: step 0 params: <name>=<value> ....
   • Use standard instrumentation: 1280×1800 viewport, headless local Firefox, no full_page=True.
4. Verify: Run the script with no arguments to ensure it reproduces the original task, then run with --help to confirm the CLI interface.

When writing automation scripts for Webwright, use the following skeleton.

Critical Rules:

• Always set the viewport to viewport={"width": 1280, "height": 1800}.
• Never call page.screenshot(full_page=True) for exploration, debugging, or final runs.
• Each run must be fresh: navigate from the start URL and reconstruct state in code; there is no persistent session.

import asyncio
import os
from pathlib import Path

from playwright.async_api import async_playwright

WORKSPACE = Path(os.environ.get("WORKSPACE_DIR", "."))
SCREENSHOTS = WORKSPACE / "screenshots"
SCREENSHOTS.mkdir(parents=True, exist_ok=True)

async def main():
    async with async_playwright() as playwright:
        browser = await playwright.firefox.launch(headless=True)
        context = await browser.new_context(viewport={"width": 1280, "height": 1800})
        page = await context.new_page()

        await page.goto("<START_URL>", wait_until="domcontentloaded")
        await page.screenshot(path=str(SCREENSHOTS / "explore_1_start.png"))

        print("URL:", page.url)
        print("TITLE:", await page.title())

        # Inspect the region you care about with an ARIA snapshot
        snapshot = await page.locator("body").aria_snapshot()
        print("ARIA:", snapshot)

        await browser.close()

asyncio.run(main())