Metadata-Version: 2.4
Name: steero
Version: 1.0.0rc5
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
```

## 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 |
| Chrome extras | `steero.chromium`: CDP metrics, CPU throttling, JS coverage |

## Status

**1.0.0rc5.** 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. 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).
