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

23 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: 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

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

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