Testing
Everything runs under Bun’s test runner. There is no Node and no separate test tool. Typecheck with bun check, not tsc.
The same commands run in CI (.github/workflows/ci.yml). Set up first as described in Building: bun install --frozen-lockfile in core, word/sidebar and gpui-ui, bun core/scripts/fetch-zotero-vendor.ts, and the fulltext placeholder file.
The checks
| Project | Command | Notes |
|---|---|---|
core |
cd core && bun check && bun test --timeout 30000 |
Includes the quick fuzz suite |
gpui-ui |
cd gpui-ui && bun check && bun test --timeout 30000 |
Pure-logic tests only; the native-window scripts are not run |
word/sidebar |
cd word/sidebar && bun check && bun test |
The Word end-to-end tests skip unless enabled |
word/addin |
dotnet build word/addin/ZoteroNextWord.csproj -c Release -nologo -v q -o "$TEMP/addin-out" |
-o keeps the build out of word/dist |
connector-host |
cd connector-host && bun run build && bun test |
Not in CI; the test needs the compiled exe |
The same commands work on Linux and macOS, apart from the word/addin and connector-host rows, which are Windows only. The --timeout 30000 matters on a cold Windows machine: a few translator tests copy about 750 files and exceed Bun’s 5 s default.
core/package.json still has a typecheck script that calls bunx tsc --noEmit; use bun check instead, as CI does.
Where tests live
| Location | What |
|---|---|
core/test/**/*.test.ts |
Core unit and integration tests, one folder per area (sync/, websync/, translate/, cite/, connector/, mcp/, zport/, update/, …) and top-level files such as migrations.test.ts, api.test.ts, server.test.ts and item-index.test.ts (GET /api/items/index must give each item’s position exactly as GET /api/items lists it, for ten sorts, filters and views, and -1 for an item outside the listing) |
core/test/fixture.ts |
Helpers that create a temporary library and insert items and attachments |
core/test/fuzz/ |
Property-based tests (fast-check) |
gpui-ui/src/**/*.test.ts |
Pure-logic tests next to the code they test (*.fuzz.test.ts for fuzzed ones) |
word/sidebar/test/ |
Sidebar, field-code and agent tests, and the Word end-to-end tests |
connector-host/test/ |
Native-messaging host tests |
core/bunfig.toml preloads core/test/tmp-preload.ts. It points os.tmpdir() at one per-run folder under %TEMP% (zn-test-run-<pid>-<time>) and removes it afterwards, plus the folders of earlier runs whose process has ended, because several tests make large library copies. Tests only use temporary folders and databases, never your library, and never the network. The HTTP tests start their own server on a free port.
Skip rules
Tests that depend on something a fresh clone does not have skip themselves.
| Missing piece | Tests that skip |
|---|---|
core/vendor/fulltext-wasm/fulltext.wasm (empty or smaller than 1 KiB counts as missing) |
core/test/fulltext/*, the Find Full Text engine tests |
vendor/document-worker/build/worker.js |
core/test/extract and “retrieve metadata for PDFs” in core/test/additems |
~/Zotero/zotero.sqlite |
The zotero-db writer tests |
~/Zotero/zotero.sqlite plus data/library.sqlite |
The real-copy sync test (core/test/sync/integration.test.ts); override with ZN_TEST_ZOTERO_DIR and ZN_TEST_LIBRARY |
process.env.CI set |
The 30k-item performance tests (core/test/perf.test.ts, api-perf.test.ts) |
ZN_WORD_E2E=1 not set |
word/sidebar/test/word-e2e.test.ts (starts a private invisible Word) |
The first two rules are in core/test/needs.ts. To see what a CI machine sees, run with USERPROFILE pointed at an empty folder.
Fuzzing
The fuzz suite (core/test/fuzz/*.fuzz.test.ts, plus gpui-ui/src/**/*.fuzz.test.ts) feeds random and mutated input to code that reads untrusted data: importers, zip handling, Word field codes, the Better BibTeX formula parser, sync apply, the HTTP API and the saved-search compiler. The full table is in core/test/fuzz/README.md. It runs inside bun test with about 150 cases per property and a random seed per run.
| Variable | Effect |
|---|---|
ZN_FUZZ_RUNS |
Cases per property (default about 150) |
ZN_FUZZ_SEED |
Fixed starting seed (default random) |
ZN_FUZZ_PATH |
With a seed, replays one shrunk counterexample |
cd corebun test test/fuzz # normalZN_FUZZ_RUNS=5000 bun test test/fuzz # long runA failing property prints [fuzz] FAILED <name>, the shrunk counterexample and a replay: line:
ZN_FUZZ_SEED=123 ZN_FUZZ_PATH="4:2:1" bun test core/test/fuzz/<file> -t "<property name>"Run that line (with the real file and property name) to reproduce exactly the failing case. After fixing the bug, add the shrunk input as a plain test() in the same file so it stays covered without the fuzzer. A case that runs longer than its time box (3 s by default) fails; that is how hangs and quadratic blow-ups are caught. The Rust crate gpui-ui/native/pdf is not fuzzed.
Headless screenshot scripts
The GPUI app can be rendered without opening a window. GPUIX’s test renderer (createTestRoot() from @gpuix/solid/testing) renders offscreen, and renderer.captureScreenshot(path) writes a PNG, about 1440 by 881 pixels whatever size you ask for. The scripts are gpui-ui/scripts/shot-*.tsx; run them from gpui-ui/:
bun scripts/shot-hello.tsx out.png # smoke testbun scripts/shot-app.tsx out.png # the whole appbun scripts/shot-settings.tsx # Settingsbun scripts/shot-update.tsx [light] # the auto-update UI against a fake feedZN_URL=<core on a library COPY> bun scripts/shot-reveal.tsx [table|cards] [stay] [direct] # "Open in Zinc"shot-reveal.tsx checks store.revealItem (see Architecture) on an item with no file. It picks the item 600 rows down My Library, so it is far off screen. By default it starts in a collection with a search typed and expects the app to switch to My Library, clear the search, select the item and scroll its row into view. It prints the checks (found, view, filter, selected, focusIndex, rowShown), the list’s scroll anchor and the scroll request, and saves a screenshot. table (default) or cards picks the list; stay starts in My Library instead, so the item is only far down; direct also makes a direct scrollToItem call afterwards and prints where the list ends up. Preferences go to a throw-away file.
The shell scripts share gpui-ui/scripts/shell-shot-lib.tsx (boot the app in the test renderer, settle, click, capture) and _shell-env.ts. ZN_SHOTS=<dir> sets the output folder (without it the scripts fall back to a fixed default folder, so set it). Each run points ZN_UI_STATE at a throw-away file so your real preferences are not touched. Scripts that need data talk to a core at ZN_URL serving a copy of a library; some scripts (for example shot-item-actions.tsx) write to that library, so always use a VACUUM INTO copy. These scripts need a GPU and are not run in CI. They are the way to check a layout change; a screenshot is not a test.
Other scripts in gpui-ui/scripts/: scroll-test.tsx and scroll-bench.ts (scroll timing), memory.ts and startup.ts (memory and start-up of the real window), aot-bench.ts (start-up of source versus compiled builds). These open a visible window; do not click in it.
Other test groups
Word
word/sidebar/test/ has fast tests (agent.test.ts, app.test.ts, fields.test.ts, popup.test.ts) that run by default. The end-to-end tests drive the real add-in in a private invisible Word and are off by default:
ZN_WORD_E2E=1 ZN_TEST_DB=<copy of a library> bun test test/word-e2e.test.tsThe harness refuses to start while any WINWORD.EXE is running. mcp-e2e.test.ts tests the add-in’s MCP server in two parts: set ZN_MCP_E2E=1 for the HTTP layer and library tools (no Word), add ZN_WORD_E2E=1 for the full citation flow. Build into a scratch folder and set ZN_WORD_DIST=<dir> so the tests never use the installed add-in in word/dist; the header of the test file lists the steps.
Connector host
connector-host/test/host.test.ts replays a browser-extension save over native-messaging frames through the compiled host against a temporary library. Build first with bun run build. ZNH_SOURCE_DB makes it work on a copy of a given library; ZNH_TEST_DIR sets the working folder.
Web sync and update end to end
core/test/websync/tests zotero.org sync against a mock server (mock.ts,rig.ts), with no network.core/test/update/e2e.test.tsruns the real updater against a localBun.servefeed with a signed manifest and a stub.cmdinstaller.ZN_E2E_OUT=<dir>keeps the evidence files; otherwise a temp folder is used. Run it withcd core && bun test test/update.
Continuous integration
ci.yml runs on every push and pull request, and on manual dispatch. A newer push to the same ref cancels the run in progress. Bun is pinned to 1.4.4.
| Job | Runner | Steps |
|---|---|---|
core |
windows-latest and ubuntu-latest (matrix, no fail-fast), 20 min timeout |
install core and word/sidebar; fetch the vendored Zotero code (cached on the hash of fetch-zotero-vendor.ts); create the empty fulltext placeholder; bun check; bun test --timeout 30000 |
windows-rest (“gpui-ui, word”) |
windows-latest, 20 min timeout |
install gpui-ui, core, word/sidebar; gpui-ui bun check and bun test --timeout 30000; word/sidebar bun check and bun test; build the add-in with dotnet build ... -o "$RUNNER_TEMP/addin-out" |
ci.yml never builds the Rust library, the executable, the installer or the connector host, and it never runs the screenshot scripts. The core job runs on Linux as well as Windows, so path and platform code in core must work on both (core/src/platform-dirs.ts takes the platform and environment as arguments so tests can resolve Linux and macOS paths from Windows).
macos.yml runs on macos-15 (Apple Silicon), by hand and on pushes to main that touch code that differs per OS (gpui-ui/native/, gpui-ui/src/webview/, gpui-ui/src/shell/, the PDF binding, the two print modules, platform-dirs.ts, library-location.ts, gpui-ui/package.json and its lock file). It runs bun check and bun test --timeout 30000 in core and gpui-ui, builds native/pdf as a dylib, fetches PDFium, and runs gpui-ui/scripts/smoke-native.ts. It keeps the screenshots as the artifact macos-smoke.
desktop-packages.yml builds the AppImage and the disk image; see Releasing.
Native smoke test
bun gpui-ui/scripts/smoke-native.ts [outDir] starts the real app window on the machine it runs on (macOS in CI; it also works on Linux and Windows) against a throw-away library with its own APPDATA. It opens a demo PDF in a reader tab and saves library.png, reader.png and summary.json. On Linux and macOS it also shows a test page in the web view, clips it, and prints pages 2 and 3 of the PDF to a file without a dialog (the file must have two pages). It exits 1 if the list did not load, the PDF library could not be used, the reader tab did not open, the web view did not come up or the print is wrong. It opens a visible window; do not click in it.
fuzz-nightly.yml runs at 03:17 UTC every day and on manual dispatch (inputs: cases per property, default 5000, and an optional fixed seed). It runs on ubuntu-latest with a 120 minute timeout, installs core and word/sidebar, fetches the vendored code, creates the placeholder, and runs bun test --timeout 3600000 test/fuzz in core/ with ZN_FUZZ_RUNS and ZN_FUZZ_SEED set. Whether or not it fails, it extracts the [fuzz] FAILED and replay: lines into failure-seeds.txt and uploads the log and that file as the artifact fuzz-failures-<run id> for 30 days. To reproduce a nightly failure, take the replay line from the artifact.