Global `vi.mock()` inside root `setupFiles` is not executed for workspace library imports in Nx + pnpm monorepo

[jasonhuang-dev]

Describe the bug

Environment

• Vitest version: v3.x
• pnpm: 9.x
• Node: 22
• Workspace tool: Nx monorepo (21+)
• Package layout: pnpm workspaces
• Test runner invoked via Nx or pnpm command
• Root-level vitest.config.ts defining global setupFiles

Note:
Previously these shared libraries were consumed using TypeScript path aliases, and the same global mock pattern worked correctly. After migrating to pnpm workspaces ("name": "@shared/ui" etc.), the issue appeared.

Problem summary

In a large Nx + pnpm workspace monorepo, I have a shared testing utility library with a global setup file:

libs/shared/testing/src/setupTests.tsx

It contains a global mock for a module from another workspace package:

import { ComponentType } from 'react';

const withI18n = (Component: ComponentType<any>) => {
  // custom HOC logic...
};

vi.mock('@shared/ui/src/i18n-context', async () => {
  console.log('[setupTests] vi.mock callback executed');
  const actual = await vi.importActual('@shared/ui/src/i18n-context');
  return { ...actual, withI18n };
});

Root-level config:

export default defineConfig({
  test: {
    ...
    globals: true,
    setupFiles: [
      path.resolve(__dirname, './libs/shared/testing/src/setupTests.tsx'),
    ],
  },
});

Expected behavior

• The setup file should run.
• The vi.mock() callback should be executed.
• All imports of @shared/ui/src/i18n-context should use the mocked implementation.

This previously worked when resolving these modules through TypeScript path aliases.

Actual behavior

After switching these libraries to pnpm workspace packages:

• The setup file runs (verified with logs).
• The vi.mock callback never executes.
• The debug console.log inside the callback never appears.
• Tests load the unmocked implementation.
• Tests depending on the mocked withI18n fail.

So the issue is not simply “mock not applied” — the mock factory function is never invoked at all.

Monorepo structure

libs/
  shared/
    testing/
      src/setupTests.tsx
    ui/
      src/i18n-context.tsx

Both @shared/ui and @shared/testing are pnpm workspace packages with a package.json containing their "name" fields.
User code imports:

import { withI18n } from '@shared/ui/src/i18n-context';

With TypeScript path aliases → mock applied correctly.
With pnpm workspace packages → mock callback not executed.

Why this appears to be a Vitest issue

• The setup file executes normally.
• The vi.mock() statement is registered.
• The callback never executes.
  The module specifier matches exactly.

The only difference between working and not working setups is the switch from TS path aliases → pnpm workspace packages.

Reproduction

I can provide a minimal public repo demonstrating:

• Nx + pnpm workspace
• libs/shared/ui
• libs/shared/testing containing setupTests.tsx
• Root vitest.config.ts
• A test showing:
  • The setup file runs
  • The vi.mock callback does not run
  • The workspace module is not mocked

System Info

irrelevant

Used Package Manager

pnpm

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion or join our Discord Chat Server.
• The provided reproduction is a minimal reproducible example of the bug.

[sheremet-va]

I can provide a minimal public repo demonstrating:

Please do.

[github-actions]

Hello @jasonhuang-dev. Please provide a minimal reproduction using a GitHub repository or StackBlitz (you can also use examples). Issues marked with needs reproduction will be closed if they have no activity within 3 days.

[jasonhuang-dev]

I can provide a minimal public repo demonstrating:

Please do.

Thank you for replying, here is the minimal public repo https://github.com/jasonhuang-dev/vitest-pnpm-workspace

[hi-ogawa]

I think this is mostly an expected behavior. From the project root, package-a is not dependency so package-a/utils/helper doesn't resolve properly. You can add "package-a": "workspace:*" to the root package.json and the mock will work properly. https://stackblitz.com/edit/github-dwxavfya?file=package.json

Alternatively, you could move vitest.setup.js inside packages/package-b and that should also expected to work.

[hi-ogawa]

The question is whether when vi.mock('invalid-thing', ...) should show warnings or not. Maybe this is still valid mocking to support mocking non-resolvable 'invalid-thing' library only on Vitest.

[jasonhuang-dev]

The question is whether when vi.mock('invalid-thing', ...) should show warnings or not. Maybe this is still valid mocking to support mocking non-resolvable 'invalid-thing' library only on Vitest.

Hi @hi-ogawa thank you very much for your answer. I think even if Vitest cannot support this kind of non-resolvable mocks, at least showing some warnings is very useful, because I have observed that Jest can support this scenario. People might encounter this problem when migrating from Jest to Vitest and not clearly understand the reason.

[sheremet-va]

Vitest supports vi.mock('invalid-mock') because there are use cases where you are importing from something which is not actually a package. For example, mocking a vscode import. Vitest doesn't know if invalid-mock is invalid. Jest, on the other hand, requires a virtual: true option when mocking a module that doesn't exist.

[hi-ogawa]

Ah, didn't know jest has { virtual: true }. Can we add similar flags to vi.mock to explicitly mock non-resolvable mock and show warning if flags are not provided?

[hi-ogawa]

@jasonhuang-dev Btw, Vitest allow syntax sugar of vi.mock(import("some-package"), ...) to let typescript infer mocked module types and also highlight resolution errors.

[sheremet-va]

Ah, didn't know jest has { virtual: true }. Can we add similar flags to vi.mock to explicitly mock non-resolvable mock and show warning if flags are not provided?

There is another inconsistency issue. In jsdom if the module in import is not resolved, Vite will throw an error during import analysis, so introducing this flag would be meaningless, unless the user also defined a virtual module: https://vitest.dev/guide/mocking/modules.html#mocking-non-existing-module