@avelonjs/conformance

@avelonjs/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 @avelonjs/conformance

Suites import bun:test and live at @avelonjs/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 @avelonjs/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 '@avelonjs/conformance'
import { databaseSuite } from '@avelonjs/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 '@avelonjs/conformance/suites'
import { createPostgresDatabase } from '@avelonjs/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 '@avelonjs/conformance'
import { mailSuite } from '@avelonjs/conformance/suites'

mailSuite({
  name: 'reference fake',
  create: () => new FakeMail('transactional', '[email protected]'),
})

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 '@avelonjs/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 '@avelonjs/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

| Method / export | Signature | Description | |---|---|---| | assertCapabilitySurface | (driver: object, capability: string, declared: boolean, methods: readonly string[]) => void | Fails when a declared method is missing or an undeclared method is present. | | captureFailure | (operation: () => Promise<unknown>) => Promise<unknown> | Runs an operation expected to throw and returns the thrown value. | | SuiteContext | interface SuiteContext<TDriver> | name, create, optional cleanup, and live-service helpers for one suite. | | FakeAI | class FakeAI | In-memory AI driver used as the AI contract reference. | | FakeCache | class FakeCache | In-memory cache driver used as the cache contract reference. | | FakeDatabase | class FakeDatabase | In-memory database driver used as the database contract reference. | | FakeFlags | class FakeFlags | In-memory flags driver with targeting enabled. | | FakeFlagsWithoutTargeting | class FakeFlagsWithoutTargeting | Flags fake with targeting declared unavailable. | | FakeIdentity | class FakeIdentity | In-memory identity driver used as the identity contract reference. | | FakeLogs | class FakeLogs | In-memory log driver with traces enabled. | | FakeTraceRecord | interface | Observable span state retained by FakeLogs. | | FakeMail | class FakeMail | In-memory mail driver with hosted templates enabled. | | FakeNotifications | class FakeNotifications | In-memory notifications driver with every channel declared. | | FakeNotificationsWithoutChannels | class FakeNotificationsWithoutChannels | Notifications fake with an empty channel list. | | FakeSentNotification | interface | One notification accepted by a notifications fake. | | FakePayments | class FakePayments | In-memory payments driver used as the payments contract reference. | | FakeQueue | class FakeQueue | In-memory queue driver with retries enabled. | | FakeQueueWithoutRetries | class FakeQueueWithoutRetries | Queue fake with retries declared unavailable. | | FakeRateLimit | class FakeRateLimit | In-memory rate-limit driver with every algorithm declared. | | FakeRateLimitWithoutAlgorithms | class FakeRateLimitWithoutAlgorithms | Rate-limit fake with an empty algorithm list. | | FakeRealtime | class FakeRealtime | In-memory realtime driver used as the realtime contract reference. | | FakeSearch | class FakeSearch | In-memory search driver with facets enabled. | | FakeSearchWithoutFacets | class FakeSearchWithoutFacets | Search fake with facets declared unavailable. | | FakeSocial | class FakeSocial | In-memory social identity driver used as the social contract reference. | | FakeStorage | class FakeStorage | In-memory storage driver used as the storage contract reference. | | FakeTokens | class FakeTokens | In-memory API-token driver used as the tokens contract reference. | | aiSuite | (context: SuiteContext<TDriver>) => void | Shared AI contract suite from @avelonjs/conformance/suites. | | cacheSuite | (context: SuiteContext<TDriver>) => void | Shared cache contract suite. | | databaseSuite | (context: SuiteContext<TDriver>) => void | Shared database contract suite. | | flagsSuite | (context: SuiteContext<TDriver>) => void | Shared flags contract suite. | | identitySuite | (context: SuiteContext<IdentityFactory<TDriver>>) => void | Shared identity contract suite. | | logsSuite | (context: SuiteContext<TDriver>) => void | Shared logs contract suite. | | mailSuite | (context: SuiteContext<TDriver>) => void | Shared mail contract suite. | | notificationsSuite | (context: SuiteContext<TDriver>) => void | Shared notifications contract suite. | | paymentsSuite | (context: SuiteContext<TDriver>) => void | Shared payments contract suite. | | queueSuite | (context: SuiteContext<TDriver>) => void | Shared queue contract suite. | | ratelimitSuite | (context: SuiteContext<TDriver>) => void | Shared rate-limit contract suite. | | realtimeSuite | (context: SuiteContext<TDriver>) => void | Shared realtime contract suite. | | searchSuite | (context: SuiteContext<TDriver>) => void | Shared search contract suite. | | socialSuite | (context: SuiteContext<TDriver>) => void | Shared social contract suite. | | storageSuite | (context: SuiteContext<TDriver>) => void | Shared storage contract suite. | | tokensSuite | (context: SuiteContext<TDriver>) => void | Shared tokens contract suite. |

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 '@avelonjs/conformance'
import { storageSuite } from '@avelonjs/conformance/suites'

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

bun test
bun run typecheck