pytest-jupyter

A set of pytest plugins for Jupyter libraries and extensions.

Basic Usage

First, install pytest-jupyter from PyPI using pip:

pip install pytest-jupyter

This installs the basic pytest-jupyter package that includes fixture definitions for the various Jupyter-based pytest plugins.

To use one of these plugins, you'll also need to install their dependencies. This requires a second pip install call. For example, if you'd like to use the jupyter_server plugin, you'll need to call:

pip install "pytest-jupyter[server]"

This should install everything you need for the plugin to work.

To use a plugin, add it to the pytest_plugins list in the conftest.py of your project's root test directory.

# inside the conftest.py
pytestplugins = ["pytestjupyter.jupyter_server"]

This library includes an echo_kernel, which is useful to speed up testing. You must have either "pytest-jupyter[server]" or "pytest-jupyter[client]" installed to use the echo kernel.

The pytestjupyter.jupyterclient plugin provides an installed echokernelspec as a fixture, and a start_kernel fixture that provides a factory function that starts a kernel using the echo kernel by default.

Note: The server plugin also includes the client plugin, so you can use both sets of fixtures with "pytestjupyter.jupyterserver". Both the client and server plugins also include the core fixtures.

Note: The client and server plugins use pytest-tornasync for async test suite running. It may not compatible with pytest-asyncio, meaning that all fixtures must be synchronous. You can use the asyncio_loop fixture and run asyncioloop.rununtil_complete against an async function in your fixtures if needed.

The server fixures use the echo kernel by default. To override this behavior, override the jpserverconfig fixture and add the following config:

{
    "MultiKernelManager": {
        "defaultkernelname": "<desiredkernelname"
    }
}

All fixtures inside the plugin (e.g. jupyter_server) will be available to all of your project's unit tests. You can use a fixtures by passing it as an argument to your unit test function:

async def testjupyterserverapi(jpfetch):
    # Send request to a temporary Jupyter Server Web Application
    response = await jp_fetch("api/spec.yml")
# Confirm that the request is successful.     assert response.code == 200

You can list the fixtures for a given plugin using the --fixtures argument from the pytest command line interface:

pytest --fixtures -p pytestjupyter.jupyterserver

or by calling the pytest --fixtures where the plugin is listed in the pytest_plugins variable of a given test directory.