# Backend live API test suite Runnable implementation of [`../API-TEST-CASES.md`](../API-TEST-CASES.md). These are **live HTTP tests**: they talk to a running backend (`wrangler dev`), authenticate with real tokens, create data through the API, and read the versioned public cache files. There are no mocks and no imports of backend runtime code (only the `AppRouter` type). ## Prerequisites ```bash cd apps/backend bun run dev # wrangler dev on :8787 (keep running) bun run tests/seed-local.ts # once: seeds e2e_super / e2e_staff / e2e_user + tests/.env bun run test:api # jest --runInBand ``` `tests/seed-local.ts` is idempotent. It writes `tests/.env` (local-only). To point at another backend, copy `tests/.env.example` to `tests/.env` and fill it in. Useful scripts: ```bash bun run test:api -- tests/api/user-auth.test.ts # one file bun run test:api -- -t "UAUTH-01" # one row bun run test:api:typecheck # tsc over tests/ ``` ## Layout ``` tests/ jest.config.js ts-jest, node, maxWorkers 1 setup.ts dotenv + timeout seed-local.ts idempotent local-D1 principals helpers/ env.ts API_BASE_URL, credentials, region/bound, poll knobs api.ts apiClient / rawQuery / rawMutation / rest / errors sessions.ts cached staff, user, superadmin sessions cache.ts versioned URLs, polling, version snapshots fixtures.ts stores, products, slots, users, addresses, orders, coupons api/ 00-harness.test.ts HARNESS-*, HTTP-01, COMMON read paths, E2E smoke -.test.ts ``` ## Clients and sessions ```ts import { apiClient, rawQuery, rawMutation, rest, uniqueSuffix, expectTrpcError } from '../helpers/api' import { staffClient, userClient, superadminClient, anonClient } from '../helpers/sessions' const admin = await staffClient() // typed as staff const user = await userClient() // typed as the seeded user const superadmin = await superadminClient() const anon = anonClient() const token = (await import('../helpers/sessions')).staffSession // for raw calls ``` ## Fixtures (create through the API) ```ts import { createStore, createProduct, createFutureSlot, createAddress, registerThrowawayUser, createCoupon, placeOrder, createCatalogOrderFixture, withBoundSetting, createRegion } from '../helpers/fixtures' const store = await createStore() const product = await createProduct({ storeId: store.storeId, price: 499 }) const slot = await createFutureSlot([product.skuId]) const user = await registerThrowawayUser() const address = await createAddress(user.token) const orders = await placeOrder(user.token, { addressId: address.id, skuId: product.skuId, slotId: slot.slotId }) ``` Every name/code carries `uniqueSuffix()`. Tests must not delete seeded rows (region 1/2/3, existing stores/products/orders/coupons). `createCatalogOrderFixture()` returns a ready user + store + product + slot + address. ## Cache contract ```ts import { getEssentialConsts, versionSnapshot, waitForVersion, productsCacheUrl, availabilityCacheUrl, slotsCacheUrl, pollCacheJson, fetchCacheJson } from '../helpers/cache' const consts = await getEssentialConsts() // bound 1 const v = consts.products_version_num // also slots_version_num / availability_version_num await waitForVersion('products', v) // polls 3s up to 180s const doc = await fetchCacheJson(productsCacheUrl(consts)) ``` Rules: - `slots` / `availability` version bumps are synchronous in the mutation. - `products` / `stores` / `banners` are rebuilt asynchronously by the `CacheCreator` Durable Object: always poll, never sleep once. - Tolerate a first 404/old version — rebuilds are not atomic (CACHE-50/105). ## Row conventions 1. One `it()` per catalogue row, named with the row id: `it('UAUTH-01: ...')`. 2. Assert the tRPC error code with `expectTrpcError(fn, 'UNAUTHORIZED')`. 3. For mutations, assert the persisted effect through a follow-up read. 4. For cache rows, assert the version moved **and** the file contains the change. 5. Rows that describe intent the code does not implement are prefixed `(current)` and carry a comment explaining the observed contract. 6. Cache/auth suites are stateful: run files serially (`--runInBand` is set). ## Local-dev environment limitations > Full-suite runs can exhaust the local `workerd` heap and crash the backend > (mass “fetch failed” failures). See **[OOM-FINDINGS.md](./OOM-FINDINGS.md)** for > the measurements, the one-time DB-init fix, and the chunked runner > (`bun run test:api:all`) that restarts the backend between chunks. These are properties of this seeded local D1, not of the contract. Pin them as `(current)` instead of failing the suite: - The dev DB contains ~490 legacy `E2E *` stores. A full cache rebuild uploads `stores.json` and `products.json`, but the per-store loop (`createAllStoresFilesInternal`) can stop partway through, so `stores/.json` may be missing for stores created later. `stores.json` itself still reflects them. - `common.essentialConsts` is served from the KV mirror; `products_version_num` there can be ahead of `region_consts` in D1 during/after a rebuild. Assert version *movement*, not equality across the two stores. - `webviewHtml` for `raw`/`mf` hosts cannot be exercised with `fetch` (the `Host` header is forbidden). Normal hosts return `null` + closable. ## Current known gaps (pin, don't "fix" silently) See `API-TEST-CASES.md` §13. In particular: `protectedProcedure` admin reads accept a user token, `admin.order.getAll` returns `undefined` on error, `getOrderById`/`cancelOrder`/`updateUserNotes` accept only numeric-string ids, `placeOrder` has no idempotency/quantity cap, and cache rebuilds are eventual.