Documentation

Testing Against CurrencyCore

Use test keys for integration checks, deterministic fixtures for unit tests, and contract tests against the OpenAPI 3.1 spec.

Tests that call the live API on every run are slow, flaky, and expensive against your quota. Test keys are not a separate sandbox either: they return the same reference data and count against the monthly quota. Keep unit tests on recorded fixtures, check response shapes against the OpenAPI contract, and reserve a small, tagged integration suite for a real test key.

A test key is always capped at 60 requests per minute, whatever plan the organization is on. If a test reaches older history, remember that Free history is the last 30 days and older dates return 403. There is no fixture dataset to seed or reset, so deterministic data has to live in your repository.

Layer	Data source	What it proves
Unit	Checked-in fixtures	Your parsing and mapping logic
Contract	Pinned `openapi.json`	Response fields still match the spec
Integration	`cc_test_` key	Auth, network, and limit behavior

import assert from "node:assert/strict";
import { readFile } from "node:fs/promises";
import test from "node:test";

const spec = JSON.parse(await readFile("openapi.json", "utf8"));
const schema = spec.components.schemas.ConvertResponse;

test("convert fixture has every required contract field", async () => {
  const fixture = JSON.parse(
    await readFile("fixtures/convert-usd-eur.json", "utf8"),
  );

  for (const field of schema.required) {
    assert.ok(field in fixture, `missing ${field}`);
  }
  assert.equal(spec.openapi, "3.1.0");
});

Download the spec from /openapi.json and pin the copy used by CI, so a contract change shows up as a reviewable diff rather than a surprise in production. For the integration layer, pass the key through the environment and skip the suite when it is absent:

CURRENCYCORE_API_KEY=cc_test_your_key npx tsx --test test/integration/*.test.ts

Do not assert exact rates in an integration test. Assert status, envelope shape, and the date rules instead. Mock the network for anything that needs a fixed number.