Skip to main content

A plugin to run pyppeteer in pytest.

Project description


A plugin to run pyppeteer in pytest.

PyPI - Python Version GitHub issues PyPI Downloads Code style: black Documentation Status 中文博客


You can install pytest-pyppeteer via pip:

$ pip install pytest-pyppeteer

or install the latest one on Github:

pip install git+


For example, The Shawshank Redemption deserves a 9.0 or higher rating on

from dataclasses import dataclass

from pytest_pyppeteer.models import Browser

class Elements:
    """Collect locators of page objects, no matter XPath or CSS Selector."""

    # query input
    query = "#inp-query"

    # search button
    apply = ".inp-btn > input:nth-child(1)"

    # the first result
    first_result = (
        "#root > div > div > div > div > div:nth-child(1) > div.item-root a.cover-link"

    # rating
    rating = (
        "#interest_sectl > div.rating_wrap.clearbox > div.rating_self.clearfix > strong"

async def test_lifetimes(pyppeteer: Browser):
    page = await pyppeteer.new_page()
    await page.goto('')

    await page.type(Elements.query, "The Shawshank Redemption")

    await page.waitfor(Elements.first_result)

    await page.waitfor(Elements.rating)
    rating = await page.get_value(Elements.rating)

    assert float(rating) >= 9.0



Command line options


You can specify the path to a Chromium or Chrome executable. otherwise pytest-pyppeteer will use the default installation location of Chrome in current platform, but now only support win64, win32 and mac platform.

For other platforms, pyppeteer will downloads the recent version of Chromium when called first time. If you don’t prefer this behavior, you can specify an exact path by override this fixture:

def executable_path(executable_path):
    if executable_path is None:
        return "path/to/Chrome/or/Chromium"
    return executable_path


The default installation location of Chrome in different platform:

  • win64: C:/Program Files/Google/Chrome/Application/chrome.exe
  • win32: C:/Program Files (x86)/Google/Chrome/Application/chrome.exe
  • mac: /Applications/Google Chrome


Run browser in headless mode.


Additional args to pass to the browser instance.

For example, specify a proxy:

$ pytest --args proxy-server "localhost:5555,direct://" --args proxy-bypass-list ";"

Or by override the args fixture:

def args(args) -> List[str]:
    return args + [


The default browser size is 800*600, you can use this option to change this behavior:

$ pytest --window-size 1200 800

--window-size 0 0 means to starts the browser maximized.


Slow down the pyppeteer operate in milliseconds. Defaults to 0.0.

No matter selector or xpath

pyppeteer fixture provide a pytest_pyppeteer.models.Browser instance, its usage is almost the same as pyppeteer.browser.Browser, except that it provides a new instance method: new_page(), which is similar to newPage(), but it returns a pytest_pyppeteer.models.Page instead of

pytest_pyppeteer.models.Page’s usage is also the same as, but it provides some new instance methods, and override some methods. For example, you can query an element by selector or xpath in just same method query_locator instead of original querySelector and xpath.

You can also get an original Page by pyppeteer.newPage().

options marker

You can override some command line options in the specified test.

For example, auto-open a DevTools panel:

import asyncio

import pytest

async def test_marker(pyppeteer):
    await pyppeteer.new_page()
    await asyncio.sleep(2)

options marker

Advanced Usage

Control multiple browsers asynchronously

You can easily to control multiple browsers at the same time.

For example, query the The Shawshank Redemption’s movie and book rating on at the same time, then compare them.

import asyncio
from dataclasses import dataclass
from typing import TYPE_CHECKING, Callable

import pytest

    from .models import Browser, Page

class Elements:
    query = "#inp-query"
    apply = ".inp-btn > input:nth-child(1)"

class BookElements(Elements):
    url = ""

    result = '(//*[@class="item-root"])[1]/a'
    rating = "#interest_sectl > div > div.rating_self.clearfix > strong"

class MovieElements(Elements):
    url = ""

    result = (
        "#root > div > div > div > div > div:nth-child(1) > div.item-root a.cover-link"
    rating = (
        "#interest_sectl > div.rating_wrap.clearbox > div.rating_self.clearfix > strong"

async def query_rating(pyppeteer: "Browser", name: str, elements: "Elements"):
    page: Page = await pyppeteer.new_page()

    await page.goto(elements.url)

    await page.type(elements.query, name)

    await page.waitfor(elements.result)

    await page.waitfor(elements.rating)
    rating = await page.get_value(elements.rating)
    return rating

async def test_multiple_browsers(pyppeteer_factory: "Callable"):
    pyppeteer1 = await pyppeteer_factory()
    pyppeteer2 = await pyppeteer_factory()

    movie_rating, book_rating = await asyncio.gather(
        query_rating(pyppeteer1, "The Shawshank Redemption", MovieElements),
        query_rating(pyppeteer2, "The Shawshank Redemption", BookElements),

    assert movie_rating == book_rating



Distributed under the terms of the MIT license, pytest-pyppeteer is free and open source software.


If you encounter any problems, please file an issue along with a detailed description.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pytest-pyppeteer, version 0.2.5
Filename, size File type Python version Upload date Hashes
Filename, size pytest_pyppeteer-0.2.5-py3-none-any.whl (15.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size pytest-pyppeteer-0.2.5.tar.gz (16.5 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page