ArctonArcton
Testing

Testing Middleware

Unit-test a Middleware in isolation with a hand-built ctx and a fake next.

A Middleware is nothing more than a (ctx, next) => ... function. That means it can be tested directly, without a server or a route — build a minimal ctx by hand, pass a fake next, and assert on what the middleware did.

A makeCtx helper

import type { Context } from '@arcton/contracts'

function makeCtx(request: Request): Context {
  return {
    request,
    params: {},
    query: {},
    response: { headers: new Headers() }
  }
}

This builds the minimum Context a middleware needs: the incoming request, empty params/query, and a fresh response with empty Headers. Reuse it for any middleware under test, not just one specific to your app.

Testing a middleware that calls next()

import { expect, test } from 'bun:test'
import type { Context } from '@arcton/contracts'
import { cors } from '@arcton/cors'

function makeCtx(request: Request): Context {
  return {
    request,
    params: {},
    query: {},
    response: { headers: new Headers() }
  }
}

test('cors adds Access-Control-Allow-Origin for an allowed origin', async () => {
  const middleware = cors({ origin: 'https://app.example.com' })
  const ctx = makeCtx(
    new Request('http://localhost/', {
      headers: { origin: 'https://app.example.com' }
    })
  )

  await middleware(ctx, async () => {})

  expect(ctx.response.headers.get('Access-Control-Allow-Origin')).toBe(
    'https://app.example.com'
  )
})

Testing a middleware that short-circuits

A middleware that returns a value without calling next() short-circuits the pipeline. Assert that next was never invoked and inspect the returned value directly:

import { expect, test } from 'bun:test'
import type { Context } from '@arcton/contracts'
import { cors } from '@arcton/cors'

function makeCtx(request: Request): Context {
  return {
    request,
    params: {},
    query: {},
    response: { headers: new Headers() }
  }
}

test('a real preflight short-circuits with a 204 Response', async () => {
  const middleware = cors({ origin: 'https://app.example.com' })
  const ctx = makeCtx(
    new Request('http://localhost/users', {
      method: 'OPTIONS',
      headers: {
        origin: 'https://app.example.com',
        'access-control-request-method': 'POST'
      }
    })
  )
  let nextCalled = false

  const result = await middleware(ctx, async () => {
    nextCalled = true
  })

  expect(nextCalled).toBe(false)
  expect(result).toBeInstanceOf(Response)
  expect((result as Response).status).toBe(204)
})

Testing your own middleware

The same technique applies to any middleware you write, not just a built-in one:

import { expect, test } from 'bun:test'
import type { Context, Middleware } from '@arcton/contracts'

function makeCtx(request: Request): Context {
  return {
    request,
    params: {},
    query: {},
    response: { headers: new Headers() }
  }
}

const withRequestId: Middleware = async (ctx, next) => {
  ctx.response.headers.set('X-Request-Id', 'test-id')
  await next()
}

test('withRequestId sets a header before calling next', async () => {
  const ctx = makeCtx(new Request('http://localhost/'))
  let nextCalled = false

  await withRequestId(ctx, async () => {
    nextCalled = true
  })

  expect(nextCalled).toBe(true)
  expect(ctx.response.headers.get('X-Request-Id')).toBe('test-id')
})

Context is imported as a type from @arcton/contracts. This tests the middleware function in isolation, decoupled from routing and the rest of the pipeline — for an end-to-end test that runs a middleware as part of a real request, see Testing routes.

On this page