5.8 KiB
Backend live API test suite
Runnable implementation of ../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
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:
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
<router>-<area>.test.ts
Clients and sessions
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)
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
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/availabilityversion bumps are synchronous in the mutation.products/stores/bannersare rebuilt asynchronously by theCacheCreatorDurable Object: always poll, never sleep once.- Tolerate a first 404/old version — rebuilds are not atomic (CACHE-50/105).
Row conventions
- One
it()per catalogue row, named with the row id:it('UAUTH-01: ...'). - Assert the tRPC error code with
expectTrpcError(fn, 'UNAUTHORIZED'). - For mutations, assert the persisted effect through a follow-up read.
- For cache rows, assert the version moved and the file contains the change.
- Rows that describe intent the code does not implement are prefixed
(current)and carry a comment explaining the observed contract. - Cache/auth suites are stateful: run files serially (
--runInBandis set).
Local-dev environment limitations
Full-suite runs can exhaust the local
workerdheap and crash the backend (mass “fetch failed” failures). See 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 uploadsstores.jsonandproducts.json, but the per-store loop (createAllStoresFilesInternal) can stop partway through, sostores/<id>.jsonmay be missing for stores created later.stores.jsonitself still reflects them. common.essentialConstsis served from the KV mirror;products_version_numthere can be ahead ofregion_constsin D1 during/after a rebuild. Assert version movement, not equality across the two stores.webviewHtmlforraw/mfhosts cannot be exercised withfetch(theHostheader is forbidden). Normal hosts returnnull+ 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.