Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
For a repeatable browser test, install the Playwright pytest plugin and its browser binaries, write a test using the supplied page fixture, then run pytest. For a one-off browser automation script, install the playwright package and use its synchronous or asynchronous Python API instead. The two setup routes share the browser-install step but serve different jobs.
Choose the right Python workflow
Playwright for Python supports both end-to-end testing and general browser automation. The official Python introduction recommends the pytest plugin for end-to-end tests; the library API is a direct fit for standalone scripts. Neither API is universally better: choose based on whether you need a test suite with assertions and fixtures or a script that performs a task.
| Need | Start with | What it provides |
|---|---|---|
| Repeatable browser tests | pytest-playwright |
Pytest fixtures such as page, test discovery, and Playwright assertions. |
| Standalone automation | playwright |
Direct control of browser launch, pages, navigation, and other automation operations. |
Both routes can use Playwright’s sync or async API where applicable. Use the synchronous API for straightforward sequential scripts; use the asynchronous API when the surrounding project uses asyncio. The official library guide describes both styles and recommends async for modern projects already built around asyncio.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Install Playwright and the browser binaries
Installing the Python package and installing browser binaries are separate steps. Complete both in the environment where you intend to run the test or script.
#1 Best Overall
Recommended route for end-to-end tests
- Install the pytest plugin:
pip install pytest-playwright. - Install Playwright’s default browser binaries:
playwright install. - Create a Python test file whose name begins with
test_, such astest_example.py. - Run the suite with
pytest.
The official guide also documents Poetry and uv installation alternatives. Use the package-manager workflow your project already uses, then run the Playwright browser-install command in that environment.
Standalone automation route
- Install the library:
pip install playwright. - Install browsers:
playwright install. - Save a script such as
automation.pyand run it with Python.
Playwright supports Chromium, Firefox, and WebKit. The basic install command installs default browsers; to install a particular browser explicitly, use a command such as playwright install webkit.
Check platform and dependency requirements
Supported operating systems, Python versions, architecture combinations, and dependency requirements can change. Check the current Python introduction and browser installation guide for the requirements that match your machine before setting up a new environment. On Linux, the browser guide documents installing system dependencies with playwright install-deps or combining dependency installation with a selected browser, for example playwright install --with-deps chromium.
Free tools Windows power users keep installed
One-click scans. No signup required.
Playwright can also use branded Chrome or Edge channels, but those browsers are not installed by default. The browser guide explains how to select channels. Use a branded channel only when that is the browser target you need; otherwise begin with Playwright’s managed browser builds.
Write and run your first pytest test
Save this as test_example.py. It uses the plugin’s page fixture and web-first assertions:
from playwright.sync_api import expect
def test_get_started_link(page):
page.goto("https://playwright.dev/")
expect(page).to_have_title("Playwright")
page.get_by_role("link", name="Get started").click()
expect(page.get_by_role("heading", name="Installation")).to_be_visible()
Run it from the directory containing the test file:
pytestPytest discovers files named test_*.py and test functions named test_*. The plugin supplies fixtures and works with Playwright’s assertions. The official guide says the default run is headless Chromium. Its pytest workflow also supports context isolation and multi-browser configuration.
What the first test does
page.goto(...)navigates the fixture’s page to the site.get_by_role("link", name="Get started")finds a link by its accessible role and name rather than relying on a brittle page position.expect(...).to_have_title(...)andto_be_visible()are web-first assertions: they retry while waiting for the expected condition, up to the applicable timeout.
If the wording or accessible name on the target site changes, update the locator to match the page’s current accessible interface. Do not replace a meaningful assertion with a fixed delay; a delay does not establish that the intended page state has arrived.
Run a standalone Python script
For automation outside pytest, the following synchronous script launches Chromium, visits a page, prints its title, and closes the browser even if an error occurs:
from playwright.sync_api import sync_playwright
with sync_playwright() as playwright:
browser = playwright.chromium.launch()
page = browser.new_page()
page.goto("https://playwright.dev/")
print(page.title())
browser.close()
Save it as automation.py and run python automation.py. The library guide also shows an asynchronous API. Use it when the application already uses asyncio:
import asyncio
from playwright.async_api import async_playwright
async def main():
async with async_playwright() as playwright:
browser = await playwright.chromium.launch()
page = await browser.new_page()
await page.goto("https://playwright.dev/")
print(await page.title())
await browser.close()
asyncio.run(main())
Both examples assume the package and browser binaries have been installed. The library guide also demonstrates using WebKit and saving a screenshot; choose a browser engine that matches the coverage your task requires.
Find elements and wait for the page reliably
Playwright locators are designed around finding elements and retrying actions or assertions as the page changes. Prefer locators based on the interface a user can perceive, where available:
page.get_by_role()for buttons, links, headings, and other accessible roles.page.get_by_text()for visible text.page.get_by_label()for form controls associated with a label.- Other semantic choices include placeholder text, alternative text, title, and configured test IDs.
CSS selectors and XPath are available when needed, but role, label, and text locators often make a test easier to understand and less coupled to the page’s markup. A locator is not merely a stored element handle: Playwright can resolve it again as the page updates.
What happens when you click
Before a click, Playwright checks that the locator resolves to exactly one element and that the element is visible, stable, enabled, and able to receive events. If those actionability conditions are not met before the timeout, the action fails rather than silently clicking an unsuitable target.
Use assertions instead of routine sleeps
Web-first assertions retry until their condition is true or the timeout is reached. For example, prefer expect(page.get_by_role("heading", name="Dashboard")).to_be_visible() over sleeping for a fixed number of seconds and hoping the heading has appeared. Fixed sleeps can waste time when a page is ready early and still fail when it takes longer. The official library guide says most users do not need manual waiting because Playwright auto-waits.
Recommended Free Tools
Select browsers, headed mode, and test artifacts
The pytest plugin’s command-line options apply to its default browser, context, and page fixtures. Check the pytest runner reference for current option details.
| Goal | Plugin option | Use |
|---|---|---|
| See the browser while tests run | --headed |
Opens a visible browser instead of the default headless run. |
| Run against browser engines | --browser chromium, --browser firefox, or --browser webkit |
Select a browser; the option can be repeated to cover multiple browsers. |
| Target a branded browser channel | --browser-channel |
Select a supported channel where needed. |
| Emulate a device | --device |
Choose a documented device configuration. |
| Collect diagnostic artifacts | Output, tracing, video, and screenshot options | Save artifacts to inspect failures; consult the runner reference for exact current flags. |
For example, run the test visibly in Chromium with pytest --headed --browser chromium. To include Firefox and WebKit as well, the browser option can be repeated according to the runner reference. Device emulation and saved artifacts are useful when a failure appears only in a particular browser or viewport.
Debug a failing test
To open the Playwright Inspector for a focused test, the official debugging guide documents this command:
PWDEBUG=1 pytest -s -k test_get_started_link-k filters tests by a name expression and -s lets the debugging session interact with the terminal. The Inspector can help examine the page and step through the test. Python developers can also use their usual debugger, including the VS Code Python extension. See the official debugging guide for the current debugging workflow.
Troubleshoot common setup and test failures
- The command says no browser is installed or launch fails: the package may be installed but its browser binaries are not. Run
playwright install; if needed, install just the selected browser, such asplaywright install webkit. - A Playwright update is followed by a browser launch error: Playwright versions require specific browser binary versions. Run the install command again after updating the package so the expected browser build is present.
- Linux reports missing shared libraries or operating-system dependencies: consult the browser installation guide for your distribution and use
playwright install-depsor the documented combined install command for the selected browser. - Pytest reports that no tests were collected: confirm the filename starts with
test_, the test function starts withtest_, and you are running pytest from the project directory that contains the file. - A click times out: inspect whether the locator matches exactly one element and whether that element is visible, stable, enabled, and receiving events. Use a more specific accessible locator if the page has multiple matching controls.
- An assertion times out: check whether the expected title, text, or page state is actually correct and whether navigation reached the intended URL. Prefer correcting the assertion or navigation over adding an arbitrary sleep.
- The test passes in Chromium but fails in another engine: run the failing case headed and capture a trace, screenshot, or video using the runner’s artifact options. Then inspect browser-specific behavior and the page state at failure.
Performance, reliability, and cost considerations
Playwright setup requires both a Python package and browser downloads, so allow for browser installation in a fresh environment or CI image. Keep package and browser versions aligned: a package upgrade can change the browser versions it expects. Running extra browser engines increases coverage but also means more browser installations and more test runs; select engines based on the compatibility risks your project needs to cover.
For test reliability, use semantic locators and retrying assertions, let Playwright’s actionability checks govern interactions, and capture artifacts when diagnosing intermittent failures. These practices follow the documented behavior of locators, actions, and assertions; they do not guarantee that a test or website is failure-free.
Or skip the browser setup:
If your goal is to capture a website screenshot rather than build browser automation, ScreenshotNeo is a website screenshot API and MCP server for developers. A single GET request returns a PNG, JPEG, WebP, or PDF. Its API accepts and removes known cookie-consent banners, newsletter popups, and chat widgets before capture, with each step configurable. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; response headers report the page verdict and billing status. Its MCP server provides screenshot and PDF tools for AI agents and MCP clients.
Install nothing locally for this API call; create an account and use your API key:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://playwright.dev/ -o shot.webpSee the ScreenshotNeo API documentation for request options. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Sign up free for 1,000 screenshots a month, with no card required.
Frequently Asked Questions
Can I use Playwright for Python without pytest?
Yes. Install the playwright package and use sync_playwright or async_playwright in a standalone script.
Which browser does the basic pytest setup use?
The official Python guide says the default pytest run is headless Chromium.
Can Playwright test websites in Safari?
Playwright’s WebKit engine is available; it is not the same as using branded Safari. Install it with playwright install webkit.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsQuick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
