Browser Workbench Setup

Browser Workbench Setup

Use this skill to configure a new repository for browser-based UI work with the smallest durable setup.

Default tool split:

• playwright-interactive is the primary tool for iterative UI/UX work, auth flows, layout debugging, screenshots, and deeper investigation.
• agent-browser is the secondary tool for quick smoke checks, annotated screenshots, fast snapshots, and lightweight CLI automation.

Do not create a custom framework, wrapper package, or shared browser helper layer unless the user explicitly asks for one.

Load references only as needed:

• Read references/playwright-interactive.md when setting up the primary interactive workflow.
• Read references/agent-browser.md when setting up CLI smoke checks, session persistence, or annotated screenshots.
• Read exactly one provider file when the repository auth stack is clear:
• references/auth-clerk.md
• references/auth-supabase.md
• references/auth-auth0.md
• references/auth-neon.md

If the repo uses Neon with an upstream identity provider such as Clerk or Auth0, read both auth-neon.md and the upstream provider file. Neon may be the database auth verifier while the browser login still belongs to the upstream provider.

Preconditions

• Confirm playwright-interactive is installed and available in Codex.
• Confirm agent-browser CLI is installed.
• Confirm Codex has js_repl = true.
• Confirm the session can run with danger-full-access when using playwright-interactive.

If any of those are missing, fix that first before touching the repository.

Setup Goals

For a normal web repository, finish with:

• repo-local Playwright dependency installed with the repository's package manager
• browser binaries installed
• stable artifact directories for screenshots, traces, and auth state
• ignore rules for local browser artifacts
• a clear convention for when to use playwright-interactive vs agent-browser

Workflow

1. Inspect the repository first.

• Read package.json, lockfiles, and any repo AGENTS.md.
• Detect the package manager from the repo, not from habit.
• Reuse existing test/artifact conventions if they already exist.
• Detect the auth provider from dependencies, env vars, routes, and middleware before making changes.
• Provider detection hints:
• Clerk: @clerk/, CLERK_, NEXT_PUBLIC_CLERK_
• Supabase: @supabase/, SUPABASE_URL, SUPABASE_, createBrowserClient, createServerClient
• Auth0: @auth0/, AUTH0_, /auth/login, Auth0Client
• Neon Auth: neon_auth, Neon auth endpoints, Neon JWT/JWKS setup, provider-owned auth integration

2. Install Playwright in the repo with the repo's package manager.

• For Bun repos, prefer:

   bun add -d playwright
   bunx playwright install chromium

• For pnpm/npm/yarn repos, match the repo standard.
• Install only what is needed. Default browser is Chromium unless the user asked for more.

3. Create a minimal artifact convention.

• Preferred defaults:
• output/playwright/screenshots/
• output/playwright/traces/
• output/playwright/auth/
• output/agent-browser/
• Reuse an existing reports/ or output/ convention if the repo already has one.

4. Add ignore rules for local-only artifacts.

• Typical entries:

   output/playwright/
   output/agent-browser/
   playwright/.auth/

• Do not add duplicate ignore entries.

5. Standardize auth-state handling.

• Prefer Playwright storageState for authenticated iteration and reusable test sessions.
• Use agent-browser profiles or session names only for quick local smoke work.
• Keep auth files out of git.
• Prefer provider-supported test helpers when they exist.
• If the provider has no first-party Playwright helper, prefer seeded test users plus saved browser state.
• Avoid MFA in automated browser runs unless the provider explicitly supports it in test helpers.

6. Keep the responsibility split explicit.

• Use playwright-interactive for:
• serious interactive debugging
• auth-heavy flows
• desktop/mobile passes
• console/network inspection
• screenshots and trace evidence
• Use agent-browser for:
• quick smoke checks
• annotated screenshots
• fast snapshots
• simple DOM or screenshot diffs

7. Avoid unnecessary additions.

• Do not add Playwright test scaffolding unless the user asked for formal test coverage.
• Do not add helper scripts, custom CLIs, or wrapper packages by default.
• Do not add CI config unless the user asked for CI.
• For auth setup, add only the minimum repo changes needed to make interactive browser work repeatable.
• User-level tools such as ~/.agent-browser/config.json belong outside the repo.

Provider Routing

After the initial repo scan:

• Read playwright-interactive.md for the primary workflow.
• Read agent-browser.md for CLI setup and persistence.
• Read one provider auth file for the active identity stack.
• For Neon-backed repos:
• if Neon Auth owns the user lifecycle, read auth-neon.md
• if Neon is only verifying JWTs from Clerk/Auth0/etc., read auth-neon.md plus that upstream provider file

Do not load every provider reference by default.

Automation Standard

When the user asks to set this up in a repo, complete the work end to end:

• install the repo-local Playwright dependency
• install browser binaries
• create artifact directories
• add ignore rules
• add or align formal auth bootstrap only if the repo already has Playwright tests or the user asked for them
• configure agent-browser persistence with either a profile path or a session name convention
• report the exact auth path chosen and why

Preferred Defaults

When no repo convention conflicts:

• install only playwright
• install only Chromium first
• keep artifacts under output/
• use repo-local ignores, not global git excludes
• keep setup changes small and reviewable

Deliverable

When you finish, report:

• package manager used
• dependency added
• directories added
• ignore rules added
• any user-level config that must exist outside the repo
• provider-specific auth path selected
• the exact command the user should run first with playwright-interactive

First-Run Prompt

After setup, suggest a first real task such as:

Use $playwright-interactive to open the local app, verify sign-in, test theme persistence, run desktop and mobile passes, and capture screenshots.

Agent Browser Setup

Use this file when configuring the secondary CLI browser workflow.

Purpose

agent-browser is the secondary tool for:

• quick smoke checks
• annotated screenshots
• accessibility-tree snapshots
• fast console and page-error reads
• lightweight DOM or screenshot diffs

Official source:

• https://github.com/vercel-labs/agent-browser

Key upstream capabilities from the README:

• session names for saved state
• persistent profiles
• annotated screenshots
• console and page error inspection
• snapshot and screenshot diff commands

Install and Baseline

Install once at the user level and install Chromium:

agent-browser install

On Linux, if needed:

agent-browser install --with-deps

User-Level Config

Preferred user config at ~/.agent-browser/config.json:

{
  "headed": true,
  "contentBoundaries": true,
  "maxOutput": 50000
}

This belongs outside the repo.

Repo-Level Convention

Preferred repo artifact directory:

• output/agent-browser/

Ignore it in git:

output/agent-browser/

Persistence Standard

Choose one of these:

• --profile <path> when you want full browser persistence including cookies, local storage, IndexedDB, and service workers
• --session-name <name> when you want lighter automatic session restore through agent-browser’s saved state

Preferred defaults for repo work:

• quick repeated local UI checks: --profile ./output/agent-browser/profile
• lightweight smoke path reuse: --session-name <repo-name>

Use profiles when auth flows are complex or rely on richer browser state.

Auth Handling

For most real apps, sign in normally once, then persist the authenticated state with a profile or session name.

Do not rely on the credential vault flow unless the app uses a simple username/password form that the CLI can drive cleanly. For OAuth-heavy or redirect-heavy apps, browser-state persistence is more reliable.

Recommended Commands

Quick smoke:

agent-browser --profile ./output/agent-browser/profile open http://127.0.0.1:3000
agent-browser snapshot -i
agent-browser console
agent-browser errors
agent-browser screenshot --annotate ./output/agent-browser/home.png

Reuse session later:

agent-browser --profile ./output/agent-browser/profile open http://127.0.0.1:3000/dashboard

Role Split

If the task becomes stateful, complex, auth-heavy, or visually subtle, switch to playwright-interactive.

Do not force agent-browser to be the primary debugger.

Auth0 Setup

Use this file when the repository uses Auth0 in the browser.

Official Docs

• Next.js quickstart: https://auth0.com/docs/quickstart/webapp
• Application settings: https://auth0.com/docs/get-started/applications/application-settings
• Management API access tokens: https://auth0.com/docs/secure/tokens/access-tokens/management-api-access-tokens
• Manage users with the Management API: https://auth0.com/docs/manage-users/user-accounts/manage-users-using-the-management-api
• Create users: https://auth0.com/docs/manage-users/user-accounts/create-users
• Auth0 Next.js SDK repo and examples: https://github.com/auth0/nextjs-auth0

Current Official Guidance

Auth0 does not currently provide the same first-party Playwright helper experience that Clerk does.

For browser automation, the reliable default is:

• use a dedicated database-connection test user
• sign in through the real app UI
• save browser state for reuse

If the repo uses @auth0/nextjs-auth0, there is also a testing utility for generating session cookies in integration-style tests:

• @auth0/nextjs-auth0/testing
• generateSessionCookie

Use that only when formal test setup is explicitly in scope and the repo already uses the Next.js SDK.

Repo Detection

Typical signals:

• @auth0/nextjs-auth0
• AUTH0_DOMAIN
• AUTH0_CLIENT_ID
• AUTH0_CLIENT_SECRET
• AUTH0_SECRET

playwright-interactive Pattern

Preferred interactive path:

1. Create or seed a dedicated database-connection user. 2. Sign in through the app UI. 3. Wait for the authenticated landing page. 4. Save storageState to:

• output/playwright/auth/auth0-user.json

Preferred account shape:

• dedicated test user
• standard database connection
• MFA disabled unless the repo explicitly supports automated MFA testing

Avoid social-login-only paths for deterministic local browser automation.

Formal Playwright Setup

Choose one:

• normal UI login once + saved storageState
• for Next.js Auth0 repos, optionally use generateSessionCookie in lower-level integration-style tests

If you need to create users automatically:

• obtain a Management API access token
• use the Management API with the minimum scopes needed
• create users only in the intended database connection

Do not add management-token setup to the repo unless the user explicitly wants automated test-user provisioning.

agent-browser Pattern

Use a persistent profile:

agent-browser --profile ./output/agent-browser/profile open http://127.0.0.1:3000

Then complete login through the app UI and reuse the profile.

Prefer profile persistence over session-name persistence because Auth0 app flows often involve redirect chains and cookie state that are easier to preserve in a full profile.

Automation Preference

When automating setup in an Auth0 repo:

• install Playwright and Chromium
• create artifact directories and ignore rules
• prefer real UI login plus saved browser state
• add Auth0 test-user provisioning only if the user asked for formal repeatable provisioning

Clerk Auth Setup

Use this file when the repository uses Clerk in the browser.

Official Docs

• Testing overview: https://clerk.com/docs/guides/development/testing/overview
• Playwright overview: https://clerk.com/docs/guides/development/testing/playwright/overview
• Playwright test helpers: https://clerk.com/docs/guides/development/testing/playwright/test-helpers
• Authenticated flows with Playwright: https://clerk.com/docs/guides/development/testing/playwright/test-authenticated-flows

Current Official Guidance

Clerk has first-party Playwright helpers. This is the best-supported provider in this set for formal Playwright auth setup.

Key points from the docs:

• use clerkSetup() in global setup
• use setupClerkTestingToken() at the start of tests that touch auth pages
• clerk.signIn() supports password, phone_code, and email_code
• navigate to an unprotected page that loads Clerk before calling the helper
• MFA is not supported by clerk.signIn()

Repo Detection

Typical signals:

• @clerk/nextjs
• @clerk/testing/playwright
• CLERK_SECRET_KEY
• NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY

playwright-interactive Pattern

For interactive work:

1. Start the app. 2. Open an unprotected page that loads Clerk. 3. If the repo already includes Clerk testing helpers, prefer them. 4. Otherwise sign in through the normal UI with a dedicated non-MFA test user. 5. Save storageState to:

• output/playwright/auth/clerk-user.json

Preferred account shape:

• dedicated test user
• password auth if available
• MFA disabled

If the product requires MFA, keep interactive browser setup separate from formal test auth and mark any fully automated login path UNVERIFIED unless the repo already supports it.

Formal Playwright Setup

If the repo already has or needs Playwright tests:

• add @clerk/testing/playwright
• create one serial global setup file using clerkSetup()
• authenticate once and save storage state
• reuse that storage state in authenticated tests

Do not re-click the full sign-in UI in every test.

agent-browser Pattern

agent-browser has no Clerk-specific first-party helper.

Use this pattern:

1. Open the app with a persistent profile:

• agent-browser --profile ./output/agent-browser/profile open http://127.0.0.1:3000

2. Complete sign-in through the normal app UI. 3. Reuse the profile for later smoke checks.

Prefer --profile over --session-name for Clerk because redirects and local state are often richer than simple cookie-only persistence.

Automation Preference

When automating setup in a Clerk repo:

• install Playwright
• add artifact directories and ignore rules
• if formal browser tests are in scope, wire in Clerk’s official Playwright helpers
• otherwise keep auth bootstrap light and rely on saved storageState for interactive work

Neon Auth Setup

Use this file when the repository uses Neon Auth directly or uses Neon as the JWT-verifying database backend.

Official Docs

• Neon API reference: https://api-docs.neon.tech/
• Add JWKS URL: https://api-docs.neon.tech/reference/addprojectjwks
• Create Auth Provider SDK keys: https://api-docs.neon.tech/reference/createneonauthprovidersdkkeys
• Create Neon Auth integration: https://api-docs.neon.tech/reference/createneonauthintegration
• Create auth user: https://api-docs.neon.tech/reference/createneonauthnewuser
• Branch auth OAuth provider endpoint: https://api-docs.neon.tech/reference/addbranchneonauthoauthprovider

Important Model

Neon can appear in two different roles:

1. Neon-managed or provider-owned auth for the application itself 2. Neon database verification of JWTs issued by an upstream provider such as Clerk or Auth0

Do not confuse them.

If the browser login belongs to Clerk/Auth0/Supabase, the browser automation instructions should come from that provider file. Neon then matters for backend JWT verification and project configuration, not for the browser sign-in UI itself.

Repo Detection

Typical signals:

• Neon auth endpoints or setup scripts
• Neon auth provisioning in project automation
• JWKS configuration for database auth
• external provider JWTs accepted by Neon

Browser Automation Pattern

If Neon Auth owns the user lifecycle:

• create or provision a test user through the Neon-managed auth path
• sign in through the app UI
• save Playwright storageState or an agent-browser profile

If Neon only verifies JWTs from another provider:

• follow the upstream provider auth instructions for browser login
• verify that Neon’s JWT configuration matches that provider

Neon JWT Verification Pattern

For external-provider JWT auth to Neon:

• configure the project JWKS URL
• set provider_name
• set jwt_audience when required
• limit accepted roles and branches when appropriate

This is not a browser automation step, but it is often a prerequisite for the authenticated app flow to work correctly against Neon-backed data.

playwright-interactive Pattern

Preferred interactive path:

• if Neon Auth is the browser identity provider, log in normally and save:
• output/playwright/auth/neon-user.json
• if Neon is downstream of Clerk/Auth0/etc., save storage state under the upstream provider name instead and separately validate Neon JWT config

agent-browser Pattern

Use a persistent profile:

agent-browser --profile ./output/agent-browser/profile open http://127.0.0.1:3000

Then:

• complete the browser login through the app’s actual auth UI
• reuse the profile for smoke checks

Automation Preference

When automating setup in a Neon repo:

• first determine whether Neon is the browser-facing auth provider or only the backend verifier
• if browser-facing, treat it like the primary provider and persist browser state normally
• if backend-only, configure browser auth from the upstream provider and validate Neon JWKS/JWT settings separately

Current Caution

Some older Neon auth endpoints are marked deprecated in the current API reference. Prefer current branch-scoped endpoints when available over older project-scoped auth setup flows.

Supabase Auth Setup

Use this file when the repository uses Supabase Auth in the browser.

Official Docs

• Auth with email/password: https://supabase.com/docs/guides/auth/passwords
• Next.js server-side auth: https://supabase.com/docs/guides/auth/server-side/nextjs
• @supabase/ssr: https://supabase.com/docs/guides/auth/server-side
• JavaScript client auth reference: https://supabase.com/docs/reference/javascript/auth-signinwithpassword

Current Official Guidance

Key points:

• browser login typically uses signInWithPassword()
• Next.js SSR setups should use @supabase/ssr
• SSR session refresh depends on correct cookie synchronization in middleware
• admin user creation is available through supabase.auth.admin.createUser()

Repo Detection

Typical signals:

• @supabase/supabase-js
• @supabase/ssr
• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY

playwright-interactive Pattern

Preferred interactive path:

1. Seed or create a dedicated test user. 2. Sign in through the app UI using email/password. 3. Wait until the authenticated landing page is stable. 4. Save storageState to:

• output/playwright/auth/supabase-user.json

Preferred account shape:

• seeded dedicated test user
• password auth enabled
• email already confirmed if the app requires confirmation

Avoid magic-link-only flows for deterministic browser automation unless the repo already has an inbox/test-email harness.

Formal Playwright Setup

Supabase does not provide a first-party Playwright helper like Clerk.

Preferred formal path:

• create or seed a test user with admin APIs or project seed logic
• authenticate once through the real UI
• save storageState
• reuse it for authenticated tests

If the repo already exposes server utilities for seeding users, prefer those over writing one-off scripts.

SSR Caution

For Next.js repos using @supabase/ssr, do not disturb the existing middleware/session-refresh path while adding browser automation.

If you touch auth middleware, preserve the cookie handoff exactly. Session drift between server and browser is a common failure mode.

agent-browser Pattern

Use a persistent profile:

agent-browser --profile ./output/agent-browser/profile open http://127.0.0.1:3000/login

Then:

• sign in through the UI
• reuse the same profile for follow-up smoke checks

Use --profile rather than --session-name when the app depends on richer browser state or SSR cookie refresh behavior.

Automation Preference

When automating setup in a Supabase repo:

• add Playwright and Chromium
• create artifact directories and ignore rules
• preserve the repo’s SSR cookie/session architecture
• prefer seeded test users plus saved browser state

Playwright Interactive Setup

Use this file when the repository needs the primary interactive browser workflow.

Purpose

playwright-interactive is the primary tool for:

• iterative UI/UX development
• auth-heavy browser flows
• desktop and mobile passes
• deeper debugging with direct Playwright control
• screenshots and traces that support final signoff

Official skill source:

• https://github.com/openai/skills/blob/main/skills/.curated/playwright-interactive/SKILL.md

Official Playwright docs:

• Auth and storage state: https://playwright.dev/docs/auth
• Emulation and devices: https://playwright.dev/docs/emulation
• Screenshots: https://playwright.dev/docs/screenshots
• Trace viewer: https://playwright.dev/docs/trace-viewer
• Videos: https://playwright.dev/docs/videos

Repo Setup

Match the repository package manager. For Bun-first repos:

bun add -d playwright
bunx playwright install chromium

Optional:

bunx playwright install firefox webkit

Default artifact layout:

• output/playwright/screenshots/
• output/playwright/traces/
• output/playwright/auth/

Ignore them in git:

output/playwright/
playwright/.auth/

Persistence Standard

For interactive browser work, the default persistence primitive is Playwright storageState.

Preferred file location:

• output/playwright/auth/<provider>-user.json

Use storageState when:

• the repo has a stable login flow
• the session should be reused across repeated debugging runs
• you want deterministic auth setup for later formal tests

Do not commit storage state files.

First Session Pattern

1. Start the local app. 2. Open the unprotected landing or sign-in page in Playwright. 3. Complete sign-in using the provider-specific path. 4. Save storageState after the authenticated landing page is stable. 5. Reuse that file for follow-up sessions instead of logging in again.

When to Add Formal Test Bootstrap

Only add repo-local Playwright auth bootstrap files when at least one is true:

• the repo already has Playwright tests
• the user asked for formal browser tests
• auth login is slow enough that repeated UI login is wasteful

If you add formal bootstrap, keep it minimal:

• one auth setup file
• one storage-state file path convention
• no helper framework unless the provider officially supplies one

Desktop and Mobile Standard

For signoff work:

• run one deterministic desktop pass
• run one mobile-emulated pass
• capture screenshots for both when the UI changed

Use explicit viewport mode first. Use native window mode only as a second pass when the bug depends on real browser chrome or OS window sizing.