A consumer-driven contract test for an SMS integration writes down exactly what your code sends and what it expects back, then fails your build when the client drifts from it. You can't make a third-party API run your tests, so the useful version is the consumer half: pin your requests, pin how you handle each response class, and check the contract against the real service on a schedule.

We make Ready, so the contract below covers the one request shape we document, POST /v1/messages. The approach works for any SMS provider.

What a contract test is, and isn't

In classic consumer-driven contracts (the Pact style), the consumer records its expectations, and the provider replays them in its own pipeline. That works between two teams in one company.

With a vendor API, only half of it is available. You can verify your client produces the right requests and handles every documented response. You can't make the vendor verify your file. So the contract is a living document of your assumptions, and a scheduled check against the real service tells you when an assumption broke.

It isn't a replacement for other layers. Unit tests with a fake client, covered in mocking an SMS API in unit tests, check your logic. Contract tests check the boundary.

Write the contract as data

Keep it small and readable. Only list shapes you really use.

{
  "request": {
    "method": "POST",
    "path": "/v1/messages",
    "headers": ["X-API-Key", "Idempotency-Key", "Content-Type"],
    "body": {
      "to": "E.164 string",
      "body": "string",
      "consent_attested": "boolean"
    }
  },
  "responses_we_handle": {
    "2xx": "mark sent, unless the body says success: false or held: true",
    "202 success:false send_outcome_unknown": "check GET /v1/messages, never mark sent",
    "202 held": "mark held, never resend",
    "409": "quiet hours: reschedule",
    "403": "consent attestation required: fix data, no retry",
    "429": "retry later, same key",
    "5xx": "retry later, same key",
    "500 with outcome_unknown: true": "check GET /v1/messages, do not just retry"
  }
}

Notice what's absent. There's no field you don't send and no response field you don't read. A contract that lists everything the provider might return is a copy of their docs, and it will rot. Yours lists only what your code depends on. For the full reference, link your team to the messages API docs.

Test 1: the request your client builds

Run your real client against a local stub server and assert on what arrives. No network, no account.

import http from 'node:http';
import assert from 'node:assert/strict';
import { sendText } from '../src/sms-client.js';

test('sendText matches the contract', async () => {
  let seen;
  const server = http.createServer((req, res) => {
    let raw = '';
    req.on('data', (c) => (raw += c));
    req.on('end', () => {
      seen = { method: req.method, url: req.url, headers: req.headers, body: JSON.parse(raw) };
      res.writeHead(200, { 'content-type': 'application/json' });
      res.end('{}');
    });
  }).listen(0);

  await sendText({
    baseUrl: `http://127.0.0.1:${server.address().port}`,
    to: '+15550100123',
    body: 'Your order #1042 has shipped.',
    idempotencyKey: 'order-1042-shipped',
    consentAttested: true,
  });

  assert.equal(seen.method, 'POST');
  assert.equal(seen.url, '/v1/messages');
  assert.ok(seen.headers['x-api-key']);
  assert.equal(seen.headers['idempotency-key'], 'order-1042-shipped');
  assert.deepEqual(Object.keys(seen.body).sort(), ['body', 'consent_attested', 'to']);
  server.close();
});

The last assertion is the useful one. If someone adds a field to the body, the test fails and a human decides whether the new field is in the contract.

Test 2: how your client treats each response

Drive the stub through each status in responses_we_handle and assert on your own behavior, not the provider's.

Stub answersYour client should
200Return success, record the message
202 with success: false (send_outcome_unknown)Check GET /v1/messages, never record it as sent
202 with held: trueRecord it as held, never resend
429Schedule a retry with the same Idempotency-Key
500 or a dropped connectionSchedule a retry with the same key
500 with outcome_unknown: trueCheck GET /v1/messages before any retry
409Reschedule rather than mark failed
403Mark failed, never retry
400Mark failed, never retry

Always assert that the retry reuses the key. A retry with a fresh key is a double text waiting to happen, as our post on SMS API idempotency and duplicate texts explains. For the status codes and their meanings, see the API error reference.

Test 3: a scheduled check against the real service

Stub tests can only encode what you believe. A small scheduled job closes the loop. Run it nightly, not on every pull request, so a vendor hiccup never blocks a merge.

  • Send one text to a number you own, using a key meant for testing, and assert the response is a 2xx.
  • Replay your request with the same Idempotency-Key and assert you don't get a second message.
  • Send a deliberately bad body and assert the failure lands in the 4xx class your client treats as permanent.

Our notes on sandbox and test numbers cover how to keep these checks from costing money or texting real people. Keep the number of calls tiny.

Treat the contract file as a change gate

When the vendor announces a change, you edit the contract file first, watch the tests fail, then change the client. When your own code needs a new field, the same happens in reverse. Either way the diff to the contract is reviewed by a person. That habit pairs well with the practices in SMS API versioning and deprecation.

Takeaways

List only the shapes you use, test the request your client builds, test the response classes you handle, and run a nightly check against the real API. The contract won't catch everything, but it catches the quiet drift that causes most integration surprises. When you're ready to run the nightly check, sign up and point it at your own number.