| .. | ||
| api | ||
| helpers | ||
| unit | ||
| .env | ||
| .env.example | ||
| constants.ts | ||
| global-setup.ts | ||
| jest.config.js | ||
| OOM-FINDINGS.md | ||
| README.md | ||
| run-all.ts | ||
| seed-local.ts | ||
| setup.ts | ||
| tsconfig.json | ||
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:
- A full suite run leaves hundreds of
E2E */ fixture stores, products, tags, regions, users and slots in the local D1 (plus a few cache/const rows). 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. See Cleaning up test data after a run. 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.
Cleaning up test data
The suite writes into the local D1 (freshyo-dev), not a throwaway DB. After
a run it leaves test regions/bounds, ~300 stores, ~300 products and their SKUs,
tags, groups, slots, staff, users, orders, coupons, banners, snippets and
global_consts probes behind. It also bumps the versioned cache files and the KV
mirror. Clean up after a full run (or before handing the DB to someone).
Local only. Never point this at
wrangler.prod.toml,--remote, or a shared D1. The helper script refuses--remote; keep it that way.
1. Back up and stop the dev server
wrangler dev holds the DB; stop it first so SQLite writes and VACUUM do not
hit a lock. Restart it when done.
cd apps/backend
pkill -f "wrangler dev --config wrangler.dev.toml" || true
DB=$(find .wrangler/state/v3/d1 -name '*.sqlite' ! -name 'metadata.sqlite' | head -1)
sqlite3 "$DB" ".backup '/tmp/freshyo-dev-before-cleanup.sqlite'"
2. Delete the rows the script knows about
scripts/remove-test-data.ts removes everything created at/after --since
(default 2026-10-18) while preserving the keep user (default mobile
9676651496) and all older real data.
bun run remove-test-data -- --dry-run # prints the SQL + before counts
bun run remove-test-data # applies it
bun run remove-test-data -- --since "2026-10-18" --keep-mobile 9676651496
3. Delete what the script does not cover
These are the leftovers observed after a full run. Run them in one transaction;
delivery_slot_info has no created_at, so the fixture dates are the marker.
sqlite3 "$DB" <<'SQL'
PRAGMA busy_timeout=15000;
BEGIN IMMEDIATE;
-- fixture-date slots (no orders reference them)
DELETE FROM delivery_slot_info
WHERE delivery_time LIKE '2030-06-01%' OR delivery_time LIKE '2020-01-01%';
-- probe keys written by the consts suites
DELETE FROM global_consts
WHERE key LIKE '\_\_e2e%' ESCAPE '\' OR key = 'zzz_probe';
-- test placeholder welcome message (re-enter it in the admin UI if it was real)
DELETE FROM region_consts
WHERE key = 'welcomeMessage' AND value = 'E2E probec';
-- test bound + its settings (check addresses first: SELECT COUNT(*) FROM addresses WHERE bound_id = <id>)
DELETE FROM region_bound_consts WHERE bound_id = 17;
DELETE FROM region_bounds WHERE id = 17;
-- old test product that predates the cutoff (cascade)
DELETE FROM sku_features WHERE sku_id IN (SELECT id FROM product_skus WHERE product_id = 150);
DELETE FROM product_market_stats WHERE sku_id IN (SELECT id FROM product_skus WHERE product_id = 150);
DELETE FROM product_combos WHERE sku_id IN (SELECT id FROM product_skus WHERE product_id = 150)
OR combo_sku_id IN (SELECT id FROM product_skus WHERE product_id = 150);
DELETE FROM special_deals WHERE sku_id IN (SELECT id FROM product_skus WHERE product_id = 150);
DELETE FROM cart_items WHERE sku_id IN (SELECT id FROM product_skus WHERE product_id = 150);
DELETE FROM order_items WHERE sku_id IN (SELECT id FROM product_skus WHERE product_id = 150);
DELETE FROM product_tags WHERE product_id = 150;
DELETE FROM product_group_membership WHERE product_id = 150;
DELETE FROM product_reviews WHERE product_id = 150;
DELETE FROM product_skus WHERE product_id = 150;
DELETE FROM product_info WHERE id = 150;
COMMIT;
SQL
Skip the product-150 block if that row was already removed. If a test bound has a
different id, look it up first
(SELECT id, region_id, description FROM region_bounds WHERE description LIKE 'e2e%';).
Slots created by tests in a real region with an ordinary delivery date and an
empty sku_ids cannot be told apart from real slots; review
SELECT id, delivery_time, region_id FROM delivery_slot_info ORDER BY id DESC;
if that matters for your DB.
$DB only exists in the shell that ran step 1 — re-export it if you split the
steps across terminals:
DB=$(find .wrangler/state/v3/d1 -name '*.sqlite' ! -name 'metadata.sqlite' | head -1)
4. Reclaim the file size
The deletes leave free pages behind; VACUUM shrinks the file. The dev server is
still stopped from step 1.
sqlite3 "$DB" "VACUUM;"
sqlite3 "$DB" "PRAGMA integrity_check; PRAGMA foreign_key_check;"
5. Clear the KV mirror and rebuild the cache files
common.essentialConsts is served from KV (freshyo_gen_dev), so stale test
values survive a DB cleanup until the mirror is rewritten. The cache files
(products.json, stores.json, …) are versioned in S3 and were built during the
run, so bump them too — otherwise the app keeps fetching the test-built version.
# stop the dev server first (step 1), then wipe the mirror (all keys are consts)
./node_modules/.bin/wrangler kv key list --binding freshyo_gen_dev --local --config wrangler.dev.toml \
| python3 -c 'import sys,json; raw=sys.stdin.read(); print(json.dumps([k["name"] for k in json.loads(raw[raw.index("["):])]))' \
> /tmp/freshyo-kv-keys.json
./node_modules/.bin/wrangler kv bulk delete /tmp/freshyo-kv-keys.json \
--binding freshyo_gen_dev --local --config wrangler.dev.toml --force
Restart the dev server (bun run dev), then rebuild each live region through the
guarded test route. It is behind authenticateUser + ENABLE_TEST_ROUTES=true,
so send a bearer token. Mint a short-lived one with the JWT_SECRET from
wrangler.dev.toml (use any row that still exists in users, e.g. the keep user
388):
# from apps/backend
cat > /tmp/freshyo-mint-jwt.ts <<'TS'
import { SignJWT } from 'jose'
import { readFileSync } from 'node:fs'
const m = readFileSync('wrangler.dev.toml', 'utf8').match(/^\s*JWT_SECRET\s*=\s*["']([^"']+)["']/m)!
const token = await new SignJWT({ userId: 388 })
.setProtectedHeader({ alg: 'HS256' })
.setExpirationTime('10m')
.sign(new TextEncoder().encode(m[1]))
console.log(token)
TS
TOKEN=$(bun /tmp/freshyo-mint-jwt.ts)
for R in 1 2 3; do
curl -s -X POST "http://127.0.0.1:8787/api/test/rebuild?regionId=$R" \
-H "Authorization: Bearer $TOKEN"
done
This rewrites essentialConsts_<boundId> for the live bounds only and bumps
products_version_num, so the app points at the freshly built files.
6. Verify the result
sqlite3 -column "$DB" "
SELECT 'regions', COUNT(*) FROM regions
UNION ALL SELECT 'stores', COUNT(*) FROM store_info
UNION ALL SELECT 'products', COUNT(*) FROM product_info
UNION ALL SELECT 'tags', COUNT(*) FROM product_tag_info
UNION ALL SELECT 'slots', COUNT(*) FROM delivery_slot_info
UNION ALL SELECT 'users', COUNT(*) FROM users
UNION ALL SELECT 'staff', COUNT(*) FROM staff_users;"
A clean local DB looked like: regions 3, stores 6, products 153, tags 9, slots
495, users 1320, staff 7, integrity_check: ok, foreign_key_check empty,
file ≈1.3 MB (from ≈3.9 MB). The keep user's own orders/complaints are preserved
by design. common.essentialConsts should return welcomeMessage: "" and only
the live bounds should remain as essentialConsts_* keys.
Restart the dev server when finished. Remember: the run itself is expected to add all of this again — clean up after the suite, not before.
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.