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. The 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

pip install steero
steero doctor

Example

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:

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

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:

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.

Command line

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

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

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

The skills

The rules

The commands

steero init: start a new test project.

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

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

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:

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:

{ "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.

What is in the box

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. 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 steero is a 16-lesson course in docs/course/, with runnable examples in examples/course/. 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.