Testing

PurposeCopy Anchor Link

permdock/testing is a subpath of permdock that only test files import. Vitest is its optional peer (permdock/testing/core needs no runner, see other test runners), 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, policyMatrix, snapshotFixture, seedRows, testRlsParity, testOrmParity, testClientParity, testLegacyParity, testClientStore, testHttpAdapter, testAgentAdapter, the core-backed conformance runners (testSubjectResolver, testMembershipSource, testRelationSource, testCustomRoleSource, testApprovalStore, testDecisionSink, testSnapshotSource, testPolicySource, testWhereCompiler, testTokenVerifier, testTokenSigner, testLimitStore, testDirectoryStore, testReplayStore, testSetQueue, testRevocationFeed, testIdempotencyStore), the AuthZEN interop runner testAuthzen with the interop Todo domain, the PermDock Cloud contract runner testCloudApi, and Vitest type fixtures, plus one signed-output fixture per typ (vnd.permdock.snapshot+jwt, vnd.permdock.approval+jwt, vnd.permdock.evidence+jwt, vnd.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,
  testRlsParity,
  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" },
    },
  },
});

Other test runnersCopy Anchor Link

permdock/testing/core exports policyMatrix, testRlsParity and testOrmParity and imports no test runner, so node:test, Bun, Deno or Jest can run them; tests/bundle asserts it loads no package. permdock/testing re-exports all three. The same matrix under node:test:

import assert from "node:assert/strict";
import { test } from "node:test";
import { policyMatrix } from "permdock/testing/core";
import { permissions } from "../src/permissions";
import { policy } from "../src/policy";

test("policy matrix", async () => {
  const report = await policyMatrix(policy, {
    subjects: {
      anonymous: null,
      member: { id: "u1", orgId: "o1", roles: ["member"] },
    },
    fixtures: { ownPost: { id: "p1", authorId: "u1", orgId: "o1" } },
    matrix: {
      [permissions.post.create.key]: { anonymous: "denied", member: "granted" },
      [permissions.post.update.key]: {
        ownPost: { anonymous: "denied", member: "granted" },
      },
    },
  });
  assert.deepEqual(report.missing, []);
  for (const cell of report.cells) {
    assert.deepEqual(cell.failures, [], cell.name);
  }
});

For one result line per cell, take the test context t and run await t.test(cell.name, () => assert.deepEqual(cell.failures, [])) for each cell.

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 { getPermDock } from "permdock";
import {
  saasPolicy,
  saasScenarioOptions,
  saasScenarios,
  saasUser,
} from "permdock/testing/saas";

for (const scenario of saasScenarios) {
  const permdock = await getPermDock(
    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); 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.

permdock/testing/fixtures exports two real documents from apps/examples/next-better-supabase, for testing code that consumes PermDock's files rather than its runtime, such as a Cloud implementation or a catalog viewer. betterSupabaseCatalog is its permissions.catalog.json (catalog-v1: resources, permissions, scopes, roles, grants and delegations) and betterSupabaseManifest its permdock.manifest.json (supabase-manifest-v1). Both are parsed with parseCatalog and parseSupabaseManifest at import. pnpm gen:check fails when the copies drift from the example.

import {
  betterSupabaseCatalog,
  betterSupabaseManifest,
} from "permdock/testing/fixtures";

const pushed = await client.catalog.push(betterSupabaseCatalog);
expect(pushed.fingerprint).toBe(betterSupabaseCatalog.fingerprint);

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: policyMatrix builds one PermDock per entry of subjects with getPermDock(policy, subject, options), null for anonymous; a subject the policy maps to an actor or delegation covers agent cases. A cell naming a subject that subjects lacks decides for undefined.
2. Check: decide for every cell, with the cell's fixture as the row. A flat row of an instance permission uses the first fixture.
3. Trace: a deniedBy cell also calls explain and reads the winning deny's name; snapshot: true decides the cell again on fromSnapshot of a JSON round trip.
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 testRlsParity against testcontainers Postgres (pnpm test:integration), testOrmParity 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). testRlsParity 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.