Skip to main content

Pytest Plugin Reference

Playwright provides a Pytest plugin to write end-to-end tests. To get started with it, refer to the getting started guide.


To run your tests, use Pytest CLI.

pytest --browser webkit --headed

If you want to add the CLI arguments automatically without specifying them, you can use the pytest.ini file:

CLI arguments

  • --headed: Run tests in headed mode (default: headless).
  • --browser: Run tests in a different browser chromium, firefox, or webkit. It can be specified multiple times (default: chromium).
  • --browser-channel Browser channel to be used.
  • --slowmo Slows down Playwright operations by the specified amount of milliseconds. Useful so that you can see what is going on (default: 0).
  • --device Device to be emulated.
  • --output Directory for artifacts produced by tests (default: test-results).
  • --tracing Whether to record a trace for each test. on, off, or retain-on-failure (default: off).
  • --video Whether to record video for each test. on, off, or retain-on-failure (default: off).
  • --screenshot Whether to automatically capture a screenshot after each test. on, off, or only-on-failure (default: off).


This plugin configures Playwright-specific fixtures for pytest. To use these fixtures, use the fixture name as an argument to the test function.

def test_my_app_is_working(fixture_name):
# Test using fixture_name
# ...

Function scope: These fixtures are created when requested in a test function and destroyed when the test ends.

Session scope: These fixtures are created when requested in a test function and destroyed when all tests end.

  • playwright: Playwright instance.
  • browser_type: BrowserType instance of the current browser.
  • browser: Browser instance launched by Playwright.
  • browser_name: Browser name as string.
  • browser_channel: Browser channel as string.
  • is_chromium, is_webkit, is_firefox: Booleans for the respective browser types.

Customizing fixture options: For browser and context fixtures, use the following fixtures to define custom launch options.

Parallelism: Running Multiple Tests at Once

If your tests are running on a machine with a lot of CPUs, you can speed up the overall execution time of your test suite by using pytest-xdist to run multiple tests at once:

# install dependency
pip install pytest-xdist
# use the --numprocesses flag
pytest --numprocesses auto

Depending on the hardware and nature of your tests, you can set numprocesses to be anywhere from 2 to the number of CPUs on the machine. If set too high, you may notice unexpected behavior.

See Running Tests for general information on pytest options.


Configure Mypy typings for auto-completion
from playwright.sync_api import Page

def test_visit_admin_dashboard(page: Page):
# ...

Configure slow mo

Run tests with slow mo with the --slowmo argument.

pytest --slowmo 100

Slows down Playwright operations by 100 milliseconds.

Skip test by browser
import pytest

def test_visit_example(page):
# ...

Run on a specific browser
import pytest

def test_visit_example(page):
# ...

Run with a custom browser channel like Google Chrome or Microsoft Edge

pytest --browser-channel chrome
def test_example(page):

Configure base-url

Start Pytest with the base-url argument. The pytest-base-url plugin is used for that which allows you to set the base url from the config, CLI arg or as a fixture.

pytest --base-url http://localhost:8080
def test_visit_example(page):
# -> Will result in http://localhost:8080/admin

Ignore HTTPS errors
import pytest

def browser_context_args(browser_context_args):
return {
"ignore_https_errors": True

Use custom viewport size
import pytest

def browser_context_args(browser_context_args):
return {
"viewport": {
"width": 1920,
"height": 1080,

Device emulation
import pytest

def browser_context_args(browser_context_args, playwright):
iphone_11 = playwright.devices['iPhone 11 Pro']
return {

Or via the CLI --device="iPhone 11 Pro"

Persistent context
import pytest
from playwright.sync_api import BrowserType
from typing import Dict

def context(
browser_type: BrowserType,
browser_type_launch_args: Dict,
browser_context_args: Dict
context = browser_type.launch_persistent_context("./foobar", **{
"locale": "de-DE",
yield context

When using that all pages inside your test are created from the persistent context.

Using with unittest.TestCase

See the following example for using it with unittest.TestCase. This has a limitation, that only a single browser can be specified and no matrix of multiple browsers gets generated when specifying multiple.

import pytest
import unittest

from playwright.sync_api import Page

class MyTest(unittest.TestCase):
def setup(self, page: Page): = page

def test_foobar(self):"")"#foobar").click()
assert"1 + 1") == 2


Use with pdb

Use the breakpoint() statement in your test code to pause execution and get a pdb REPL.

def test_bing_is_working(page):
# ...

Deploy to CI

See the guides for CI providers to deploy your tests to CI/CD.