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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
/* Copyright 2026 Marimo. All rights reserved. */
import type { ExtractAtomValue } from "jotai";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { AnyWidget } from "@anywidget/types";
import { hasRunAnyCellAtom } from "@/components/editor/cell/useRunCells";
import { userConfigAtom } from "@/core/config/config";
import { parseUserConfig } from "@/core/config/config-schema";
import { initialModeAtom } from "@/core/mode";
import { store } from "@/core/state/jotai";
import type { DataURLString } from "@/utils/json/base64";
import { Model } from "../model";
import type { Host } from "../host";
import type { ModelState, WidgetModelId } from "../types";
import { WidgetRuntime } from "../runtime";
import { Deferred } from "@/utils/Deferred";
import { visibleForTesting } from "../widget-binding";
const { WidgetDefRegistry, WidgetBinding } = visibleForTesting;
function createMockComm() {
return {
sendUpdate: vi.fn().mockResolvedValue(undefined),
sendCustomMessage: vi.fn().mockResolvedValue(undefined),
};
}
const createTestHost = (): Host => ({
getModel: vi.fn(),
getWidget: vi.fn(),
});
// oxlint-disable-next-line marimo/prefer-object-params -- terse test helper
function createBinding<T extends ModelState>(
widgetDef: AnyWidget<T>,
model: Model<T>,
options: { controller?: AbortController; onDestroy?: () => void } = {},
) {
return WidgetBinding.create({
widgetDef,
model,
createHost: createTestHost,
controller: options.controller,
onDestroy: options.onDestroy,
});
}
// oxlint-disable-next-line marimo/prefer-object-params -- terse test helper
function getModule(
registry: InstanceType<typeof WidgetDefRegistry>,
jsUrl: string,
jsHash: string,
) {
return registry.getModule({ jsUrl, jsHash });
}
describe("WidgetDefRegistry", () => {
let registry: InstanceType<typeof WidgetDefRegistry>;
let previousConfig: ExtractAtomValue<typeof userConfigAtom>;
let previousMode: ExtractAtomValue<typeof initialModeAtom>;
let previousHasRunAnyCell: ExtractAtomValue<typeof hasRunAnyCellAtom>;
beforeEach(() => {
registry = new WidgetDefRegistry();
// Force "no notebook trust" so the `data:` rejection test below
// exercises the untrusted branch. The positive trust path is covered
// centrally in trusted-url.test.ts.
previousConfig = store.get(userConfigAtom);
previousMode = store.get(initialModeAtom);
previousHasRunAnyCell = store.get(hasRunAnyCellAtom);
store.set(hasRunAnyCellAtom, false);
const cleared = parseUserConfig({});
store.set(userConfigAtom, {
...cleared,
runtime: { ...cleared.runtime, auto_instantiate: false },
});
store.set(initialModeAtom, "edit");
});
afterEach(() => {
store.set(userConfigAtom, previousConfig);
store.set(initialModeAtom, previousMode);
store.set(hasRunAnyCellAtom, previousHasRunAnyCell);
});
it("should cache modules by jsHash and return same promise", () => {
// Two calls with same hash should return the exact same promise object
const promise1 = getModule(registry, "http://localhost/widget.js", "hash1");
const promise2 = getModule(registry, "http://localhost/widget.js", "hash1");
expect(promise1).toBe(promise2);
// Catch the unhandled rejection from the import() attempt
promise1.catch(() => undefined);
});
it("should deduplicate concurrent imports for the same hash", () => {
const promise1 = getModule(registry, "http://localhost/a.js", "same-hash");
const promise2 = getModule(registry, "http://localhost/b.js", "same-hash");
// Same hash means same promise, even with different URLs
expect(promise1).toBe(promise2);
promise1.catch(() => undefined);
});
it("should retry a new URL after invalidating the same hash", () => {
const promise1 = getModule(registry, "http://localhost/a.js", "same-hash");
registry.invalidate("same-hash");
const promise2 = getModule(registry, "http://localhost/b.js", "same-hash");
expect(promise1).not.toBe(promise2);
promise1.catch(() => undefined);
promise2.catch(() => undefined);
});
it("should create different promises for different hashes", () => {
const promise1 = getModule(registry, "http://localhost/a.js", "hash-a");
const promise2 = getModule(registry, "http://localhost/b.js", "hash-b");
expect(promise1).not.toBe(promise2);
promise1.catch(() => undefined);
promise2.catch(() => undefined);
});
it("should remove from cache on import failure so retry creates new promise", async () => {
const promise1 = getModule(registry, "http://localhost/a.js", "fail-hash");
// The URL is rejected by the trusted-URL validator.
await expect(promise1).rejects.toThrow(/untrusted/i);
// After failure, cache should be cleared, so next call creates a new promise
const promise2 = getModule(registry, "http://localhost/a.js", "fail-hash");
expect(promise1).not.toBe(promise2);
promise2.catch(() => undefined);
});
it("does not evict a replacement when an invalidated import fails", async () => {
const oldImport = getModule(
registry,
"http://localhost/old.js",
"replaced",
);
registry.invalidate("replaced");
const newImport = registry.getModule({
jsUrl: "data:text/javascript,export default {}",
jsHash: "replaced",
kernelAuthored: true,
});
await expect(oldImport).rejects.toThrow(/untrusted/i);
await newImport;
expect(getModule(registry, "http://localhost/new.js", "replaced")).toBe(
newImport,
);
});
describe("URL validation", () => {
it.each([
// Attack vector: raw <marimo-anywidget data-js-url=...> in markdown
"http://127.0.0.1:8820/poc.mjs",
"https://evil.example.com/widget.mjs",
"//evil.example.com/widget.mjs",
"javascript:alert(1)",
"data:text/javascript;base64,YWxlcnQoMSk=",
"./@file/x.js?redirect=http://evil.com",
"",
])("rejects untrusted URL: %s", async (url) => {
await expect(getModule(registry, url, `hash-${url}`)).rejects.toThrow(
/untrusted/i,
);
});
it("accepts virtual file paths (fails later at import time)", async () => {
// The URL passes validation but the import still fails because this
// is a Node test environment with no server. We only assert that
// the rejection reason is NOT the "untrusted URL" refusal.
await expect(
getModule(registry, "./@file/123-widget.js", "trusted-hash"),
).rejects.not.toThrow(/untrusted/i);
});
});
describe("static module URLs", () => {
afterEach(() => {
delete window.__MARIMO_STATIC__;
vi.restoreAllMocks();
});
it("releases the generated URL when a static module fails to import", async () => {
window.__MARIMO_STATIC__ = {
files: {
"/@file/widget.js":
"data:text/javascript;base64,ZXhwb3J0IHt9" as DataURLString,
},
};
const create = vi
.spyOn(URL, "createObjectURL")
.mockReturnValue("blob:widget-module");
const revoke = vi
.spyOn(URL, "revokeObjectURL")
.mockImplementation(() => undefined);
await expect(
getModule(registry, "./@file/widget.js", "static-module"),
).rejects.toThrow(/blob:/);
expect(create).toHaveBeenCalledOnce();
expect(revoke).toHaveBeenCalledExactlyOnceWith("blob:widget-module");
});
it("does not revoke active modules when their cache entry is invalidated", async () => {
window.__MARIMO_STATIC__ = {
files: {
"/@file/widget.js":
"data:text/javascript;base64,ZXhwb3J0IHt9" as DataURLString,
},
};
const oldUrl = "data:text/javascript,export const version = 1";
const newUrl = "data:text/javascript,export const version = 2";
vi.spyOn(URL, "createObjectURL")
.mockReturnValueOnce(oldUrl)
.mockReturnValueOnce(newUrl);
const revoke = vi
.spyOn(URL, "revokeObjectURL")
.mockImplementation(() => undefined);
const oldLifetime = new AbortController();
const newLifetime = new AbortController();
const options = { jsUrl: "./@file/widget.js", jsHash: "invalidated" };
const oldImport = registry.getModule({
...options,
lifetime: oldLifetime.signal,
});
registry.invalidate(options.jsHash);
const newImport = registry.getModule({
...options,
lifetime: newLifetime.signal,
});
await Promise.all([oldImport, newImport]);
expect(revoke).not.toHaveBeenCalled();
oldLifetime.abort();
await vi.waitFor(() =>
expect(revoke).toHaveBeenCalledExactlyOnceWith(oldUrl),
);
const siblingLifetime = new AbortController();
expect(
registry.getModule({ ...options, lifetime: siblingLifetime.signal }),
).toBe(newImport);
newLifetime.abort();
siblingLifetime.abort();
await vi.waitFor(() => expect(revoke).toHaveBeenLastCalledWith(newUrl));
});
it("waits for a canceled import to settle before revoking its URL", async () => {
window.__MARIMO_STATIC__ = {
files: {
"/@file/widget.js":
"data:text/javascript;base64,ZXhwb3J0IHt9" as DataURLString,
},
};
const moduleUrl = "data:text/javascript,export const pending = true";
vi.spyOn(URL, "createObjectURL").mockReturnValue(moduleUrl);
const revoke = vi
.spyOn(URL, "revokeObjectURL")
.mockImplementation(() => undefined);
const lifetime = new AbortController();
const pending = registry.getModule({
jsUrl: "./@file/widget.js",
jsHash: "pending",
lifetime: lifetime.signal,
});
lifetime.abort();
expect(revoke).not.toHaveBeenCalled();
await pending;
expect(revoke).toHaveBeenCalledExactlyOnceWith(moduleUrl);
});
it("does not revoke an unchanged URL for a missing static file", async () => {
window.__MARIMO_STATIC__ = { files: {} };
const revoke = vi
.spyOn(URL, "revokeObjectURL")
.mockImplementation(() => undefined);
await expect(
getModule(registry, "./@file/missing.js", "missing-module"),
).rejects.toThrow(/http:/);
expect(revoke).not.toHaveBeenCalled();
});
it("keeps a shared module URL until the last widget generation is destroyed", async () => {
window.__MARIMO_STATIC__ = {
files: {
"/@file/widget.js":
"data:text/javascript;base64,ZXhwb3J0IHt9" as DataURLString,
},
};
// Node cannot import blob URLs; a data URL exercises successful loading.
const moduleUrl = `data:text/javascript,${encodeURIComponent(
"export default { initialize: () => ({ moduleUrl: import.meta.url }) }",
)}`;
vi.spyOn(URL, "createObjectURL").mockReturnValue(moduleUrl);
const revoke = vi
.spyOn(URL, "revokeObjectURL")
.mockImplementation(() => undefined);
const createRuntime = (id: string) => {
const runtime = new WidgetRuntime(id as WidgetModelId, {
timeout: 50,
isEditMode: () => true,
createHost: createTestHost,
onModelTimeout: vi.fn(),
});
runtime.setModel(new Model({}, createMockComm()));
runtime.setSpec({ url: "./@file/widget.js", hash: "static-success" });
return runtime;
};
const first = createRuntime("first");
const second = createRuntime("second");
const widgets = await Promise.all([
first.getWidget(),
second.getWidget(),
]);
expect(widgets.map((widget) => widget.exports)).toEqual([
{ moduleUrl },
{ moduleUrl },
]);
expect(URL.createObjectURL).toHaveBeenCalledOnce();
expect(revoke).not.toHaveBeenCalled();
first.dispose();
await new Promise((resolve) => setTimeout(resolve, 0));
expect(revoke).not.toHaveBeenCalled();
second.dispose();
await vi.waitFor(() => {
expect(revoke).toHaveBeenCalledExactlyOnceWith(moduleUrl);
});
// A later generation reuses the evaluated module rather than
// re-running its top-level side effects, and does not revoke again.
const third = createRuntime("third");
const widget = await third.getWidget();
expect(widget.exports).toEqual({ moduleUrl });
expect(URL.createObjectURL).toHaveBeenCalledOnce();
third.dispose();
await new Promise((resolve) => setTimeout(resolve, 0));
expect(revoke).toHaveBeenCalledOnce();
});
});
});
describe("WidgetBinding", () => {
it("releases module resources after asynchronous generation cleanup", async () => {
const cleanup = new Deferred<void>();
const onDestroy = vi.fn();
const binding = await createBinding(
{ initialize: () => () => cleanup.promise },
new Model({}, createMockComm()),
{ onDestroy },
);
const destroying = binding.destroy();
expect(onDestroy).not.toHaveBeenCalled();
cleanup.resolve();
await destroying;
await binding.destroy();
expect(onDestroy).toHaveBeenCalledOnce();
});
it("retains module resources until canceled initialization and late cleanup settle", async () => {
const initialize = new Deferred<() => Promise<void>>();
const cleanup = new Deferred<void>();
const controller = new AbortController();
const onDestroy = vi.fn();
const pending = createBinding(
{ initialize: () => initialize.promise },
new Model({}, createMockComm()),
{ controller, onDestroy },
);
controller.abort();
await expect(pending).rejects.toThrow(/binding destroyed/);
expect(onDestroy).not.toHaveBeenCalled();
initialize.resolve(() => cleanup.promise);
await Promise.resolve();
expect(onDestroy).not.toHaveBeenCalled();
cleanup.resolve();
await vi.waitFor(() => expect(onDestroy).toHaveBeenCalledOnce());
});
it("releases module resources when initialization fails", async () => {
const onDestroy = vi.fn();
await expect(
createBinding(
{ initialize: () => Promise.reject(new Error("initialize failed")) },
new Model({}, createMockComm()),
{ onDestroy },
),
).rejects.toThrow("initialize failed");
await vi.waitFor(() => expect(onDestroy).toHaveBeenCalledOnce());
});
it("should run initialize exactly once and expose exports", async () => {
const model = new Model<ModelState>({ count: 0 }, createMockComm());
const exports = { setValue: vi.fn() };
const widgetDef = {
initialize: vi.fn().mockResolvedValue(exports),
render: vi.fn(),
};
const binding = await createBinding(widgetDef, model);
expect(widgetDef.initialize).toHaveBeenCalledTimes(1);
expect(binding.exports).toBe(exports);
const controller = new AbortController();
await binding.createView(
{ el: document.createElement("div") },
{ signal: controller.signal },
);
await binding.createView(
{ el: document.createElement("div") },
{ signal: controller.signal },
);
expect(widgetDef.initialize).toHaveBeenCalledTimes(1);
expect(widgetDef.render).toHaveBeenCalledTimes(2);
});
it("should handle widget def as a factory function", async () => {
const model = new Model<ModelState>({ count: 0 }, createMockComm());
const render = vi.fn();
const factory = vi.fn().mockResolvedValue({ render });
const binding = await createBinding(factory, model);
const controller = new AbortController();
await binding.createView(
{ el: document.createElement("div") },
{ signal: controller.signal },
);
expect(factory).toHaveBeenCalledTimes(1);
expect(render).toHaveBeenCalledTimes(1);
});
it("should handle a widget with no initialize or render", async () => {
const model = new Model<ModelState>({ count: 0 }, createMockComm());
const binding = await createBinding({}, model);
expect(binding.exports).toBeUndefined();
const controller = new AbortController();
// No render — createView is a no-op, not an error.
await binding.createView(
{ el: document.createElement("div") },
{ signal: controller.signal },
);
});
it("should expose undefined exports for void initialize", async () => {
const model = new Model<ModelState>({ count: 0 }, createMockComm());
const binding = await createBinding(
{ initialize: vi.fn(), render: vi.fn() },
model,
);
expect(binding.exports).toBeUndefined();
});
it("should run a legacy initialize cleanup on destroy", async () => {
const model = new Model<ModelState>({ count: 0 }, createMockComm());
const initCleanup = vi.fn();
const binding = await createBinding(
{ initialize: vi.fn().mockResolvedValue(initCleanup), render: vi.fn() },
model,
);
expect(binding.exports).toBeUndefined();
expect(initCleanup).not.toHaveBeenCalled();
binding.destroy();
expect(initCleanup).toHaveBeenCalledTimes(1);
});
it("should reject and run cleanup when aborted mid-initialize", async () => {
const model = new Model<ModelState>({ count: 0 }, createMockComm());
const initCleanup = vi.fn();
let resolveInit!: (v: unknown) => void;
const widgetDef = {
initialize: vi.fn().mockReturnValue(
new Promise((r) => {
resolveInit = r;
}),
),
render: vi.fn(),
};
const controller = new AbortController();
const pending = createBinding(widgetDef, model, { controller });
pending.catch(() => undefined);
controller.abort();
resolveInit(initCleanup);
await expect(pending).rejects.toThrow(/binding destroyed/);
expect(initCleanup).toHaveBeenCalledTimes(1);
});
it("should pass an AbortSignal to initialize that aborts on destroy", async () => {
const model = new Model<ModelState>({ count: 0 }, createMockComm());
const widgetDef = { initialize: vi.fn(), render: vi.fn() };
const binding = await createBinding(widgetDef, model);
const initSignal = widgetDef.initialize.mock.calls[0][0]
.signal as AbortSignal;
expect(initSignal.aborted).toBe(false);
binding.destroy();
expect(initSignal.aborted).toBe(true);
});
it("should abort a view when its own signal aborts", async () => {
const model = new Model<ModelState>({ count: 0 }, createMockComm());
const renderCleanup = vi.fn();
const widgetDef = {
render: vi.fn().mockResolvedValue(renderCleanup),
};
const binding = await createBinding(widgetDef, model);
const controller = new AbortController();
await binding.createView(
{ el: document.createElement("div") },
{ signal: controller.signal },
);
const renderSignal = widgetDef.render.mock.calls[0][0]
.signal as AbortSignal;
expect(renderSignal.aborted).toBe(false);
controller.abort();
expect(renderSignal.aborted).toBe(true);
expect(renderCleanup).toHaveBeenCalledTimes(1);
});
it("runs a late render cleanup after the view already aborted", async () => {
const model = new Model<ModelState>({ count: 0 }, createMockComm());
const renderCleanup = vi.fn();
let resolveRender!: (cleanup: () => void) => void;
const widgetDef = {
render: vi.fn(
() =>
new Promise<() => void>((resolve) => {
resolveRender = resolve;
}),
),
};
const binding = await createBinding(widgetDef, model);
const controller = new AbortController();
const pending = binding.createView(
{ el: document.createElement("div") },
{ signal: controller.signal },
);
controller.abort();
resolveRender(renderCleanup);
await pending;
expect(renderCleanup).toHaveBeenCalledTimes(1);
});
it("should abort every view when the binding is destroyed", async () => {
const model = new Model<ModelState>({ count: 0 }, createMockComm());
const renderCleanup = vi.fn();
const widgetDef = {
render: vi.fn().mockResolvedValue(renderCleanup),
};
const binding = await createBinding(widgetDef, model);
const controller = new AbortController();
await binding.createView(
{ el: document.createElement("div") },
{ signal: controller.signal },
);
const renderSignal = widgetDef.render.mock.calls[0][0]
.signal as AbortSignal;
binding.destroy();
expect(renderSignal.aborted).toBe(true);
expect(renderCleanup).toHaveBeenCalledTimes(1);
// The caller's own signal is untouched — only the combined one.
expect(controller.signal.aborted).toBe(false);
});
it("should auto-clear render listeners when the view aborts", async () => {
const model = new Model<ModelState>({ count: 0 }, createMockComm());
const onCount = vi.fn();
const widgetDef = {
render: vi.fn(({ model }) => {
model.on("change:count", onCount);
}),
};
const binding = await createBinding(widgetDef, model);
const controller = new AbortController();
await binding.createView(
{ el: document.createElement("div") },
{ signal: controller.signal },
);
model.set("count", 1);
expect(onCount).toHaveBeenCalledTimes(1);
controller.abort();
model.set("count", 2);
expect(onCount).toHaveBeenCalledTimes(1);
});
it("should auto-clear initialize listeners on destroy", async () => {
const model = new Model<ModelState>({ count: 0 }, createMockComm());
const onCount = vi.fn();
const widgetDef = {
initialize: vi.fn(({ model }) => {
model.on("change:count", onCount);
}),
render: vi.fn(),
};
const binding = await createBinding(widgetDef, model);
model.set("count", 1);
expect(onCount).toHaveBeenCalledTimes(1);
binding.destroy();
model.set("count", 2);
expect(onCount).toHaveBeenCalledTimes(1);
});
});
describe("WidgetBinding render listeners", () => {
it("fire only for changes after mount, never for pre-existing state", async () => {
const model = new Model<ModelState>({ count: 8 }, createMockComm());
const onCount = vi.fn();
const onAnyChange = vi.fn();
const widgetDef = {
render: vi.fn(({ model }) => {
model.on("change:count", onCount);
model.on("change", onAnyChange);
}),
};
const binding = await createBinding(widgetDef, model);
const controller = new AbortController();
await binding.createView(
{ el: document.createElement("div") },
{ signal: controller.signal },
);
expect(onCount).not.toHaveBeenCalled();
expect(onAnyChange).not.toHaveBeenCalled();
model.set("count", 9);
expect(onCount).toHaveBeenCalledTimes(1);
expect(onCount).toHaveBeenCalledWith(9);
});
it("mounting a second view does not fire the first view's listeners", async () => {
const model = new Model<ModelState>({ count: 0 }, createMockComm());
const listeners: Array<ReturnType<typeof vi.fn>> = [];
const widgetDef = {
render: vi.fn(({ model }) => {
const listener = vi.fn();
listeners.push(listener);
model.on("change:count", listener);
}),
};
const binding = await createBinding(widgetDef, model);
const controller = new AbortController();
await binding.createView(
{ el: document.createElement("div") },
{ signal: controller.signal },
);
await binding.createView(
{ el: document.createElement("div") },
{ signal: controller.signal },
);
expect(listeners[0]).not.toHaveBeenCalled();
expect(listeners[1]).not.toHaveBeenCalled();
});
it("clears the element before rendering into it", async () => {
const model = new Model<ModelState>({ count: 0 }, createMockComm());
const el = document.createElement("div");
el.innerHTML = "<span>stale content</span>";
const binding = await createBinding({ render: vi.fn() }, model);
const controller = new AbortController();
await binding.createView({ el }, { signal: controller.signal });
expect(el.innerHTML).toBe("");
});
});