How to Use Playwright Test Agents with Python
Use Playwright Test Agents for planning, then build reliable Python end-to-end tests with pytest-playwright and Codegen.
Short answer: Playwright Test Agents are documented as a planner, generator, and healer workflow whose examples produce Playwright Test files in TypeScript. For a Python suite, use the agents to explore and plan, then keep executable tests in pytest-playwright; use Python Codegen when you want recorded Python interactions. The reviewed Playwright documentation does not establish a Python-native Test Agents generator.
This distinction lets you use the agent workflow without quietly introducing TypeScript files into a Python repository.
1. Decide which workflow you need
| Route | Output and runner | Best fit | Limit |
|---|---|---|---|
| Test Agents | Markdown plan and Playwright Test files | Exploring flows, generating scenarios, healing failures | Official examples reviewed here are TypeScript; pytest output is not documented. |
| pytest-playwright + Python Codegen | Python tests run by pytest; Codegen records Python | Python-native end-to-end suites | Codegen is a recorder, not the planner-generator-healer chain. |
Use Test Agents when planning and repair are the goal. Use pytest-playwright when your repository, fixtures, CI, and review process are Python-first. You can combine them by implementing reviewed agent scenarios as Python tests.
2. Install Playwright for Python
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install pytest-playwright
playwright install
pytestThe official Python guide recommends the pytest plugin, which supplies the page fixture, isolated browser contexts, and browser configuration. It supports synchronous and asynchronous Python APIs.
from playwright.sync_api import expect
def test_homepage_title(page):
page.goto("https://example.com")
expect(page).to_have_title("Example Domain")pytest -q3. Initialize Test Agent definitions
npx playwright init-agents --loop=codexOther documented loop values include vscode, claude, and opencode. Regenerate definitions after upgrading Playwright. The agentic experience in VS Code requires VS Code 1.105 or newer, according to the official Test Agents guide.
4. Give the planner a useful seed and request
The planner explores the application and writes a Markdown test plan. Provide a precise flow, starting URL, account state, expected result, and a seed test that performs initialization. Playwright says the planner runs the seed test, allowing global setup, project dependencies, fixtures, and hooks to run. A PRD is optional.
Explore the checkout flow as a signed-in customer.
Cover an empty cart, a valid card, a declined card, and recovery after a network error.
Use the existing seed test for environment setup. Record stable user-visible
assertions and note state that must be reset between scenarios.Review the Markdown plan before generation. Remove duplicates, add missing permissions or test data, and mark destructive actions that require disposable accounts.
5. Generate and review executable tests
The generator reads the plan and creates executable Playwright Test files. It verifies selectors and assertions while performing scenarios, but generated tests can still contain errors for the healer. The documented examples use TypeScript and the Playwright Test runner, so inspect output language and structure before adding files to a Python repository.
- Check that every scenario has an isolated starting state.
- Prefer role, label, or test-id locators over brittle CSS chains.
- Ensure assertions describe user-visible outcomes.
- Port reviewed behavior to
pytest-playwrightwhen Python is your maintained suite.
import re
from playwright.sync_api import Page, expect
def test_checkout_success(page: Page):
page.goto("https://shop.example/checkout")
page.get_by_label("Email").fill("buyer@example.test")
page.get_by_role("button", name=re.compile("place order", re.I)).click()
expect(page.get_by_role("heading", name="Order confirmed")).to_be_visible()6. Use the healer carefully
The healer runs a failing test, replays its steps, inspects the current UI for an equivalent element or flow, proposes a locator or wait change, and reruns the test. It may finish with a passing test or skip a test when it believes functionality is broken. Review every repair.
- Verify changed locators when duplicate elements exist.
- Ensure waits observe real readiness conditions instead of adding arbitrary delays.
- Check that assertions still match the plan.
- Run repaired tests alone and in the full suite.
7. Record Python with Codegen
Python Codegen is separate from Test Agents. Start it with:
playwright codegen --target=python https://example.comPerform the flow, copy the generated Python into a pytest test, and replace incidental selectors or values. Codegen records interactions; it does not create the planner’s Markdown plan or run the healer loop. See the Codegen reference.
8. Project layout and execution
project/
├── tests/
│ ├── conftest.py
│ └── test_checkout.py
├── requirements.txt
└── playwright.config.pyKeep URLs and credentials outside test files. Put login and data setup in pytest fixtures, then make the seed test call those fixtures so planner exploration starts like CI.
pytest tests/test_checkout.py -q
pytest -q9. Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
playwright: command not found |
Environment inactive or package missing | Activate .venv and install pytest-playwright. |
| Browser executable missing | Browser binaries absent | Run playwright install; install browsers during CI image builds. |
| No Python tests from agents | Documented examples generate TypeScript | Keep the plan and implement it with pytest-playwright or Python Codegen. |
| Planner starts unauthenticated | Seed test omitted login or fixtures | Make the seed perform and verify initialization. |
| Generated locator fails | Ambiguous, changed, or unready control | Use role, label, or test-id locators and wait for meaningful state. |
| Healer skips a test | It believes functionality is broken | Reproduce manually and decide whether product or test needs correction. |
| Suite-only failures | Shared state or leaked context | Use isolated fixtures, reset data, and avoid order dependence. |
| CI cannot reach app | DNS, proxy, certificate, or environment mismatch | Validate the base URL from the runner and configure required network access. |
10. Performance, reliability, and cost
- Keep plans focused to reduce duplicate exploration.
- Use deterministic accounts and resettable fixtures.
- Prefer locator and assertion auto-waiting over fixed sleeps.
- Keep exploratory agent runs separate from stable CI execution.
- Regenerate agent definitions after Playwright upgrades.
- Increase parallelism only when the application and test data support it.
11. Or skip the browser setup
If you need screenshots for a plan, bug report, or visual checkpoint, ScreenshotNeo provides one HTTP request instead of maintaining a browser runner. Cookie and consent banners, newsletter popups, and chat widgets are removed before capture. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing result.
See the ScreenshotNeo API docs for options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo also provides an MCP server for Claude, Cursor, and other MCP clients with take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots monthly with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
12. FAQ
Can Test Agents generate pytest files?
The reviewed official pages demonstrate TypeScript Playwright Test output and do not establish pytest generation.
Can I use the planner without the generator?
Yes. The three agents can be used independently, sequentially, or as a chained loop.
Do I need Codegen if I use agents?
No. Codegen records a concrete interaction into Python; agents handle planning, generation, and healing.
Should generated tests be committed immediately?
Review language, fixtures, selectors, assertions, and data isolation first.
