Expect: a browser QA skill that reads your diff and drives Playwright with your own cookies

The gap Expect fills: diff-scoped browser checks without selector maintenance

The README states the pitch plainly: instead of writing scripts, maintaining selectors, and wiring up assertions, Expect reads your code changes and tests them in a real browser automatically. That is the whole product thesis. The target user is someone who already has a coding agent open in a repository and wants a smoke pass over the current change set before merging, without opening a test file. The README's own comparison is against Puppeteer, Playwright and Cypress, and the distinction it draws is maintenance: those tools require you to author and keep a spec, while Expect derives the plan from the diff. The second comparison is against computer-use agents, which the README says rely on screenshots and mouse coordinates; Expect uses Playwright for DOM automation instead. That is a design lineage it credits to dev-browser by Sawyer Hood, described in the acknowledgements as the Playwright-first approach that inspired Expect's core design. So the audience is narrow and specific: agent users who want browser coverage scoped to what they just changed, and who accept that the plan is generated rather than written.

How the plan gets built and what runs it

The mechanism visible in the README has four stages. Expect reads your git changes, generates a test plan, and runs it in a real browser with Playwright. It then reports back what is broken so the agent can fix it. The README's getting-started flow describes step three as Expect spawning subagents simulating real logged-in users to find issues and regressions, after which your agent fixes the issues and re-runs to verify. The scope of what those subagents check is enumerated in the FAQ: performance (long animation frames, INP, LCP), security (npm dependencies, CSRF attacks, vulnerabilities), design (broken hover states, links, buttons), and app completeness (missing metadata, dead links). That is a wide net, and it is worth noting that these are different classes of check bundled under one command. A CSRF probe and an LCP measurement do not share a failure mode or a fix, so when Expect reports a problem you should expect to triage by category rather than treat the output as a single pass or fail. The agent integration is the second half of the architecture: Expect hooks into your existing agent and runs entirely on your machine, per the FAQ. The -a flag selects the provider from claude, codex, copilot, gemini, cursor, opencode or droid, and auto-detection picks the first one found on your PATH if you do not specify.

Install and first run, using the commands in the README

The README gives a two-step start. First, ask your agent to Fetch https://www.expect.dev/ and run init script. Second, run /expect inside Claude Code, Codex, or one of the other supported agents. The CLI is published as expect-cli, and the version badge in the README points at the npm package of that name; the most recent release listed is expect-cli@0.0.26 from 2026-04-05, alongside expect-sdk@0.0.26 published three seconds later, which suggests the two packages are released in lockstep. The options table is where the real control lives. -t, --target takes unstaged, branch or changes and defaults to changes, which determines what diff Expect reads. -u, --url takes one or more base URLs and skips the port picker, which is the flag you want when your dev server is already running somewhere non-obvious. -m, --message takes a natural language instruction if you want to steer the plan, and -f, --flow reuses a saved flow by slug, which is the closest thing to a repeatable test the tool offers. --browser-mode switches between headed and headless and defaults to headed. --output takes text or json and defaults to text, so piping into another tool means passing --output json explicitly. -y runs without confirmation, and --no-cookies skips system browser cookie extraction.

Cookie extraction is the feature and the risk

The most consequential design choice in Expect is that it runs with your real cookies. The README says it runs the plan with your real cookies, and the FAQ frames the subagents as simulating real logged-in users. That is what makes the tool useful on anything behind authentication, which is most of a real application. It is also the part you should think hardest about. There are two escape hatches. --no-cookies skips system browser cookie extraction entirely, and --profile reuses a Chrome profile by name, for example Default, if you would rather point at a specific profile than let Expect pull from the system browser. CI mode takes the opposite path: the README states that --ci runs headless, skips cookie extraction, auto-approves the plan, and enforces a 30-minute timeout. So the authenticated path is a local-only capability in practice, and your CI runs are unauthenticated unless you build something yourself. That is a reasonable default, but it means a class of bugs that only appear behind a login will not be caught by the workflow Expect generates. If your application is entirely behind auth, the CI half of the product does less for you than the local half.

CI mode, the GitHub Action command, and the 30-minute ceiling

The README answers the CI question directly: use --ci or the add github-action command to set up a workflow that tests every PR. The listed behaviour of CI mode is headless, no cookies, auto-yes, and a 30-minute timeout. Two things follow from that. The auto-approve behaviour means nobody reviews the generated plan before it runs in CI, so a plan that misreads the diff will run to completion and report whatever it reports. The 30-minute timeout is a hard ceiling on the whole run, and because the plan is generated rather than fixed, the runtime is not something you can estimate from a spec file. If a change touches many routes, the plan grows and you find the ceiling by hitting it. --timeout takes milliseconds if you need to set a different bound for a local or non-default run. The release list includes an entry named ci-pr-81 (CI Recording, PR #81) dated 2026-04-05, which indicates the project records CI runs from its own pull requests, though the README does not document what that artifact contains or where it is published.

Where Expect is the wrong tool

The README is upfront about two gaps: mobile testing is coming soon, and a hosted or enterprise version is coming soon. Treat both as absent, not as shipping. Beyond that, the generated-plan model has a structural limitation. A written Playwright spec is a durable artifact: it fails the same way twice, you can bisect it, and a reviewer can read it. A plan generated from a diff is a fresh artifact each run, and the README does not describe a mechanism for pinning a generated plan as a regression test. The --flow flag reuses a saved flow by slug, which is a partial answer, but the README does not explain how a flow is saved, where it is stored, or how it is versioned alongside the code. If your requirement is a stable regression suite that runs identically on every commit, Expect is a complement at best. The same applies to teams with no coding agent installed: the entire interface is a skill invoked from inside Claude Code, Codex, Cursor or a peer, so without one of those on the PATH there is nothing to run.

Compared with a hand-written Playwright suite

The honest alternative is Playwright itself, used directly. The difference is not the browser engine, since Expect uses Playwright for DOM automation. The difference is who authors the assertions. With Playwright you write the spec, choose the selectors, and decide what passing means; the suite is code in your repository and it changes only when you change it. With Expect the agent reads the diff and produces the plan, so coverage tracks the change rather than the specification. That inverts the maintenance cost. You stop paying to update selectors when the UI shifts, and you start paying in review effort, because you cannot read a generated plan the way you read a committed spec. For a solo developer or a small team shipping frequently, that trade is often worth it. For a team with a compliance requirement to show what was tested and when, a generated plan is a weaker artifact than a file under version control. Cypress sits on the same side of that line as Playwright: authored tests, maintained by hand. Expect's README does not claim to replace either, and you should not read it that way.

Licence, versioning and the maintenance question

The README ends with FSL-1.1-MIT and Million Software, Inc., while the repository metadata reports the licence as NOASSERTION. Those two signals disagree, and the discrepancy is worth resolving before you depend on the tool in a commercial setting. FSL-1.1-MIT is a source-available licence with a time-delayed conversion to MIT, but the exact terms, the conversion window and the permitted uses are not reproduced in the README, so read the licence file in the repository rather than the badge. I am not giving legal advice here; the point is simply that NOASSERTION means an automated licence detector could not classify the repository, and that is a flag for anyone running dependency review. On maintenance, the evidence available is thin: the last push is 2026-05-06, the latest releases are expect-cli@0.0.26 and expect-sdk@0.0.26 from 2026-04-05, and the version numbers are still 0.0.x. The two packages moving together suggests they must be upgraded as a pair, so pin both in your lockfile and check that the CLI and SDK versions match before filing a bug. The README also points to a CONTRIBUTING.md and a Code of Conduct, and the acknowledgements credit dev-browser as the design ancestor, which is the clearest statement of where the ideas came from.

Editorial conclusion

Adopt Expect if you already drive Claude Code, Codex or Cursor from a terminal and you want a diff-scoped smoke pass in a real browser without writing selectors. Do not adopt it if you need mobile viewports, a hosted runner, or deterministic assertions you can pin in a spec file; the README lists mobile and a hosted version as coming soon, and the generated plan is not a substitute for a checked-in test suite. Before you trust CI mode, verify three things in the repo: what the generated workflow file actually contains after add github-action, whether expect-sdk@0.0.26 and expect-cli@0.0.26 are version-locked together in your lockfile, and what the NOASSERTION licence field resolves to against the FSL-1.1-MIT text shipped in the repository.

Official sources

1. Issues
2. millionco/expect on GitHub
3. Project website
4. README
5. Releases