fix(migrate): preserve Vitest config and assertion semantics

Author: fengmk2

packages/cli/src/migration/__tests__/vitest-v5.spec.ts

@@ -203,6 +203,98 @@ export default defineConfig({ test: { projects: [
     expect(config(input, false).content).toBe(input);
   });
 
+  it.each([
+    `export default mergeConfig(
+      defineConfig({ test: { clearMocks: true } }),
+      defineConfig({ test: { environment: 'jsdom' } }),
+    );`,
+    `const base = defineConfig({ test: { clearMocks: true } });
+const overrides = defineConfig({ test: { environment: 'jsdom' } });
+export default mergeConfig(base, overrides);`,
+    `export default defineConfig(mergeConfig(
+      { test: { clearMocks: true } },
+      defineProject({ test: { environment: 'jsdom' } }),
+    ));`,
+  ])('does not insert defaults into merged config fragments: %s', (body) => {
+    const input = `import { defineConfig, defineProject, mergeConfig } from 'vitest/config';\n${body}`;
+    const result = config(input);
+    expect(result.content).toBe(input);
+    expect(result.findings).toContainEqual(
+      expect.objectContaining({ code: 'merged-config-defaults', severity: 'review' }),
+    );
+  });
+
+  it('leaves defaults in imported merge fragments for review across migration runs', () => {
+    const base = `import { defineConfig } from 'vitest/config';
+export default defineConfig({ test: { clearMocks: true, browser: { locators: { exact: true } } } });`;
+    const overrides = `import { defineConfig } from 'vitest/config';
+export default defineConfig({ test: { browser: { enabled: true } } });`;
+    const root = project({
+      'vitest.config.ts': `import { mergeConfig } from 'vitest/config';
+import base from './base';
+import overrides from './overrides';
+export default mergeConfig(base, overrides);`,
+      'base.ts': base,
+      'overrides.ts': overrides,
+    });
+    const plan = planProject(root);
+    expect(plan.changes).toEqual([]);
+    expect(plan.findings).toContainEqual(
+      expect.objectContaining({
+        file: path.join(root, 'overrides.ts'),
+        code: 'merged-config-defaults',
+      }),
+    );
+    applyVitestV5Migration(plan);
+    const findings = finishVitestV5Migration(plan);
+    expect(fs.readFileSync(path.join(root, 'base.ts'), 'utf8')).toBe(base);
+    expect(fs.readFileSync(path.join(root, 'overrides.ts'), 'utf8')).toBe(overrides);
+    expect(findings.some(({ code }) => code === 'merged-config-defaults')).toBe(true);
+    expect(planProject(root).changes).toEqual([]);
+  });
+
+  it.each(['true', 'false'])(
+    'preserves inherited locators.exact: %s without a child override',
+    (exact) => {
+      const result = config(`export default { test: {
+  browser: { enabled: true, locators: { exact: ${exact} } },
+  projects: [{ extends: true, test: { browser: { enabled: true } } }],
+} };`);
+      expect(result.content.match(/locators:/g)).toHaveLength(1);
+      expect(result.content).toContain(`locators: { exact: ${exact} }`);
+      expect(result.findings).toEqual([]);
+      expect(config(result.content).content).toBe(result.content);
+    },
+  );
+
+  it('adds locator defaults to an inheriting child when its parent has no browser options', () => {
+    const result = config(`export default { test: {
+  projects: [{ extends: true, test: { browser: { enabled: true } } }],
+} };`);
+    expect(result.content).toContain('locators: { exact: false }');
+    expect(result.findings).toEqual([]);
+  });
+
+  it('adds the locator default only to the parent browser config', () => {
+    const result = config(`export default { test: {
+  browser: { enabled: true },
+  projects: [{ extends: true, test: { browser: { enabled: true } } }],
+} };`);
+    expect(result.content.match(/locators:/g)).toHaveLength(1);
+    expect(result.content).toContain('locators: { exact: false }');
+  });
+
+  it('does not override dynamic inherited browser settings', () => {
+    const result = config(`export default { test: {
+  browser: sharedBrowser,
+  projects: [{ extends: true, test: { browser: { enabled: true } } }],
+} };`);
+    expect(result.content).not.toContain('exact: false');
+    expect(result.findings).toContainEqual(
+      expect.objectContaining({ code: 'dynamic-project', severity: 'review' }),
+    );
+  });
+
   it('does not guess dynamic projects or spread options', () => {
     const result = config(`export default { test: { ...shared, projects: [() => project] } };`);
     expect(result.content).not.toContain('clearMocks');
@@ -403,6 +495,28 @@ test('x', () => assert(() => {}).toThrow(''));`;
     expect(result.content).toContain('toThrow(/^$/)');
   });
 
+  it.each(['@vitest/expect', 'vite-plus/test/plugins/expect'])(
+    'migrates assertions from %s in the same pass as their imports',
+    (specifier) => {
+      const result = source(`import { expect as check } from '${specifier}';
+import { test } from 'vitest';
+function helper(check) { check(() => {}).toThrow(''); }
+test('works', () => {
+  check(() => { throw new Error('boom'); }).not.toThrow('');
+  check(Promise.resolve(1)).resolves.toBe(1);
+  check.element(el).toHaveTextContent('partial');
+});`);
+      expect(result.content).toContain("import { expect as check } from 'vite-plus/test'");
+      expect(result.content).toContain("function helper(check) { check(() => {}).toThrow(''); }");
+      expect(result.content).toContain('.not.toThrow(/^$/)');
+      expect(result.content).toContain("test('works', async () =>");
+      expect(result.content).toContain('await check(Promise.resolve(1)).resolves.toBe(1)');
+      expect(result.content).toContain("await check.element(el).toMatchTextContent('partial')");
+      expect(result.findings).toEqual([]);
+      expect(source(result.content).content).toBe(result.content);
+    },
+  );
+
   it('only makes async-compatible callbacks async', () => {
     const result = source(`import { test, describe, expect } from 'vitest';
 import { render as mount } from 'vitest-browser-vue';

packages/cli/src/migration/migrator/vitest-v5.ts

@@ -13,6 +13,7 @@ import { type SourceOptions, type VitestV5Finding } from '../vitest-v5/ast.ts';
 import { migrateVitestV5Command } from '../vitest-v5/commands.ts';
 import {
   findVitestV5ConfigFiles,
+  findVitestV5MergedConfigFiles,
   migrateVitestV5Config,
   resolveVitestV5BrowserModes,
 } from '../vitest-v5/config.ts';
@@ -468,6 +469,7 @@ function scanAndRewriteFile(
   source: string,
   project: ProjectPlan,
   browserMode: boolean | undefined,
+  mergedConfig: boolean,
 ): { content: string; findings: VitestV5Finding[] } {
   const findings: VitestV5Finding[] = [];
   scanNode(file, source, findings);
@@ -504,7 +506,7 @@ function scanAndRewriteFile(
         findings.push(...review.findings.filter(({ code }) => pending.includes(code)));
       }
       if (project.configFiles.has(file)) {
-        const configResult = migrateVitestV5Config(file, content, project.options);
+        const configResult = migrateVitestV5Config(file, content, project.options, mergedConfig);
         content = configResult.content;
         findings.push(...configResult.findings);
       }
@@ -700,6 +702,7 @@ export function planVitestV5Migration(
     }
   }
   const allConfigs = findVitestV5ConfigFiles(allSources);
+  const mergedConfigs = findVitestV5MergedConfigFiles(allSources, allConfigs);
   const browserPossible = [...allSources.values()].some((source) => BROWSER_SIGNAL.test(source));
   const browserCliOverride = [...allSources].some(
     ([file, source]) =>
@@ -786,6 +789,7 @@ export function planVitestV5Migration(
         source,
         project,
         browserCliOverride ? undefined : browserModes.get(file),
+        mergedConfigs.has(file),
       );
       findings.push(...result.findings);
       if (source !== result.content) {
@@ -910,6 +914,10 @@ export function finishVitestV5Migration(plan: VitestV5MigrationPlan): VitestV5Fi
   const findings: VitestV5Finding[] = [];
   const state = structuredClone(plan.state);
   const projectConfigs = currentProjectConfigs(plan);
+  const configSources = new Map(
+    [...projectConfigs.values()].flat().map((file) => [file, fs.readFileSync(file, 'utf8')]),
+  );
+  const mergedConfigs = findVitestV5MergedConfigFiles(configSources, new Set(configSources.keys()));
   for (const project of plan.projects) {
     if (!project.active || !project.sourceVersion) {
       continue;
@@ -918,7 +926,12 @@ export function finishVitestV5Migration(plan: VitestV5MigrationPlan): VitestV5Fi
     for (const file of configs) {
       const before = fs.readFileSync(file, 'utf8');
       try {
-        const result = migrateVitestV5Config(file, before, project.options);
+        const result = migrateVitestV5Config(
+          file,
+          before,
+          project.options,
+          mergedConfigs.has(file),
+        );
         findings.push(...result.findings);
         if (
           !result.findings.some((finding) => finding.severity === 'block') &&

packages/cli/src/migration/vitest-v5/config.ts

@@ -148,6 +148,70 @@ export function findVitestV5ConfigFiles(sources: ReadonlyMap<string, string>): S
   return files;
 }
 
+function hasConfigMerge(editor: SourceEditor): boolean {
+  let found = false;
+  traverse(editor.ast, {
+    CallExpression(p) {
+      if (importedName(p, p.node.callee, CONFIG_SOURCES) === 'mergeConfig') {
+        found = true;
+      }
+    },
+  });
+  return found;
+}
+
+/** Defaults on one merge fragment can override explicit settings in another.
+ * Include local imported configs so the preflight and finalization agree. */
+export function findVitestV5MergedConfigFiles(
+  sources: ReadonlyMap<string, string>,
+  configFiles: ReadonlySet<string>,
+): Set<string> {
+  const merged = new Set<string>();
+  const imports = new Map<string, string[]>();
+  const extensions = ['.ts', '.mts', '.cts', '.js', '.mjs', '.cjs', '.tsx', '.jsx'];
+  for (const file of configFiles) {
+    try {
+      const editor = new SourceEditor(file, sources.get(file)!);
+      if (hasConfigMerge(editor)) {
+        merged.add(file);
+      }
+      const dependencies: string[] = [];
+      for (const node of editor.ast.program.body) {
+        if (
+          node.type !== 'ImportDeclaration' &&
+          node.type !== 'ExportNamedDeclaration' &&
+          node.type !== 'ExportAllDeclaration'
+        ) {
+          continue;
+        }
+        const reference = node.source?.value;
+        if (!reference?.startsWith('.')) {
+          continue;
+        }
+        const target = path.resolve(path.dirname(file), reference);
+        const dependency = [
+          target,
+          target.replace(/\.([cm]?)js$/, '.$1ts'),
+          ...extensions.map((extension) => `${target}${extension}`),
+          ...extensions.map((extension) => path.join(target, `index${extension}`)),
+        ].find((candidate) => configFiles.has(candidate));
+        if (dependency) {
+          dependencies.push(dependency);
+        }
+      }
+      imports.set(file, dependencies);
+    } catch {
+      // The normal config pass reports unsupported syntax.
+    }
+  }
+  for (const file of merged) {
+    for (const dependency of imports.get(file) ?? []) {
+      merged.add(dependency);
+    }
+  }
+  return merged;
+}
+
 interface BrowserTestScope {
   root?: string;
   include?: string[];
@@ -373,9 +437,23 @@ export function resolveVitestV5BrowserModes(
   );
 }
 
-export function migrateVitestV5Config(file: string, source: string, options: SourceOptions) {
+export function migrateVitestV5Config(
+  file: string,
+  source: string,
+  options: SourceOptions,
+  mergedConfig = false,
+) {
   const editor = new SourceEditor(file, source);
   const visited = new Set<t.ObjectExpression>();
+  const merged = mergedConfig || hasConfigMerge(editor);
+  const preserveDefaults = options.preserveV4 && !merged;
+  if (merged && (options.preserveV4 || options.reviewV4)) {
+    editor.report(
+      undefined,
+      'merged-config-defaults',
+      'Review the effective merged config before adding v4 defaults for clearMocks, browser locators, fake timers, reporters, and projects. Defaults were not added to config fragments because they can override explicit settings in another fragment.',
+    );
+  }
 
   function nested(
     object: t.ObjectExpression,
@@ -442,7 +520,7 @@ export function migrateVitestV5Config(file: string, source: string, options: Sou
           }
         }
       }
-      if (!options.preserveV4 || !['json', 'junit'].includes(name.value)) {
+      if (!preserveDefaults || !['json', 'junit'].includes(name.value)) {
         continue;
       }
       if (output && (!staticObject(output.value) || objectProperty(output.value, name.value))) {
@@ -475,14 +553,21 @@ export function migrateVitestV5Config(file: string, source: string, options: Sou
     }
   }
 
-  function testOptions(test: t.ObjectExpression, inherits: boolean) {
-    if (options.preserveV4 && !inherits) {
+  function testOptions(
+    test: t.ObjectExpression,
+    inherits: boolean,
+    parentTest?: t.ObjectExpression,
+  ) {
+    if (preserveDefaults && !inherits) {
       editor.add(test, 'clearMocks', 'false');
     }
     const browser = objectProperty(test, 'browser');
     if (browser && staticObject(browser.value)) {
       const value = browser.value;
-      if (options.preserveV4) {
+      // An inherited browser config already receives its defaults at the parent.
+      // Do not replace its explicit or dynamic locator setting in the child.
+      const inheritsBrowser = inherits && parentTest && objectProperty(parentTest, 'browser');
+      if (preserveDefaults && !inheritsBrowser) {
         nested(value, 'locators', 'exact: false', (locators) =>
           editor.add(locators, 'exact', 'false'),
         );
@@ -526,7 +611,7 @@ export function migrateVitestV5Config(file: string, source: string, options: Sou
       );
     }
 
-    if (options.preserveV4 && options.temporalPolyfill) {
+    if (preserveDefaults && options.temporalPolyfill) {
       nested(test, 'fakeTimers', "toNotFake: ['Temporal']", (timers) =>
         editor.add(timers, 'toNotFake', "['Temporal']"),
       );
@@ -545,7 +630,7 @@ export function migrateVitestV5Config(file: string, source: string, options: Sou
       }
       const thresholds = objectProperty(coverage.value, 'thresholds');
       if (
-        options.preserveV4 &&
+        preserveDefaults &&
         thresholds &&
         staticObject(thresholds.value) &&
         isTrue(objectProperty(thresholds.value, 'perFile')?.value)
@@ -614,7 +699,7 @@ export function migrateVitestV5Config(file: string, source: string, options: Sou
       return;
     }
     const hasInline = projects.value.elements.some((item) => item && item.type !== 'StringLiteral');
-    if (hasInline && options.preserveV4) {
+    if (hasInline && preserveDefaults) {
       editor.add(test, 'sharedViteServer', 'false');
     }
     for (const project of projects.value.elements) {
@@ -630,29 +715,29 @@ export function migrateVitestV5Config(file: string, source: string, options: Sou
         continue;
       }
       const extendsValue = objectProperty(project, 'extends');
-      if (options.preserveV4) {
+      if (preserveDefaults) {
         editor.add(project, 'extends', 'false');
       }
-      config(project, isTrue(extendsValue?.value));
+      config(project, isTrue(extendsValue?.value), test);
     }
   }
 
-  function config(object: t.ObjectExpression, inherits = false) {
+  function config(object: t.ObjectExpression, inherits = false, parentTest?: t.ObjectExpression) {
     if (visited.has(object)) {
       return;
     }
     visited.add(object);
     const test = objectProperty(object, 'test');
     if (!test) {
-      if (options.preserveV4 && !inherits) {
+      if (preserveDefaults && !inherits) {
         editor.add(
           object,
           'test',
           `{ clearMocks: false${options.temporalPolyfill ? ", fakeTimers: { toNotFake: ['Temporal'] }" : ''} }`,
         );
       }
     } else if (staticObject(test.value)) {
-      testOptions(test.value, inherits);
+      testOptions(test.value, inherits, parentTest);
     } else {
       editor.report(
         test,

packages/cli/src/migration/vitest-v5/source.ts

@@ -149,7 +149,11 @@ function chain(
 export function migrateVitestV5Source(file: string, source: string, options: SourceOptions) {
   const editor = new SourceEditor(file, source);
   const asyncFunctions = new Set<t.Node>();
-  const apiName = (p: NodePath, node: t.Node) => testApiName(p, node, options.globals);
+  // Import edits are offset-based, so bindings still refer to the old module
+  // while this traversal visits the assertions that must migrate with them.
+  const apiName = (p: NodePath, node: t.Node) =>
+    testApiName(p, node, options.globals) ??
+    (importedName(p, node, EXPECT_SOURCES) === 'expect' ? 'expect' : undefined);
   const canAwait = (p: NodePath) => {
     const fn = p.getFunctionParent();
     if (!fn) {