Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

10.4 KB
Raw Blame
/* Copyright 2026 Marimo. All rights reserved. */

import NodeFs from "node:fs";
import NodeUrl from "node:url";
import { afterEach, describe, expect, expectTypeOf, it, vi } from "vitest";
import { z } from "zod";
import {
  NotebookClient,
  type unstable_NotebookCall,
} from "../notebook/client.ts";
import type { OperationsBelow } from "../request.ts";
import type * as Protocol from "../protocol.ts";

const fixtures = new NodeUrl.URL(
  "../../../../protocols/host/fixtures/",
  import.meta.url,
);

function readFixture(name: string): unknown {
  return JSON.parse(
    NodeFs.readFileSync(new NodeUrl.URL(name, fixtures), "utf8"),
  );
}

function json(status: number, body: unknown, type = "application/json") {
  return new Response(JSON.stringify(body), {
    status,
    headers: { "Content-Type": type },
  });
}

/** A notebook client whose requests are answered by `answer`. */
function connect(
  answer: (request: Request) => Response,
  url = "http://127.0.0.1:2718/api/marimo/v1/notebooks/n1",
) {
  const fetch = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) =>
    answer(new Request(input, init)),
  );
  const notebook = new NotebookClient(url, {
    token: "secret",
    fetch,
  });
  const sent = () => new Request(...fetch.mock.calls[0]);
  return { notebook, fetch, sent };
}

type NotebookOperationId = OperationsBelow<"/notebooks/{notebook_id}">;

afterEach(() => {
  vi.unstubAllGlobals();
});

describe("NotebookClient", () => {
  it("sends an edit below the notebook's URL and returns the validated response", async () => {
    const response = readFixture("edit-response.json");
    const { notebook, sent } = connect(() => json(200, response));
    const { changes } = readFixture("edit.json") as Protocol.EditRequest;

    const result = await notebook.edit(changes);

    expect(result).toEqual({ ok: true, status: 200, data: response });
    const request = sent();
    expect(request.method).toBe("POST");
    expect(request.url).toBe(
      "http://127.0.0.1:2718/api/marimo/v1/notebooks/n1/edits",
    );
    expect(request.headers.get("Authorization")).toBe("Bearer secret");
    expect(request.headers.get("Idempotency-Key")).toMatch(/^[\da-f-]{36}$/);
    expect(await request.json()).toEqual({ changes });
  });

  it("keeps the notebook URL's query string and ignores a trailing slash", async () => {
    const problem = readFixture("problems/not-found.json");
    const { notebook, fetch } = connect(
      () => json(404, problem, "application/problem+json"),
      "http://localhost/api/marimo/v1/notebooks/n1/?session_id=s1",
    );
    await notebook.delete();
    await notebook.interrupt("r/1");
    expect(fetch.mock.calls.map(([url]) => String(url))).toMatchInlineSnapshot(`
      [
        "http://localhost/api/marimo/v1/notebooks/n1?session_id=s1",
        "http://localhost/api/marimo/v1/notebooks/n1/runtime/runs/r%2F1?session_id=s1",
      ]
    `);
  });

  it("accepts problems and reads their media type without regard to case", async () => {
    const problem = readFixture("problems/not-found.json");
    const { notebook, sent } = connect(() =>
      json(404, problem, "Application/Problem+JSON; charset=utf-8"),
    );
    expect(await notebook.open()).toEqual({ ok: false, status: 404, problem });
    expect(sent().headers.get("Accept")).toBe(
      "application/json, application/problem+json",
    );
  });

  it.each(["", ".", ".."])(
    "rejects the run id %j before sending",
    async (runId) => {
      const { notebook, fetch } = connect(() => json(202, {}));
      await expect(notebook.interrupt(runId)).rejects.toThrow("valid run_id");
      expect(fetch).not.toHaveBeenCalled();
    },
  );

  it("keeps its URL when a caller changes the copy it reads", async () => {
    const { notebook, fetch } = connect(
      () => new Response(null, { status: 204 }),
    );
    notebook.url.host = "attacker.example";
    await notebook.delete();
    expect(String(fetch.mock.calls[0][0])).toBe(
      "http://127.0.0.1:2718/api/marimo/v1/notebooks/n1",
    );
  });

  it("makes idempotency keys outside secure contexts", async () => {
    const { getRandomValues } = globalThis.crypto;
    vi.stubGlobal("crypto", {
      getRandomValues: getRandomValues.bind(globalThis.crypto),
    });
    const { notebook, sent } = connect(() => json(202, {}));
    await notebook.stop().catch(() => undefined);
    expect(sent().headers.get("Idempotency-Key")).toMatch(
      /^[\da-f]{8}-[\da-f]{4}-4[\da-f]{3}-[89ab][\da-f]{3}-[\da-f]{12}$/,
    );
  });

  it("returns problems as values", async () => {
    const problem = readFixture("problems/edit-conflict.json");
    const { notebook } = connect(() =>
      json(409, problem, "application/problem+json"),
    );
    expect(await notebook.edit([])).toEqual({
      ok: false,
      status: 409,
      problem,
    });
  });

  it("sends preconditions, decisions, and the caller's idempotency key", async () => {
    const { notebook, sent } = connect(() =>
      json(200, readFixture("edit-response.json")),
    );
    await notebook.save({
      ifMatch: "etag-1",
      decisions: { environment: "keep" },
      idempotencyKey: "retry-1",
    });
    const request = sent();
    expect(request.url).toBe(
      "http://127.0.0.1:2718/api/marimo/v1/notebooks/n1/save",
    );
    expect(request.headers.get("If-Match")).toBe("etag-1");
    expect(request.headers.get("Idempotency-Key")).toBe("retry-1");
    expect(await request.json()).toEqual({
      decisions: { environment: "keep" },
    });
  });

  it("accepts empty responses", async () => {
    const { notebook } = connect(() => new Response(null, { status: 204 }));
    expect(await notebook.delete()).toEqual({
      ok: true,
      status: 204,
      data: undefined,
    });
  });

  it("validates requests before sending them", async () => {
    const { notebook, fetch } = connect(() => json(202, {}));
    await expect(notebook.run({ cells: [] })).rejects.toBeInstanceOf(
      z.ZodError,
    );
    expect(fetch).not.toHaveBeenCalled();
  });

  it("throws on answers the protocol does not describe", async () => {
    const { notebook } = connect(() => json(200, { unexpected: true }));
    await expect(notebook.open()).rejects.toBeInstanceOf(z.ZodError);
    const html = connect(() => new Response("<html>", { status: 502 }));
    await expect(html.notebook.open()).rejects.toThrow(
      "Unexpected 502 response to notebook.open",
    );
  });

  it("has a method for each request below a notebook", () => {
    // A new operation below a notebook fails this until it has a method.
    expectTypeOf({
      "notebook.update": "update",
      "notebook.delete": "delete",
      "notebook.open": "open",
      "notebook.edit": "edit",
      "notebook.save": "save",
      "runtime.start": "start",
      "runtime.stop": "stop",
      "runtime.restart": "restart",
      "runtime.run": "run",
      "runtime.interrupt": "interrupt",
    } as const).toExtend<Record<NotebookOperationId, keyof NotebookClient>>();
  });
});

/** A notebook client whose calls `reply` answers. */
function over(reply: (call: unstable_NotebookCall) => unknown) {
  const send = vi.fn(async (call: unstable_NotebookCall) => reply(call));
  const notebook = NotebookClient.unstable_over(send, { notebookId: "n1" });
  return { notebook, send };
}

describe("NotebookClient.unstable_over", () => {
  it("sends each method as its call", async () => {
    const response = readFixture("edit-response.json");
    const { notebook, send } = over(() => ({ status: 200, body: response }));
    const { changes } = readFixture("edit.json") as Protocol.EditRequest;

    expect(await notebook.edit(changes)).toEqual({
      ok: true,
      status: 200,
      data: response,
    });
    expect(send).toHaveBeenLastCalledWith({
      operation: "notebook.edit",
      params: { notebook_id: "n1" },
      headers: { "idempotency-key": expect.stringMatching(/^[\da-f-]{36}$/) },
      body: { changes },
    });

    await notebook.save({
      ifMatch: "etag-1",
      decisions: { environment: "keep" },
      idempotencyKey: "retry-1",
    });
    expect(send).toHaveBeenLastCalledWith({
      operation: "notebook.save",
      params: { notebook_id: "n1" },
      headers: { "idempotency-key": "retry-1", "if-match": "etag-1" },
      body: { decisions: { environment: "keep" } },
    });
  });

  it("names every path parameter and returns problems as values", async () => {
    const problem = {
      type: "tag:marimo.io,2026:host/not-found",
      title: "Not found",
      status: 404,
    };
    const { notebook, send } = over(() => ({ status: 404, body: problem }));
    expect(await notebook.interrupt("r1", { idempotencyKey: "k" })).toEqual({
      ok: false,
      status: 404,
      problem,
    });
    expect(send).toHaveBeenCalledWith({
      operation: "runtime.interrupt",
      params: { notebook_id: "n1", run_id: "r1" },
      headers: { "idempotency-key": "k" },
      body: undefined,
    });
  });

  it("throws on replies the protocol does not describe", async () => {
    await expect(over(() => ({})).notebook.open()).rejects.toBeInstanceOf(
      z.ZodError,
    );
    await expect(
      over(() => ({ status: 200, body: { unexpected: true } })).notebook.open(),
    ).rejects.toBeInstanceOf(z.ZodError);
  });

  it("stops waiting on abort without sending again", async () => {
    let answer!: (reply: unknown) => void;
    const { notebook, send } = over(
      () => new Promise((resolve) => (answer = resolve)),
    );
    const controller = new AbortController();
    const editing = notebook.edit([], { signal: controller.signal });
    controller.abort();
    await expect(editing).rejects.toBe(controller.signal.reason);
    answer({ status: 200, body: readFixture("edit-response.json") });
    await expect(notebook.edit([], { signal: controller.signal })).rejects.toBe(
      controller.signal.reason,
    );
    expect(send).toHaveBeenCalledOnce();
  });

  it("types each call from the operations table", () => {
    expectTypeOf<unstable_NotebookCall["operation"]>().toEqualTypeOf<
      OperationsBelow<"/notebooks/{notebook_id}">
    >();
    expectTypeOf<
      unstable_NotebookCall<"runtime.interrupt">["params"]
    >().toEqualTypeOf<{
      readonly notebook_id: string;
      readonly run_id: string;
    }>();
    expectTypeOf<unstable_NotebookCall<"notebook.save">["headers"]>().toExtend<{
      readonly "idempotency-key": string;
      readonly "if-match"?: string;
    }>();
    expectTypeOf<
      unstable_NotebookCall<"runtime.stop">["body"]
    >().toEqualTypeOf<undefined>();
    expectTypeOf(over(() => ({})).notebook).not.toHaveProperty("url");
  });
});