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 answers | Your client should |
|---|---|
| 200 | Return success, record the message |
202 with success: false (send_outcome_unknown) | Check GET /v1/messages, never record it as sent |
202 with held: true | Record it as held, never resend |
| 429 | Schedule a retry with the same Idempotency-Key |
| 500 or a dropped connection | Schedule a retry with the same key |
500 with outcome_unknown: true | Check GET /v1/messages before any retry |
| 409 | Reschedule rather than mark failed |
| 403 | Mark failed, never retry |
| 400 | Mark 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.