freshyo/apps/backend/test-case-info.md
2026-09-26 17:50:33 +05:30

21 KiB
Raw Blame History

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: 21 suites / 103 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

# 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.

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

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