jupytertestutil

Documentation

Overview

Package jupytertestutil contains utilities for mockign and testing Jupyter backend requests.

Index

• Variables
• func AddXSRFHeaderAndCookie(r *http.Request, token string)
• func Delete(server *httptest.Server, path string) error
• func ExerciseKernelWebsockets(serverURL, jupyterBasePath, kernelID string, requestHeader http.Header) error
• func Get(server *httptest.Server, path string, out any) error
• func NewMockJupyter(basePath string, injectErrors bool, ...) http.Handler
• func Patch(server *httptest.Server, path string, res any, out any) error
• func Post(server *httptest.Server, path string, res any, out any) error
• type KernelMessage
• type KernelMessageHeader

Variables

var DefaultKernelSpecs *resources.KernelSpecs = &resources.KernelSpecs{
	Default: "python3",
	KernelSpecs: map[string]*resources.KernelSpec{
		"python3": &resources.KernelSpec{
			ID: "python3",
			Spec: &resources.Spec{
				Language:    "python",
				DisplayName: "Python",
			},
			Resources: map[string]string{
				"example":  "example.jpg",
				"logo-svg": "/kernelspecs/python3/logo-svg.svg",
			},
		},
	},
}

DefaultKernelSpecs is a hard-coded KernelSpecs instance with a single kernelspec.

var DefaultMockJupyter http.Handler = NewMockJupyter("", false, 0, 0, DefaultKernelSpecs)

DefaultMockJupyter is an HTTP handler that implements a mock Jupyter server with one kernelspec.

Functions

func AddXSRFHeaderAndCookie

func AddXSRFHeaderAndCookie(r *http.Request, token string)

AddXSRFHeaderAndCookie adds an XSRF token header and cookie in the format expected by Jupyter.

func Delete

func Delete(server *httptest.Server, path string) error

Delete issues a DELETE request to the test server at the given path.

func ExerciseKernelWebsockets

func ExerciseKernelWebsockets(serverURL, jupyterBasePath, kernelID string, requestHeader http.Header) error

ExerciseKernelWebsockets sends one end-to-end kernel message to the given URL.

func Get

func Get(server *httptest.Server, path string, out any) error

Get issues a GET request to the test server at the given path, and then deserializes the response into the supplied `out` parameter.

func NewMockJupyter

func NewMockJupyter(basePath string, injectErrors bool, injectLatency, injectStartupLatency time.Duration, kernelspecs *resources.KernelSpecs) http.Handler

NewMockJupyter returns a new HTTP handler that implements a mock Jupyter backend server.

func Patch

func Patch(server *httptest.Server, path string, res any, out any) error

Patch issues a PATCH request to the test server at the given path, with a serialized form of the supplied `res` parameter.

It then deserializes the response into the supplied `out` parameter.

func Post

func Post(server *httptest.Server, path string, res any, out any) error

Post issues a POST request to the test server at the given path, with a serialized form of the supplied `res` parameter.

It then deserializes the response into the supplied `out` parameter.

Types

type KernelMessage

type KernelMessage struct {
	// Buffers is used for extensions. We just leave it empty.
	Buffers []any `json:"buffers"`

	// Channel identifies which of the kernel's communication channels is being used.
	//
	// We hardcode this to "shell"
	Channel string `json:"channel"`

	// Content is the contents of the message and its values depend on the message type.
	Content map[string]any `json:"content"`

	// Header is the header for this message.
	Header *KernelMessageHeader `json:"header"`

	// Metadata is used for extensions. We leave it empty.
	Metadata map[string]any `json:"metadata"`

	// MsgID duplicates the "msg_id" field inside the header.
	//
	// It appears to be optional, so we always set it but never read it.
	MsgID string `json:"msg_id"`

	// MsgType duplicates the "msg_type" field inside the header.
	//
	// It appears to be optional, so we always set it but never read it.
	MsgType string `json:"msg_type"`

	// ParentHeader is set for reply messages, and is the header value of
	// the message being replied to.
	ParentHeadder *KernelMessageHeader `json:"parent_header"`
}

KernelMessage encodes the message used to communicate with a (in this case, mock) Jupyter kernel.

Communication with a Jupyter kernel follows the protocol defined here:

https://jupyter-client.readthedocs.io/en/latest/messaging.html

For kernel gateways, this protocol is layered on top of a websocket connection to the endpoint `<BASE_PATH>/api/kernels/<KERNEL_UUID>/channels?session_id=...`, with the messages going back and forth both being JSON objects as described below.

type KernelMessageHeader

type KernelMessageHeader struct {
	// Date is a string encoding the date of the message in ISO 8601 format.
	Date string `json:"date"`

	// MsgID is a unique ID for the message.
	MsgID string `json:"msg_id"`

	// MsgType is a string specifying how the message's `content` field should be interpreted.
	// for the purposes of testing, we only use the `execute_request` and `execute_reply` types.
	MsgType string `json:"msg_type"`

	// Session is a unique ID for the running process (i.e. the kernel).
	Session string `json:"session"`

	// Username is the username of the user. We just hardcode this to "user".
	Username string `json:"username"`

	// Version is the version string of the Jupyter messaging protocol. We hardcode it to "5.4".
	Version string `json:"version"`
}

KernelMessageHeader defines the encoding of the header field for kernel messages.