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 {
act,
fireEvent,
render,
screen,
waitFor,
within,
} from "@testing-library/react";
import { beforeAll, describe, expect, it, vi } from "vitest";
import { SetupMocks } from "@/__mocks__/common";
import { initialModeAtom } from "@/core/mode";
import { store } from "@/core/state/jotai";
import { CellNotInitializedError } from "@/utils/errors";
import type { IPluginProps } from "../../types";
import { FileBrowser, FileBrowserPlugin } from "../FileBrowserPlugin";
interface MockFile {
id: string;
path: string;
name: string;
is_directory: boolean;
}
const FILES: MockFile[] = [
{ id: "1", path: "/home/user/docs", name: "docs", is_directory: true },
{ id: "2", path: "/home/user/a.txt", name: "a.txt", is_directory: false },
{ id: "3", path: "/home/user/b.txt", name: "b.txt", is_directory: false },
];
type Value = MockFile[];
function mockListDirectory(files: MockFile[]) {
return vi.fn().mockResolvedValue({
files,
total_count: files.length,
is_truncated: false,
});
}
function makeProps(
overrides: {
selectionMode?: string;
multiple?: boolean;
value?: Value;
setValue?: (v: Value) => void;
files?: MockFile[];
list_directory?: ReturnType<typeof vi.fn>;
host?: HTMLElement;
} = {},
): IPluginProps<Value, Record<string, unknown>> {
const files = overrides.files ?? FILES;
const list_directory = overrides.list_directory ?? mockListDirectory(files);
return {
data: {
initialPath: "/home/user",
filetypes: [],
selectionMode: overrides.selectionMode ?? "all",
multiple: overrides.multiple ?? true,
label: null,
restrictNavigation: false,
},
value: overrides.value ?? [],
setValue: overrides.setValue ?? vi.fn(),
host: overrides.host ?? document.createElement("div"),
functions: {
list_directory,
},
} as unknown as IPluginProps<Value, Record<string, unknown>>;
}
function renderBrowser(overrides: Parameters<typeof makeProps>[0] = {}) {
const listDirectory =
overrides.list_directory ?? mockListDirectory(overrides.files ?? FILES);
const result = render(
FileBrowserPlugin.render(
makeProps({ ...overrides, list_directory: listDirectory }) as Parameters<
typeof FileBrowserPlugin.render
>[0],
),
);
return { ...result, listDirectory };
}
beforeAll(() => {
SetupMocks.resizeObserver();
store.set(initialModeAtom, "edit");
});
describe("FileBrowserPlugin session cache recovery", () => {
it("delays the initial loading overlay and hides it when listing completes", async () => {
vi.useFakeTimers();
try {
let resolveListing: (value: {
files: MockFile[];
total_count: number;
is_truncated: boolean;
}) => void = () => undefined;
const listDirectory = vi.fn(
() =>
new Promise((resolve) => {
resolveListing = resolve;
}),
);
const { unmount } = renderBrowser({ list_directory: listDirectory });
await act(async () => {
vi.advanceTimersByTime(199);
});
expect(screen.queryByText("Listing files...")).not.toBeInTheDocument();
await act(async () => {
vi.advanceTimersByTime(1);
});
expect(screen.getByText("Listing files...")).toBeInTheDocument();
await act(async () => {
resolveListing({
files: FILES,
total_count: FILES.length,
is_truncated: false,
});
});
expect(screen.queryByText("Listing files...")).not.toBeInTheDocument();
expect(screen.getByText("docs")).toBeInTheDocument();
await act(async () => {
vi.advanceTimersByTime(200);
});
expect(screen.queryByText("Listing files...")).not.toBeInTheDocument();
unmount();
} finally {
vi.useRealTimers();
}
});
it("retries a failed cached listing when the plugin resets", async () => {
const host = document.createElement("marimo-file-browser");
const wrapper = document.createElement("marimo-ui-element");
wrapper.setAttribute("random-id", "cached-id");
wrapper.append(host);
const props = {
initialPath: "/home/user",
filetypes: [],
selectionMode: "directory",
multiple: false,
label: "Pick folder",
restrictNavigation: false,
value: [],
setValue: vi.fn(),
host,
};
const error = new CellNotInitializedError();
const cachedListDirectory = vi.fn().mockRejectedValue(error);
const { rerender } = render(
<FileBrowser {...props} list_directory={cachedListDirectory} />,
);
expect(await screen.findByText(error.message)).toBeInTheDocument();
// PluginSlot recreates the RPC functions on reset, even when the path
// and the host's attributes are unchanged.
const liveListDirectory = mockListDirectory(FILES);
rerender(<FileBrowser {...props} list_directory={liveListDirectory} />);
expect(await screen.findByText("docs")).toBeInTheDocument();
expect(screen.queryByText(error.message)).not.toBeInTheDocument();
expect(liveListDirectory.mock.calls).toEqual([[{ path: "/home/user" }]]);
fireEvent.click(screen.getByRole("checkbox", { name: "Select docs" }));
expect(props.setValue).toHaveBeenCalledWith([
{ ...FILES[0], id: FILES[0].path },
]);
fireEvent.keyDown(screen.getAllByRole("row")[0], { key: "End" });
rerender(
<FileBrowser {...props} list_directory={mockListDirectory([FILES[0]])} />,
);
await waitFor(() => expect(screen.getAllByRole("row")).toHaveLength(2));
expect(screen.getAllByRole("row")[0]).toHaveAttribute("tabindex", "0");
});
});
describe("FileBrowserPlugin keyboard accessibility", () => {
it("renders a row per file plus the parent row", async () => {
renderBrowser();
expect(await screen.findByText("docs")).toBeInTheDocument();
// parent "..", docs, a.txt, b.txt
expect(screen.getAllByRole("row")).toHaveLength(4);
});
it("marks the list as a multiselectable grid", async () => {
renderBrowser({ multiple: true });
await screen.findByText("docs");
const grid = screen.getByRole("grid");
expect(grid).toHaveAttribute("aria-multiselectable", "true");
});
it("does not select a non-selectable file on click (mode=directory)", async () => {
const setValue = vi.fn();
renderBrowser({ selectionMode: "directory", setValue });
const fileCell = await screen.findByText("a.txt");
fireEvent.click(fileCell.closest('[role="row"]')!);
expect(setValue).not.toHaveBeenCalled();
});
it("labels each selectable checkbox with the file name", async () => {
renderBrowser({ selectionMode: "all" });
await screen.findByText("docs");
expect(
screen.getByRole("checkbox", { name: "Select a.txt" }),
).toBeInTheDocument();
expect(
screen.getByRole("checkbox", { name: "Select docs" }),
).toBeInTheDocument();
});
it("keeps checkboxes out of the tab order", async () => {
renderBrowser({ selectionMode: "all" });
await screen.findByText("docs");
expect(
screen.getByRole("checkbox", { name: "Select a.txt" }),
).toHaveAttribute("tabindex", "-1");
});
it("places exactly one row in the tab order", async () => {
renderBrowser();
await screen.findByText("docs");
const rows = screen.getAllByRole("row");
const tabbable = rows.filter((r) => r.getAttribute("tabindex") === "0");
expect(tabbable).toHaveLength(1);
// the parent row is first and starts active
expect(rows[0]).toHaveAttribute("tabindex", "0");
});
it("resets the active row to the parent row after navigating", async () => {
renderBrowser({ selectionMode: "all" });
const docs = await screen.findByText("docs");
const docsRow = docs.closest('[role="row"]')!;
fireEvent.keyDown(docsRow, { key: "ArrowDown" }); // move active off the parent
fireEvent.click(docs); // navigate into "docs"
await within(screen.getByRole("grid")).findByText("docs"); // listing reloads (mock returns same files)
const rows = screen.getAllByRole("row");
expect(rows[0]).toHaveAttribute("tabindex", "0");
// the focused row must match the only tabbable row
expect(rows[0]).toHaveFocus();
});
it("resets the active row when the listing refreshes in place", async () => {
// The cell's random-id changes when the cell re-renders, refetching the
// same path. A shrinking listing must not leave activeIndex out of bounds.
const parent = document.createElement("div");
parent.setAttribute("random-id", "a");
const host = document.createElement("div");
parent.append(host);
document.body.append(parent);
const list_directory = vi
.fn()
.mockResolvedValueOnce({
files: FILES,
total_count: FILES.length,
is_truncated: false,
})
.mockResolvedValue({
files: [FILES[0]],
total_count: 1,
is_truncated: false,
});
const props = () =>
FileBrowserPlugin.render(
makeProps({ host, list_directory }) as Parameters<
typeof FileBrowserPlugin.render
>[0],
);
const { rerender } = render(props());
await screen.findByText("a.txt");
// Move the active row to the last row, then trigger a same-path refresh.
fireEvent.keyDown(screen.getAllByRole("row")[0], { key: "End" });
expect(screen.getAllByRole("row").at(-1)).toHaveAttribute("tabindex", "0");
parent.setAttribute("random-id", "b");
rerender(props());
await waitFor(() =>
// parent ".." plus the single remaining file
expect(screen.getAllByRole("row")).toHaveLength(2),
);
const rows = screen.getAllByRole("row");
const tabbable = rows.filter((r) => r.getAttribute("tabindex") === "0");
expect(tabbable).toHaveLength(1);
expect(rows[0]).toHaveAttribute("tabindex", "0");
});
it("syncs the tabbable row to whichever row gains focus", async () => {
renderBrowser();
await screen.findByText("docs");
const rows = screen.getAllByRole("row"); // [.., docs, a.txt, b.txt]
expect(rows[0]).toHaveAttribute("tabindex", "0");
fireEvent.focus(rows[2]); // e.g. focus from a mouse click, not arrow keys
expect(rows[2]).toHaveAttribute("tabindex", "0");
expect(rows[0]).toHaveAttribute("tabindex", "-1");
});
it("moves focus to the parent row after navigating from within the grid", async () => {
// Navigating into a directory unmounts the focused row; focus must follow
// to the parent row instead of falling back to the document body.
const list_directory = vi
.fn()
.mockResolvedValueOnce({
files: FILES,
total_count: FILES.length,
is_truncated: false,
})
.mockResolvedValue({
files: [
{
id: "99",
path: "/home/user/docs/inner.txt",
name: "inner.txt",
is_directory: false,
},
],
total_count: 1,
is_truncated: false,
});
renderBrowser({ selectionMode: "all", list_directory });
await screen.findByText("docs");
const rows = screen.getAllByRole("row"); // [.., docs, a.txt, b.txt]
fireEvent.keyDown(rows[0], { key: "ArrowDown" }); // focus the docs row
expect(rows[1]).toHaveFocus();
fireEvent.keyDown(rows[1], { key: "Enter" }); // navigate into docs
await screen.findByText("inner.txt");
expect(screen.getAllByRole("row")[0]).toHaveFocus();
});
it("moves focus with arrows and clamps at the ends", async () => {
renderBrowser();
await screen.findByText("docs");
const rows = screen.getAllByRole("row"); // [.., docs, a.txt, b.txt]
fireEvent.keyDown(rows[0], { key: "ArrowDown" });
expect(rows[1]).toHaveFocus();
expect(rows[1]).toHaveAttribute("tabindex", "0");
fireEvent.keyDown(rows[1], { key: "ArrowUp" });
expect(rows[0]).toHaveFocus();
fireEvent.keyDown(rows[0], { key: "ArrowUp" }); // clamp at top
expect(rows[0]).toHaveFocus();
fireEvent.keyDown(rows[0], { key: "End" });
expect(rows[3]).toHaveFocus();
fireEvent.keyDown(rows[3], { key: "ArrowDown" }); // clamp at bottom
expect(rows[3]).toHaveFocus();
fireEvent.keyDown(rows[3], { key: "Home" });
expect(rows[0]).toHaveFocus();
});
it("Enter navigates into a directory", async () => {
const setValue = vi.fn();
const { listDirectory } = renderBrowser({
selectionMode: "all",
setValue,
});
await screen.findByText("docs");
fireEvent.keyDown(rowFor("docs"), { key: "Enter" });
await waitFor(() =>
expect(listDirectory).toHaveBeenCalledWith({ path: "/home/user/docs" }),
);
// navigation does not mutate value
expect(setValue).not.toHaveBeenCalled();
});
it("Enter toggles selection on a selectable file", async () => {
const setValue = vi.fn();
renderBrowser({ selectionMode: "all", multiple: true, setValue });
await screen.findByText("a.txt");
fireEvent.keyDown(rowFor("a.txt"), { key: "Enter" });
expect(setValue).toHaveBeenCalledWith([
expect.objectContaining({ path: "/home/user/a.txt" }),
]);
});
it("Space toggles selection and never navigates", async () => {
const setValue = vi.fn();
renderBrowser({ selectionMode: "all", multiple: true, setValue });
await screen.findByText("docs");
// Space on a selectable directory selects it (does not navigate)
fireEvent.keyDown(rowFor("docs"), { key: " " });
expect(setValue).toHaveBeenCalledWith([
expect.objectContaining({ path: "/home/user/docs" }),
]);
});
it("Space on the parent row is a no-op", async () => {
const setValue = vi.fn();
renderBrowser({ selectionMode: "all", setValue });
await screen.findByText("docs");
const parentRow = screen.getAllByRole("row")[0];
fireEvent.keyDown(parentRow, { key: " " });
expect(setValue).not.toHaveBeenCalled();
});
});
function rowFor(name: string): HTMLElement {
return screen.getByText(name).closest('[role="row"]') as HTMLElement;
}
describe("FileBrowserPlugin breadcrumbs", () => {
function breadcrumbs() {
return within(
screen.getByRole("navigation", { name: "Current directory" }),
);
}
it("renders a crumb per ancestor with the current directory last", async () => {
renderBrowser();
await screen.findByText("docs");
const items = breadcrumbs().getAllByRole("listitem");
expect(items.map((li) => li.textContent)).toEqual(["/", "home", "user"]);
expect(breadcrumbs().getByRole("button", { name: "user" })).toHaveAttribute(
"aria-current",
"page",
);
expect(
breadcrumbs().getByRole("button", { name: "home" }),
).not.toHaveAttribute("aria-current");
});
it("keeps focus on a crumb after navigating to it", async () => {
const { listDirectory } = renderBrowser();
await screen.findByText("docs");
const home = breadcrumbs().getByRole("button", { name: "home" });
home.focus();
fireEvent.click(home);
await waitFor(() =>
expect(listDirectory).toHaveBeenLastCalledWith({ path: "/home" }),
);
const current = breadcrumbs().getByRole("button", { name: "home" });
expect(current).toHaveAttribute("aria-current", "page");
expect(current).toBe(home);
expect(current).toHaveFocus();
});
it("does not reload when the current crumb is clicked", async () => {
const { listDirectory } = renderBrowser();
await screen.findByText("docs");
fireEvent.click(breadcrumbs().getByRole("button", { name: "user" }));
expect(listDirectory).toHaveBeenCalledTimes(1);
});
it("navigates to an ancestor when a crumb is clicked", async () => {
const { listDirectory } = renderBrowser();
await screen.findByText("docs");
fireEvent.click(breadcrumbs().getByRole("button", { name: "home" }));
await waitFor(() =>
expect(listDirectory).toHaveBeenLastCalledWith({ path: "/home" }),
);
fireEvent.click(breadcrumbs().getByRole("button", { name: "/" }));
await waitFor(() =>
expect(listDirectory).toHaveBeenLastCalledWith({ path: "/" }),
);
});
it("hides ancestors outside the initial path when navigation is restricted", async () => {
render(
<FileBrowser
initialPath="/home/user"
filetypes={[]}
selectionMode="all"
multiple={true}
label={null}
restrictNavigation={true}
value={[]}
setValue={vi.fn()}
host={document.createElement("div")}
list_directory={mockListDirectory(FILES)}
/>,
);
await screen.findByText("docs");
const items = breadcrumbs().getAllByRole("listitem");
expect(items.map((li) => li.textContent)).toEqual(["user"]);
});
});