fix(test): auto-inline packages that use expect.extend() to fix module instance splitting (#1113)

## Summary

Fixes `expect.extend()` matchers from third-party packages (e.g.,
`@testing-library/jest-dom`) not being registered on the test runner's
`expect` instance, causing errors like `Invalid Chai property:
toBeInTheDocument`.

resolve #897

## Root Cause

When third-party packages call
`require('vitest').expect.extend(matchers)` internally, the npm override
(`vitest` → `@voidzero-dev/vite-plus-test`) causes Node.js to load a
**separate module instance** with its own `chai` and `expect`.

Matchers are registered on this separate instance, not on the test
runner's `expect`.

The root issue is the **externalization behavior** of vitest's module
runner. By default, third-party packages in `node_modules` are
externalized — loaded via Node.js native `require`/`import`.

When an externalized package calls `require('vitest')`, Node.js resolves
it through the npm override, producing a different module instance with
a separate `chai`.

## Fix

Patch vitest's `ModuleRunnerTransform` plugin during re-packaging
(`build.ts`) to automatically add known affected packages to
`server.deps.inline` in the `configResolved` hook.

This forces the Vite module runner to process these packages through its
transform pipeline instead of externalizing them to Node.js.

### Normal flow (plain vitest — no npm override)

```mermaid
sequenceDiagram
    participant Runner as Test Runner
    participant JestDOM as @testing-library/jest-dom
    participant NodeJS as Node.js require()
    participant Vitest as vitest module

    Runner->>Vitest: import vitest (cached by Node.js)
    Runner->>Runner: createExpect() → globalExpect

    Note over JestDOM: setupFiles execution
    JestDOM->>NodeJS: require('vitest')
    NodeJS-->>JestDOM: Same vitest module (cached)
    JestDOM->>Vitest: expect.extend(matchers)
    Note over Vitest: OK: Matchers registered on<br/>the same chai instance

    Runner->>Runner: expect(el).toBeInTheDocument() OK:
```

### Bug flow (vite-plus — npm override splits module instances)

```mermaid
sequenceDiagram
    participant Runner as Test Runner
    participant JestDOM as @testing-library/jest-dom
    participant NodeJS as Node.js require()
    participant VitestA as vitest (runner instance)
    participant VitestB as @voidzero-dev/vite-plus-test<br/>(override instance)

    Runner->>VitestA: import vitest
    Runner->>Runner: createExpect() with chai-A

    Note over JestDOM: setupFiles execution (externalized by default)
    JestDOM->>NodeJS: require('vitest')
    NodeJS->>NodeJS: npm override rewrites to<br/>@voidzero-dev/vite-plus-test
    NodeJS-->>JestDOM: Different module instance
    JestDOM->>VitestB: expect.extend(matchers)
    Note over VitestB: Matchers registered on chai-B

    Runner->>Runner: expect(el).toBeInTheDocument()
    Note over Runner: NG: chai-A has no matchers<br/>Invalid Chai property
```

### Fix flow (with `server.deps.inline` patch)

```mermaid
sequenceDiagram
    participant Runner as Test Runner
    participant JestDOM as @testing-library/jest-dom
    participant ModRunner as Vite Module Runner
    participant Resolve as vitest:resolve-core
    participant Vitest as vitest (single instance)

    Runner->>Vitest: import vitest (cached)
    Runner->>Runner: createExpect() with chai

    Note over JestDOM: setupFiles execution (inlined by patch)
    JestDOM->>ModRunner: require('vitest')
    ModRunner->>ModRunner: Transform to __vite_ssr_import__
    ModRunner->>Resolve: resolve 'vitest'
    Resolve-->>ModRunner: dist/index.js (same file)
    ModRunner-->>JestDOM: Same module instance (cached)
    JestDOM->>Vitest: expect.extend(matchers)
    Note over Vitest: OK: Matchers registered on<br/>the same chai instance

    Runner->>Runner: expect(el).toBeInTheDocument() OK:
```

### Auto-inlined packages

-
[testing-library/jest-dom](https://github.com/testing-library/jest-dom):
17.7M/weekly download, Calls `require('vitest').expect.extend(matchers)`
via `./vitest` subpath
- [storybookjs/storybook](https://github.com/storybookjs/storybook):
2M/weekly download, Uses `@vitest/expect` internally with
`expect.extend()`
-
[jest-community/jest-extended](https://github.com/jest-community/jest-extended):
958K/weekly download, Calls `expect.extend()` on import

These three packages cover **99.5%** of weekly downloads among all
affected packages.

The list was determined by downloading npm tarballs of all known
`expect.extend` using packages and inspecting their source code.

Author: kazupon

.github/workflows/e2e-test.yml

@@ -285,6 +285,10 @@ jobs:
               vp run lint
               vp run test:types
               vp test --project unit
+          - name: vite-plus-jest-dom-repro
+            node-version: 24
+            command: |
+              vp test run
         exclude:
           # frm-stack uses Docker (testcontainers) which doesn't work the same way on Windows
           - os: windows-latest

ecosystem-ci/repo.json

@@ -91,5 +91,11 @@
     "branch": "main",
     "hash": "230b7c7ddb6bb8551ce797144f0ce0f047ff8d7d",
     "forceFreshMigration": true
+  },
+  "vite-plus-jest-dom-repro": {
+    "repository": "https://github.com/why-reproductions-are-required/vite-plus-jest-dom-repro.git",
+    "branch": "master",
+    "hash": "01bd9ce1ac66ee3c21ed8a7f14311317d87fb999",
+    "forceFreshMigration": true
   }
 }

packages/test/__tests__/build-artifacts.spec.ts

@@ -3,9 +3,8 @@
  * contains the expected files and that patches applied during the build
  * (in build.ts) produce correct artifacts.
  *
- * This is important because vite-plus re-packages vitest with custom
- * patches, and missing exports or incorrect patches can break
- * third-party integrations (e.g., @storybook/addon-vitest, #1086).
+ * These tests run against the already-built dist/ directory, ensuring
+ * that re-packaging patches produce correct artifacts.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -16,6 +15,16 @@ import { describe, expect, it } from 'vitest';
 const testPkgDir = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), '..');
 const distDir = path.join(testPkgDir, 'dist');
 
+function findCliApiChunk(): string {
+  const chunksDir = path.join(distDir, 'chunks');
+  const files = fs.readdirSync(chunksDir);
+  const chunk = files.find((f) => f.startsWith('cli-api.') && f.endsWith('.js'));
+  if (!chunk) {
+    throw new Error('cli-api chunk not found in dist/chunks/');
+  }
+  return path.join(chunksDir, chunk);
+}
+
 describe('build artifacts', () => {
   describe('@vitest/browser/context.js', () => {
     const contextPath = path.join(distDir, '@vitest/browser/context.js');
@@ -55,4 +64,31 @@ describe('build artifacts', () => {
       expect(vendorMapContent).not.toContain("'@vitest/browser/context'");
     });
   });
+
+  /**
+   * Third-party packages that call `expect.extend()` internally
+   * (e.g., @testing-library/jest-dom) break under npm override because
+   * the vitest module instance is split, causing matchers to be registered
+   * on a different `chai` instance than the test runner uses.
+   *
+   * The build patches vitest's ModuleRunnerTransform plugin to auto-add
+   * these packages to `server.deps.inline`, so they are processed through
+   * Vite's transform pipeline and share the same module instance.
+   *
+   * See: https://github.com/voidzero-dev/vite-plus/issues/897
+   */
+  describe('server.deps.inline auto-inline (regression test for #897)', () => {
+    it('should contain the expected auto-inline packages', () => {
+      const content = fs.readFileSync(findCliApiChunk(), 'utf-8');
+      expect(content).toContain('Auto-inline packages');
+      expect(content).toContain('"@testing-library/jest-dom"');
+      expect(content).toContain('"@storybook/test"');
+      expect(content).toContain('"jest-extended"');
+    });
+
+    it('should not override user inline config when set to true', () => {
+      const content = fs.readFileSync(findCliApiChunk(), 'utf-8');
+      expect(content).toContain('server.deps.inline !== true');
+    });
+  });
 });

packages/test/build.ts

@@ -224,6 +224,7 @@ await createBrowserEntryFiles();
 await patchModuleAugmentations();
 await patchChaiTypeReference();
 await patchMockerHoistedModule();
+await patchServerDepsInline();
 const pluginExports = await createPluginExports();
 await mergePackageJson(pluginExports);
 generateLicenseFile({
@@ -2360,6 +2361,83 @@ async function patchMockerHoistedModule() {
   }
 }
 
+/**
+ * Patch vitest's ModuleRunnerTransform plugin to automatically add known
+ * packages that use `expect.extend()` internally to `server.deps.inline`.
+ *
+ * When third-party libraries (e.g., @testing-library/jest-dom) call
+ * `require('vitest').expect.extend(matchers)`, the npm override causes
+ * a separate module instance to be created, so matchers are registered
+ * on a different `chai` instance than the one used by the test runner.
+ *
+ * By inlining these packages via `server.deps.inline`, the Vite module
+ * runner processes them through its transform pipeline, ensuring they
+ * share the same module instance as the test runner.
+ *
+ * See: https://github.com/voidzero-dev/vite-plus/issues/897
+ */
+async function patchServerDepsInline() {
+  console.log('\nPatching server.deps.inline for expect.extend compatibility...');
+
+  let cliApiChunk: string | undefined;
+  for await (const chunk of fsGlob(join(distDir, 'chunks/cli-api.*.js'))) {
+    cliApiChunk = chunk;
+    break;
+  }
+
+  if (!cliApiChunk) {
+    throw new Error('cli-api chunk not found for patchServerDepsInline');
+  }
+
+  let content = await readFile(cliApiChunk, 'utf-8');
+
+  // Packages that internally call expect.extend() and break under npm override.
+  // These must be inlined so they share the same vitest module instance.
+  const inlinePackages = ['@testing-library/jest-dom', '@storybook/test', 'jest-extended'];
+
+  // Find the configResolved handler in ModuleRunnerTransform (vitest:environments-module-runner)
+  // and inject our inline packages after the existing server.deps.inline logic.
+  const original = `if (external.length) {
+          testConfig.server.deps.external ??= [];
+          testConfig.server.deps.external.push(...external);
+        }`;
+
+  const patched = `if (external.length) {
+          testConfig.server.deps.external ??= [];
+          testConfig.server.deps.external.push(...external);
+        }
+        // Auto-inline packages that use expect.extend() internally (#897)
+        // Only inline packages that are actually installed in the project.
+        if (testConfig.server.deps.inline !== true) {
+          testConfig.server.deps.inline ??= [];
+          if (Array.isArray(testConfig.server.deps.inline)) {
+            const _require = createRequire(config.root + "/package.json");
+            const autoInline = ${JSON.stringify(inlinePackages)};
+            for (const pkg of autoInline) {
+              if (testConfig.server.deps.inline.includes(pkg)) continue;
+              try {
+                _require.resolve(pkg);
+                testConfig.server.deps.inline.push(pkg);
+              } catch {
+                // Package not installed in the project — skip silently
+              }
+            }
+          }
+        }`;
+
+  if (!content.includes(original)) {
+    throw new Error(
+      'Could not find server.deps.external pattern in ' +
+        cliApiChunk +
+        '. This likely means vitest code has changed and the patch needs to be updated.',
+    );
+  }
+
+  content = content.replace(original, patched);
+  await writeFile(cliApiChunk, content, 'utf-8');
+  console.log(`  Added auto-inline for: ${inlinePackages.join(', ')}`);
+}
+
 /**
  * Create /plugins/* exports for all copied @vitest/* packages.
  * This allows pnpm overrides to redirect @vitest/* imports to our copied versions.