Conformance tests

An all-day event that comes back a day early or a 412 that surfaces as a generic error is easy to miss until a user finds it. Run @cal-sdk/provider-tests against your provider to catch round-trip and error-mapping mistakes like these. Most official providers use the same suite, and it skips anything your provider doesn't declare as supported.

import { describeProviderConformance } from '@cal-sdk/provider-tests';
import { acme } from '../src/acme';

describeProviderConformance({
  name: 'acme',
  createProvider: ({ fetch }) => acme({ accessToken: process.env.ACME_TOKEN ?? 'replay', fetch }),
  recording: {
    path: 'test/fixtures/conformance.json',
    mode: process.env.CALSDK_RECORD ? 'record' : 'replay',
  },
});

Pass the suite's fetch through to your provider. That's how the suite records, replays and stubs error responses.

The tests cover calendars, event create, read, update and delete, all-day and time zone round trips, pagination, recurring series and their exceptions, etags, sync, free/busy and HTTP error mapping. A provider without recurring events, say, is never asked to split a series.

Record once, replay everywhereCopy Anchor Link

CALSDK_RECORD=1 ACME_TOKEN=... bunx vitest run test/conformance.test.ts

Record against a calendar made for testing, set with calendarId. The tests delete what they create, but they do write to it.

Credentials aren't saved: only the few request headers that change what a request does, and no token query parameters. Response bodies are saved as the API returned them, though, so they can hold names and email addresses. Read a recording before you commit it.

OptionsCopy Anchor Link

namestring

Suite name, such as 'acme'.

createProvider(settings: { fetch }) => CalendarProviderV1

Creates the provider under test. Pass fetch through.

calendarId?string= 'primary'

Calendar the tests write to.

recording?{ path: string; mode?: 'record' | 'replay' }

Record and replay HTTP traffic. Leave out to call the API live.

http?boolean= true

Run the tests that stub HTTP responses. Set false for providers that do not call fetch.

firstDay?string= '2030-01-07'

First day test events are placed on, 'YYYY-MM-DD'. Fixed rather than relative to today, so recordings replay.

Your own testsCopy Anchor Link

For tests of behavior specific to your API, createRecordingFetch is exported with the same record and replay modes. The suite needs Vitest 5 and a runtime with node:fs.