freshyo/apps/backend/test-case-info.md
2026-09-26 22:29:54 +05:30

340 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# backend — API test case info
HTTP/API tests that drive a **running** backend (not unit tests): they log in with
real credentials, create data through the API, and pull the generated static JSON
cache the apps consume.
- **Runner**: jest + ts-jest, node environment, serial (`--runInBand`)
- **Total**: **22 suites / 107 tests** — all green (`bun run test:api`, ~2.5 min)
- Tests live in `apps/backend/tests/`; they do not import server runtime code beyond
the `AppRouter` type.
## Run
```bash
# 1. start the backend (wrangler dev, port 8787)
cd apps/backend && bun run dev
# 2. fill in credentials (git-ignored)
cp apps/backend/tests/.env.example apps/backend/tests/.env # then edit
# 3. run
cd apps/backend && bun run test:api
bun run test:api:typecheck # tsc over tests/
```
`API_BASE_URL` defaults to `http://localhost:8787`; override it in `tests/.env`.
## Environment notes
- **Auth**: `admin.staffUser.login` (staff) and `user.auth.login` (user). Login, not OTP —
OTP requires a real SMS. The user must exist in the **local** D1.
- **Preconditions are not seeded** (only config/constants are): the suites create a store,
a one-SKU product and a future slot through the **admin** API, plus an address for the user.
Data is **left behind**; names carry a unique suffix so reruns stay valid.
- **Cache files** are written through the R2 S3 API to the real dev bucket and read back from
the **assets domain** (`assetsDomain` from `common.essentialConsts`, e.g.
`https://assets2.freshyo.in`). The machine therefore needs network access to both.
- **Trigger timing** decides the suite layout: `slots.json` and `availability.json` are
regenerated **synchronously** inside their mutations; `products.json` / `stores/<id>.json`
are rebuilt ~30 s later by the `CACHE_CREATOR` Durable Object → those tests poll.
- Test slots must be in the **future** and not at capacity — the public slots payload filters
to future, non-full slots.
## Findings from the first green run
- **`availability.json` is keyed by SKU id**, not product id (`id: stat.skuId`), and its
`isOutOfStock` comes from `product_market_stats`. `admin.product.toggleOutOfStock` takes a
**product** id and flips `product_market_stats` for all of that product's SKUs, so it *is*
app-visible — but look the entry up by `skuId`.
- **The cache rebuild writes files in parallel (non-atomic).** After `cacheVersion` advances,
`products.json` can be readable while `stores/<id>.json` is still uploading (observed: 404 at
the new version, 200 moments later). The tests therefore poll for each individual file.
- **`placeOrder` accepts a non-existent `slotId`.** It only checks slot *capacity*; there is no
FK/validity check, so a bogus id is stored verbatim. Case 17 documents this gap — it will need
updating if the backend adds validation.
- **Admin *reads* are not staff-guarded.** `protectedProcedure` only requires *some* identity, so a
plain user token can call `admin.product.getProducts` (documented by the authorization suite).
Staff-guarded writes (e.g. `admin.slots.createSlot`) do check `ctx.staffUser`.
- **`availability.json` and `slots.json` can lead `products.json`.** Both are bumped synchronously
(stock toggle / slot mutation) while `products.json` only rebuilds ~30 s later, so for a window
the cache references product ids that the product file doesn't have yet. The consistency checks
poll for convergence and assert the stable parts.
- **`essential-consts.json` embeds a version snapshot** taken when it was written, so its
`slotsVersionNum`/`availabilityVersionNum` can lag the live values (slots bump independently).
Consumers get versions from `common.essentialConsts` (tRPC), not from this file.
- **`updateProduct` requires a SKU feature literally named `quantity`** ("Every SKU must have a
quantity feature") — the same rule as the create path.
- **`admin.order.updateAddressCoords` succeeds but is not visible to the user.** The
user-facing `address.getUserAddresses` still returns `latitude` null/0, so the admin write and
the user read disagree. The test asserts the mutation contract only.
- **`admin.order.cancelOrder` refuses an already-delivered order**; the test cancels a freshly
placed one instead.
- **`admin.order.*` id types are inconsistent**: `getOrderDetails` / `updateNotes` /
`removeDeliveryCharge` / `cancelOrder` take a **number**; `updatePackaged` / `updateDelivered` /
`getSlotOrders` take a **string**.
- **`admin.coupon.create` returns an array** (`Coupon[]`) — take `[0].id`. `update` takes
`{ id, updates }` and merges partially (fields present win). `delete` **soft-invalidates**
("Coupon invalidated successfully"): `getById` still returns the row, but it vanishes from
`coupon.getEligible` and `placeOrder` rejects it. Creating with **both** `discountPercent` and
`flatDiscount` is rejected.
- **`admin.user.getUserDetails` breaks once a user has a long order history.** It builds an
unchunked `select … from order_status where order_id in (…)` over every order the user ever
placed; at ~110 orders the query fails outright (`Failed query`). Reproduction: call it for the
shared test account after a few runs. The suite now exercises it against a fresh user. Same
unchunked pattern is used for the order stats in `admin.user.getAllUsers`.
- **`admin.product.deleteProduct` fails for a product that has SKUs.** It issues a hard
`delete from product_info … returning …`, which trips the FK from the product's SKUs /
market stats; the API returns a raw "Failed query" instead of a 404/409. There is no
soft-delete path reachable through this procedure. The test asserts the rejection.
- **`admin.store.deleteStore` takes `{ storeId }`**, unlike its siblings
(`product.deleteProduct`, `banner.deleteBanner`, `product.deleteProductTag`) which take `{ id }`.
Mismatched shape → zod `invalid_type` on `storeId`.
- **`admin.slots.getAll` returns at most 20 slots** (hard-coded limit) and keeps returning them as
runs accumulate data, so a freshly created slot is not guaranteed to be inside that window. The
membership assertion moved to the unbounded public `user.slots.getSlots`; the cap itself is now
asserted.
- **`vendorSnippets.getOrdersBySnippet` requires the snippet to be linked to a slot** —
otherwise it throws "Vendor snippet not associated with a slot", because it resolves orders
through the slot. `snippetCode` is also **required** on create.
- **`admin.banner.createBanner` needs a URL-shaped `imageUrl`** (`z.string().url()`) and extracts an
object key from it; a plausible assets-domain URL is accepted without any upload.
- **Suspension is a live precondition for ordering.** `placeOrder` rejects a suspended user
("Unable to place order"), so the admin-ops suite unsuspends the shared test user in
`beforeAll` and the suspension test restores the flag in a `finally`.
- **`stores/<id>.json` can land in a *later* cache version than the one captured after a write.**
`cacheVersion` advances on every admin write while the ~30 s rebuild writes the per-store files
separately, so the store-detail test resolves the current version on each poll attempt instead
of pinning it.
- **A presigned upload URL is usable by any client, with no R2 credentials.** The signature
travels in the query string and `Content-Type` is deliberately left unsigned (see the comment
in `generateUploadUrl`), so the test process can PUT bytes straight to R2 and read the object
back from the public assets domain. `X-Amz-Expires` is 180 s.
- **The object key is `${folder}/${Date.now()}${extension}`** (`common.generateUploadUrls`), with
the folder chosen from `contextString` (product-images, tags, store-images, review-images,
review-response-images, complaint-images, profile-images) and the extension from the mime type
(jpg/png/gif, jpg fallback). Two files with the *same* mime type in one call share a
millisecond and therefore a key — one pending-status row, two URLs, one object. Deliberately
not covered here.
- **Every presign writes a `pending` status row** (`createUploadUrlStatus`), and `claimUploadUrl`
flips it to claimed — throwing `Failed to claim upload URL` when the row is absent or already
claimed. The admin create paths that accept `uploadUrls` (product SKU images, tag image,
review response) depend on it. Not covered here: claim/re-claim, and `deleteImageUtil` on image
replacement (store update, tag update/delete, product update).
## Suites
### `api/health.test.ts` — 3 (no auth)
| # | Test | Request → assert |
| --- | --- | --- |
| 1 | GET /api/health responds 200 | `GET /api/health` → 200 + ok |
| 2 | common.healthCheck resolves over tRPC | `common.healthCheck` → truthy |
| 3 | common.essentialConsts returns the runtime config | numeric `freeDeliveryThreshold`, string `assetsDomain`/`apiCacheKey`, numeric `cacheVersion`/`slotsVersionNum` |
### `api/auth.test.ts` — 3
| # | Test | Request → assert |
| --- | --- | --- |
| 4 | staff login returns a token and staff id | `admin.staffUser.login` → token, `staff.id > 0` |
| 5 | user login returns a token and user id | `user.auth.login` → token, `user.id > 0` |
| 6 | each token authenticates its own protected procedures | staff → `admin.product.getProducts`; user → `user.address.getUserAddresses` |
### `api/admin.test.ts` — 2
| # | Test | Request → assert |
| --- | --- | --- |
| 7 | admin.product.getProducts includes the created SKU | created product found with the created sku id |
| 8 | admin.slots.getAll includes the created slot | created slot id present |
### `api/order-flow.test.ts` — 5 (the requested flow)
| # | Test | Request → assert |
| --- | --- | --- |
| 9 | lists the created slot via user.slots.getSlots | created slot id present |
| 10 | places a COD order and echoes the total | `user.order.placeOrder` (cod) → one order, id/total > 0 |
| 11 | returns the new order from user.order.getOrders | order id present, `deliveryStatus: 'pending'`, 1 item, `pagination.totalCount > 0` |
| 12 | returns the same order from user.order.getOrderById | id/amount match, 1 item |
| 13 | places an online order with a pending payment | `paymentMethod:'online'` → `paymentMode: 'Online'`, `paymentStatus: 'pending'` |
### `api/order-edge-cases.test.ts` — 4
| # | Test | Request → assert |
| --- | --- | --- |
| 14 | rejects an unauthenticated request | no token → UNAUTHORIZED |
| 15 | rejects an address that is not the user's | bogus addressId → "Invalid address" |
| 16 | rejects an unknown skuId | bogus skuId → "not found" |
| 17 | accepts a non-existent slotId (known gap) | bogus slotId → order is created and `slotId` stored verbatim (no validity/FK check) — documents the gap |
### `api/cache-slots.test.ts` — 3 (synchronous cache)
| # | Test | Request → assert |
| --- | --- | --- |
| 18 | exposes a numeric slotsVersionNum | `common.essentialConsts` → number > 0 |
| 19 | contains a newly created slot | create slot → GET `slots/v-<sv>/slots.json` → slot id present, deliveryTime matches |
| 20 | bumps the version and rewrites the file for a second slot | `slotsVersionNum` increases; the new file contains the second slot |
### `api/cache-availability.test.ts` — 2 (synchronous cache)
| # | Test | Request → assert |
| --- | --- | --- |
| 21 | reflects an out-of-stock toggle for the new SKU | `admin.product.toggleOutOfStock({id})` → `isOutOfStock: true` in the response, `availabilityVersionNum` increases → GET `av-<av>/availability.json` → entry (keyed by **skuId**) `isOutOfStock: true` |
| 22 | has a count matching the number of entries | `count === availability.length` |
### `api/cache-products.test.ts` — 2 (eventual cache, polls ~30–120 s)
| # | Test | Request → assert |
| --- | --- | --- |
| 23 | lists the new product in products.json | poll `cacheVersion` past the baseline → GET `<apiCacheKey>/v-<cv>/products.json` → new product id present |
| 24 | writes stores/&lt;id&gt;.json for the new store | GET `<apiCacheKey>/v-<cv>/stores/<id>.json` → `store.id` matches |
### `api/authorization.test.ts` — 5
| # | Test | Request → assert |
| --- | --- | --- |
| 25 | rejects anonymous requests | no token → UNAUTHORIZED |
| 26 | a staff token cannot act as a user (no ctx.user) | staff token → `user.order.getOrders` rejects |
| 27 | a user token cannot use staff-guarded admin writes | user token → `admin.slots.createSlot` rejected |
| 28 | DOCUMENTS: a user token CAN read `admin.product.getProducts` | no staff guard on admin reads — documents the gap |
| 29 | one user cannot see another user's addresses | registered user B's list excludes user A's address |
### `api/order-rules.test.ts` — 6
Uses a tiny-priced SKU (5) so one unit is below `minRegularOrderValue`.
| # | Test | Request → assert |
| --- | --- | --- |
| 30 | adds the configured delivery charge below the minimum order value | qty 1 → `deliveryCharge === deliveryCharge` const |
| 31 | waives the delivery charge at or above the minimum order value | qty to exceed min → `deliveryCharge === '0'` |
| 32 | groups items from different slots into one order per slot, charging once | 2 slots → 2 orders, exactly 1 charged |
| 33 | rejects an order for a full slot | `updateSlotCapacity(true)` → 403 "capacity"; capacity restored |
| 34 | rejects flash delivery while it is disabled | `isFlashDeliveryEnabled` forced off → 403 "flash"; restored |
| 35 | rejects an invalid quantity | `quantity: 0` → zod rejection |
### `api/order-lifecycle.test.ts` — 5
| # | Test | Request → assert |
| --- | --- | --- |
| 36 | persists special instructions | `updateUserNotes` → `getOrderById.userNotes` |
| 37 | cancels the order with a reason and reflects it in the list | `cancelOrder` → `cancelReason` + cancelled status in `getOrders` |
| 38 | rejects a cancellation without a reason | empty reason → zod rejection |
| 39 | rejects a readable order id ("ORD&lt;id&gt;") | numeric-string contract |
| 40 | paginates orders and rejects an oversized page size | page 1 vs 2 differ; `pageSize: 51` → rejection |
### `api/user-surface.test.ts` — 7
| # | Test | Request → assert |
| --- | --- | --- |
| 41 | returns the product detail for a product id | `product.getProductDetails` |
| 42 | creates a review and returns it from getProductReviews | `createReview` → listed |
| 43 | returns presigned upload URLs | `common.generateUploadUrls` → 1 URL |
| 44 | exposes eligible and owned coupons | `coupon.getEligible` + `getMyCoupons` arrays |
| 45 | rejects redeeming an unknown coupon code | bogus `secretCode` → 400 |
| 46 | returns the signed-in user profile | `user.user.getSelfData.data.user.id` |
| 47 | raises a complaint that staff can resolve | `complaint.raise` → `getAll` → admin `complaint.resolve` → `isResolved` |
### `api/cache-consistency.test.ts` — 5 (cross-file invariants)
| # | Test | Request → assert |
| --- | --- | --- |
| 48 | every availability entry maps to a product in products.json | 0 orphan ids (polls — availability can lead) |
| 49 | availability count matches the number of entries | `count === availability.length` |
| 50 | every product referenced by slots.json exists in products.json | 0 orphans (polls) |
| 51 | essential-consts.json is self-consistent with the version in its path | file's `cacheVersion` == path; other versions numeric |
| 52 | stores.json productCount matches each store detail file | `productCount === detail.products.length` |
### `api/admin-catalog.test.ts` — 9
| # | Test | Request → assert |
| --- | --- | --- |
| 53 | getStoreById returns the created store | `{ id }` → store.id |
| 54 | updateStore renames the store | update → getStoreById reflects the new name |
| 55 | getProductById returns the product with its SKU | product id + sku id present |
| 56 | updateProduct renames the product | update (sku feature `quantity`) → getProducts reflects the new name |
| 57 | getGroups lists product groups | `groups` array |
| 58 | createGroup adds a group that getGroups returns | group name present |
| 59 | coupon.getAll returns a coupons array | `coupons` array |
| 60 | vendorSnippets.getAll returns an array | array |
| 61 | complaint.getAll returns a complaints array | `complaints` array |
### `api/admin-orders.test.ts` — 10
| # | Test | Request → assert |
| --- | --- | --- |
| 62 | getAll returns recent orders | `{ limit: 5 }` → `orders` array |
| 63 | getOrderDetails returns the order | `{ orderId: number }` → id matches |
| 64 | getSlotOrders lists the orders for a slot (string slotId) | `{ slotId: string }` → truthy |
| 65 | updateNotes stores admin notes on the order | `{ orderId, adminNotes }` → details reflect |
| 66 | marks the order packaged | `{ orderId: string, isPackaged: true }` → success |
| 67 | marks the order delivered and the user sees "success" | user's `getOrderById.deliveryStatus === 'success'` |
| 68 | removes the delivery charge | user's `deliveryCharge === 0` |
| 69 | updates the address coordinates | mutation succeeds (coords not exposed to the user read — documented) |
| 70 | cancels a fresh order as staff and the user sees it cancelled | new order → `cancelOrder` → status cancelled |
| 71 | rebalances the orders for a slot | `{ slotIds: [id] }` → truthy |
### `api/coupons.test.ts` — 7 (admin CRUD → user applies it)
| # | Test | Request → assert |
| --- | --- | --- |
| 72 | creates the coupon and getById returns it | `coupon.create` (flat 2, minOrder 1, apply-for-all) → `[0].id`; getById code + discount |
| 73 | updates the coupon | `coupon.update({ id, updates })` → getById reflects |
| 74 | is eligible for the user | `user.coupon.getEligible` contains the coupon |
| 75 | reduces the order amount when the user applies it | `placeOrder({ couponId })` → `getOrderById.couponCode` + `discountAmount === 2` |
| 76 | deleting the coupon invalidates it for the user | `coupon.delete` → no longer in `getEligible` |
| 77 | rejects applying the invalidated coupon to an order | `placeOrder({ couponId })` → invalid/expired error |
| 78 | rejects a coupon with both discount types | `coupon.create({ discountPercent, flatDiscount })` → rejected |
### `api/admin-users.test.ts` — 8 (admin user surface)
| # | Test | Request → assert |
| --- | --- | --- |
| 79 | getEssentials returns the dashboard counters | `user.getEssentials` → numeric `unresolvedComplaints` |
| 80 | getAllUsers returns users | `user.getAllUsers({ limit: 5 })` → `users` array |
| 81 | getUserDetails returns the user | `user.getUserDetails({ userId })` → id matches a fresh user |
| 82 | getStaff lists the staff | `staffUser.getStaff` → includes the logged-in staff id |
| 83 | adds a user incident that getUserIncidents returns | `addUserIncident({ userId, adminComment })` → the comment comes back |
| 84 | getUsersForNotification returns a users array | `{ search: '' }` → array |
| 85 | suspends and unsuspends the user | `updateUserSuspension(true/false)` → `getUserDetails` reflects each |
| 86 | sendNotification tolerates a recipient with no push token | `{ userIds: [fresh] }` → resolves (nothing delivered) |
### `api/admin-banners.test.ts` — 4
| # | Test | Request → assert |
| --- | --- | --- |
| 87 | getBanners returns a banners array | `banner.getBanners` → array |
| 88 | createBanner creates a banner that getBanner returns | `createBanner({ name, imageUrl })` → `getBanner({ id }).name` |
| 89 | updateBanner renames the banner | `updateBanner({ id, name })` → `getBanner` reflects |
| 90 | deleteBanner removes it | `deleteBanner({ id })` → `getBanner` is null |
### `api/admin-tags.test.ts` — 4
| # | Test | Request → assert |
| --- | --- | --- |
| 91 | creates a tag that getProductTags returns | `createProductTag({ tagName, isDashboardTag })` → new id in `getProductTags` |
| 92 | getProductTagById returns the tag | `getProductTagById({ id })` → tagName matches |
| 93 | updateProductTag renames the tag | `updateProductTag({ id, tagName })` → reflected |
| 94 | deleteProductTag removes it | `deleteProductTag({ id })` → gone from `getProductTags` |
### `api/admin-vendor-snippets.test.ts` — 4
| # | Test | Request → assert |
| --- | --- | --- |
| 95 | creates a snippet that getAll returns | `vendorSnippets.create({ snippetCode, slotId, skuIds, isPermanent })` → id in `getAll` |
| 96 | updates the snippet | `update({ id, updates: { validTill } })` → still listed |
| 97 | returns the orders for the snippet code | `getOrdersBySnippet({ snippetCode })` → resolves (needs a slot) |
| 98 | deletes the snippet | `delete({ id })` → gone from `getAll` |
### `api/admin-ops.test.ts` — 5 (config, lifecycle, concurrency)
| # | Test | Request → assert |
| --- | --- | --- |
| 99 | round-trips a constant through updateConstants | `updateConstants(minOrderAmountForCoupon = 123)` → `getConstants` shows 123 → restored |
| 100 | updates and deletes a product group | `createGroup` → `updateGroup({ id, group_name })` visible in `getGroups` → `deleteGroup({ id })` removes it |
| 101 | deleteProduct rejects for a product that still has SKUs | `deleteProduct({ id })` → rejected (FK on the hard delete) |
| 102 | deletes a store | `store.createStore` → `deleteStore({ storeId })` → `getStoreById` no longer resolves |
| 103 | places two concurrent orders for different slots | two `placeOrder` calls in parallel → two distinct, persisted order ids |
### `api/uploads.test.ts` — 4 (image upload round trip)
The presigned PUT is self-signed, so these cases upload real bytes without any R2 credentials and
read them back from the public assets domain (`common.essentialConsts.assetsDomain`, the same
source the app renders from). Objects stay in the dev bucket.
| # | Test | Request → assert |
| --- | --- | --- |
| 104 | stores exactly the bytes that were uploaded | `common.generateUploadUrls({contextString:'product_info'})` → PUT a 1×1 PNG → GET `<assetsDomain>/<key>` → same length, byte-equal, same sha256 |
| 105 | keeps two uploads distinct — each URL serves its own object | presign in two folders (product-images, tags) → different keys → each serves its own PNG, shas differ |
| 106 | gives every mime type in one call a usable URL | one call with `['image/png','image/jpeg']` → 2 distinct keys → both objects hold their own bytes |
| 107 | returns 404 for an object that was never uploaded | guards the read-back: a passing comparison must mean the object really exists |
## Harness reference
| Path | Purpose |
| --- | --- |
| `tests/jest.config.js` | jest project (ts-jest, node env, `runInBand`, clearMocks) |
| `tests/tsconfig.json` | typecheck scope for tests (`bun run test:api:typecheck`) |
| `tests/setup.ts` | loads `tests/.env` before the suites |
| `tests/.env.example` | credentials template (copy to `tests/.env`, git-ignored) |
| `tests/helpers/env.ts` | `API_BASE_URL` + credentials with actionable errors |
| `tests/helpers/api.ts` | tRPC client (`httpBatchLink`) + bearer token, `health()`, `assertServerUp()`, `uniqueSuffix()` |
| `tests/helpers/sessions.ts` | staff/user login with cached tokens |
| `tests/helpers/fixtures.ts` | `createStoreWithSku` (optional price), `createFutureSlot`, `ensureUserAddress`, `registerThrowawayUser` |
| `tests/helpers/consts.ts` | `getConstants` (normalised), `setConst` (used to flip the flash gate, always restored), `asNumber` |
| `tests/helpers/cache.ts` | `essentialConsts`, versioned cache URLs (products/stores/slots/availability/essential-consts), `fetchCacheJson`, `pollUntil` |