Browser Automation skill for Codex

A browser script is done when it runs headless unattended, waits on page state rather than on timers, never handles the user’s password in code, stops before any irreversible click unless the user has approved it, and leaves a trace you can open when it fails.

Decide first

Situation	Choice
The site has an API or the page calls a JSON endpoint	Use HTTP instead ($web-scraping); faster and sturdier
Writing automated tests for your own app	$playwright-e2e (test runner, fixtures, CI)
Screenshots or social images at scale	$screenshot-automation
Chores on third-party sites: export, upload, form fill, download	This skill, Playwright library API
Existing Selenium script that works	Keep it; migrate only when flakiness justifies the rewrite

Default to Python sync API for one-off chores and Node for projects already on Node. Read AGENTS.md for the project’s runtime. Install needs network (pip install playwright then playwright install chromium, or npm i -D playwright then npx playwright install chromium); ask for approval if the Codex sandbox blocks it. Running the browser against a remote site also needs network.

Workflow

- [ ] 1. Record the flow once: npx playwright codegen https://portal.example.com
- [ ] 2. Have the user log in by hand in a headed browser; save storage state
- [ ] 3. Rewrite codegen output with role/label locators and explicit assertions
- [ ] 4. Add a dry-run flag that stops before the final submit / send / delete
- [ ] 5. Run headed once with the user watching, then headless with tracing on
- [ ] 6. Schedule it (cron / launchd / CI) and alert on failure

Authentication without touching passwords

Never write a password into the script, a prompt or a log. Let the user sign in once in a headed browser, then reuse the session:

# save_session.py - run once, interactively, by the user
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=False)
    ctx = browser.new_context()
    page = ctx.new_page()
    page.goto("https://portal.example.com/login")
    input("Log in in the browser window (including MFA), then press Enter here... ")
    ctx.storage_state(path=".auth/portal.json")
    browser.close()

Add .auth/ to .gitignore: the file holds live session cookies. When the session expires, the script should detect the login page and exit with a clear message asking the user to rerun save_session.py, not attempt to log in itself.

The task script

import argparse, sys
from datetime import date
from pathlib import Path
from playwright.sync_api import sync_playwright, expect, TimeoutError as PWTimeout

ap = argparse.ArgumentParser()
ap.add_argument("--headed", action="store_true")
ap.add_argument("--dry-run", action="store_true")
args = ap.parse_args()
out_dir = Path("downloads"); out_dir.mkdir(exist_ok=True)

with sync_playwright() as p:
    browser = p.chromium.launch(headless=not args.headed)
    ctx = browser.new_context(storage_state=".auth/portal.json", accept_downloads=True)
    ctx.tracing.start(screenshots=True, snapshots=True, sources=True)
    page = ctx.new_page()
    page.set_default_timeout(15_000)
    ok = False
    try:
        page.goto("https://portal.example.com/reports")
        if "login" in page.url:
            sys.exit("Session expired: run save_session.py again")
        page.get_by_label("Period").select_option("last-month")
        page.get_by_role("button", name="Generate").click()
        expect(page.get_by_role("status")).to_have_text("Ready", timeout=120_000)
        if args.dry_run:
            print("dry run: stopping before download"); ok = True
        else:
            with page.expect_download() as dl:
                page.get_by_role("link", name="Download CSV").click()
            target = out_dir / f"report-{date.today():%Y-%m}.csv"
            dl.value.save_as(target)
            print(f"saved {target}"); ok = True
    except PWTimeout as e:
        print(f"timed out: {e}", file=sys.stderr)
    finally:
        ctx.tracing.stop(path=None if ok else "trace-failed.zip")
        browser.close()
    sys.exit(0 if ok else 1)

Open a failure with playwright show-trace trace-failed.zip: it shows DOM snapshots, network and console for every step.

Locator rules

Use	Instead of
get_by_role("button", name="Save")	page.click("#btn-7f3a")
get_by_label("Email"), get_by_placeholder(...)	XPath from codegen
get_by_test_id(...) when the site has data-testid	nth-child chains
locator("tr").filter(has_text="Invoice 42")	Index into a table by position
expect(locator).to_be_visible() / to_have_text()	time.sleep(3) / wait_for_timeout

Playwright actions auto-wait for the element to be visible, enabled and stable. Replace every fixed sleep with a wait on the condition you actually need: page.wait_for_url, expect(...), or page.wait_for_response(lambda r: "/api/report" in r.url).

Irreversible actions

Submitting payments, sending messages, deleting records, publishing posts and accepting terms are outward-facing. The script must:

• default to --dry-run behaviour until the user has seen one headed run end to end;
• print exactly what will be submitted (recipient, amount, record ids) before the click;
• require an explicit --confirm flag (or interactive “yes”) for the final action.

Never automate CAPTCHAs, bot checks or MFA prompts. If one appears, stop and report.

Bulk form filling from a file

• Read rows with csv.DictReader; validate every row before opening the browser.
• Process one row per page load; after submit, assert the confirmation text and record the row id plus confirmation number in a results CSV.
• On failure, screenshot (page.screenshot(path=f"fail-{row_id}.png", full_page=True)) and continue; rerunning skips rows already in the results file.
• Throttle (a second or two between rows) so the site does not rate-limit or lock the account.

Gotchas

• Codegen locators are a starting point: it often emits brittle CSS for unlabelled controls.
• New tabs and popups: wrap the click in with page.expect_popup() as pop: and use pop.value.
• Iframes need page.frame_locator("iframe#payment") before locating inside them.
• File inputs: get_by_label("Upload").set_input_files("file.pdf"); no native dialog.
• Headless runs may get a different layout or a bot wall. Set a realistic viewport (viewport={"width": 1440, "height": 900}) and locale; if the site still blocks automation, stop rather than adding stealth plugins.
• Storage state does not include sessionStorage; apps that keep tokens there need a fresh login each run.
• macOS launchd and cron have no display: always run headless when scheduled.

Verification

• Run headed once with the user watching every step of the dry run.
• Run headless three times in a row; all succeed and produce identical output names.
• Expire the session (delete the state file copy) and confirm the script exits with the “run save_session.py” message instead of hanging.
• Confirm downloaded files are non-empty and parse (open the CSV, check the header row).

Report

**Automates:** monthly CSV export from portal.example.com/reports
**Run:** `python export_report.py` (add --headed to watch, --dry-run to stop before download)
**Auth:** saved session in .auth/portal.json (gitignored); rerun save_session.py when it expires
**Output:** downloads/report-YYYY-MM.csv
**On failure:** exit code 1 plus trace-failed.zip, open with `playwright show-trace`