Lockally

      Use your API key in the examples

      Replaces lk_live_… in the code samples on this site so you can copy and run them. It is stored in this browser only and is never sent anywhere, including to Ask AI.

      It will be visible on the page. Use a test key if you are sharing your screen or taking screenshots.

      Integration testing and mocking

      Two honest options, and the choice is about what you want the test to prove.

      Option 1: call the real API with a test key

      What it proves: your request is well formed, your credentials and scopes are right, the response is the shape you think, and your webhook handler survives a real signed event.

      What it costs: CI needs network access and a secret, and the suite depends on our availability.

      This is the better default, because the failures it catches are the ones that actually happen: a scope you forgot to grant, a field you renamed, a response shape you assumed.

      Practical notes for CI:

      • Give CI its own key, labelled ci, with the narrowest scopes that work. A test key is not read-only, so scopes are the real protection. See Testing API requests.
      • Generate a fresh Idempotency-Key per request, or your suite asserts against a cached response for ever.
      • Nothing you do with a test key counts against rate limits or allowance, so the suite cannot exhaust anything or cost you money.
      • Test rows persist in your workspace. They are excluded from every count and from the console’s figures, but they are not swept, so a long-lived CI key accumulates sandbox messages. GET /v1/sandbox/messages is capped at 200 per page, newest first.

      Option 2: mock us

      What it proves: your code’s behaviour given a response. Nothing about whether that response is one we would actually send.

      That second half is the whole risk of mocking, and it is not theoretical: a hand-written mock encodes what the author believed in the week they wrote it, and then stays that way through every change we make.

      Generate the mock from the spec, do not hand-write it. The OpenAPI specification is served at developers.lockally.com/openapi.yaml and is staged from the source of truth at every docs build, with a CI check that fails if the two diverge. Tools like Prism will stand up a mock server from it:

      npx @stoplight/prism-cli mock https://developers.lockally.com/openapi.yaml

      A spec-generated mock goes stale the day we change the spec, which you will notice, rather than the day you wrote it, which you will not. Re-fetch it in CI rather than vendoring a copy.

      Two caveats on the spec itself. 2 of 185 responses are still untyped, so a mock will return a loose body for those. And the spec describes the API, not the asynchronous half: no mock will produce a webhook, so handler tests still need a real event.

      A shape that works

      Most teams end up with three layers, and the middle one is the one worth arguing about:

      1. Unit tests against a mock or a stub, for your own branching. Fast, run on every save.
      2. Integration tests against the real API with a test key, for the handful of calls your product actually makes. Run in CI, a few seconds each.
      3. One manual live check before a release that touches sending, because nothing above proves mail arrives. See Safe production testing.

      Layer 2 is where teams under-invest, usually because layer 1 feels like it covers it. It does not: a mock cannot tell you that your key lacks templates:read.