ArctonArcton
Testing

Testing Routes

Test routes end to end with app.listen({ port 0 }) and real fetch.

The reliable way to test a route is to run the real app on a real (ephemeral) port and hit it with a real fetch call. Nothing is mocked — matching, middleware, providers, validation and the handler all run exactly as they would in production.

The basic shape

import { expect, test } from 'bun:test'
import { Arcton } from '@arcton/core'

test('GET /health returns ok', async () => {
  const app = Arcton()
  app.get('/health', () => ({ status: 'ok' }))

  const server = app.listen({ port: 0 })

  const res = await fetch(new URL('/health', server.url))
  expect(await res.json()).toEqual({ status: 'ok' })

  server.stop()
})

port: 0 asks the runtime for a free port instead of a fixed one, so tests can run concurrently without colliding. server.url is a real URL — pass it straight to fetch, or resolve a path against it with new URL(path, server.url). Always call server.stop() once the test is done so the port is released.

Testing a 404

A path with no matching route responds 404 with a { code: 'NOT_FOUND', message: 'Not Found' } JSON body (see HTTP errors) — worth asserting directly:

import { expect, test } from 'bun:test'
import { Arcton } from '@arcton/core'

test('an unmatched path responds 404', async () => {
  const app = Arcton()
  app.get('/health', () => ({ status: 'ok' }))

  const server = app.listen({ port: 0 })

  const res = await fetch(new URL('/missing', server.url))
  expect(res.status).toBe(404)

  server.stop()
})

Testing validation

A route with a body, query or params schema responds 400 with a JSON { issues: [...] } body on the first validation failure. This example uses Valibot:

import { expect, test } from 'bun:test'
import { Arcton } from '@arcton/core'
import * as v from 'valibot'

test('an invalid body responds 400 with issues', async () => {
  const app = Arcton()
  app.post('/orders', {
    body: v.object({ item: v.string(), quantity: v.number() }),
    handler: ctx => ctx.body
  })

  const server = app.listen({ port: 0 })

  const res = await fetch(new URL('/orders', server.url), {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ item: 'widget' })
  })

  expect(res.status).toBe(400)
  const body = (await res.json()) as { issues: { message: string }[] }
  expect(Array.isArray(body.issues)).toBe(true)

  server.stop()
})

Testing a WebSocket route

The same app.listen({ port: 0 }) server also serves registered WebSocket routes. Open a WebSocket against server.url with the protocol swapped to ws::

import { expect, test } from 'bun:test'
import { Arcton } from '@arcton/core'

test('a ws route echoes messages', async () => {
  const app = Arcton()
  app.ws('/chat', {
    message(ws, message) {
      ws.send(`echo: ${message}`)
    }
  })

  const server = app.listen({ port: 0 })

  const wsUrl = new URL('/chat', server.url)
  wsUrl.protocol = 'ws:'
  const ws = new WebSocket(wsUrl)

  await new Promise<void>(resolve => {
    ws.addEventListener('open', () => resolve())
  })

  const reply = new Promise<string>(resolve => {
    ws.addEventListener('message', event => resolve(event.data as string))
  })
  ws.send('hi')
  expect(await reply).toBe('echo: hi')

  ws.close()
  server.stop()
})

For unit-testing a piece of middleware on its own, without running a server at all, see Testing middleware.

On this page