Metadata-Version: 2.4
Name: kaprevo
Version: 1.0.0rc8
Summary: Typed, async-first Python driver for stock Chrome and Firefox over W3C WebDriver BiDi, with auto-waiting and self-healing locators
Project-URL: Repository, https://github.com/Pandiyarajk/kaprevo
Project-URL: Issues, https://github.com/Pandiyarajk/kaprevo/issues
Author-email: Pandiyaraj Karuppasamy <pandiyarajk@live.com>
License-Expression: MIT
License-File: LICENSE
Keywords: auto-wait,bidi,browser-automation,chrome,firefox,pytest,testing,ui-testing,webdriver,webdriver-bidi
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: websockets>=14
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: psutil>=5.9; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=4.0; extra == 'dev'
Requires-Dist: types-psutil; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
Description-Content-Type: text/markdown

# 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](https://github.com/Pandiyarajk/kaprevo/blob/main/DISCLAIMER.md).
> The [LICENSE](https://github.com/Pandiyarajk/kaprevo/blob/main/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](docs/migration/steero.md). 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

```bash
pip install kaprevo
kaprevo doctor
```

## Example

```python
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:

```python
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")
```

```bash
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:

```python
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](https://github.com/Pandiyarajk/kaprevo/blob/main/docs/migration/playwright.md).

## Command line

```bash
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

```bash
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.

```bash
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.

```bash
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:

```bash
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:

```json
{ "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](https://github.com/Pandiyarajk/kaprevo/blob/main/docs/guides/ai-assistants.md).

## 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](https://github.com/Pandiyarajk/kaprevo/blob/main/docs/upstream-findings.md). See the
[policy](https://github.com/Pandiyarajk/kaprevo/blob/main/docs/policy.md) for
versioning, deprecation and supported browsers, and the
[changelog](https://github.com/Pandiyarajk/kaprevo/blob/main/CHANGELOG.md).

## Documentation

The guides live in
[docs/](https://github.com/Pandiyarajk/kaprevo/tree/main/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/](https://github.com/Pandiyarajk/kaprevo/tree/main/docs/course), with runnable examples
in [examples/course/](https://github.com/Pandiyarajk/kaprevo/tree/main/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/](https://github.com/Pandiyarajk/kaprevo/tree/main/examples/demo): run
`python examples/demo/demo_tour.py`.

## Contributing

Contributions are welcome: see
[CONTRIBUTING.md](https://github.com/Pandiyarajk/kaprevo/blob/main/CONTRIBUTING.md),
the [Code of Conduct](https://github.com/Pandiyarajk/kaprevo/blob/main/CODE_OF_CONDUCT.md)
and [GOVERNANCE.md](https://github.com/Pandiyarajk/kaprevo/blob/main/GOVERNANCE.md).
Report security problems privately, as described in
[SECURITY.md](https://github.com/Pandiyarajk/kaprevo/blob/main/SECURITY.md).

## License

MIT - see [LICENSE](https://github.com/Pandiyarajk/kaprevo/blob/main/LICENSE).
