How do I test Koa middleware without faking ctx?

Record the running server with Keploy. The request arrives over a real socket, so it enters the cascade at the top and every middleware runs both before and after await next() — including the halves a fabricated ctx never reaches.

Does the Koa cascade run under Keploy?

Yes, in both directions. That is the main reason to record rather than call a middleware directly: the code after await next(), where response shaping and error wrapping live, only runs when the request actually travels the cascade.

Is Keploy a supertest alternative for Koa?

For integration tests, yes. supertest drives an app the test file assembles, so middleware registered in your entrypoint is absent. Keploy records the real process, so the app under test is the app you deploy.

Can Keploy mock database calls in Koa?

Yes. Capture happens at the wire protocol beneath the driver, so node-postgres, Prisma, mongoose, and ioredis all replay with the exact rows and documents they received. No test database in CI.

Is Keploy free for Koa projects?

Yes. The Keploy CLI is open source under Apache 2.0 and free to run on any Koa service with no seat limits. It is not an npm package, so it never appears in package.json.

Keploy as a Koa testing framework

Keploy tests Koa applications by recording real requests through the running server and every database or outbound call they trigger, then replaying both as assertions. The full middleware cascade runs, because the request travelled it rather than being handed a fabricated ctx.

Generate Koa tests free

keploy record -c "node dist/server.js"

18.4K+

1.2M+300M+mocks createdSlack

What Keploy gives a Koa team

Any Koa app, unchanged

Keploy runs your real entrypoint. Koa's cascade, custom context properties, and router middleware all execute because capture is at the socket rather than inside the app object.

Koa 2 and above
@koa/router and koa-compose
Custom ctx properties preserved
CJS, ESM, and TypeScript

Try Keploy for free Explore the docs

The problem

Why Koa integration tests slow teams down

The friction is rarely the assertions. It is everything around them — spinning up dependencies, keeping mocks honest, and repairing tests after every refactor.

Book a call Explore the docs

Three ways to do it

Testing Koa: by hand, with Jest + supertest + nock, or with Keploy

A fabricated ctx never enters the cascade, so the post-await half of every middleware is skipped. Keploy records the running server, so the whole cascade runs both ways.

By hand

Jest + supertest + nock

With Keploy

Select any row for the full comparison, with code.

Get started Book a call

Same coverage, three costs

What you write for Koa vs what Keploy records

All three produce the same assertion. Only the third still passes after the next refactor without anyone editing it.

By hand2–4 hours

confirm.test.js

hand-written

// Hand-written: a ctx literal that never enters the cascade.

const confirm = require('../src/middleware/confirm');

test('confirms an authorized order', async () => {

const ctx = {

params: { id: 'ord_1' },

request: { body: { paymentToken: 'tok_123' } },

// Everything earlier middleware decorates has to be faked here.

state: { user: { id: 'usr_1' } },

db: fakeDb,

body: undefined,

status: 404,

};

await confirm(ctx, async () => {});

expect(ctx.status).toBe(200);

});

The ctx is invented, so every property earlier middleware would have set is guessed — and the code after await next() in the surrounding cascade never runs.

Jest + supertest + nock1–2 hours

confirm.supertest.test.js

tool-assisted

// Jest + supertest + nock against an assembled app.

const nock = require('nock');

const request = require('supertest');

const Koa = require('koa');

test('confirms an authorized order', async () => {

nock('https://api.payments.example.com')

.post('/v1/payment_intents/tok_123/confirm')

.reply(200, { status: 'AUTHORIZED' });

const app = new Koa();

app.use(bodyParser());

app.use(router.routes());

// The error middleware and auth from server.js are not here.

const res = await request(app.callback())

.post('/orders/ord_1/confirm')

.send({ paymentToken: 'tok_123' });

expect(res.status).toBe(200);

});

The cascade runs, which is better — and it is the cascade this test file assembled, not the one server.js builds, so the error and auth middleware are missing.

With Keploy~5 minutes

test-1.yaml

auto-generated

# Recorded with: keploy record -c 'node dist/server.js'

# Nobody wrote this file. Keploy captured it from a real request.

version: api.keploy.io/v1beta1

kind: Http

name: test-1

spec:

req:

method: POST

url: /orders/ord_1/confirm

header:

Authorization: Bearer <captured>

body: '{"paymentToken":"tok_123"}'

resp:

status_code: 200

body:

id: "ord_1"

state: "CONFIRMED"

amountMinor: 4200

noise:

- body.confirmedAt

mocks:

- kind: Postgres

operation: "SELECT id, amount_minor, state FROM orders WHERE id = $1"

- kind: Http

url: https://api.payments.example.com/v1/payment_intents/tok_123/confirm

The recorded response carries headers set by middleware after await next(), which is the proof the whole cascade ran in both directions.

Times are estimates for authoring one endpoint’s coverage from scratch, not measurements.

Explore the docs Request a trial

Keploy vs the alternatives

Koa testing tools, compared

The options a team on Node.js actually reaches for, and where each one genuinely wins. Select a row for the full comparison.

Keploy

Jest + supertest

nock

Mocha + Sinon

Mock Service Worker

Postman

SmartBear ReadyAPI

Best in classStrongPartialNot covered

Assessments reflect each tool’s documented behaviour, not benchmark measurements.

Request a trial Book a call

How it works

Record your Koa app once, replay it forever

Keploy sits below your Koa process at the network layer. It watches the calls your app already makes, then serves them back on replay so tests run with no dependencies attached.

Your Koa appGET/api/v1/orders/{id}200

RecordingKeploy proxyeBPF · userspace

PostgreSQLPostgres frontend/backend protocol

MySQLMySQL wire protocol

MongoDBMongoDB wire protocol

RedisRESP over TCP

+3 more Koa dependencies

An example shape of a captured call. Your own endpoints and dependencies come from your real traffic, so nothing here has to be written by hand.

Try Keploy for free Request a trial

Mock coverage

What Keploy mocks for Koa, with zero config

7 of the 7 dependencies a typical Koa service talks to are stubbed from the recording itself — no mock classes, no fixture files, no containers in CI.

Auto-mocked
PostgreSQLView page
Postgres frontend/backend protocol
Auto-mocked
MySQLView page
MySQL wire protocol
Auto-mocked
MongoDBView page
MongoDB wire protocol
Auto-mocked
RedisView page
RESP over TCP
Auto-mocked
Apache KafkaView page
Kafka producer and consumer protocol
Auto-mocked
gRPCView page
HTTP/2 framed gRPC calls
Outbound HTTP
Auto-mocked
Outbound HTTP
Any HTTP client call the service makes

Explore the docs Book a call

Quick start

Your first Koa test suite in under five minutes

Every command below runs against your existing Koa service. Nothing in your source tree changes.

1
1Install the Keploy CLI
A single binary. It needs a Linux kernel with eBPF support, or Docker on macOS and Windows — and it adds nothing to your project's dependencies.
curl -sSL https://keploy.io/install.sh | bash
2
2Record your service
Pass the command you already use to start the app. Keploy runs it and watches every socket it opens.
keploy record -c "node dist/server.js"
3
3Exercise the paths you care about
Drive the running server. Every request becomes a test case with its database and HTTP calls captured alongside.
npm run build
curl -X POST localhost:3000/orders/ord_1/confirm -H 'Content-Type: application/json' -H 'Authorization: Bearer $TOKEN' -d '{"paymentToken":"tok_123"}'
4
4Replay in CI
Replay serves the recorded dependency responses, so the job needs no service containers and no Docker daemon.
keploy test -c "node dist/server.js" --delay 8