Identify the behavior being protected and the narrowest workspace test suite.
Reuse nearby test setup patterns before adding helpers or dependencies.
For apps/client, place tests in the owning __tests__/ folder described by the client architecture and use existing Testing Library/React Query test helpers.
For apps/client API operations and hooks, test both successful mocked responses and mocked API error responses.
For API service tests, mock only the Prisma methods and collaborators the test exercises.
For evaluator and SDK tests, assert public behavior through package exports.
For client coverage changes, run the coverage script and keep configured thresholds at 90% or higher unless the user explicitly narrows scope.

Expected Output

Regression tests cover bug fixes.
Client tests follow the current __tests__/ folder layout instead of loose sibling *.test.ts(x) files.
Client request functions and React Query hooks cover success, error, enabled state, and cache invalidation where applicable.
Domain tests cover role gates, tenant boundaries, revision bumps, SDK key secrecy, config serialization, fallback behavior, or evaluation order when those paths change.
No .only remains.

Verification

Run the targeted test file first when one exists.
Run the affected workspace test command after the targeted test passes.
Run npm --workspace @capture-flag/client run test:coverage after changing client coverage configuration or broad client tests.
State blockers clearly if tests cannot run because of missing services or dependencies.

Referenced Context

Reference: `ai/rules/testing-rules.md`

Testing Rules

Testing rules for this Vitest-based monorepo.

Always

Use Vitest APIs such as describe, it, expect, vi.fn, and vi.spyOn.
Add regression tests next to changed behavior when fixing bugs.
Test observable behavior and domain invariants instead of implementation details.
Run a targeted test first when a specific test file exists.
Run the affected workspace test command after targeted tests pass.
Keep client tests in __tests__/ folders next to the source area they cover, matching the Storybook stories/ grouping convention.
Keep apps/client/src/api request and hook tests in src/api/__tests__, using the existing fetch, React Query, and render helpers from src/test.
Keep apps/client/src/core tests under src/core/<category>/__tests__/<name>.test.ts.
Keep shared client component tests under src/components/__tests__ and shared member component tests under src/components/members/__tests__.
Keep page tests under src/pages/<PageName>/__tests__ or src/pages/<PageName>/<section>/__tests__ for colocated page internals.
Use src/__tests__ only for source files owned directly by apps/client/src, such as permissions.ts.
For apps/client code that calls the API, cover both successful responses and API error responses with mocked fetch/response behavior.
Keep apps/client coverage at 90% or higher for configured client coverage targets; aim for 100% on pure helpers and request functions.
For API tests, mock Prisma and collaborators with plain objects containing only exercised vi.fn() methods.
For SDK and evaluator packages, prefer pure unit tests around evaluation order, fallback behavior, type handling, and request/cache boundaries.

Never

Do not use Jest-only APIs or jest.mock patterns.
Do not leave .only in tests.
Do not introduce coverage targets unless a coverage script exists or the task explicitly asks for coverage.
Do not place apps/client tests beside source files as loose *.test.ts(x) files when a nearby __tests__/ folder is available.
Do not add duplicate client test helpers when src/test/render.tsx, src/test/api.ts, or src/test/pageApi.ts already cover the setup.
Do not reach for a real database in API unit tests by default.

Verification

API tests: npm --workspace @capture-flag/api run test.
Client tests: npm --workspace @capture-flag/client run test.
Client coverage: npm --workspace @capture-flag/client run test:coverage.
Shared tests: npm --workspace @capture-flag/shared run test.
Evaluator tests: npm --workspace @capture-flag/evaluator run test.
SDK tests: npm --workspace @capture-flag/sdk-js run test.
All workspace tests: npm run test.

Reference: `ai/architecture/monorepo.md`

Monorepo Architecture

Capture Flag is a TypeScript npm workspaces monorepo.

Workspaces

apps/api: NestJS API, Prisma access, authentication, tenant services, public SDK config endpoint.
apps/client: Vite React app for platform UI.
packages/shared: shared package boundary for reusable cross-workspace code.
packages/evaluator: pure local evaluation engine.
packages/sdk-js: JavaScript SDK that fetches public config and evaluates locally.
packages/react: React provider and hook around the JavaScript SDK.

Root Commands

Build all workspaces: npm run build.
Test all workspaces: npm run test.
Lint repository: npm run lint.
Sync AI routes: npm run ai:sync.
Check AI routes: npm run ai:check.

Boundaries

API-only code stays in apps/api.
Client-only code stays in apps/client.
SDK and evaluator code must not import server-only packages.
Shared code belongs in packages/* only when there is a real cross-workspace consumer.
Product and contract docs in docs/* are part of the source of truth for behavior.

Reference: `ai/architecture/client-app.md`

Client App Architecture

apps/client is a Vite React application for the Capture Flag platform UI.

Entry And Routing

src/main.tsx owns top-level providers.
src/router.tsx owns React Router route definitions.
Route modules are lazy-loaded through the local lazyRoute() helper and should expose named exports.
src/layouts contains route layout wrappers that render shared shells, navigation, headers, and nested <Outlet /> regions.
src/pages contains route-level screens. Multi-file route screens use folder modules with index.ts named exports; simple one-file screens may stay as direct page files.
src/components contains shared UI used by multiple pages or sections.
src/core contains context-independent client utilities and reusable hooks organized by category.
src/api contains client request functions, React Query hooks, operation barrels, domain barrels, and domain query keys.
src/routing contains route path and route context helpers shared by pages and layouts.
src/stories contains shared Storybook fixtures and API mocks, not component stories.
src/test contains shared Vitest and Testing Library helpers.
PlatformLayout owns the authenticated shell, navigation frame, sidebar/header state, logout flow, and nested route outlet.
Selected organization, project, config, and environment state is derived by route helpers such as useRouteContext, not stored in a mutable layout context.

Route Map

/: redirects to /organizations.
/login: GitHub login screen.
/account: authenticated user account details and display name editing.
/organizations and /organizations/:organizationId: organization selection and organization members.
/organizations/:organizationId/projects and /organizations/:organizationId/projects/:projectId: project selection and project members.
/organizations/:organizationId/projects/:projectId/environments: environments for the selected project.
/organizations/:organizationId/projects/:projectId/configs and /organizations/:organizationId/projects/:projectId/configs/:configId: configs and public Config JSON preview.
/organizations/:organizationId/projects/:projectId/configs/:configId/flags: feature flags and remote config values.
/organizations/:organizationId/projects/:projectId/configs/:configId/segments: reusable targeting segments.
/organizations/:organizationId/projects/:projectId/sdk-keys: SDK key lifecycle for project configs/environments, with selected config/environment in ?configId= and ?environmentId= when needed.
/organizations/:organizationId/audit-logs: organization/project audit log timeline, with selected project in ?projectId= when needed.
*: redirects to /.

Data Flow

React Query owns server state such as authenticated user, organizations, projects, configs, environments, SDK keys, members, and feature flags.
API operations live under src/api/<domain>/<operation>.
Request functions perform HTTP calls and contain no React imports.
Query and mutation hooks are the UI-facing API.
Query hooks may use useQuery or useInfiniteQuery according to the API shape.
Mutation hooks invalidate affected query keys.
Mutations that affect derived server state may invalidate query keys from multiple API domains inside the mutation hook.
API request and hook tests mock successful responses and API errors instead of reaching a real backend.
Route params, search params, and server state are combined by useRouteContext for selected resources and redirect-safe navigation paths.
Permission gates in the client are UX only; API guards and services remain authoritative.

UI Composition

Route components compose page sections and own screen-level flow.
Repeated panels, forms, controls, lists, and empty states move into named components.
React component files should stay at or below 400 lines by splitting real responsibilities into focused files.
Short, fixed navigation or action sets should be rendered explicitly instead of through artificial arrays.
Page-specific components stay colocated under the page folder until reused elsewhere.
Layout-specific components stay colocated under src/layouts/<LayoutName> until reused by another layout or page.
Shared primitives live under src/components and are imported directly through aliases such as @components/Button.
Member management uses shared components/members primitives with page-specific role options.
Feature flag and segment page internals stay colocated under their page folders until reused.
Storybook stories live in a stories/ child folder beside the source area they cover.
Route-level and cross-page grouping stories live in src/pages/stories.
Shared Storybook data and fetch mocks live in src/stories and are reused by stories and page tests.

Shared Core Utilities

Context-independent helpers and reusable client hooks live under src/core/<category>/<name>.ts.
Current core categories include date, json, strings, validation, and hooks.
Each core file exports one function or hook; import it from the direct file path such as src/core/date/toDate.
Do not add index.ts barrels under src/core; multiple helpers require multiple explicit imports.
Core tests live under src/core/<category>/__tests__/<name>.test.ts next to the category they cover.
Client tests live in __tests__/ child folders beside the source area they cover, mirroring Storybook stories/ folders.
Shared test setup and helpers live under src/test and provide Testing Library render helpers, React Query providers, and fetch response mocks.
Coverage is run with npm --workspace @capture-flag/client run test:coverage and should stay at 90% or higher for configured client targets.
Page, domain, API, or route-specific helpers stay colocated with their owning feature until they become context-independent reuse.

Client Test And Story Layout

API request and hook tests live in src/api/__tests__ and cover operation behavior through mocked fetch responses.
Shared component tests live in src/components/__tests__; member component tests live in src/components/members/__tests__.
Page tests live in src/pages/<PageName>/__tests__ when they cover one page folder.
Page subsection tests live in src/pages/<PageName>/<section>/__tests__ when they cover colocated page internals such as feature flags or segments.
Root-level client tests live in src/__tests__ only for source files owned directly by src, such as permissions.ts.
Shared component stories live in src/components/stories; member component stories live in src/components/members/stories.
Layout stories live in src/layouts/<LayoutName>/stories.
Page and page subsection stories live in the owning page folder's stories/ child folder.
Cross-page route or panel grouping stories live in src/pages/stories and use route parameters plus shared mock data to render realistic page states.
Do not place component stories in src/stories; that folder is reserved for shared Storybook data, routes, and API mocks.

Form Flow

React Hook Form owns field state and submission.
Zod schemas parse and validate form values.
API mutation hooks submit normalized payloads and refresh server state.

Reference: `ai/examples/good-evaluator-test.md`

Good Evaluator Test

Source: packages/evaluator/test/index.spec.ts (sha256: 40f396c39736d1e39ecc8575adc4f3566a656b3665b3513c10b64d3d49018e81)

Why this is canonical:

Builds small config fixtures around the public evaluator contract.
Tests observable evaluation behavior instead of internals.
Covers fallback, rule order, segment references, prerequisite flags, advanced operators, rollout determinism, JSON values, and type mismatch behavior.

Canonical evaluator test pattern from packages/evaluator/test/index.spec.ts.

function createFlag(overrides: Partial<CaptureFlagConfigFlag> = {}): CaptureFlagConfigFlag {
  return {
    defaultValue: false,
    percentageAttribute: "identifier",
    percentageOptions: [],
    rules: [],
    type: "boolean",
    ...overrides,
  };
}

function createConfig(flag: CaptureFlagConfigFlag = createFlag()): CaptureFlagConfig {
  return {
    configKey: "default",
    environment: "production",
    flags: {
      newCheckout: flag,
    },
    generatedAt: "2026-05-12T00:00:00.000Z",
    projectKey: "ecommerce",
    revision: 1,
    schemaVersion: 1,
  };
}

Tests build small config fixtures and assert behavior through the public evaluate function.

Behavior Focus

Missing or invalid config returns fallback.
Rules evaluate top-down.
Segment references evaluate locally and invalid segment references do not match.
Prerequisite flags evaluate locally and cycles do not match.
Advanced operators cover arrays, dates, and SemVer precedence.
All rule conditions must match.
Percentage rollout is deterministic, including basis-point decimal percentages.
JSON object and array values are evaluated through default, rule, and rollout behavior.
Type mismatches return fallback.

Reference: `ai/examples/good-public-config-service.md`

Good Public Config Service

Source: apps/api/src/public-sdk/public-sdk.service.ts (sha256: 85e49bab9d48419a9c4333b902d45cd724ae62a4b946eea88831bc3a4d42007c)

Why this is canonical:

Authenticates public config access through hashed SDK keys.
Reads SDK key, state, and flag values in one transactional path.
Emits config-scoped segments for local SDK evaluation.
Preserves ETag and not-modified semantics for SDK cache behavior.
Uses safe default cache headers for SDK-key URLs while allowing explicit deployment override.
Records SDK key usage without making telemetry writes break valid config responses.

Canonical public config pattern from apps/api/src/public-sdk/public-sdk.service.ts.

const transactionResult = await this.prisma.$transaction(
  async (tx) => {
    const sdkKey = await this.sdkKeyAuth.findActiveSdkKey(tx, rawSdkKey);
    const state = await tx.configEnvironmentState.findUnique({
      where: {
        configId_environmentId: {
          configId: sdkKey.configId,
          environmentId: sdkKey.environmentId,
        },
      },
    });
  },
  { isolationLevel: Prisma.TransactionIsolationLevel.RepeatableRead },
);

The public endpoint authenticates by hashed SDK key and reads config state in the same transaction as flag values.

ETag Pattern

if (this.cache.matchesIfNoneMatch(ifNoneMatch, state.etag)) {
  return {
    result: {
      etag: state.etag,
      cacheControl,
      notModified: true,
    },
    sdkKeyId: sdkKey.id,
  };
}

Not-modified responses still count as valid SDK config access for lastUsedAt.

Cache-Control And Usage Pattern

const cacheControl = this.cache.cacheControlHeader();

await this.sdkKeyUsage.recordUse(transactionResult.sdkKeyId);

The public endpoint defaults away from shared caching because the raw SDK key is in the URL path, and usage telemetry is best-effort after a valid config read.

vitest-testing-guidelines

المزيد من هذا المستودع

المزيد من هذا المستودع

Compiled AI Skill: vitest-testing-guidelines

Canonical Skill: ai/skills/vitest-testing-guidelines.md