Why I built it
Playwright now ships AI test agents: a planner that explores your app and writes a test plan, a generator that turns the plan into tests, and a healer that fixes them when they break. It is one of the most useful things to happen to test automation in years.
But a lot of teams run Selenium: Python, Java or C# suites, Selenium Grid, years of tests that work. So I built the same workflow for Selenium: Selenium AI Agent, an open-source MCP server.
In this post I walk through a real run on a practice web shop: one prompt to a structured test plan, a second prompt to running pytest tests, an HTML report, and a real bug the tests found on the way.
What Selenium AI Agent is
Selenium AI Agent lets an AI assistant drive a real browser through Selenium WebDriver, and gives it the tools to plan, generate, run and repair tests.
- Built in Node.js: run it with
npx -y selenium-ai-agent; the matching ChromeDriver is downloaded for you. - Works in your AI client: Claude Desktop, Claude Code, VS Code (GitHub Copilot agent mode) and Cursor.
- Python + pytest by default: generated tests are Python unless you ask for something else, such as Java, C#, JavaScript/TypeScript, WebdriverIO or Robot Framework.
- Test agents like Playwright's: a planner, a generator and a healer, which
init-agentsinstalls in your project. - Selenium Grid: parallel sessions on Chrome, Firefox and Edge.
Step 1: the planner explores the shop and writes a test plan
The first prompt is plain English:
Explore the shopping section of practiceautomatedtesting.com and create a test plan for the shopping cart and checkout.
The planner opens the shop in Chrome and takes an inventory of each page: every field with its label and test id, every button, every link. When a pop-up opens, such as the product details or the checkout, it looks only inside the pop-up, so the plan is about what the user actually sees.
The result is specs/shopping-cart-and-checkout.md, in the same structure as Playwright's planner: 2 suites, 8 tests and 16 steps, each step with its own expected results. One test from the plan:
#### 1.1. Add a product from the grid **File:** `tests/cart/test_add_from_grid.py` **Steps:** 1. Open the shop - expect: The heading shows "Search Results (10 products)" - expect: The cart button shows "0 items" and "$0.00" 2. Click "Add to Cart" for the Mechanical Keyboard - expect: The cart button shows "1 items" - expect: The cart total is "$89.99" On top of Playwright's format, the plan keeps two extras: a table of the elements it found, with stable locators (the shop's data-testids), and the gaps. The shop's own test scenarios mention quantity buttons and a "Your cart is empty" message that don't exist, so the planner lists them as questions for the product owner instead of inventing tests.
Step 2: the generator turns the plan into pytest tests
The second prompt:
Generate Selenium tests from specs/shopping-cart-and-checkout.md, run them, and show me the test report.
The generator writes one test file per plan test, at the path the plan gives, with one assertion for every expect. Before it writes an assertion, it checks the value live in the browser: the $89.99, the 21% VAT on the order summary, the iDeal bank list. No language was named, so it uses the default, Python with pytest, and sets up a virtual environment with Selenium and pytest in the project.
Plan test 1.1 became this:
"""Plan 1.1: Add a product from the grid (specs/shopping-cart-and-checkout.md).""" from selenium.webdriver.common.by import By def test_add_from_grid(shop): # 1. Open the shop (done by the shop fixture) # expect: The heading shows "Search Results (10 products)" heading = shop.driver.find_element(By.XPATH, "//h2[contains(., 'Search Results')]").text assert "Search Results (10 products)" in " ".join(heading.split()) # expect: The cart button shows "0 items" and "$0.00" assert "0 items" in shop.cart_text() and "$0.00" in shop.cart_text() # 2. Click "Add to Cart" for the Mechanical Keyboard shop.add_to_cart(2) # expect: The cart button shows "1 items" # expect: The cart total is "$89.99" shop.wait_for_cart(1, "$89.99") The shop fixture in conftest.py keeps each test short: open the shop, click by test id (scrolled clear of the sticky header), wait for the cart. The # expect: comments line up one-to-one with the plan, so a reviewer can check the test against the plan line by line.
Step 3: the tests run, and find a real bug
Seven tests pass. The eighth, "close the checkout without ordering", fails, and it is right to.
The checkout is about 1,040 px tall and sits centred in a fixed, full-screen overlay. In a browser window shorter than about 1,070 px, the top of the checkout falls off the screen, and you cannot scroll back up to it. The close button is up there. On most laptop screens, a real user cannot close the checkout. Selenium reports the button as not visible, because it isn't.
I kept the test honest: it is marked as a known bug with xfail(strict=True). The suite stays green, and the day the shop is fixed, pytest reports that the test unexpectedly passes.
Every run writes two reports:
-
reports/report.html(pytest-html): the application, the test plan and the Chrome version; a summary with filters; a "Plan test" column that links each result to its test in the plan; and a screenshot of the browser for every failure. The bug's screenshot shows the checkout with its top cut off. -
reports/junit.xml: for Jenkins, GitHub Actions or Azure DevOps.
Try it yourself
You need Node.js 18+ and Chrome. Pick your client:
Claude Code, plus the planner, generator and healer as subagents in your project:
claude mcp add selenium-mcp -- npx -y selenium-ai-agent npx selenium-ai-agent init-agents --loop=claude Claude Desktop (claude_desktop_config.json) and Cursor (~/.cursor/mcp.json):
{ "mcpServers": { "selenium-mcp": { "command": "npx", "args": ["-y", "selenium-ai-agent"] } } } VS Code / GitHub Copilot (.vscode/mcp.json):
{ "servers": { "selenium-mcp": { "command": "npx", "args": ["-y", "selenium-ai-agent"] } } } Then ask it to plan tests for your own app. Run npx selenium-ai-agent doctor if something doesn't start.
Watch the demos
Both steps are on my YouTube channel as short demos with a voice-over: the planner exploring the shop and writing the plan, and the generator writing, running and reporting the tests.
- YouTube: Ralph van der Horst, about learning test automation in the world of AI.
- GitHub: learn-automated-testing/selenium_agent, open source; a star helps others find it.
- npm: selenium-ai-agent
- Practice site used in the demos: practiceautomatedtesting.com
- Courses and articles: learnautomatedtesting.com
Next up is the healer: changing the shop and watching the tests repair themselves. What would you want to see in that demo? Let me know in the comments.
