Testing Overview

RitoSwap’s dapp has a substantial automated test suite (over 200 Vitest files and well over a thousand individual tests) covering wallet UX, token gating, API routes, OpenAPI contracts, and state management.

This page explains how the tests are structured, what each layer is responsible for, and how they work together. It is intentionally focused on project-specific patterns, not generic Vitest tutorials.

This overview focuses on Vitest-based tests inside the dapp.
E2E flows using Playwright, Synpress, Postman, and Supertest are mentioned for context but documented separately.

At a glance

Test runner: Vitest (vitest, @vitest/ui) with a happy-dom environment.
UI testing: React Testing Library + @testing-library/jest-dom for wallet UX and components.
Network & infra:
- MSW (msw/node) for mocking external HTTP calls (e.g. Alchemy).
- Prisma client mocked globally so tests never touch a real database.
- Next.js primitives (next/link, next/image, next/navigation) stubbed for DOM-safe rendering.
API routes: Next.js route handlers (app/api/.../route.ts) tested directly via NextRequest + mocked dependencies. The same pattern is used for every gate‑adjacent surface (gate-access, token-status, nonce, form-submission-gate, quota-reset, chat, mcp, and openapi).
Contract tests: A dedicated layer (app/api/__contract__/contract.test.ts) validating example responses against public/openapi.json using an OpenAPI validator.
Coverage: Enforced via vitest.config.ts with thresholds on branches, functions, lines, and statements, plus a curated exclusion list for infra, configs, and non-critical UI.

The goal is to prioritize security‑critical flows (auth, token gating, rate limiting) and user‑visible wallet UX, rather than chase artificial 100% coverage.

Test layers

Layer	What it tests	Examples	Primary tools
Unit / Store	Pure logic, Zustand state transitions, and invariants without network or DOM.	`app/store/tests/chatModeStore.test.ts`	Vitest, direct store access, custom env helpers.
Component	Wallet and chain UI behaviour: ENS name handling, address truncation, modals, button flows.	`components/utilities/wallet/tests/AddressDisplay.test.tsx` `components/utilities/wallet/tests/AccountModal.test.tsx`	React Testing Library, `happy-dom`, wagmi hook mocks, timers.
API route	Next.js route behaviour: status codes, headers, problem+json payloads, rate limits, DB/chain decisions. Beyond the flagship key-gate endpoints, suites also cover nonce issuance, form submissions, quota resets, chat/MCP bridges, and the OpenAPI surface so every authenticated entry point stays pinned.	`app/api/gate-access/tests/gate-access.test.ts` `app/api/token-status/tests/token-status.test.ts` (and similar)	Vitest, `NextRequest`, mocks for viem, Prisma, SIWE, JWT, rate limiters.
API contract	Alignment between documented OpenAPI spec and example responses for each endpoint & status code.	`app/api/contract/contract.test.ts`	OpenAPI validator, `public/openapi.json`, Vitest.

Each layer focuses on a different failure mode:

Unit/Store tests guard business rules and state transitions.
Component tests guard wallet UX and visual behaviour.
API route tests guard HTTP contracts and security-sensitive flows.
API contract tests guard OpenAPI documentation drift.

Infrastructure

Infrastructure & configuration

Key files

Vitest configuration

The vitest.config.ts file wires together:

Vite plugins: React + vite-tsconfig-paths so tests respect path aliases and JSX transforms.
CSS modules: css.modules.generateScopedName ensures deterministic class names in tests.
Test runner settings:
- environment: 'happy-dom' for browser-like DOM without a real browser.
- globals: true so describe, it, expect, vi are available globally.
- setupFiles: ['./test/setup.ts'] to register mocks, MSW, and DOM shims once.
- exclude patterns for node_modules, build output, Cloudflare workers, and e2e directories.
Coverage:
- Provider: v8 with text, json, and html reporters.
- Thresholds: branches, functions, lines, and statements all at 75.
- A curated coverage.exclude list for:
  - Config files and build artefacts.
  - Test utilities, Storybook stories, debug views.
  - Server-only entry points that don’t make sense in a browser env.

Test environment helpers

test/setup.ts
- Mocks Prisma client so no real DB is used.
- Starts an MSW server using alchemyHandlers for portfolio tests.
- Defines onUnhandledRequest so localhost Supertest traffic passes while other unhandled requests cause errors.
- Stubs next/navigation, next/link, and next/image for React Testing Library.
- Installs matchMedia and IntersectionObserver shims so responsive logic and observers work in tests.
test/helpers/env.ts
- Provides seedBase, seedServerTest, and other helpers to set up consistent process.env for tests.
- Mocks @config/server.env so env-dependent code reads from a controlled snapshot.
- Includes helpers like withEnv and resetModulesAndSeed for tests that need fresh module evaluation.
test/utils/wagmi.tsx
- Provides createTestConfig and TestWrapper components with WagmiProvider + QueryClientProvider for tests that need actual wagmi context.
- Re-exports React Testing Library utilities for convenience.

Configuration & infrastructure validation

Vitest also enforces the repo’s configuration contracts so a misconfigured run fails fast:

Environment schemas: Suites in app/config/__tests__ (e.g. server.env.test.ts, public.env.test.ts, jwt.server.test.ts, chain.test.ts, ai.server.test.ts, ai.public.test.ts, pinecone.config.test.ts) import the real modules under fresh env snapshots to guarantee required secrets, feature flags, and connector settings are present.
Client utilities: Tests like app/utils/__tests__/assetFetcher.test.ts and mobile.test.ts mock viem/fetch/globals to keep wallet-dependent helpers deterministic.
Cloudflare workers: cloudflare/src/__tests__ covers the durable object state store and email worker so rate limits, nonce storage, and breach notifications behave the same in Node and on the edge.

Adding tests

Adding tests in this repo

This section focuses on when to use each layer and the expected patterns, rather than syntax.

Choosing the right layer

You changed a Zustand store or complex state logic
- Add or update tests under app/store/tests.
- Use the existing pattern from chatModeStore.test.ts:
  - Assert initial state.
  - Assert state transitions for each public method.
  - Verify immutability (new state objects where appropriate).
You added or modified a wallet or chain UI component
- Add tests under components/utilities/wallet/tests (or an equivalent tests folder).
- Mock wagmi hooks (e.g. useAccount, useEnsName, useEnsAvatar, useChainId) directly, or wrap with TestWrapper if you need real providers.
- Use fake timers for time-based transitions (e.g. ENS reveal).
- Assert on rendered text, attributes, and DOM structure rather than implementation details.
You changed a Next.js API route
- Add or update tests under app/api/<route>/tests.
- Import the handler (GET, POST, etc.) and construct NextRequest instances.
- Mock external dependencies: Prisma, viem, SIWE helpers, JWT helpers, rate limiters, gated content.
- Cover at least:
  - Happy path (200s).
  - Validation failures (400s).
  - Auth failures (401/403).
  - Not‑found or domain‑specific errors (404).
  - Rate limiting (429).
  - At least one unexpected error scenario.
You changed the OpenAPI spec or external contract
- Update public/openapi.json.
- Update CONTRACT_TESTS in app/api/contract/contract.test.ts:
  - Add/modify the endpoint entry.
  - Ensure test cases cover each documented status code.
- Use the meta tests at the bottom of contract.test.ts to confirm all paths and status codes are represented.

How to run tests

Run the full Vitest suite:
```
pnpm vitest
```

Run a single file:


pnpm vitest app/api/gate-access/__tests__/gate-access.test.ts

Use the Vitest UI:
```
pnpm vitest --ui
```

These commands assume you are in the dapp directory and that dependencies have been installed.

Where to go next

Use the pages below for deeper, layer-specific guidance:

Unit & Component Testing API Route Testing API Contract & OpenAPI Testing