freshyo/docs/test-cases/location-region-switching.md
2026-10-18 10:59:18 +05:30

6.1 KiB

Location resolution and region switching

Scope: native location store/useRegion, web region gate/store, manual selector, GPS attachment. Platform difference to respect: native (user-ui) keeps the browsing region in memory only — never persisted, re-derived each launch from the device location and/or the default address; web (web-ui) still persists it (freshyo-region in localStorage) and its gate resolves no location at all (it validates the saved id against listRegions, else shows the region selector).

ID Priority Action / input Expected result
LOC-01 P0 Fresh signed-out/signed-in launch inside A. One-shot resolution selects A; bound/catalog loads without mandatory login.
LOC-02 P1 Permission denied/permanently denied/GPS unavailable. A usable manual chooser (and, when a default address exists, that region); no silently "remembered" region, since none is persisted.
LOC-03 P1 Coordinates outside all bounds; empty regions list. Useful unavailable-service state, not endless spinner.
LOC-04 P0 Delayed GPS A response after manual B selection. Late automatic response cannot undo manual choice.
LOC-05 P1 Location changes A→B while app remains open. No unexpected continuous cart-clearing auto-switch.
LOC-06 P0 Both A carts populated; request B switch, cancel then confirm. Cancel preserves all; confirm clears regional carts/slots/coupons/address context and loads B.
LOC-07 P0 Rapid A→B→A with delayed catalog responses. Region-generation guard rejects stale B/A responses and mixed prices.
LOC-08 P1 Relaunch after the region's service metadata changed/removed. Region re-derived (nothing persisted); changed metadata revalidated; no stale cached context.
LOC-09 P1 Cold launch physically in B with A carts. One-shot resolution follows the anchored startup decision; region adoption does not clear the local cart; no silent mixed-region order. Known open: startup adoption can still wipe the cart (review #10); record a failure if observed.
LOC-10 P1 U1 A/B addresses; default B while browsing A. No automatic foreign default override; A browsing choice retained.
LOC-11 P0 Explicit foreign-address switch confirm/cancel. Same safe region-switch behavior and cleared regional state.
LOC-12 P1 Saved address without a stored bound. Bound is derived from the address coordinates; never a foreign region's bound; warnings accurate.
LOC-13 P1 Shared location-store consumers mount/unmount repeatedly. No duplicate listeners/resolutions or memory leaks affecting selection.
LOC-14 P2 Browser refresh/SSR/private-mode. No hydration crash; usable manual region selector.
LOC-15 P1 Force-quit during confirmed switch/state clearing. Relaunch coherent region and carts; no half-reset checkout.
LOC-16 P1 Resolve request offline/timeout, then restore network. Bounded retry; manual selection remains usable.
LOC-17 P2 Emulator/mock-location environment vs physical device. Supported location path without production-only/emulator-only assumptions.
LOC-18 P0 Change region while submit request is pending. No duplicate order or new-region UI falsely representing old-region order.
LOC-19 P0 Cold launch (a) with a default address in the resolved region, (b) with the location resolving to another serviceable region, (c) with location off/out-of-area and a default address, (d) with no default address. (a) use the default silently; (b) ask the user to choose; (c) use the default; (d) use the resolved region, else ask.
LOC-20 P1 Set a region → force-quit → relaunch with location unavailable. Native: nothing is persisted; the region is re-derived from the default address/location and a chooser appears when neither resolves. Web: the saved region is validated against listRegions; an invalid/deleted saved id falls back to the chooser.
LOC-21 P0 Cold start adopts the first region while a local cart has items. Adoption uses the non-clearing path (local cart preserved). Only an explicit switch away from an already-set region confirms and clears regional state. Known open: review finding #10 reports this can still clear the cart; record a failure rather than assuming the requirement is met.
LOC-22 P1 Launch with location access denied, then with device location services off, then with permission granted but no fix. Distinct messages ("access not granted" vs "services off" vs "couldn't get a fix") plus an "Open location settings" action, then an address-chooser fallback.
LOC-23 P1 Signed out, no region resolves (location off/denied/out-of-area). The chooser shows "Login to get existing addresses." with a Login action. Tapping it shows the login screen in place (the gate renders outside the navigator, so no route push), and after a successful login the chooser returns with the account's saved addresses selectable; backing out leaves region/cart untouched.
LOC-24 P2 A region-gate screen (no region yet) offers any "go to another route" action. The action works without a mounted navigator (inline screen/state change), because LocationTestWrapper / FirstUserWrapper / HealthTestWrapper replace the root <Stack />; a router.push/router.back there must not silently no-op.
LOC-25 P1 The device fix succeeds but the point is outside every bound, with and without a saved default address. With a default address: that region is used. Without one: an explicit "outside our delivery area" state is shown on the chooser (not a bare chooser with no explanation), and a usable manual path remains.

Related: the cart's first-address gate for a signed-in user with zero addresses (even an empty cart) is CART-23; the signed-out address draft that syncs after login is ADDR-25. Native manual switching is the address switcher sheet, not a region list (the region list selector is web-only).

Open policy: exact cold-start/manual-choice precedence after a populated local cart. Do not label ambiguity PASS.