Testing locally

Local testing points Cofactor at the app running on your machine — http://localhost:3000 — and drives it in a real browser, on your laptop, against the code you're editing right now. It's the fastest inner loop there is: change code, watch a browser exercise it, fix, repeat.

And the best way to drive that loop isn't by hand — it's through your coding agent.

Don't want to read this? Copy this prompt and give it to your agent:

Or read on to do it yourself.

Looking for staging behind a VPN instead? That's Testing private environments. This page is about your own machine.

01Set up the local environment

One command registers your local URL as an environment on your application:

cofactor local init --property <name|id> --url http://localhost:3000

If the app needs login, set up a credential in the same breath — give it a username, password, and (for unusual sign-in flows) a plain-language description the agent will follow:

cofactor local init --property <name|id> --url http://localhost:3000 \
  --credentials enter \
  --username you@example.com --password '••••••' \
  --login-instructions "Click Sign in, choose Email, then enter the username and password"

From then on: cofactor local start launches a browser against your local URL, cofactor local list shows what's set up, and cofactor local login refreshes an expired credential without re-initializing.

02Give your agent a browser

The browser-testing skill teaches your agent the whole driving loop — snapshot the page, find elements by accessibility ref, act, verify:

cofactor skill install browser-testing   # auto-detects Claude Code, Cursor, Copilot…

Now "test that the signup form validates emails" is a one-line request. The agent works in a tight loop:

cofactor session start --url http://localhost:3000
cofactor session snapshot --search "Sign up"        # accessibility tree + refs
cofactor session click --ref e15 --element "Sign up button"
cofactor session type --ref e7 --text "not-an-email" --submit
cofactor session snapshot --search "error|invalid"  # verify, don't assume
cofactor session console --only-errors              # and check under the hood

The browser is headed — you literally watch the agent work. Two quality-of-life commands worth knowing: cofactor session allow-screenshots grants Claude auto-read access to the screenshots it takes, and cofactor session network shows the requests behind whatever just happened.

03Start logged in

Credentials stored in Cofactor carry login state — so sessions can start authenticated instead of burning the first minute on a sign-in form:

# Start a session as a saved credential (interactive picker if no name)
cofactor session start --credential "Admin User" --url http://localhost:3000

# Or log in mid-session: load a credential into a running browser
cofactor session load-credential --credential "Admin User"

# Signed in manually and want to keep it? Persist the state back
cofactor session save-credential

save-credential is the underrated one: sign in by hand once — MFA, SSO dance, whatever — and the session's login state is saved to the credential, so the next session starts past all of it.

04Run sessions side by side

Sessions are named, and every browser command takes --session — so multiple browsers can run at once, each as a different user:

cofactor session start --credential "Admin" --name admin --url http://localhost:3000
cofactor session start --credential "Member" --name member --url http://localhost:3000

cofactor session click --ref e22 --element "Publish button" --session admin
cofactor session snapshot --search "New post" --session member   # did it show up?

This is the honest way to test the things single-session tests fake: permissions (admin changes a setting, member sees the effect), collaboration (two users in one document), and notification flows. cofactor session list shows everything running; cofactor session stop --all cleans up.

05Attach to your real Chrome

Sometimes the state that matters lives in your browser — your extensions, your logged-in accounts, that twelve-tab reproduction you finally got into a broken state. Attach a session to your actual Chrome instead of launching a fresh one:

cofactor session start --attach-real-chrome

Requires Chrome 144+ with remote debugging approved at chrome://inspect/#remote-debugging. The session drives your live profile — which is the point — so it can't combine with --headless, --credential, --storage-state, or --url. Your agent can now snapshot and drive the exact browser you're looking at: "see this tab? figure out why the form won't submit."

06From exploration to a test

The browser-testing skill doesn't just drive — it can write down what it found. When the agent has walked a flow worth keeping, ask it to author the test. It builds the workflow from semantic targets it observed (button text, labels — never brittle selectors) and creates it in quarantine, the right mode for tests born on localhost:

echo '<workflow JSON>' | cofactor workflow create --from-stdin --quarantine

A quarantined test runs without blocking anyone, and auto-promotes after three clean passes once your code is deployed — so a test written against localhost:3000 today graduates on its own next week. Replay it locally anytime with cofactor debug <workflowId>.

07Next steps

• Driving Cofactor from your coding agent — the full agent toolkit beyond the browser
• Designing a good test — flows that hold up after they leave your machine
• Running your tests — the same tests, remotely and in CI
• Testing private environments — staging behind a VPN