Testing

PurposeCopy Anchor Link

permdock/testing is a subpath of permdock that only test files import. Vitest is its optional peer, it never takes a Postgres client as a dependency (runners receive a query function), and no application entry imports it, so it adds nothing to an app bundle. It ships describePolicy, snapshotFixture, rlsParity, ormParity, testClientParity, testClientStore, testHttpAdapter, testAgentAdapter, the core-backed conformance runners (testSubjectResolver, testMembershipSource, testRelationSource, testRoleSource, testApprovalStore, testDecisionSink, testSnapshotSource, testPolicySource, testWhereCompiler, testTokenVerifier, testTokenSigner, testLimitStore, testDirectoryStore, testReplayStore, testRevocationFeed), the AuthZEN interop runner testAuthZen with the interop Todo domain, and Vitest type fixtures, plus one signed-output fixture per typ (permdock-snapshot+jwt, permdock-approval+jwt, permdock-decisions+jwt, permdock-policy+jwt). mockEndpoint and mswHandlers are planned. There is no instant() wrapper: call @next/playwright instant() directly (Next.js Cache Components guide).

APICopy Anchor Link

import {
  describePolicy,
  snapshotFixture,
  rlsParity,
  expectTypeOf,
} from "permdock/testing";
import { policy } from "../src/policy";
import { permissions } from "../src/permissions";

describePolicy(policy, {
  subjects: {
    anonymous: null,
    member: { id: "u1", orgId: "o1", roles: ["member"] },
    admin: { id: "u2", orgId: "o1", roles: ["admin"] },
  },
  fixtures: {
    ownPost: { id: "p1", authorId: "u1", orgId: "o1", published: false },
    otherPost: { id: "p2", authorId: "u9", orgId: "o1", published: true },
  },
  matrix: {
    [permissions.post.create.key]: {
      anonymous: "denied",
      member: "granted",
      admin: "granted",
    },
    [permissions.post.update.key]: {
      ownPost: { anonymous: "denied", member: "granted", admin: "granted" },
      otherPost: { anonymous: "denied", member: "denied", admin: "granted" },
    },
    [permissions.post.delete.key]: {
      ownPost: { member: "approval-required", admin: "granted" },
    },
  },
});

Shared SaaS domainCopy Anchor Link

The scenario testing guide explains how PermDock runs these against every surface and how to add a fixture app.

permdock/testing/saas is a second entry that imports neither Vitest nor Node built-ins, so a fixture app can load it at runtime. It is one realistic multi-tenant SaaS: the oracle every framework fixture, ORM parity run and client suite in this repository shares.

permdock/testing/saas/permissions carries only the definitions (saasPermissions, saasRoles, saasPlans, the row schemas and types) for client bundles that cannot tree-shake the policy, seed and test key away, such as Metro in the Expo fixture.

import { createPermDock } from "permdock";
import {
  saasPolicy,
  saasScenarioOptions,
  saasScenarios,
  saasUser,
} from "permdock/testing/saas";

for (const scenario of saasScenarios) {
  const permdock = await createPermDock(
    saasPolicy,
    saasUser(scenario),
    saasScenarioOptions(scenario),
  );
  expect(permdock.decide(scenario.permission, scenario.row).outcome).toBe(
    scenario.expected.outcome,
  );
}

describePolicy subjects may carry memberships and tenant (tenancy), and the config accepts tenants so one matrix runs with each active tenant; the repository's own matrix carries the tenancy cases from tenancy (tenant allow versus global deny, team role outside the active tenant, resource role through parent hops, expired membership, custom role with an unknown include, collection action in a foreign tenant). snapshotFixture accepts { tenant, tenants: 'all', simulated: true } and emits a v: 1 snapshot.

Matrix rows are keyed by permission.key computed from the reference ([permissions.post.update.key]), never by a string literal, because an object literal cannot be keyed by the reference itself. The matrix is a test, not a report; the permission inventory comes from permdock catalog.

Request lifecycleCopy Anchor Link

Tests do not run a request, but the helpers follow the same order as adapters so failures point at the right layer:

1. Subject: describePolicy builds each PermDock with createPermDock(policy, subject), including null for anonymous and optional actor / delegation for agent cases (a matrix may declare agents whose cells must never exceed their principal's).
2. Instance: one immutable instance per subject; fixtures are validated against the resource schema before use so a malformed fixture fails as PermDockValidationError, not as a wrong outcome.
3. Check: decide for every cell; filter for collection cells when fixtures are arrays; simulate for agent plans.
4. Denial surface: cells asserting denials compare role and reason text, keeping error messages stable for models and UI.

What it validatesCopy Anchor Link

• Matrix exhaustiveness against listPermissions(permissions).
• Fixtures against resource schemas (always, regardless of the policy's validate mode).
• Agent cells: an actor with delegation never receives granted where its principal is denied.
• RLS parity: for each read cell, filter in-process equals the rows visible under the database role; for create/update/delete, granted equals a successful statement and denied equals rejected 42501 or filtered (zero rows affected), per the semantics in Postgres RLS.
• Snapshot fixtures round-trip through the snapshot schema so UI tests use exactly what the provider validates.
• RLS parity for memberOf: named scopes and resource scopes compile to the mapped membership tables and agree with can() for each dialect, including expired memberships and parent hops.

How denials surfaceCopy Anchor Link

Test failures print the Decision: outcome, matched grant, denials with role and reason, alternatives. Parity failures print both sides (in-process outcome and database outcome with the SQL error code). Type failures are ordinary tsc errors surfaced by Vitest's typecheck mode.

Example appCopy Anchor Link

— (no dedicated example). describePolicy suites run in packages/permdock/tests/testing; every example under apps/examples runs permdock doctor. tests/integration runs rlsParity against testcontainers Postgres (pnpm test:integration), ormParity for Drizzle (node-postgres and PGlite), Kysely and Prisma 7 in src/orm-parity.test.ts, testAgentAdapter in packages/permdock/tests/testing against permdock/ai-sdk, permdock/openai, permdock/claude-agent, permdock/eve, permdock/mcp, permdock/a2a and permdock/terminal, and testHttpAdapter in tests/integration/src/http against the kernel, permdock/node, Hono, Express, Fastify, Elysia, Nest on both platforms, tRPC, oRPC and permdock/supabase/middleware. apps/examples/supabase-rls is the consumer-facing fixture. tests/runtimes (pnpm test:runtimes) serves one Fetch app built from the kernel, permdock/hono, permdock/authzen and permdock/jwt under Bun, Deno and workerd, plus permdock/elysia on Bun, and replays the same request table against each; the workerd bundle is built with platform: 'neutral' and runs without nodejs_compat.

Related standardsCopy Anchor Link

• Postgres RLS: parity semantics (USING, WITH CHECK, 42501). rlsParity takes a query function, so any driver or a Neon branch works; this repository uses pg against testcontainers.
• AuthZEN: mockEndpoint request and response shapes.
• Next.js Cache Components: Instant Navigations testing.