Metadata-Version: 2.4
Name: steero
Version: 1.0.0rc6
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/steero
Project-URL: Issues, https://github.com/Pandiyarajk/steero/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

# steero

> **Disclaimer.** steero 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. steero is not
> certified for regulated, forensic, safety-critical or high-assurance use.
> See [DISCLAIMER.md](https://github.com/Pandiyarajk/steero/blob/main/DISCLAIMER.md).
> The [LICENSE](https://github.com/Pandiyarajk/steero/blob/main/LICENSE) (MIT) is
> the governing text and prevails wherever it and this summary differ.

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

- **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
  `steero.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**
  (`steero show-trace`, `steero 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 steero
steero doctor
```

## Example

```python
import asyncio
import steero
from steero import expect

async def main() -> None:
    async with steero.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 steero.sync_api import expect

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

```bash
pytest --steero-browser chrome --steero-browser firefox
```

## Coming from Playwright

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

```python
from steero.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.get_by_role("heading", level=1)).to_have_text("Example Domain")
    browser.close()
```

pytest-playwright suites run with `pytest -p steero.compat.playwright.pytest`.
Calls steero cannot honour (WebKit, `connect_over_cdp` ...)
raise `UnsupportedFeature` naming the call. See the
[migration guide](https://github.com/Pandiyarajk/steero/blob/main/docs/migration/playwright.md).

## Command line

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

## Working with AI assistants

steero 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 steero 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 steero pytest
steero 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** | `steero 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 |
|---|---|---|
| `steero-testing` | Test layout, the `steero_page` fixture, choosing locators, `expect` assertions, running on several browsers, recording with `codegen`, porting from Playwright | "Add a test for the checkout form" |
| `steero-debugging` | Reading the saved screenshot, HTML and console of a failed test, timeout messages, traces and video, `steero doctor`, fixing flaky tests | "Why does test_login fail on Firefox?" |
| `steero-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" |

### The rules

| Rule | Applies to | In short |
|---|---|---|
| `steero-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 |
| `steero-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 |

### The commands

**`steero init`**: start a new test project.

```bash
steero init                       # in the current folder, Chrome by default
steero init --browser firefox     # default browser for pytest and the MCP server
steero init --dir path/to/project
steero 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 steero and where the skills are |
| `.mcp.json` | Connects the assistant to `steero 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 |

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

```bash
steero skills                     # skills and Claude rules into the current folder
steero skills --dir path/to/repo  # into another project
steero skills --cursor            # also write the rules for Cursor
steero skills --no-rules          # skills only
steero skills --list              # show what is bundled, copy nothing
steero 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 steero version it came from. After upgrading:

```bash
pip install -U steero
steero skills --force --cursor
```

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

### Using the browser from the assistant

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

```json
{ "mcpServers": { "steero": { "command": "steero", "args": ["mcp", "--browser", "chrome"] } } }
```

Reload the VS Code window, approve the `steero` server when asked, and the
assistant can open pages, click, type and take screenshots. Use
`"args": ["mcp", "--headed"]` to watch it work.

More detail: the [AI assistants guide](https://github.com/Pandiyarajk/steero/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 ...), `steero.devices`, storage state, `context.request` and `steero.request` |
| Visual | `to_have_screenshot` baselines, `aria_snapshot` and `to_match_aria_snapshot` |
| Debugging | `context.tracing` and `steero show-trace`, video (`record_video_dir`), `steero codegen` |
| Playwright | `steero.compat.playwright.{sync_api,async_api,pytest}`; pytest-playwright's options |
| pytest | `steero_page` and friends; screenshot, HTML and console saved on failure; `--tracing`, `--video`, `--screenshot` |
| Healing | deterministic fingerprint healing, refuses when unsure, `--steero-strict-heal` |
| Agents | `steero mcp`: Model Context Protocol server for Chrome and Firefox |
| AI assistants | `steero init` and `steero skills`: bundled skills and rules for Claude Code and Cursor |
| Chrome extras | `steero.chromium`: CDP metrics, CPU throttling, JS coverage |

## Status

**1.0.0rc6.** 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 releases those fixes and adds `steero init` and `steero skills`, which install skills and rules for Claude Code and Cursor. Some emulation options are Chrome only; see [upstream findings](https://github.com/Pandiyarajk/steero/blob/main/docs/upstream-findings.md). See the
[policy](https://github.com/Pandiyarajk/steero/blob/main/docs/policy.md) for
versioning, deprecation and supported browsers, and the
[changelog](https://github.com/Pandiyarajk/steero/blob/main/CHANGELOG.md).

## Documentation

The guides live in
[docs/](https://github.com/Pandiyarajk/steero/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 steero** is a 16-lesson course in
[docs/course/](https://github.com/Pandiyarajk/steero/tree/main/docs/course), with runnable examples
in [examples/course/](https://github.com/Pandiyarajk/steero/tree/main/examples/course). A static
demo site and the scripts that automate it are in
[examples/demo/](https://github.com/Pandiyarajk/steero/tree/main/examples/demo): run
`python examples/demo/demo_tour.py`.

## Contributing

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

## License

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