feat(runner): add mergeTests utility to compose TestAPI fixtures

docs/api/test.md

@@ -284,6 +284,21 @@ test('server uses correct port', ({ config, server }) => {
 })
 ```
 
+## mergeTests <Version>4.1.0</Version>
+
+`mergeTests` utility allows you to merge multiple `TestAPI` instances into a single one. This is equivalent to calling `.extend()` repeatedly with the fixtures from each test.
+
+```ts
+import { mergeTests, test } from 'vitest'
+
+// Combined test has fixtures from test, otherTest, and uiTest
+const myTest = mergeTests(test, otherTest, uiTest)
+```
+
+`mergeTests` is variadic and accepts any number of test instances. If multiple tests define the same fixture name, the one from the later test overrides the earlier one.
+
+See [Merging Test Contexts](/guide/test-context#merging-test-contexts) for more details.
+
 ## test.override <Version>4.1.0</Version> {#test-override}
 
 Use `test.override` to override fixture values for all tests within the current suite and its nested suites. This must be called at the top level of a `describe` block. See [Overriding Fixture Values](/guide/test-context.html#overriding-fixture-values) for more information.

docs/guide/test-context.md

@@ -818,6 +818,41 @@ Note that you cannot introduce new fixtures inside `test.override`. Extend the t
 `test.scoped` is deprecated in favor of `test.override`. The `test.scoped` API still works but will be removed in a future version.
 :::
 
+### Merging Test Contexts <Version>4.1.0</Version> {#merging-test-contexts}
+
+Vitest allows you to merge test contexts from multiple sources using the `mergeTests` utility. This is useful when you have separate test extensions (e.g., one for database, one for network, and one for UI) and want to combine them into a single test API.
+
+`mergeTests` is variadic and accepts any number of test instances. Calling `mergeTests(testA, testB, testC)` is equivalent to calling `testA.extend(fixturesFromB).extend(fixturesFromC)`.
+
+```ts
+import { test as base, mergeTests } from 'vitest'
+
+const dbTest = base.extend({
+  db: async ({}, use) => {
+    // ... setup db
+    await use(db)
+    // ... teardown db
+  }
+})
+
+const serverTest = base.extend({
+  server: async ({}, use) => {
+    // ... setup server
+    await use(server)
+    // ... teardown server
+  }
+})
+
+// Combined test has both `db` and `server` fixtures
+const test = mergeTests(dbTest, serverTest)
+
+test('uses both db and server', ({ db, server }) => {
+  // ...
+})
+```
+
+If multiple tests define the same fixture name, the one from the later test (further to the right in the arguments) overrides the earlier one.
+
 ### Type-Safe Hooks
 
 When using `test.extend`, the extended `test` object provides type-safe hooks that are aware of the extended context:

packages/runner/src/fixture.ts

@@ -54,13 +54,26 @@ export class TestFixtures {
     TestFixtures._definitions.push(this)
   }
 
-  extend(runner: VitestRunner, userFixtures: UserFixtures): TestFixtures {
+  extend(runner: VitestRunner, userFixtures: UserFixtures | TestFixtures): TestFixtures {
     const { suite } = getCurrentSuite()
     const isTopLevel = !suite || suite.file === suite
+
+    if (userFixtures instanceof TestFixtures) {
+      const registrations = new Map(this._registrations)
+      for (const [name, item] of userFixtures._registrations) {
+        registrations.set(name, item)
+      }
+      return new TestFixtures(registrations)
+    }
+
     const registrations = this.parseUserFixtures(runner, userFixtures, isTopLevel)
     return new TestFixtures(registrations)
   }
 
+  getFixtures(): TestFixtures {
+    return this
+  }
+
   get(suite: Suite): FixtureRegistrations {
     let currentSuite: Suite | undefined = suite
     while (currentSuite) {

packages/runner/src/index.ts

@@ -16,6 +16,7 @@ export {
   describe,
   getCurrentSuite,
   it,
+  mergeTests,
   suite,
   test,
 } from './suite'

packages/runner/src/suite.ts

@@ -220,7 +220,7 @@ function createDefaultSuite(runner: VitestRunner) {
   if (config.concurrent != null) {
     options.concurrent = config.concurrent
   }
-  const collector = suite('', options, () => {})
+  const collector = suite('', options, () => { })
   // no parent suite for top-level tests
   delete collector.suite
   return collector
@@ -302,7 +302,7 @@ function parseArguments<T extends (...args: any[]) => any>(
 // implementations
 function createSuiteCollector(
   name: string,
-  factory: SuiteFactory = () => {},
+  factory: SuiteFactory = () => { },
   mode: RunMode,
   each?: boolean,
   suiteOptions?: SuiteOptions,
@@ -1092,3 +1092,46 @@ function formatTemplateString(cases: any[], args: any[]): any[] {
   }
   return res
 }
+
+/**
+ * Merges multiple test instances into a single test instance.
+ *
+ * This is equivalent to calling `.extend()` repeatedly with the fixtures from each test.
+ * All fixtures from the provided tests will be available in the returned test.
+ * If multiple tests define the same fixture name, the one from the later test wins.
+ *
+ * @example
+ * const test = mergeTests(dbTest, serverTest, uiTest)
+ */
+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')
+  }
+
+  // Use the first test as the base
+  let [currentTest, ...rest] = tests
+
+  for (const nextTest of rest) {
+    const nextContext = getChainableContext(nextTest)
+    if (!nextContext || typeof nextContext.getFixtures !== 'function') {
+      throw new TypeError('mergeTests requires extended test instances created via test.extend()')
+    }
+
+    // Extract fixtures from the next test and extend the current test
+    // This behaves exactly like currentTest.extend(nextFixtures)
+    const currentContext = getChainableContext(currentTest)
+    if (!currentContext) {
+      throw new TypeError('Cannot merge tests: base test is not a valid test instance')
+    }
+    const fixtures = nextContext.getFixtures()
+    currentTest = currentTest.extend(fixtures as any)
+  }
+
+  return currentTest
+}

packages/vitest/src/public/index.ts

@@ -112,6 +112,7 @@ export {
   suite,
   test,
 } from '@vitest/runner'
+export { mergeTests } from '@vitest/runner'
 export type {
   ImportDuration,
   OnTestFailedHandler,

test/core/test/exports.test.ts

@@ -36,6 +36,7 @@ it('exports snapshot', async ({ skip, task }) => {
         "expectTypeOf": "function",
         "inject": "function",
         "it": "function",
+        "mergeTests": "function",
         "onTestFailed": "function",
         "onTestFinished": "function",
         "recordArtifact": "function",

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

@@ -0,0 +1,42 @@
+import { expectTypeOf, mergeTests, test } from 'vitest'
+
+const testA = test.extend({
+  a: 1,
+})
+
+const testB = test.extend({
+  b: 2,
+})
+
+const merged = mergeTests(testA, testB)
+
+merged('types', ({ a, b }) => {
+  expectTypeOf(a).not.toBeAny()
+  expectTypeOf(b).not.toBeAny()
+  expectTypeOf(a).toEqualTypeOf<number>()
+  expectTypeOf(b).toEqualTypeOf<number>()
+})
+
+const testC = test.extend({
+  c: 'string',
+})
+
+const merged3 = mergeTests(merged, testC)
+
+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

@@ -0,0 +1,122 @@
+import { describe, expect, mergeTests, test } from 'vitest'
+
+describe('mergeTests', () => {
+  const testA = test.extend({
+    a: 1,
+  })
+  const testB = test.extend({
+    b: 2,
+  })
+  const merged = mergeTests(testA, testB)
+
+  merged('merges fixtures from two tests', ({ a, b }) => {
+    expect(a).toBe(1)
+    expect(b).toBe(2)
+  })
+
+  describe('nested describe', () => {
+    const testC = test.extend({
+      a: 2,
+    })
+    const mergedOverride = mergeTests(testA, testC)
+
+    mergedOverride('overrides fixtures', ({ a }) => {
+      expect(a).toBe(2)
+    })
+  })
+
+  const mergedReverse = mergeTests(testB, testA)
+
+  mergedReverse('overrides fixtures (reverse)', ({ a }) => {
+    expect(a).toBe(1)
+  })
+
+  const testD = test.extend({
+    c: 3,
+  })
+
+  const mergedChained = mergeTests(mergeTests(testA, testB), testD)
+
+  mergedChained('chained merge', ({ a, b, c }) => {
+    expect(a).toBe(1)
+    expect(b).toBe(2)
+    expect(c).toBe(3)
+  })
+
+  describe('shared base', () => {
+    const base = test.extend({
+      base: 'base',
+    })
+    const derivedA = base.extend({
+      a: 'a',
+    })
+    const derivedB = base.extend({
+      b: 'b',
+    })
+    const mergedDerived = mergeTests(derivedA, derivedB)
+
+    mergedDerived('shared base fixtures', ({ base, a, b }) => {
+      expect(base).toBe('base')
+      expect(a).toBe('a')
+      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('overrides are dropped during merge (extend semantics)', () => {
+      const base = test.extend({ a: 1 })
+      base.override({ a: 2 })
+      const other = test.extend({ b: 3 })
+      const merged = mergeTests(base, other)
+
+      merged('overrides are reset like extend()', ({ a, b }) => {
+        expect(a).toBe(1)
+        expect(b).toBe(3)
+      })
+    })
+
+    describe('scoped (identity)', () => {
+      const base = test.extend({ a: 1 })
+      base.override({ a: 2 })
+      const merged = mergeTests(base)
+
+      merged('confirms scoped overrides are preserved', ({ a }) => {
+        expect(a).toBe(2)
+      })
+    })
+  })
+})