Skip to main content
Version: 1.16

Pytest plugin

Write end-to-end tests for your web apps with Pytest.


pip install pytest-playwright

Use the page fixture to write a basic test. See more examples.

# test_my_application.pydef test_example_is_working(page):    page.goto("")    assert page.inner_text('h1') == 'Example Domain'"text=More information")

To run your tests, use pytest CLI.

# Run tests (Chromium and headless by default)pytest
# Run tests in headed modepytest --headed
# Run tests in a different browser (chromium, firefox, webkit)pytest --browser firefox
# Run tests in multiple browserspytest --browser chromium --browser webkit

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: all browsers).
  • --browser-channel Browser channel to be used.
  • --slowmo Run tests with slow mo.
  • --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.

  • 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 the following fixtures to define custom launch options.


Configure Mypy typings for auto-completion#

# test_my_application.pyfrom playwright.sync_api import Page
def test_visit_admin_dashboard(page: Page):    page.goto("/admin")    # ...

Configure slow mo#

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

pytest --slowmo 100

Skip test by browser#

# test_my_application.pyimport pytest
@pytest.mark.skip_browser("firefox")def test_visit_example(page):    page.goto("")    # ...

Run on a specific browser#

# conftest.pyimport pytest
@pytest.mark.only_browser("chromium")def test_visit_example(page):    page.goto("")    # ...

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

pytest --browser-channel chrome
# test_my_application.pydef test_example(page):    page.goto("")

Configure base-url#

Start Pytest with the base-url argument.

pytest --base-url http://localhost:8080
# test_my_application.pydef test_visit_example(page):    page.goto("/admin")    # -> Will result in http://localhost:8080/admin

Ignore HTTPS errors#

# conftest.pyimport pytest
@pytest.fixture()def browser_context_args(browser_context_args):    return {        **browser_context_args,        "ignore_https_errors": True    }

Use custom viewport size#

# conftest.pyimport pytest
@pytest.fixture()def browser_context_args(browser_context_args):    return {        **browser_context_args,        "viewport": {            "width": 1920,            "height": 1080,        }    }

Device emulation#

# conftest.pyimport pytest
@pytest.fixture()def browser_context_args(browser_context_args, playwright):    iphone_11 = playwright.devices['iPhone 11 Pro']    return {        **browser_context_args,        **iphone_11,    }

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

Persistent context#

# conftest.pyimport pytestfrom playwright.sync_api import BrowserTypefrom typing import Dict
@pytest.fixture(scope="session")def context(    browser_type: BrowserType,    browser_type_launch_args: Dict,    browser_context_args: Dict):    context = browser_type.launch_persistent_context("./foobar", **{        **browser_type_launch_args,        **browser_context_args,        "locale": "de-DE",    })    yield context    context.close()

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 pytestimport unittest
from playwright.sync_api import Page

class MyTest(unittest.TestCase):    @pytest.fixture(autouse=True)    def setup(self, page: Page): = page
    def test_foobar(self):"")"#foobar")        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):    page.goto("")    breakpoint()    # ...

Deploy to CI#

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