308 lines
13 KiB
Markdown
308 lines
13 KiB
Markdown
# 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
|
|
<router>-<area>.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:
|
|
|
|
- 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](#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 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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
# 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`):
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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.
|