Override any plugin, decorator or hook in your Fastify application. This is useful for mocking specific functionalities when testing your application. For the motivation of this plugin see here.
Note: You should use this plugin only for testing purposes.
npm install fastify-override --save-dev| Plugin Version | Fastify Version | Node Versions |
|---|---|---|
| 1.x | 4.x | 18, 20, 21 |
This plugin allows you to override specific plugins, decorators and hooks within the plugin hierarchy. This can happen from any level within the hierarchy, and you can also register this plugin multiple times. But as soon as the plugin is to be used, the register call must be awaited so that all subsequently added plugins, decorators and hooks are considered.
Note: Only plugins that are not registered as promise are supported.
app.register(import('...'))would result in incorrect behaviour. If this occurs, the plugin will log a message accordingly.
app.decorate('foo', 'bar')
await app.register(fastifyOverride, {
override: {
decorators: {
decorate: {
foo: 'overridden',
num: 42
}
}
}
})
app.decorate('num', 1)
app.foo // === 'bar'
app.num // === 42As you can see above, only the decorators (and of course plugins and hooks) that were added after the plugin was registered are actually taken into account. There are some differences in the way the plugins, decorators and hooks are overridden. We will therefore briefly look at these 3 separately.
Only plugins that have been assigned a name with fastify-plugin can be overridden. This name can then be used to
specify which plugin should be used to override it.
const plg = fp(async app => {}, {
name: 'myPlugin' // <-- Therefore, this must match with...
})
await app.register(fastifyOverride, {
override: {
plugins: {
myPlugin: fp(async () => {}) // ...this name
}
}
})Keep in mind that the encapsulation behavior of the plugin can also be changed by using or not using fastify-plugin.
Decorators are identified by their name and type. Therefore, the plugin with the following options
{
override: {
decorators: {
decorateReply: {
num: 1
}
}
}
}would override app.decorateReply('num', 2) but not app.decorateRequest('num', 3).
For each hook type, you can provide one function. This function then
overrides all hooks of this type. This can of course lead to different hook functions being overridden with the same function.
Please note that only hooks that have been added via the addHook API are being checked.
await app.register(fastifyOverride, {
override: {
hooks: {
onRequest: async () => {},
onSend: async () => {}
}
}
})The following options are available.
import Fastify from 'fastify'
const app = Fastify()
await app.register(import('fastify-override'), {
override: {
plugins: {},
decorators: {
decorate: {},
decorateRequest: {},
decorateReply: {}
},
hooks: {}
}
})Use the override object to specify which decorators, which plugins and which hooks are to be overwritten.
import Fastify from 'fastify'
const app = Fastify()
await app.register(import('fastify-override'), {
override: {
plugins: {
'@fastifyPostgres': async app => {}
},
decorators: {
decorate: {
db: {
query: async () => {}
}
}
},
hooks: {
onRequest: async (req, reply) => {}
}
}
})Let's assume our Fastify application has the following structure:
│
├── routes
│ ├── users/
│ ├── articles/
│ ├── ...
│ ...
│
├── plugins
│ ├── postgres
│ ├── auth
│ ├── ...
│ ...
│
├── test
│ ├── users-routes.test.js
│ ├── ...
│ ...
│
└── server.js
In most cases, our server.js file will look like this:
import fastifyAutoload from '@fastify/autoload'
import { fileURLToPath } from 'url'
import { dirname, join } from 'path'
const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)
export default async function (app, opts) {
app.register(fastifyAutoload, {
dir: join(__dirname, 'plugins'),
encapsulate: false
})
app.register(fastifyAutoload, {
dir: join(__dirname, 'routes'),
encapsulate: true
})
}We would now like to test the routes within the routes/users folder. Let's do this in the
users-routes.test.js file with the tap testing library.
import t from 'tap'
import Fastify from 'fastify'
import application from '../server.js'
t.test('test users routes', async t => {
const app = Fastify()
app.register(application)
// app.pg is undefined
// so we cannot mock like this
// app.pg.query = () => 'mocked value'
})Because a new context is created by the register call, we have no access to all functionalities that are added by the
plugins in the plugin folder. For example, we couldn't mock the Postgres plugin now simply because we don't have access
to the decorated pg value that the plugin actually decorates the Fastify instance with. You could of course argue that
by using fastify-plugin we could prevent the creation of a new context. That would work in this example, but what if
we want to mock a plugin, decorator or hook that is deeper in the plugin hierarchy?
This is exactly where fastify-override comes to the rescue. fastify-override makes it possible to override plugins,
decorators and hooks in the entire plugin hierarchy.
Let's look at a code example:
import t from 'tap'
import Fastify from 'fastify'
import application from '../server.js'
t.test('test users routes', async t => {
const app = Fastify()
await app.register(fastifyOverride, {
override: {
plugins: {
// We can mock a whole plugin...
'@fastify/postgres': fp(async app => {
app.decorate('pg', {
query: () => 'mocked value',
})
})
},
decorators: {
decorate: {
// ...or just specific decorators
pg: {
query: () => 'mocked value'
}
}
}
}
})
app.register(application)
await app.ready()
app.pg.query() // returns 'mocked value'
})As we can see, this plugin allows us to overwrite entire plugins or just specific decorators. Thereby it does not matter how deep in the plugin hierarchy the plugin and/or the decorators are registered.
Licensed under MIT.