# Testing Against CurrencyCore

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

Canonical: https://currency-core.com/docs/guides/testing/
Updated: 2026-11-11
Published: 2026-11-11

---
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 |

```ts

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:

```bash
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.

## Related

- [OpenAPI specification](/docs/openapi/)
- [Authentication](/docs/authentication/)
- [Errors](/docs/errors/)
- [Rate limits](/docs/rate-limits/)
- [Guides](/docs/guides/)