Skip to content

BjornMelin/dev-skills / archive/skills/browser-workbench-setup

browser-workbench-setup

Verified

Set up browser automation and UI QA for a new repository using playwright-interactive as the primary interactive tool and agent-browser as the secondary CLI smoke-check tool. Use when a user wants to bootstrap browser testing, screenshots, auth-state reuse, or local UI debugging conventions in a fresh repo.

FileKindSize
SKILL.mdskill md8.1 KB
agents/openai.yamlconfig631 B
archive.jsonconfig1.1 KB
references/agent-browser.mdmarkdown3.2 KB
references/auth-auth0.mdmarkdown3.5 KB
references/auth-clerk.mdmarkdown3.0 KB
references/auth-neon.mdmarkdown3.3 KB
references/auth-supabase.mdmarkdown3.2 KB
references/playwright-interactive.mdmarkdown2.6 KB

references/auth-clerk.md

View on GitHub
# 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 handled only by the `emailAddress` parameter, which creates a server-side token and bypasses email verification and MFA. The `signInParams` path completes first-factor verification only and does not support MFA; use `emailAddress` when the instance has MFA enabled.

## 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
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall