# 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](https://aborakati.github.io/zinc/developer-guide/building.md): `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 core
bun test test/fuzz                       # normal
ZN_FUZZ_RUNS=5000 bun test test/fuzz     # long run
```

A 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 test
bun scripts/shot-app.tsx out.png          # the whole app
bun scripts/shot-settings.tsx             # Settings
bun scripts/shot-update.tsx [light]       # the auto-update UI against a fake feed
ZN_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](https://aborakati.github.io/zinc/developer-guide/architecture.md#open-in-zinc-showing-an-item-from-outside-the-app)) 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.ts
```

The 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.ts` runs the real updater against a local `Bun.serve` feed with a signed manifest and a stub `.cmd` installer. `ZN_E2E_OUT=<dir>` keeps the evidence files; otherwise a temp folder is used. Run it with `cd 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](https://aborakati.github.io/zinc/developer-guide/releasing.md#linux-and-macos-packages).

### 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.
