Jupyter Server plugin#

The jupyter_server module provides fixtures for automatically setting-up/tearing-down Jupyter Servers.

To use this plugin, install the dependencies for this plugin:

pip install 'pytest-jupyter[server]'

and list the plugin in the conftest.py file at the root of your project’s test directory.

You can make requests to a test server using the jp_fetch and jp_ws_fetch fixtures.

Fixtures#

Fixtures for use with jupyter server and downstream.

jp_argv()#: Allows tests to setup specific argv values.

jp_auth_header(jp_serverapp)#: Configures an authorization header using the token from the serverapp fixture.

jp_base_url()#: Returns the base url to use for the test.

jp_configurable_serverapp(jp_nbconvert_templates, jp_environ, jp_server_config, jp_argv, jp_http_port, jp_base_url, tmp_path, jp_root_dir, jp_logging_stream, jp_asyncio_loop)#

Starts a Jupyter Server instance based on the provided configuration values. The fixture is a factory; it can be called like a function inside a unit test. Here’s a basic example of how use this fixture:

def my_test(jp_configurable_serverapp):
    app = jp_configurable_serverapp(...)
    ...

jp_create_notebook(jp_root_dir)#: Creates a notebook in the test’s home directory.

jp_extension_environ(jp_env_config_path, monkeypatch)#: Monkeypatch a Jupyter Extension’s config path into each test’s environment variable

jp_fetch(jp_serverapp, http_server_client, jp_auth_header, jp_base_url)#

Sends an (asynchronous) HTTP request to a test server. The fixture is a factory; it can be called like a function inside a unit test. Here’s a basic example of how use this fixture:

async def my_test(jp_fetch):
    response = await jp_fetch("api", "spec.yaml")
    ...

jp_http_port(http_server_port)#: Returns the port value from the http_server_port fixture.

jp_logging_stream()#: StringIO stream intended to be used by the core Jupyter ServerApp logger’s default StreamHandler. This helps avoid collision with stdout which is hijacked by Pytest.

jp_nbconvert_templates(jp_data_dir)#: Setups up a temporary directory consisting of the nbconvert templates.

jp_root_dir(tmp_path)#: Provides a temporary Jupyter root directory value.

jp_server_auth_core_resources()#: The core auth resources for use with a server.

jp_server_auth_resources(jp_server_auth_core_resources)#: The auth resources used by the server.

jp_server_authorizer(jp_server_auth_resources)#: An authorizer for the server.

jp_server_cleanup(jp_asyncio_loop)#: Automatically cleans up server resources.

jp_server_config()#: Allows tests to setup their specific configuration values.

jp_serverapp(jp_server_config, jp_argv, jp_configurable_serverapp)#: Starts a Jupyter Server instance based on the established configuration values.

jp_template_dir(tmp_path)#: Provides a temporary Jupyter templates directory value.

jp_web_app(jp_serverapp)#: app fixture is needed by pytest_tornasync plugin

jp_ws_fetch(jp_serverapp, http_server_client, jp_auth_header, jp_http_port, jp_base_url)#

Sends a websocket request to a test server. The fixture is a factory; it can be called like a function inside a unit test. Here’s a basic example of how use this fixture:

async def my_test(jp_fetch, jp_ws_fetch):
    # Start a kernel
    r = await jp_fetch(
        "api", "kernels", method="POST", body=json.dumps({"name": "python3"})
    )
    kid = json.loads(r.body.decode())["id"]
    # Open a websocket connection.
    ws = await jp_ws_fetch("api", "kernels", kid, "channels")
    ...

send_request(jp_fetch, jp_ws_fetch)#: Send to Jupyter Server and return response code.