How do I test a contract I consume?

import { contractDrift } from '@evanion/acl/testing';
import type { Matrix } from '@evanion/acl';
 
// The contract this consumer pinned, checked in beside the test.
const pinned: Matrix = {
  version: 'orders@7',
  permissions: [
    {
      key: 'orders:order.refund',
      object: 'orders:order',
      action: 'refund',
      rules: [
        {
          id: 'bookseller',
          when: [
            { field: 'subject.roles', op: 'contains', value: 'bookseller' },
          ],
        },
      ],
    },
    {
      key: 'orders:order.cancel',
      object: 'orders:order',
      action: 'cancel',
      rules: [{ id: 'anyone', when: [] }],
    },
  ],
};
 
// What the producer publishes now, fetched in CI. The refund key is gone.
const fetched: Matrix = {
  version: 'orders@8',
  permissions: [
    {
      key: 'orders:order.cancel',
      object: 'orders:order',
      action: 'cancel',
      rules: [{ id: 'anyone', when: [] }],
    },
  ],
};
 
const staff = { id: 'u1', roles: ['bookseller'] };
 
const drift = contractDrift({
  pinned,
  fetched,
  // The decisions this application renders, named the way a reader reads them.
  cases: [
    {
      name: 'the refund button',
      subject: staff,
      key: 'orders:order',
      action: 'refund',
    },
    {
      name: 'the cancel button',
      subject: staff,
      key: 'orders:order',
      action: 'cancel',
    },
  ],
});
 
drift.removed; // -> ['orders:order.refund']
drift.changed.map((change) => change.name); // -> ['the refund button']
drift.changed[0]?.fetched.reason; // -> 'unknown-action'

import { AclAssertionError, ContractDriftError } from '@evanion/acl/testing';
import { assertNoContractDrift } from '@evanion/acl/testing';
import { describeContractDrift } from '@evanion/acl/testing';
import type { Matrix } from '@evanion/acl';
 
// One refund permission, held by whoever carries `role`.
const refund = (version: string, role: string): Matrix => ({
  version,
  permissions: [
    {
      key: 'orders:order.refund',
      object: 'orders:order',
      action: 'refund',
      rules: [
        {
          id: 'staff',
          when: [{ field: 'subject.roles', op: 'contains', value: role }],
        },
      ],
    },
  ],
});
 
// The producer kept the key and narrowed the role that holds it.
const staff = { id: 'u1', roles: ['bookseller'] };
 
let caught: unknown;
try {
  assertNoContractDrift({
    pinned: refund('orders@7', 'bookseller'),
    fetched: refund('orders@8', 'supervisor'),
    cases: [
      {
        name: 'the refund button',
        subject: staff,
        key: 'orders:order',
        action: 'refund',
      },
    ],
  });
} catch (error) {
  caught = error;
}
 
const drift = caught as ContractDriftError;
drift instanceof AclAssertionError; // -> true
drift.report.removed; // -> []
drift.report.changed[0]?.fetched.reason; // -> 'no-rule-matched'
describeContractDrift(drift.report).split('\n')[0]; // -> 'contract drift, orders@7 -> orders@8'

import { diffMatrix } from '@evanion/acl';
import { contractDrift } from '@evanion/acl/testing';
import type { Matrix } from '@evanion/acl';
 
const bookseller = {
  id: 'staff',
  when: [{ field: 'subject.roles', op: 'contains', value: 'bookseller' }],
} as const;
 
const supervisor = {
  id: 'supervisor',
  when: [{ field: 'subject.roles', op: 'contains', value: 'supervisor' }],
} as const;
 
const contract = (version: string, rules: readonly unknown[]): Matrix =>
  ({
    version,
    permissions: [
      {
        key: 'orders:order.refund',
        object: 'orders:order',
        action: 'refund',
        rules,
      },
    ],
  }) as Matrix;
 
const report = contractDrift({
  pinned: contract('orders@7', [bookseller]),
  fetched: contract('orders@8', [bookseller, supervisor]),
  diff: diffMatrix,
});
 
report.changed; // -> []
report.diff?.unchanged; // -> false
report.diff?.findings.map((finding) => finding.kind); // -> ['granted']

import { parseMatrix } from '@evanion/acl';
import { assertRefused, fixtureClock } from '@evanion/acl/testing';
import type { Matrix } from '@evanion/acl';
 
const contract: Matrix = {
  version: 'orders@7',
  maxStale: 300_000,
  permissions: [
    {
      key: 'orders:order.refund',
      object: 'orders:order',
      action: 'refund',
      rules: [{ id: 'anyone', when: [] }],
    },
  ],
};
 
const clock = fixtureClock(contract, { fetchedAt: '2026-01-01T00:00:00Z' });
const storefront = parseMatrix(contract, clock.options);
const shopper = { id: 'u1' };
 
const inside = storefront.can(
  shopper,
  'orders:order',
  'refund',
  undefined,
  clock.fresh,
);
inside.reason; // -> 'allow'
 
// `assertRefused` names the key, the reason and the rule when it throws, so a
// failure says which refusal arrived instead of `false !== true`.
const past = storefront.can(
  shopper,
  'orders:order',
  'refund',
  undefined,
  clock.stale,
);
assertRefused(past, 'stale-contract').allowed; // -> false

import { parseMatrix } from '@evanion/acl';
import { AclAssertionError, assertAllowed } from '@evanion/acl/testing';
import { assertFieldState, assertRefused } from '@evanion/acl/testing';
import { explainDecision, explainFieldDecision } from '@evanion/acl/testing';
import type { Matrix } from '@evanion/acl';
 
const contract: Matrix = {
  version: 'orders@8',
  permissions: [
    {
      key: 'orders:order.update',
      object: 'orders:order',
      action: 'update',
      rules: [
        {
          id: 'staff',
          when: [
            { field: 'subject.roles', op: 'contains', value: 'bookseller' },
          ],
        },
      ],
      fields: { fields: ['note'] },
    },
  ],
};
 
const storefront = parseMatrix(contract);
const staff = { id: 'u1', roles: ['bookseller'] };
 
const decision = storefront.can(staff, 'orders:order', 'update');
assertAllowed(decision, 'the order editor').rule; // -> 'staff'
explainDecision(decision); // -> '"orders:order.update" allowed with reason "allow", from rule "staff"'
 
// A shopper holds no role the rule names, so no allow rule matched.
const shopper = { id: 'u2', roles: [] };
const refused = storefront.can(shopper, 'orders:order', 'update');
assertRefused(refused, 'no-rule-matched', 'the order editor').allowed; // -> false
 
// No proposed write, so the decision covers the row's fields and the listed names.
const fields = storefront.canFields(
  staff,
  'orders:order',
  'update',
  { note: 'held for pickup' },
  'write',
);
assertFieldState(fields, 'note', 'allowed').allowed; // -> true
explainFieldDecision(fields); // -> '"orders:order.update" allowed with reason "allow", from rule "staff"; note: allowed (allow)'
 
let caught: unknown;
try {
  assertFieldState(fields, 'total', 'allowed');
} catch (error) {
  caught = error;
}
 
const failure = caught as AclAssertionError;
failure instanceof AclAssertionError; // -> true
failure.message; // -> '"orders:order.update" has no field "total": it carries note'