Test a provider

Provider tests must cover the public contract, race boundaries, and native failure modes. A happy-path task run is not enough.

Start with the shared suite

The raw storage conformance suite is runner-agnostic. Vitest users can register it directly:

import { createLocalStorageDriver } from '@runlane/local-adapters'
import { describeStorageDriverConformance } from '@runlane/testing/vitest'
import { expect, test } from 'vitest'

test('creates an isolated provider instance', async () => {
  // Given / When
  const driver = createLocalStorageDriver()

  // Then
  expect(driver.name).toBe('local-memory-record-storage')
  await driver.close?.()
})

// Replace createLocalStorageDriver with the factory exported by your provider.
describeStorageDriverConformance({
  createDriver: createLocalStorageDriver,
  name: 'my provider',
})

Run the suite against an isolated provider instance. Cleanup must leave no state for the next case.

Set append: true in the conformance options when the provider implements ordered append. Set exclusiveCandidates: true when its profile advertises exclusive selection. These flags enable required behavioral checks for those optional features; leave them omitted for existing providers without them. Local implements append. PostgreSQL implements both.

Storage checklist

Prove:

• exact point-read positions, duplicates, misses, and defensive copies.
• create, replace, and delete atomicity.
• callback replay, rollback, version fencing, and read-only conflicts.
• no partial write when any mutation fails.
• frozen transaction time and rejection of reads after sealing.
• every range bound in both sort directions.
• equal-sort key ordering and scoped pagination.
• explicit failures for every reported limit.
• optional operator filters, sorts, cursors, and tombstone visibility.
• optional append ordering, defensive copies, position bounds, atomic rollback, and combined transaction limits.
• optional exclusive selection across overlapping transactions, including release after rollback.

Run the same behavioral suite against more than one provider when possible. Parity catches assumptions hidden by one database.

Transport checklist

Prove:

• canonical byte preservation.
• one same-index outcome per input.
• native batch splitting and reconstruction.
• request-level versus item-level failure mapping.
• handled, retry, and reject settlement.
• cancellation, visibility or lock refresh, and shutdown.
• poison-message handling and terminal-policy failure.
• ordering within a partition and progress across partitions.

Test real infrastructure

Mocks cannot prove how a real service handles isolation, locks, clocks, batch errors, or redelivery. Add an opt-in suite for the real service. A supported compatible implementation is also useful.

Exercise at least:

1. startup and compatibility checks.
2. concurrent writers or consumers.
3. process interruption during an owned operation.
4. provider timeout and reconnect behavior.
5. clean and repeated shutdown.

Run the package gates

Before release, run the package's typecheck, lint, tests, build, and publint. Then run its documented live-provider command.

Do not weaken a shared assertion to fit a provider. If the infrastructure cannot meet a contract, report a weaker profile where the contract allows it or do not expose that capability.