Metadata-Version: 2.4
Name: steero
Version: 1.0.0rc2
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 both. Firefox needs no
  driver; Chrome uses chromedriver 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.
- **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
```

## 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 |
| pytest | `steero_page` and friends; screenshot, HTML and console saved on failure |
| 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.0rc2.** Tested on Windows and Linux with Chrome 155 and Firefox 158, including a 279-test hard-controls suite (ControlLab) on each browser configuration. 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, contexts, the pytest plugin, self-healing, the
MCP server, migrating from Selenium or Playwright, and an honest comparison.

## 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).
