@avelon/conformance

@avelon/conformance is the load-bearing test artifact for Avelon drivers. It ships one suite per frozen contract, written against the contract rather than any implementation, plus in-memory fakes that run those same suites. Reach for this package when you certify a driver: pass a create factory that returns a known-empty instance, and let the suite own the assertions. A passing driver means someone other than the driver author wrote the tests.

Installation

bun add -d @avelon/conformance

Suites import bun:test and live at @avelon/conformance/suites. Fakes stay on the package root so a Next or Node production graph can import FakeMail without loading the test runner. Point a driver package at @avelon/core for the contract and at this package for the suite.

Basic Usage

Wire the shared database suite to an in-memory fake, then swap create for your driver when you certify it.

import { FakeDatabase } from '@avelon/conformance'
import { databaseSuite } from '@avelon/conformance/suites'

databaseSuite({
  name: 'reference fake',
  create: () => new FakeDatabase(),
})

A live driver owns fixture reset and cleanup. The suite still assumes each create() returns a known-empty world.

import { databaseSuite } from '@avelon/conformance/suites'
import { createPostgresDatabase } from '@avelon/postgres'

databaseSuite({
  name: 'live postgres',
  create: async () => {
    const driver = createPostgresDatabase()
    await driver.resetFixtures()
    return driver
  },
  cleanup: (driver) => driver.close(),
})

Shared Suites

Every contract has one suite. You did not write it. That is the point. Call the matching function from a bun test file; the suite registers describe and test blocks itself.

import { FakeMail } from '@avelon/conformance'
import { mailSuite } from '@avelon/conformance/suites'

mailSuite({
  name: 'reference fake',
  create: () => new FakeMail('transactional', 'mailer@example.test'),
})

A driver either passes a capability's tests or declares that capability false. Declaring true and failing, or declaring false while still implementing the method, is a suite failure.

Reference Fakes

Each fake is an in-memory implementation of one contract. Fakes run the same suites as live drivers, so new FakeMail() cannot drift from the mail contract. Use them in application tests and in this package's own certification of the suites.

Capability-narrowed variants exist where a boolean or spectrum can be off: FakeFlagsWithoutTargeting, FakeNotificationsWithoutChannels, FakeQueueWithoutRetries, FakeRateLimitWithoutAlgorithms, and FakeSearchWithoutFacets.

import { FakeFlags, FakeFlagsWithoutTargeting } from '@avelon/conformance'

const withTargeting = new FakeFlags()
const withoutTargeting = new FakeFlagsWithoutTargeting()

const targeted = await withTargeting.evaluate('assay.targeted', false, { actorId: 'actor-enabled' })
const globalOnly = await withoutTargeting.evaluate('assay.enabled', false)

Capability Surfaces

assertCapabilitySurface checks both lies: a declared capability whose method is missing, and an implemented method whose capability is false. Suites call it; you may also call it from a driver test when a surface is method-gated.

import { assertCapabilitySurface, captureFailure, FakeStorage } from '@avelon/conformance'

const storage = new FakeStorage()
assertCapabilitySurface(storage, 'signedUrls', storage.capabilities.signedUrls, ['signedUrl'])

const error = await captureFailure(() => storage.get('missing/avatar.png'))

captureFailure returns the thrown value so suites can assert the framework error taxonomy instead of a vendor code.

Method Reference

Testing

This package is the suite. Run it against the shipped fakes here, and again against a real driver in that driver's package. A deliberately broken stub in tests/ proves the suite rejects compiler defects rather than echoing the fake back to itself.

import { FakeStorage } from '@avelon/conformance'
import { storageSuite } from '@avelon/conformance/suites'

storageSuite({
  name: 'reference fake',
  create: () => new FakeStorage(),
})

bun test
bun run typecheck