feat(runner): implement nominal overloads for mergeTests API

- Refactor mergeTests to use explicit nominal overloads (up to 6 args)
- Remove complex structural extraction types (ExtractTestContext, UnionToIntersection)
- Implement context-aware fixture merging in TestFixtures.merge
- Add comprehensive runtime and type tests for mergeTests
- Ensure strictly nominal TestAPI propagation

Author: Ujjwaljain16

packages/runner/src/fixture.ts

@@ -77,22 +77,16 @@ export class TestFixtures {
     return this._registrations
   }
 
-  /**
-   * @internal
-   */
-  resolveFixtures(): UserFixtures {
+  toUserFixtures(): UserFixtures {
     const fixtures: UserFixtures = {}
-    const registrations = this._registrations
-
-    for (const [name, fixture] of registrations.entries()) {
+    for (const [name, fixture] of this._registrations) {
       const options: FixtureOptions = {
         auto: fixture.auto,
         scope: fixture.scope,
         injected: fixture.injected,
       }
       fixtures[name] = [fixture.value, options]
     }
-
     return fixtures
   }
 
@@ -213,7 +207,37 @@ export class TestFixtures {
       }
     })
 
-    // validate fixture dependency scopes
+    this.validateFixtureGraph(registrations, errors)
+
+    return registrations
+  }
+
+  merge(other: TestFixtures): TestFixtures {
+    const registrations = new Map(this._registrations)
+    const errors: Error[] = []
+
+    const { suite, file } = getCurrentSuite()
+    const context = suite || file
+    const isTopLevel = !suite || suite.file === suite
+
+    // We need to resolve fixtures from the current context, because test.override
+    // inside the suite only modifies overrides for that suite.
+    const otherRegistrations = context ? other.get(context) : other._registrations
+
+    for (const [name, fixture] of otherRegistrations) {
+      if (!isTopLevel && fixture.scope !== 'test') {
+        errors.push(new FixtureDependencyError(`The "${name}" fixture cannot be defined with a ${fixture.scope} scope inside the describe block. Define it at the top level of the file instead.`))
+      }
+      registrations.set(name, fixture)
+    }
+
+    this.validateFixtureGraph(registrations, errors)
+
+    return new TestFixtures(registrations)
+  }
+
+  private validateFixtureGraph(registrations: FixtureRegistrations, errors: Error[] = []) {
+
     for (const fixture of registrations.values()) {
       for (const depName of fixture.deps) {
         if (TestFixtures._builtinFixtures.includes(depName)) {
@@ -243,7 +267,6 @@ export class TestFixtures {
     else if (errors.length > 1) {
       throw new AggregateError(errors, 'Cannot resolve user fixtures. See errors for more information.')
     }
-    return registrations
   }
 }
 

packages/runner/src/suite.ts

@@ -1093,14 +1093,44 @@ function formatTemplateString(cases: any[], args: any[]): any[] {
   return res
 }
 
-export function mergeTests<A, B>(
-  test: TestAPI<A>,
-  testB: TestAPI<B>,
-): TestAPI<A & B> {
-  const ctx = getChainableContext(testB)
-  if (!ctx) {
-    throw new TypeError('Cannot merge tests: extension is not a valid TestAPI')
+export function mergeTests<A>(a: TestAPI<A>): TestAPI<A>
+export function mergeTests<A, B>(a: TestAPI<A>, b: TestAPI<B>): TestAPI<A & B>
+export function mergeTests<A, B, C>(a: TestAPI<A>, b: TestAPI<B>, c: TestAPI<C>): TestAPI<A & B & C>
+export function mergeTests<A, B, C, D>(a: TestAPI<A>, b: TestAPI<B>, c: TestAPI<C>, d: TestAPI<D>): TestAPI<A & B & C & D>
+export function mergeTests<A, B, C, D, E>(a: TestAPI<A>, b: TestAPI<B>, c: TestAPI<C>, d: TestAPI<D>, e: TestAPI<E>): TestAPI<A & B & C & D & E>
+export function mergeTests<A, B, C, D, E, F>(a: TestAPI<A>, b: TestAPI<B>, c: TestAPI<C>, d: TestAPI<D>, e: TestAPI<E>, f: TestAPI<F>): TestAPI<A & B & C & D & E & F>
+export function mergeTests(...tests: TestAPI<any>[]): TestAPI<any> {
+  if (tests.length === 0) {
+    throw new TypeError('mergeTests requires at least one test')
   }
-  const fixtures = ctx.getFixtures().resolveFixtures()
-  return test.extend(fixtures as any) as TestAPI<A & B>
+
+  // use the base test as the starting point
+  const [base, ...rest] = tests
+  const baseContext = getChainableContext(base)
+  if (!baseContext || typeof baseContext.getFixtures !== 'function') {
+    throw new TypeError('Cannot merge tests: argument is not a valid test instance')
+  }
+
+  let fixtures = baseContext.getFixtures()
+
+  for (const test of rest) {
+    const ctx = getChainableContext(test)
+    if (!ctx || typeof ctx.getFixtures !== 'function') {
+      throw new TypeError('Cannot merge tests: argument is not a valid test instance')
+    }
+    fixtures = fixtures.merge(ctx.getFixtures())
+  }
+
+  // We call extend({}) to clone the chainable API while preserving internal flags.
+  // The newly created fixtures are immediately replaced via mergeContext.
+  const result = base.extend({})
+  const resultContext = getChainableContext(result)
+
+  if (!resultContext) {
+    throw new TypeError('Cannot merge tests: argument is not a valid test instance')
+  }
+
+  resultContext.mergeContext({ fixtures })
+
+  return result
 }

packages/vitest/src/public/index.ts

@@ -106,13 +106,13 @@ export {
   beforeEach,
   describe,
   it,
-  mergeTests,
   onTestFailed,
   onTestFinished,
   recordArtifact,
   suite,
   test,
 } from '@vitest/runner'
+export { mergeTests } from '@vitest/runner'
 export type {
   ImportDuration,
   OnTestFailedHandler,

test/core/test/merge-tests.test-d.ts

@@ -11,8 +11,10 @@ const testB = test.extend({
 const merged = mergeTests(testA, testB)
 
 merged('types', ({ a, b }) => {
-  expectTypeOf(a).toBeNumber()
-  expectTypeOf(b).toBeNumber()
+  expectTypeOf(a).not.toBeAny()
+  expectTypeOf(b).not.toBeAny()
+  expectTypeOf(a).toEqualTypeOf<number>()
+  expectTypeOf(b).toEqualTypeOf<number>()
 })
 
 const testC = test.extend({
@@ -21,8 +23,20 @@ const testC = test.extend({
 
 const merged3 = mergeTests(merged, testC)
 
-merged3('chained types', ({ a, b, c }) => {
+merged3('chained merge types', ({ a, b, c }) => {
   expectTypeOf(a).toBeNumber()
   expectTypeOf(b).toBeNumber()
   expectTypeOf(c).toBeString()
 })
+
+const testBool = test.extend({
+  d: true,
+})
+
+const mergedVariadic = mergeTests(testA, testB, testBool)
+
+mergedVariadic('variadic types', ({ a, b, d }) => {
+  expectTypeOf(a).toBeNumber()
+  expectTypeOf(b).toBeNumber()
+  expectTypeOf(d).toBeBoolean()
+})

test/core/test/merge-tests.test.ts

@@ -61,4 +61,50 @@ describe('mergeTests', () => {
       expect(b).toBe('b')
     })
   })
+
+  describe('variadic merge (A, B, C) overrides correctly', () => {
+    const testA = test.extend({
+      a: 1,
+      shared: 'a',
+    })
+    const testB = test.extend({
+      b: 2,
+      shared: 'b',
+    })
+    const testC = test.extend({
+      c: 3,
+      shared: 'c',
+    })
+
+    const merged = mergeTests(testA, testB, testC)
+
+    merged('inherits all fixtures and overrides from last', ({ a, b, c, shared }) => {
+      expect(a).toBe(1)
+      expect(b).toBe(2)
+      expect(c).toBe(3)
+      expect(shared).toBe('c')
+    })
+  })
+
+  describe('overrides', () => {
+    describe('top-level', () => {
+      const base = test.extend({ a: 1 })
+      base.override({ a: 2 })
+      const merged = mergeTests(base)
+
+      merged('confirms top-level overrides are respected', ({ a }) => {
+        expect(a).toBe(2)
+      })
+    })
+
+    describe('scoped', () => {
+      const base = test.extend({ a: 1 })
+      base.override({ a: 2 })
+      const merged = mergeTests(base)
+
+      merged('confirms scoped overrides are respected', ({ a }) => {
+        expect(a).toBe(2)
+      })
+    })
+  })
 })