196 lines
7.6 KiB
Markdown
196 lines
7.6 KiB
Markdown
# admin-ui test suite
|
|
|
|
Runnable implementation of the cases catalogued in
|
|
[`../JEST-TEST-CASES.md`](../JEST-TEST-CASES.md).
|
|
|
|
```bash
|
|
cd apps/admin-ui
|
|
bun run test -- tests/pages/dashboard.test.tsx # a single file
|
|
bun run test # everything
|
|
bun run test:typecheck # tsc over the app + tests
|
|
```
|
|
|
|
Runner: `jest-expo` + `@testing-library/react-native`. Application code (pages,
|
|
hooks, components, auth context) runs for real; only the tRPC client and native
|
|
modules are mocked. React Query is real, but the tRPC mock replaces the hooks, so
|
|
queries resolve synchronously from the procedure registry.
|
|
|
|
---
|
|
|
|
## Layout
|
|
|
|
```
|
|
tests/
|
|
jest.config.js preset, aliases, native-module mocks
|
|
setup.ts globals (fetch, console, act env)
|
|
fixtures/index.ts backend-shaped fixtures
|
|
helpers/
|
|
test-utils.tsx render helpers + auth seeding
|
|
reset.ts resetAllMocks() for beforeEach
|
|
mocks/
|
|
trpc-client.ts procedure-registry mock (queries + mutations + utils)
|
|
trpc-defaults.ts default payload per procedure
|
|
staff-auth-context.tsx deterministic StaffAuthContext replacement
|
|
expo-router-mock.tsx recorded router + layout primitives
|
|
secure-store-mock.ts in-memory SecureStore
|
|
expo-notifications-mock.ts
|
|
native/* native-module shims
|
|
```
|
|
|
|
## Standard test shape
|
|
|
|
```tsx
|
|
import React from 'react'
|
|
import { fireEvent } from '@testing-library/react-native'
|
|
import Products from '@/app/(drawer)/dashboard/products/index'
|
|
import { renderWithProviders, flush } from '../helpers/test-utils'
|
|
import { resetAllMocks } from '../helpers/reset'
|
|
import { setProcedure, lastMutationInput } from '../mocks/trpc-client'
|
|
import { router } from '../mocks/expo-router-mock'
|
|
|
|
describe('Products', () => {
|
|
beforeEach(() => resetAllMocks())
|
|
|
|
it('APLIST-01: shows the loading copy', () => {
|
|
setProcedure('admin.product.getProducts', { mode: 'pending' })
|
|
const view = renderWithProviders(<Products />, { auth: 'in' })
|
|
expect(view.getByText('Loading products...')).toBeTruthy()
|
|
})
|
|
})
|
|
```
|
|
|
|
Rules:
|
|
|
|
1. One `it()` per catalogue row, prefixed with the row id (`APLIST-01: ...`).
|
|
2. `resetAllMocks()` in `beforeEach`.
|
|
3. Assert the procedure + exact input for every mutation
|
|
(`lastMutationInput('admin.product.createProduct')`).
|
|
4. Prefer `getByTestId` / `queryByTestId` over text matching, but text matching
|
|
is fine for the catalogue's visible-copy assertions. If a component is
|
|
missing a testID, **add only the `testID` attribute** (never change
|
|
behaviour) and report it.
|
|
5. `act(...)` warnings are noisy but non-fatal. Use `await flush()` /
|
|
`waitFor` after mutations and async effects.
|
|
|
|
## Render helpers
|
|
|
|
| Helper | Purpose |
|
|
| --- | --- |
|
|
| `renderWithProviders(ui, opts)` | QueryClient + `trpc.Provider` + `RefreshProvider` + real `StaffAuthProvider` |
|
|
| `renderAndFlush(ui, opts)` | same, then `await flush()` |
|
|
| `flush(times = 1)` | drain microtasks/macrotasks inside `act` |
|
|
| `createTestQueryClient()` | fresh client (retry off, infinite gc) |
|
|
|
|
`opts`: `auth` = `'in' | 'out' | false` (default `'out'`; `false` skips both the
|
|
auth seeding and the auth provider), `queryClient`, `withRefresh`, `withAuth`.
|
|
|
|
`auth: 'in'` writes `jwt_token` + `staff_session` to the storage mock so the real
|
|
`StaffAuthProvider` boots signed in after a flush.
|
|
|
|
## Seeding / resetting
|
|
|
|
```ts
|
|
import { __set, __delete, __snapshot } from '../mocks/secure-store-mock'
|
|
__set('jwt_token', TEST_JWT)
|
|
__set('staff_session', JSON.stringify(STAFF))
|
|
```
|
|
|
|
## Procedure mock
|
|
|
|
```ts
|
|
setProcedure('admin.product.getProducts', { data: PRODUCTS_RESPONSE })
|
|
setProcedure('admin.product.getProducts', { mode: 'error', error: new Error('boom') })
|
|
setProcedure('admin.product.getProducts', { mode: 'pending' })
|
|
setProcedure('admin.product.createProduct', { impl: (input) => ({ product: input }) })
|
|
|
|
lastMutationInput('admin.product.createProduct') // exact input of the last call
|
|
lastProcedureInput('admin.coupon.getAll') // query or mutation
|
|
procedureMutationCalls('admin.coupon.create') // all inputs
|
|
procedureQueryCalls('admin.coupon.getAll')
|
|
trpc.useUtils() // invalidations recorded as jest.fn()s
|
|
```
|
|
|
|
Defaults for every procedure live in `mocks/trpc-defaults.ts`.
|
|
|
|
## Deterministic auth
|
|
|
|
For exact signed-in / loading states without the provider's async bootstrap:
|
|
|
|
```tsx
|
|
jest.mock('@/components/context/staff-auth-context', () => require('../../mocks/staff-auth-context'))
|
|
import { __setStaffState } from '../../mocks/staff-auth-context'
|
|
|
|
__setStaffState({ isLoggedIn: true, isLoading: false, staff: STAFF })
|
|
```
|
|
|
|
`renderWithProviders(..., { auth: false })` skips both seeding and the provider;
|
|
the mocked `useStaffAuth` still supplies the state above.
|
|
|
|
## Navigation
|
|
|
|
```ts
|
|
import { router, __setParams } from '../mocks/expo-router-mock'
|
|
__setParams({ id: '21' })
|
|
expect(router.push).toHaveBeenCalledWith('/(drawer)/dashboard/products/edit')
|
|
```
|
|
|
|
`boom`/`expo-router` layouts render their children, so route files can be mounted
|
|
directly.
|
|
|
|
## Fixtures
|
|
|
|
`STAFF`, `STAFF_NO_REGION`, `REGION`, `BOUNDS`, `BOUND_SETTINGS`,
|
|
`REGION_CONSTANTS`, `STORE_1`, `STORE_GLOBAL`, `STORES`,
|
|
`P_CHICKEN`, `P_CUCUMBER`, `P_GLOBAL`, `P_OUT`, `P_NO_IMAGE`, `P_PARTIAL`,
|
|
`PRODUCTS`, `PRODUCTS_RESPONSE`, `SKUS_SUMMARY`, `SLOT_1`, `SLOT_FULL`,
|
|
`SLOT_INACTIVE`, `SLOTS`, `SLOT_DETAIL`, `ORDER_1`, `ORDER_FLASH`,
|
|
`ORDER_DELIVERED`, `ORDER_CANCELLED`, `ORDER_NEGATIVE`, `ORDERS`,
|
|
`ORDERS_RESPONSE`, `ORDER_DETAILS`, `SLOT_ORDERS`, `USER_1`, `USER_SUSPENDED`,
|
|
`USER_NO_NAME`, `USERS`, `USER_DETAILS`, `USER_INCIDENTS`,
|
|
`NOTIFICATION_USERS`, `COUPON_1`, `COUPON_GLOBAL`, `COUPON_EXPIRED`,
|
|
`COUPON_INVALIDATED`, `COUPON_RESERVED`, `COUPONS`, `TAG_1`, `TAG_2`, `TAGS`,
|
|
`GROUP_1`, `GROUPS`, `BANNER_1`, `BANNERS`, `SNIPPET_1`, `SNIPPETS`,
|
|
`SNIPPET_ORDERS`, `COMPLAINT_1`, `COMPLAINT_2`, `COMPLAINTS`, `TEST_JWT`.
|
|
|
|
---
|
|
|
|
## Real tRPC client, mocked network (current harness)
|
|
|
|
The app's **real** `@/src/trpc-client` and **real React Query** run in tests. Only
|
|
the network response is faked:
|
|
|
|
```
|
|
real hook → real httpBatchLink → global fetch (tRPC network mock) → procedure registry
|
|
```
|
|
|
|
- `tests/mocks/trpc-client.ts` no longer replaces the client module. It exports the
|
|
procedure registry (`setProcedure`, defaults, call recording) and
|
|
`installTrpcNetworkMock()`, which `tests/setup.ts` installs on `global.fetch`.
|
|
- The mock parses the client's batch request
|
|
(`GET /api/trpc/a.b,c.d?batch=1&input=…` / `POST … body {"0":…}`) and answers
|
|
with the tRPC batch envelope. `mode: 'pending'` keeps the hook loading;
|
|
`mode: 'error'` returns a tRPC error entry.
|
|
- `renderWithProviders` wraps with `QueryClientProvider` **and** the real
|
|
`trpc.Provider`.
|
|
- `lastProcedureInput` / `procedureMutationCalls` are filled from the real
|
|
requests. `useUtils().x.invalidate()` is real; the test QueryClient records the
|
|
query keys so `procedureInvalidations(path)` still works.
|
|
|
|
### Assertions are asynchronous
|
|
|
|
Queries resolve after a tick and mutations settle asynchronously. Prefer:
|
|
|
|
```tsx
|
|
const view = renderWithProviders(<Page />, { auth: 'in' })
|
|
expect(await view.findByText('Chicken Breast')).toBeTruthy()
|
|
|
|
fireEvent.press(view.getByTestId('save'))
|
|
await waitFor(() => expect(lastProcedureInput('user.order.updateUserNotes')).toEqual({ … }))
|
|
```
|
|
|
|
`renderAndFlush(ui)` renders and drains the first round of queries when a test
|
|
does several synchronous lookups. Check `isLoading` / `Processing…` **before**
|
|
awaiting, and never assume a mutation has completed on the next line.
|
|
|
|
`forceExit` is enabled in `jest.config.js` because a `mode: 'pending'` fixture
|
|
leaves the client's request timer open.
|