kaprevo

Disclaimer. kaprevo is provided AS IS, without warranty of any kind, express or implied. Use it entirely at your own risk. It launches and controls web browsers and can act on any site you point it at. The authors accept no liability for data loss or corruption, damage to hardware, systems that will not start, business interruption, or any consequential damages. You are responsible for checking what you automate, keeping tested backups, and being authorised to act on the sites and accounts you drive. kaprevo is not certified for regulated, forensic, safety-critical or high-assurance use. See DISCLAIMER.md. The LICENSE (MIT) is the governing text and prevails wherever it and this summary differ.

kaprevo: web automation for Python. Typed, async-first Python driver for the stock Chrome and Firefox you already have, over the W3C WebDriver BiDi standard.

Formerly steero: see moving from steero. Current version: 1.0.0rc8 (pip install kaprevo).

• No patched browsers. One standard protocol drives Chrome, Edge and Firefox. Firefox needs no driver; Chrome and Edge use chromedriver or msedgedriver (downloaded on first use) or, with backend="chromium-bidi", nothing extra.
• Auto-waiting before every action, with errors that say which check failed.
• Typed end to end. The protocol layer is generated from the specification.
• Runs Playwright for Python scripts by changing the import to kaprevo.compat.playwright; pytest-playwright's fixtures and options work too.
• Emulation: viewport, devices, locale, timezone, geolocation, permissions, colour scheme, offline, proxy; storage state to log in once; API requests that share the browser's cookies.
• Tracing with a local trace viewer, video, and a script recorder (kaprevo show-trace, kaprevo codegen).
• Visual comparison (to_have_screenshot) and ARIA snapshots.
• Async core, sync API, pytest plugin with failure artifacts, self-healing locators, and an MCP server so AI agents can drive Firefox too.
• Leaves nothing behind. No orphaned browser processes, no leaked profiles.

Install

pip install kaprevo
kaprevo doctor

Example

import asyncio
import kaprevo
from kaprevo import expect

async def main() -> None:
    async with kaprevo.launch("firefox") as browser:
        page = await browser.new_page()
        await page.goto("https://example.com/login")
        await page.get_by_label("User name").fill("ada")
        await page.get_by_role("button", name="Sign in").click()
        await expect(page.get_by_role("status")).to_have_text("Welcome, ada")

asyncio.run(main())

Sync, with pytest:

from kaprevo.sync_api import expect

def test_login(kaprevo_page):
    kaprevo_page.goto("https://example.com/login")
    kaprevo_page.get_by_label("User name").fill("ada")
    kaprevo_page.get_by_role("button", name="Sign in").click()
    expect(kaprevo_page.get_by_role("status")).to_have_text("Welcome, ada")

pytest --kaprevo-browser chrome --kaprevo-browser firefox

Coming from Playwright

Change the import; the rest of the script stays as it is, timeouts in milliseconds included:

from kaprevo.compat.playwright.sync_api import sync_playwright, expect

with sync_playwright() as p:
    browser = p.firefox.launch()          # stock Firefox; p.chromium is Chrome
    page = browser.new_page()
    page.goto("https://example.com")
    expect(page).to_have_title("Example Domain")
    browser.close()

pytest-playwright suites run with pytest -p kaprevo.compat.playwright.pytest. Calls kaprevo cannot honour (WebKit, connect_over_cdp ...) raise UnsupportedFeature naming the call. See the migration guide.

Command line

kaprevo smoke https://example.com          # exit 1 on console errors or failed requests
kaprevo install chromedriver               # or chromium-bidi, chrome@155, firefox@esr
kaprevo screenshot https://example.com out.png --full-page
kaprevo pdf https://example.com out.pdf
kaprevo mcp --browser firefox              # MCP server for AI agents
kaprevo doctor                             # browsers, drivers and cache kaprevo finds
kaprevo show-trace trace.zip               # local trace viewer
kaprevo codegen https://example.com        # record actions into a kaprevo script
kaprevo init                               # new test project with AI-assistant skills and rules
kaprevo skills                             # add the skills and rules to an existing project
kaprevo course                             # copy the 16-lesson course and its practice site into ./kaprevo-course

Working with AI assistants

kaprevo comes with ready-made instructions for AI coding assistants (Claude Code in VS Code or the terminal, and Cursor). Once they are in your project, the assistant writes kaprevo tests the right way, debugs failures from evidence instead of guessing, and can drive a real browser for you.

In one minute

mkdir my-tests && cd my-tests
python -m venv .venv
.venv\Scripts\activate          # Linux and macOS: source .venv/bin/activate
pip install kaprevo pytest
kaprevo init                      # creates the project, skills and rules
pytest                           # runs the sample test

Open the folder in VS Code with Claude Code (or in Cursor) and ask, for example, "write a test that signs in and checks the dashboard".

What the words mean

Term	What it is	When the assistant uses it
Skill	A how-to guide for one job, in .claude/skills/<name>/SKILL.md	Loaded automatically when your request matches the job
Rule	A short list of must-follow instructions, in .claude/rules/ (Claude) or .cursor/rules/ (Cursor)	Applied every time it works on matching files
MCP server	kaprevo mcp, which gives the assistant browser tools (open, click, type, screenshot)	When you ask it to look at or click through a web page

All of them are plain Markdown files. You can read them, edit them, and commit them with your project.

The skills

Skill	What it teaches	Try asking
kaprevo-testing	Test layout, the kaprevo_page fixture, choosing locators, expect assertions, running on several browsers, recording with codegen, porting from Playwright	"Add a test for the checkout form"
kaprevo-debugging	Reading the saved screenshot, HTML and console of a failed test, timeout messages, traces and video, kaprevo doctor, fixing flaky tests	"Why does test_login fail on Firefox?"
kaprevo-mcp	Driving the live browser step by step, then turning what it found into a proper test	"Open our staging site and find the locators for the search box"
kaprevo-auth	Logging in once and reusing the session (storage_state), basic auth, credentials from environment variables, several users at once	"Make the tests start signed in"
kaprevo-network	Mocking and blocking requests with route, changing real responses, waiting for a response, calling the API directly	"Test what the page shows when the API returns 500"
kaprevo-files-frames	Uploads, downloads, iframes, popups and new tabs, alert / confirm / prompt dialogs	"Test the CSV export"
kaprevo-migration	Running a Playwright suite unchanged, then porting it file by file	"Move our Playwright tests to kaprevo"

The rules

Rule	Applies to	In short
kaprevo-tests	Test files and conftest.py	Prefer get_by_role and labels over CSS; assert with expect; never sleep; timeouts are in seconds; each test stands alone; passwords come from environment variables; run the test before calling it done
kaprevo-safety	Everything	Only automate sites you are allowed to; never buy, send, delete or publish for real without your OK; screenshots and traces can hold personal data, so keep them out of git
kaprevo-data	Test files and conftest.py	Each test makes its own data (through the API where possible) and cleans it up; no production data or real people's details; no hard-coded dates
kaprevo-page-objects	Test files and pages/ folders	Page objects only for flows used by several tests; locators in one place; no assertions or sleeps inside them
kaprevo-visual	Test files and __snapshots__/	Screenshots for layout only; fixed viewport; mask changing content instead of loosening the threshold; check every new baseline image
kaprevo-ci	CI files, pytest.ini, pyproject.toml	Headless; kaprevo doctor first; keep traces and videos of failures; run every browser; secrets from the CI store; a retried pass is still flaky

The commands

kaprevo init: start a new test project.

kaprevo init                       # in the current folder, Chrome by default
kaprevo init --browser firefox     # default browser for pytest and the MCP server
kaprevo init --dir path/to/project
kaprevo init --force               # replace files that differ from the templates

Creates	Why
tests/test_example.py	A small working test (runs offline) to copy from
conftest.py	Where your own shared fixtures go
pytest.ini	Default browser, and a trace kept for every failed test
CLAUDE.md	Tells the assistant this project uses kaprevo and where the skills are
.mcp.json	Connects the assistant to kaprevo mcp (added to an existing file, never replacing other servers)
.gitignore	Keeps test output folders out of git (lines added, nothing removed)
.claude/skills/, .claude/rules/, .cursor/rules/	The skills and rules above

kaprevo skills: add or refresh only the skills and rules, in a project you already have.

kaprevo skills                     # skills and Claude rules into the current folder
kaprevo skills --dir path/to/repo  # into another project
kaprevo skills --cursor            # also write the rules for Cursor
kaprevo skills --no-rules          # skills only
kaprevo skills --list              # show what is bundled, copy nothing
kaprevo skills --force             # overwrite older or edited copies

Each command prints one line per file: created, updated, unchanged, or skipped (the file exists and differs; add --force to replace it).

Keeping them up to date

Every copied file names the kaprevo version it came from. After upgrading:

pip install -U kaprevo
kaprevo skills --force --cursor

Only kaprevo's own files are replaced; your other skills and rules are left alone. If you edited a kaprevo skill, --force overwrites your edits, so keep local changes in a separate file of your own.

Using the browser from the assistant

kaprevo init already registered the MCP server. To set it up by hand, add this to .mcp.json in the project root:

{ "mcpServers": { "kaprevo": { "command": "kaprevo", "args": ["mcp", "--browser", "chrome"] } } }

Reload the VS Code window, approve the kaprevo server when asked, and the assistant can open pages, click, type, drag, upload files, answer dialogs, work inside iframes, save downloads, list network requests, save a login and take screenshots. Uploads and saved logins stay inside the project folder (--files-root changes it). Use "args": ["mcp", "--headed"] to watch it work.

More detail: the AI assistants guide.

What is in the box

Area	Highlights
Locators	get_by_role/label/text/placeholder/test_id, CSS, XPath, chaining, nth, filter; shadow DOM pierced; strict
Actions	click, fill, press, type, check, select, hover, drag, file upload; real BiDi input events
Assertions	expect(...): text, value, visibility, count, URL, title, class, CSS, accessible name; not_ and not_to_*
Network	route() to fulfill, continue or abort; requests, responses and bodies; downloads
Pages	events, dialogs, popups, frames, isolated contexts, cookies, PDF, screenshots
Emulation	context options (viewport, locale, timezone, geolocation, permissions, colour scheme, offline, proxy ...), kaprevo.devices, storage state, context.request and kaprevo.request
Visual	to_have_screenshot baselines, aria_snapshot and to_match_aria_snapshot
Debugging	context.tracing and kaprevo show-trace, video (record_video_dir), kaprevo codegen
Playwright	kaprevo.compat.playwright.{sync_api,async_api,pytest}; pytest-playwright's options
pytest	kaprevo_page and friends; screenshot, HTML and console saved on failure; --tracing, --video, --screenshot
Healing	deterministic fingerprint healing, refuses when unsure, --kaprevo-strict-heal
Agents	kaprevo mcp: Model Context Protocol server for Chrome and Firefox
AI assistants	kaprevo init and kaprevo skills: bundled skills and rules for Claude Code and Cursor
Chrome extras	kaprevo.chromium: CDP metrics, CPU throttling, JS coverage

Status

1.0.0rc7. 1.0.0rc2 was tested on Windows and Linux with Chrome 155 and Firefox 158, including a 279-test hard-controls suite (ControlLab) on each browser configuration; rc3 added error-page navigation and listener access; rc4 adds Playwright parity (emulation, tracing, video, codegen, visual comparison, the compat layer, Edge); rc5 adds remote and persistent browsers, HAR, WebSocket routing, the clock, element handles and an HTML test report. Since rc5, main runs its full suite (about 2,300 tests on Chrome, chromium-bidi and Firefox) on Windows 11 and on Ubuntu 24.04 with Chrome 157 and Firefox 159, and fixes CSS selector lists, slotted accessible names, Enter and Space on Firefox buttons and a stale mocked response in expect_response (see the CHANGELOG). rc6 released those fixes and added kaprevo init and kaprevo skills, which install skills and rules for Claude Code and Cursor. rc7 adds the review fixes for leaks, hangs and timeouts, seven skills and six rules in all, and MCP tools for uploads, dialogs, drag, network requests and saved logins. Some emulation options are Chrome only; see upstream findings. See the policy for versioning, deprecation and supported browsers, and the changelog.

Documentation

The guides live in docs/: getting started, locators, auto-waiting, network, visual comparison, contexts, emulation and API requests, the pytest plugin, self-healing, tracing and video, codegen, the MCP server, migrating from Selenium or Playwright, and an honest comparison.

Learn kaprevo is a 16-lesson course in docs/course/, with runnable examples in examples/course/. The examples and the practice site ship in the package: kaprevo course copies them into kaprevo-course, then python examples/course/serve.py starts the site there. A static demo site and the scripts that automate it are in examples/demo/: run python examples/demo/demo_tour.py.

Contributing

Contributions are welcome: see CONTRIBUTING.md, the Code of Conduct and GOVERNANCE.md. Report security problems privately, as described in SECURITY.md.

License

MIT - see LICENSE.