Skip to content


Running in non-headless mode

Because tests must run in a CI environment that obviously doesn't have a display environment, girder-pytest-pyppeteer defaults to launching Chromium in headless mode. However, when debugging a pyppeteer test, it is frequently invaluable to see and interact with the browser as the test is running.

This can be achieved by setting the environment variable PYPPETEER_BROWSER_HEADLESS=0. In the recommended tox.ini configuration, PYPPETEER_BROWSER_HEADLESS is set to be passed through from the shell environment, so you can simply invoke tox like this:

PYPPETEER_BROWSER_HEADLESS=0 tox -e test-pyppeteer

Since the test will generally use the page much faster than a human would, using breakpoint() or other debugging tools is also recommended so you have time to inspect the browser state.

Running in a container

The cookiecutter recommends running tox like this:

docker-compose run --rm django tox

This conveniently isolates the tox installation to the django container, meaning you don't need to install tox yourself to run it.

However, pyppeteer has issues running inside of a container (especially in non-headless mode), so this way of running tox is not supported. You will need to install and run tox natively for pyppeteer to work correctly.

Why aren't my Celery tasks running?

There is unfortunately no way to have Celery tasks run normally (i.e. asynchronously) while running pyppeteer tests. This is a drawback of using the live_server fixture. To keep test data atomic, live_server wraps the entire test in a transaction so that it can easily reset the database after the test is over. Within the test thread, this is not a huge concern. However, external services like Celery obviously cannot interact with the transaction, so there is no way for Celery tasks to read or write test data.

The workaround is to use CELERY_TASK_ALWAYS_EAGER to force your Celery tasks to execute immediately instead of being queued. Because they execute within the test context, they will be within the bounds of the live_server transaction and will be able to read and write test data.

The default configuration specifies DJANGO_CONFIGURATION = DevelopmentConfiguration in tox.ini. To enable CELERY_TASK_ALWAYS_EAGER, you will probably need a new configuration:

class PyppeteerTestingConfiguration(TestAppMixin, DevelopmentBaseConfiguration):
    ... copy required config from DevelopmentConfiguration ...

You can then specify DJANGO_CONFIGURATION = PyppeteerTestingConfiguration in your tox.ini to use that new configuration in your pyppeteer tests.

Note that any calls to my_celery_task.delay() will block until the task is complete, which may break assumptions about asynchronicity.

Browser closed unexpectedly: cannot open display

When running in non-headless mode in Ubuntu, you may encounter this error:

LaunchProcess: failed to execvp:
[1722838:1722838:0322/] Bad NaCl helper startup ack (0 bytes)

(chrome:1722836): Gtk-WARNING **: 22:13:16.142: cannot open display: :2

I was able to resolve this by setting the DISPLAY=:1 environment variable in tox.ini, then running DISPLAY=:1 xhost + to open up your X server.