Vitest mocking isn't working using tsx (esm target)

[OlivierCuyp]

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

5.6.0

Plugin version

6.3.1

Node.js version

24.7.0

Operating system

macOS

Operating system version (i.e. 20.04, 11.3, 10)

15.6.1

Description

Testing my app using fastify & autoload I just can't mock anything.
It is always the original code that is called.

Here is the concerned piece of code.

src/helpers/testHelper.ts

const run = () => {
  return 'REAL';
};

export const testMock = { run };

src/routes/test/testHanlder.ts

import type { FastifyInstance } from 'fastify';

import { testMock } from '@/helpers/testHelper.ts';

export default async (app: FastifyInstance) => {
  app.get('', async (_request, reply) => {
    const result = testMock.run();
    reply.send({ result });
  });
};

test/server.ts

import { describe, expect, it, vi } from 'vitest';
import { testMock } from '@/helpers/testHelper.ts';

import { createApp } from '../src/server.ts';

describe('server api', () => {
  it('should mock', async () => {
    vi.spyOn(testMock, 'run').mockImplementation(() => {
      return 'MOCK';
    });

    const res = await createApp().inject({
      method: 'GET',
      url: '/test'
    });

    expect(res.statusCode).toEqual(200);
    expect(res.json()).toEqual({
      result: 'MOCK'
    });
  });
});

Test

FAIL  test/server.ts > server api > should mock
AssertionError: expected { result: 'REAL' } to deeply equal { result: 'MOCK' }

- Expected
+ Received

  {
-   "result": "MOCK",
+   "result": "REAL",
  }

 ❯ test/server.ts:27:24
     25| 
     26|     expect(res.statusCode).toEqual(200);
     27|     expect(res.json()).toEqual({
       |                        ^
     28|       result: 'MOCK'
     29|     });

See MRE

Link to code that reproduces the bug

https://github.com/OlivierCuyp/fastify-autoload-vitest-esm-mock

Expected Behavior

Mock should be applied and test should pass.

[OlivierCuyp]

@climba03003 as you ask for in the old issue, I created this new issue.
Let me know if you need anything more.

[Uzlopak]

When you do encapsulate: false then you get further. But unfortunately, I cant use vscode debugger with your reproduction, so I cant investigate further.

[OlivierCuyp]

@Uzlopak sorry for the inconvenience there was a useless env NODE_OPTIONS='--import tsx' on the test script.
Typescript was transpiled twice since vitest also transpile with esbuild.
I removed it so you can use the vscode debugger now.

[Uzlopak]

@OlivierCuyp

Seems like importing results in new instances and not returning cached values.

[OlivierCuyp]

@Uzlopak thanks for the heads-up, on my side I tried many configurations/settings, nothing really works.
Does this means, there is no way to use vitest mocking with autoload ?

[OlivierCuyp]

I made a quick and naive implementation to see if the issue was coming from the dynamic import somehow.
But if I replace the autoload call with the call of the following function the mock works and the test succeed:

import { join, sep } from 'node:path';
import fg from 'fast-glob';

const __dirname = import.meta.dirname;

const autoImportRoutes = async (app: FastifyInstance, routeFolder: string) => {
  const routesPaths = await fg(`${routeFolder}${sep}**${sep}*.ts`);

  for (const routesPath of routesPaths) {
    const routePrefixMatch = routesPath.match(
      new RegExp(`^${routeFolder}${sep}(.*)${sep}[^${sep}]+\.ts$`)
    );
    const routePrefix = routePrefixMatch?.[1];

    const route = await import(routesPath);

    app.register(route, { prefix: routePrefix });
  }
};

export const createApp = async () => {
  const app = fastify();

  await autoImportRoutes(app, join(__dirname, 'routes'));

  await app.ready();

  return app;
};

[Uzlopak]

I think it has to do with the encapsulation logic of autoload.

[OlivierCuyp]

Just for other people who might face the same issue and need a temporary solution.
I builded a quick plugin replacement while waiting for this issue to be fixed:

import { sep } from 'node:path';

import fg from 'fast-glob';
import type { FastifyPluginAsync, FastifyPluginOptions } from 'fastify';
import fp from 'fastify-plugin';

type AutorouteOption = FastifyPluginOptions & {
  dir: string;
  encapsulate?: boolean;
  routeParams?: boolean;
};

// This is a replacement fastify-autoload for autoroute because of this issue: https://github.com/fastify/fastify-autoload/issues/475
// TODO: Remove this once the issue is fixed
export const autoroute: FastifyPluginAsync<AutorouteOption> = async (
  app,
  options: AutorouteOption
) => {
  if (!options.dir) {
    throw new Error('dir is required');
  }
  const { dir, routeParams = false, encapsulate = true } = options;
  const routesPaths = await fg(`${dir}${sep}**${sep}*.ts`);

  const routes = await Promise.all(
    routesPaths.map(async (routesPath) => {
      const routePrefixMatch = routesPath.match(
        new RegExp(`^${dir}${sep}(.*)${sep}[^${sep}]+\.(?:ts|js|mjs)$`)
      );
      let routePrefix = `/${routePrefixMatch?.[1] ?? ''}`;

      if (routeParams) {
        routePrefix = routePrefix.replace(/__(\w+)/g, ':$1').replace(/\/_([^/]+)$/g, '/:$1');
      }

      return [routePrefix, await import(routesPath)] as const;
    })
  );

  for (const [prefix, routeModule] of routes) {
    const routeFunction = routeModule.default ?? routeModule;

    app.register(routeFunction, { prefix, encapsulate });
  }
};

export default fp(autoroute, {
  name: 'autoroute',
  encapsulate: false
});

This hasn't been widely tested and work for my setup so no warranty it will work for yours.

[francisdaigle]

If you have a flat routes directory (no nested folders), here's a minimal solution that works with Vitest 4 + Istanbul coverage:

async function loadRoutes(fastify: FastifyInstance, routesDir: string) {
  const files = fs
    .readdirSync(routesDir)
    .filter((f) => f.endsWith(".ts") && !f.startsWith("README"));

  for (const file of files) {
    const route = await import(path.join(routesDir, file));

    await fastify.register(route.default);
  }
}

Use it in your test helper instead of AutoLoad for routes:

// Keep AutoLoad for plugins (works fine)
await fastify.register(AutoLoad, {
  dir: path.join(__dirname, "..", "src", "plugins"),
  forceESM: true,
});

// Use loadRoutes for routes to fix Istanbul coverage
await loadRoutes(fastify, path.join(__dirname, "..", "src", "routes"));

This bypasses whatever in AutoLoad's encapsulation logic prevents Istanbul from tracking the imports. Production code stays unchanged - only the test helper needs this.