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

pytest_plugins = ["pytest_jupyter.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 pytest_jupyter.jupyter_client plugin provides an installed echo_kernel_spec 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 "pytest_jupyter.jupyter_server". 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 asyncio_loop.run_until_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 jp_server_config fixture and add the following config:

{
    "MultiKernelManager": {
        "default_kernel_name": "<desired_kernel_name"
    }
}

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 test_jupyter_server_api(jp_fetch):
    # 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 pytest_jupyter.jupyter_server

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