Browser Automation Runner

Project roadmap

1. 01

   Design the runner

   ~2.5h

   Write DESIGN.md: a job has a name, a Playwright script, the allowed domains, a timeout, a retry count and an approval status; a run has a status (queued, running, passed, failed, timed out or cancelled), the attempt number, timing, logs and artifacts. Describe the isolation (a new browser context per run, no access to other runs' data, network requests limited to allowed domains, and scripts run in a separate process), limits, and how artifacts are stored and cleaned up. Done when: DESIGN.md covers jobs, runs, isolation and limits.

2. 02

   Run one job with Playwright

   ~2.5h

   Write a runner that launches Chromium with Playwright, creates a new context with video and tracing on, blocks every request to a domain not on the job's list (with page.route), runs the job's script with the page, and saves screenshots, the video and the trace to the run's folder. Enforce the timeout and always close the browser. Done when: a sample job against a local test site produces artifacts, and requests to other domains are blocked.

3. 03

   Isolate job scripts

   ~2h

   Run each job in a child process (or a worker thread) with a memory limit and a hard kill after the timeout, so a stuck or misbehaving script can't affect the service. Only approved scripts can run, and scripts are stored with a hash so a changed script needs approval again. Done when: an infinite loop in a job is killed at the timeout, and an unapproved or changed job is refused.

4. 04

   Queue and retry runs

   ~2h

   Build a queue stored in SQLite that runs at most N jobs at once, retries failures up to the job's retry count (marking a run flaky when it passes on retry), and records every attempt. Add scheduled runs (for example every hour). On restart, mark runs that were running as interrupted and requeue them. Done when: several queued jobs run with the concurrency limit, and flaky jobs are retried.

5. 05

   Build the API and dashboard

   ~3h

   Add a REST API to create and approve jobs, trigger runs, list runs and fetch artifacts, protected with a token and approval restricted to an admin role. Build a React dashboard with Vite showing jobs and their recent results, a run's details with logs, screenshots, the video player and a link to download the trace (to open in the Playwright trace viewer). Done when: jobs can be managed and runs inspected from the dashboard.

6. 06

   Manage storage and alerts

   ~1.5h

   Delete artifacts older than a retention period, limit total storage, and keep only screenshots for passing runs (videos and traces for failures). Send a webhook alert when a scheduled job starts failing and when it recovers. Done when: old artifacts are cleaned up, and alerts are sent on state changes.

7. 07

   Test it

   ~2h

   Write tests with a local test site: a passing job, a failing job, a flaky job passing on retry, a timeout, blocked domains, unapproved and changed scripts, recovery after a restart, and artifact cleanup. Done when: all tests pass.

Resources

• DocsPlaywright documentation
• DocsPlaywright: network interception (page.route)
• DocsPlaywright: trace viewer
• DocsNode.js: child processes
• DocsVite: getting started