freshyo/apps/backend/tests
2026-10-23 15:58:40 +05:30
..
api enh 2026-10-23 15:58:40 +05:30
helpers enh 2026-10-20 00:31:05 +05:30
unit enh 2026-10-20 19:15:58 +05:30
.env enh 2026-10-23 15:58:40 +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 12:54:32 +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:

  • 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 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. See Cleaning up test data after a run.
  • 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.

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.