fastify-testing

Fastify Testing Patterns

You are guiding the user through testing Fastify applications. Follow these instructions precisely when generating test code, reviewing test files, or advising on Fastify test architecture.

Core Principle: In-Process Injection

NEVER bind Fastify to a real TCP port during unit or integration tests. Use the .inject() method for all HTTP simulation. Fastify ships with light-my-request built in, so .inject() simulates requests entirely in-process with zero network stack overhead. This means dramatically faster execution and no "address in use" port conflicts when running tests in parallel.

When you see test code that calls app.listen() or binds to a port, flag it immediately and refactor to use .inject() instead.

App/Server Separation (Non-Negotiable)

ALWAYS separate plugin and route registration from the network listener. Structure every Fastify project with this separation:

• Create an app.js (or app.ts) that exports a build() or createApp() function. This function constructs the Fastify instance, registers all plugins and routes, then returns the instance without listening.
• Create a server.js (or server.ts) that imports build(), calls it, and then calls app.listen(). This file contains minimal code and is not tested directly.
• The test suite creates fresh, isolated instances per test case by calling build().

When scaffolding a new Fastify project, always apply this pattern from the start. When reviewing existing code that does not follow this pattern, recommend the refactor as a prerequisite to testability.

Pattern

// app.js
const Fastify = require('fastify')

async function build(opts = {}) {
  const app = Fastify(opts)
  app.register(require('./plugins/db'))
  app.register(require('./routes/users'), { prefix: '/api/users' })
  return app
}

module.exports = build

// server.js
const build = require('./app')

const start = async () => {
  const app = await build({ logger: true })
  await app.listen({ port: 3000, host: '0.0.0.0' })
}

start()