To test inbound SMS end to end in CI, record real webhook payloads once, store them as fixtures, and replay them against your running app, then assert on what your code did with them. Pair that with a contract test that fails when a fixture stops matching what your handler reads, and a test key for the outbound half. You never need a phone in the loop.
This post is about the test that sits between a unit test and a launch check. Mocking the HTTP client is covered in mock SMS API in unit tests, and what a sandbox does and doesn't prove is in SMS API sandbox and test numbers. Here we wire the pieces into a pipeline that runs on every pull request.
What an end-to-end SMS test covers
An end-to-end test starts your real app, sends it a webhook request the way a provider would, and checks the effects: a row written, a reply queued, an opt-out recorded. It skips the carrier, which is the one part you can't run in CI.
| Layer | Runs in CI | What it catches |
|---|---|---|
| Unit test with a mocked client | Always | Wrong request shape, bad error handling |
| Replay of recorded webhooks | Always | Handler bugs, duplicate and ordering bugs |
| Contract test on fixtures | Always | Payload drift, renamed fields |
| Test key send | Always, if a secret is set | Auth, request shape, response handling |
| Real send to your own phone | Before release, by hand | Delivery, STOP round trip |
The first four are cheap and deterministic. The last one costs money and a person, so keep it out of the pull request path.
Record payloads, then freeze them
Capture a payload from your staging environment the first time a real inbound text, delivery report or opt-out reaches your endpoint. Log the raw body and headers, then save each one as a file under test/fixtures/webhooks/.
Scrub before you commit. Replace real numbers with made-up ones in the 555-01xx range, like +12125550199, and strip names and message text that came from a real person. A fixture in your repository is a fixture everyone can read.
Name each file for the situation, not the date: inbound-plain-text.json, inbound-stop-keyword.json, delivery-failed.json, duplicate-delivery.json. Add the odd ones as you meet them in production: a reply with an emoji, a very long message, an empty body. Each production surprise becomes one more file. Our webhook payload changes post explains why your parser should ignore unknown fields.
We don't list Ready's webhook field names here. Take them from the API quickstart and the error codes reference, and from your own recordings, which are the ground truth for your account.
Replay fixtures against the running app
The replay test boots your app on a random port, posts each fixture, and checks the effect. This sketch uses Node's built-in test runner. The handler path and the readMessages helper are yours, and the file names are the ones above.
import { test } from "node:test";
import assert from "node:assert/strict";
import { readFile } from "node:fs/promises";
import { createApp } from "../src/app.js";
import { readMessages, resetDb } from "./helpers.js";
const fixture = async (name) =>
readFile(new URL(`./fixtures/webhooks/${name}.json`, import.meta.url), "utf8");
async function post(base, name) {
return fetch(`${base}/webhooks/sms`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: await fixture(name),
signal: AbortSignal.timeout(5_000),
});
}
test("inbound webhooks", async (t) => {
const server = createApp().listen(0);
const base = `http://127.0.0.1:${server.address().port}`;
t.after(() => server.close());
t.beforeEach(resetDb);
await t.test("stores a plain inbound text once", async () => {
assert.equal((await post(base, "inbound-plain-text")).status, 200);
assert.equal((await post(base, "inbound-plain-text")).status, 200);
assert.equal((await readMessages()).length, 1);
});
await t.test("marks the contact opted out on a STOP fixture", async () => {
await post(base, "inbound-stop-keyword");
const [row] = await readMessages();
assert.equal(row.contactOptedOut, true);
});
}); Posting the same fixture twice is the cheap way to test idempotency on your side, and it catches a surprising number of bugs. Provider retries and your own retries both deliver duplicates, so a handler that writes two rows is a bug waiting for a slow day. The inbound webhooks guide and dead letter queue replay cover the production side.
Also replay fixtures out of order. Post the delivered report before the sent report and assert the status never moves backward. Out-of-order SMS webhooks explains the rank approach.
Add a contract test so fixtures can't rot
Fixtures go stale quietly. The provider adds a field, your team renames one in the handler, and every test still passes against old files. A contract test closes that gap by asserting that every fixture contains the fields your code reads.
import { test } from "node:test";
import assert from "node:assert/strict";
import { readdir, readFile } from "node:fs/promises";
// Placeholder paths. Fill these from whatever your provider documents
// and your own recordings; they are not Ready field names.
const READS = {
inbound: ["senderPath", "bodyPath", "idPath"],
};
const dig = (obj, path) => path.split(".").reduce((o, k) => o?.[k], obj);
test("every inbound fixture has the fields the handler reads", async () => {
const dir = new URL("./fixtures/webhooks/", import.meta.url);
const files = (await readdir(dir)).filter((f) => f.startsWith("inbound-"));
for (const f of files) {
const payload = JSON.parse(await readFile(new URL(f, dir), "utf8"));
for (const path of READS.inbound) {
assert.notEqual(dig(payload, path), undefined, `${f} is missing ${path}`);
}
}
}); Two refinements help. Re-record one fixture per quarter from staging and diff it against the committed file, and keep a short list of the fields your handler depends on in one module, so the contract test and the handler read the same list.
Test the outbound half with a test key
Inbound flows usually trigger a send: an auto-reply, a confirmation, a follow-up. Use a test key for that path. A test key simulates POST /v1/messages and POST /v1/messages/bulk: nothing is sent or charged, and each result has a test-msg- id and its segments. Writes it can't simulate answer 403 test_key_not_allowed. The test keys docs have the details.
import { test } from "node:test";
import assert from "node:assert/strict";
import { randomUUID } from "node:crypto";
const key = process.env.READY_TEST_KEY;
test("reply send with a test key", { skip: !key }, async () => {
const res = await fetch("https://api.tryready.com/v1/messages", {
method: "POST",
headers: {
"X-API-Key": key,
"Idempotency-Key": randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+12125550199",
body: "Thanks, we got your message.",
consent_attested: true,
}),
signal: AbortSignal.timeout(10_000),
});
assert.ok(res.ok, `status ${res.status}`);
assert.match(await res.text(), /test-msg-/);
}); The skip option means forks without the secret still pass. In your CI config, expose the key as an encrypted secret and keep it out of logs. A separate test key per pipeline makes rotation painless, as in API key security and rotation.
A simulated send skips the real send path: quiet hours, opt-out refusals and carrier filtering. If your inbound flow depends on those, assert them in unit tests against your own code, then check them once by hand with real phones before release.
Wire it into the pipeline
Keep the order cheap to expensive, and fail fast.
- Run the unit tests with the mocked client first, since they fail fastest.
- Run the contract test on fixtures, which catches drift before anything boots.
- Run the replay test against the booted app, with duplicates and out-of-order cases included.
- Run the test key send, skipped when the secret is absent.
- On release branches only, work through a manual checklist with real phones.
Run steps one to four on every pull request. They need no network except step four, and they finish in seconds. For load behavior before a launch, load testing your SMS API is a separate exercise and doesn't belong in this pipeline.
What to take away
Fixtures give you repeatable inbound events, replay gives you real handler coverage, a contract test keeps both honest, and a test key covers the outbound call. None of it proves delivery, and it isn't meant to. Keep one human-run check with real phones before a release, and let the pipeline handle everything else on every commit.