freshyo/apps/backend/tests
2026-10-20 00:31:05 +05:30
..
api enh 2026-10-20 00:31:05 +05:30
helpers enh 2026-10-20 00:31:05 +05:30
unit enh 2026-10-20 00:31:05 +05:30
.env enh 2026-10-20 00:31:05 +05:30
.env.example enh 2026-10-20 00:31:05 +05:30
constants.ts enh 2026-10-20 00:31:05 +05:30
global-setup.ts enh 2026-10-20 00:31:05 +05:30
jest.config.js enh 2026-10-20 00:31:05 +05:30
OOM-FINDINGS.md enh 2026-10-20 00:31:05 +05:30
README.md enh 2026-10-20 00:31:05 +05:30
run-all.ts enh 2026-10-20 00:31:05 +05:30
seed-local.ts enh 2026-10-20 00:31:05 +05:30
setup.ts enh 2026-10-20 00:31:05 +05:30
tsconfig.json enh 2026-10-20 00:31:05 +05:30

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 / 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 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/<id>.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.