# pytest-jupyter

A set of pytest plugins for Jupyter libraries and extensions.

[![Build Status](https://github.com/jupyter-server/pytest-jupyter/actions/workflows/test.yml/badge.svg?query=branch%3Amain++)](https://github.com/jupyter-server/pytest-jupyter/actions/workflows/test.yml/badge.svg?query=branch%3Amain++)

## Basic Usage

First, install `pytest-jupyter` from PyPI using pip:

```bash
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:

```bash
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.

```python
# 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:

```json
{
    "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:

```python
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:

```bash
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.
