feat(runner): add mergeTests utility to compose TestAPI fixtures by Ujjwaljain16 · Pull Request #9662 · vitest-dev/vitest

Ujjwaljain16 · 2026-02-14T15:20:49Z

Description

This adds a new mergeTests(testA, testB) utility that allows composing fixtures from multiple TestAPI instances.

Example:

const testA = test.extend({ a: 1 })
const testB = test.extend({ b: 2 })

const merged = mergeTests(testA, testB)

merged('works', ({ a, b }) => {
  // both fixtures available
})

Implementation

The implementation reuses the existing .extend() mechanism to preserve fixture graph integrity.

Instead of manually merging internal TestFixtures maps, the approach is:

Extract fixture definitions from testB via resolveFixtures()
Call testA.extend(fixturesFromB)
Return a new TestAPI<A & B>

This ensures:

Proper dependency resolution
Correct scope handling (test / worker)
Auto fixtures behave naturally
No mutation of internal state

Override Semantics

If both tests define the same fixture name, the second argument (testB) overrides the first.
This mirrors .extend() behavior (last-writer-wins).

Type Support

The return type is TestAPI<A & B>.
Type-level tests verify correct intersection inference and chained merging.

Tests

Added runtime tests covering:

Basic merging
Override behavior
Nested describe
Shared base extension
Chained merging

Added type-level tests verifying fixture intersection types.

All tests pass.

Resolves #9483

Tests

Run:

pnpm test:ci

Documentation

No public docs changes required. The utility is self-contained and exposed via public API.

Changesets

PR name follows conventional format:

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

- Adds resolveFixtures() to TestFixtures - Implements mergeTests(testA, testB) using existing .extend() mechanism - Supports override semantics (last writer wins) - Includes runtime tests and type-level tests - Verified nested describe, shared base, and chained merges

Ujjwaljain16 · 2026-02-15T06:47:43Z

@sheremet-va waiting for the review

sheremet-va · 2026-02-15T10:44:24Z

packages/runner/src/fixture.ts

  }

+  /**
+   * @internal


Everything here is internal, so no need to add this

sheremet-va · 2026-02-15T10:45:50Z

packages/runner/src/fixture.ts

+  /**
+   * @internal
+   */
+  resolveFixtures(): UserFixtures {


I don't like this idea, why do we need to convert already converted fixtures into user definitions and then convert them back again?

I would do the opposite and add a merge function that accepts another Fixtures, then we can just iterate over the registrations overriding them

sheremet-va · 2026-02-15T10:46:52Z

packages/runner/src/suite.ts

+export function mergeTests<A, B>(
+  test: TestAPI<A>,
+  testB: TestAPI<B>,
+): TestAPI<A & B> {


Hm, I assumed it can accept more than 2 (any number in fact). Would it make sense?

Agreed this utility should support composing any number of test APIs.

I updated the signature to:

mergeTests<T extends readonly unknown[]>(...tests: T)

Runtime behavior:

Iteratively extends left -> right.

Later fixtures override earlier ones (last-writer-wins)

Works for arbitrarily long argument lists.

Type behavior:

MergeTestContexts<T> iterates over the tuple and intersects all extracted contexts.

Variadic inference is preserved even for nested merges.

This is now covered by runtime and type tests (including 3+ merges)

sheremet-va · 2026-02-15T10:47:28Z

packages/runner/src/suite.ts

+): TestAPI<A & B> {
+  const ctx = getChainableContext(testB)
+  if (!ctx) {
+    throw new TypeError('Cannot merge tests: extension is not a valid TestAPI')


This is a bit cryptic, what is a TestAPI to the user? Maybe just mention that this function requires an extended test

Agreed exposing internal terminology like "TestAPI" in runtime errors isn’t ideal

I updated the error message to:

"mergeTests requires extended test instances created via test.extend()"

This makes the requirement clearer without leaking internal implementation concepts

sheremet-va · 2026-02-15T10:47:47Z

packages/vitest/src/public/index.ts

  beforeEach,
  describe,
  it,
+  mergeTests,


This function needs to be documented

Ujjwaljain16 · 2026-02-16T12:23:52Z

@sheremet-va
I’d really appreciate your guidance on a few architectural decisions here, especially around typing and fixture composition.

Strict Type Safety & Generic Constraints

While implementing mergeTests, I initially tried constraining inputs as:

T extends readonly TestAPI<any>[]

However this fails because TestAPI is invariant in its generic parameter due to the TestCollectorCallable definition:

<ExtraContext extends C>(...)

This makes:

TestAPI<{ a: number }>

not assignable to:

TestAPI<any>

So constraining to TestAPI<any>[] rejects valid usage.

To work around this, I relaxed the constraint to:

T extends readonly unknown[]

and enforced type validity structurally via ExtractTestContext<T>.

This preserves full context inference for consumers while avoiding the invariance trap.

My question:

Would you prefer a stricter nominal constraint even if it requires internal casts, or is structural validation acceptable here given the variance characteristics of TestAPI?

Context Extraction Strategy

I initially attempted:

T extends TestAPI<infer C> ? C : never

But this proved unreliable because TestAPI is a complex intersection type with overloaded call signatures. In many cases TypeScript collapsed inference to unknown or never

Instead, I switched to structural extraction based on beforeEach, since it is the canonical API that consumes the contextual type:

T extends { beforeEach: (fn: infer F, ...args: any) => any }
  ? F extends (context: infer C, ...args: any) => any
    ? C
    : never
  : never

This also correctly accounts for the actual listener signature:

(context, suite)

Structurally matching on beforeEach felt more stable than relying on TestAPI<infer C>.

Would you prefer:

Structural extraction (as implemented), or
A nominal extraction approach even if it’s slightly less inference-friendly?

Fixture Merging Strategy

I explored implementing a low-level merge() directly on TestFixtures.

However, that would:

Bypass the .extend() validation pipeline
Duplicate dependency/scope validation logic
Risk drifting from canonical fixture behavior

Instead, I:

Added toUserFixtures() to serialize definition-time registrations
Re-applied them using .extend()

This keeps all validation inside the existing extension mechanism and preserves immutability.

Would you consider this acceptable alignment with Vitest’s design, or would you prefer fixture merging to happen at the TestFixtures level instead?

I’m happy to adjust direction based on your preference

sheremet-va · 2026-02-16T12:35:33Z

Would you prefer a stricter nominal constraint even if it requires internal casts, or is structural validation acceptable here given the variance characteristics of TestAPI?

Casting types internally is fine to me as long as public API is strict

Structural extraction (as implemented), or A nominal extraction approach even if it’s slightly less inference-friendly?

I don't have a preference. As long as public API works correctly, any trick is good to me

Bypass the .extend() validation pipeline
Duplicate dependency/scope validation logic

Why would it do that? Didn't we already validated everything in the original test.extend calls? We are just merging them afterwards, no?

Could we abstract it in a better way, so it's more reusable without extra loops?

Risk drifting from canonical fixture behavior

I don't know what that means

sheremet-va · 2026-02-16T15:28:08Z

To work around this, I relaxed the constraint to:

I think one of the possible solutions here is to define a lot of overloads of mergeTests:

function mergeTests<A, B, C>(test1: TestAPI<A>, test2: TestAPI<B>, test3: TestAPI<C>): TestAPI<A & B & C>
function mergeTests<A, B>(test1: TestAPI<A>, test2: TestAPI<B>): TestAPI<A & B>
// ... and so on

netlify · 2026-02-16T16:42:40Z

✅ Deploy Preview for vitest-dev ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`a526ad8`
🔍 Latest deploy log	https://app.netlify.com/projects/vitest-dev/deploys/699348ba9f31d400082c2e88
😎 Deploy Preview	https://deploy-preview-9662--vitest-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

netlify · 2026-02-16T17:35:27Z

✅ Deploy Preview for vitest-dev ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`000fec2`
🔍 Latest deploy log	https://app.netlify.com/projects/vitest-dev/deploys/699604424bd90700088edd1b
😎 Deploy Preview	https://deploy-preview-9662--vitest-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

- 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

… in mergeTests

…Options typing

sheremet-va

It's pretty hard to review

The previous implementation is clean and easy to follow, the new one removes all the helpful comments and introduces concepts and code that's just hard to follow

There are registrations and overrides. registrations are scoped to the last test.extend, and overrides are applied to tests in specified suites, that's it. What this PR adds are some kind of pure registrations, and keeps track of parents and ancestors (why? we have registrations already - overridden suites also include all fixtures already)

…line architecture

Ujjwaljain16 · 2026-02-18T18:21:54Z

Appreciate the push to simplify you were right about the overhead. I've refactored the implementation back to the baseline 'flat model' and moved to direct Map-merging in extend()
It's much cleaner now and avoids the conversion loop entirely.
I also restored all original documentation and synchronized the internal types with main to ensure there's no drift. Everything is verified and synced with upstream

sheremet-va

I don't think there is enough tests. Unit tests are not enough, we need a comprehensive test suite similar to test/cli/test/scoped-fixtures.test.ts

What happens here, for example?

const t1 = test.extend('f', { scope: 'file' }, () => 'file')
const t2 = test.extend('f', { scope: 'test', () => 'test')
mergeTests(t1, t2)

This should fail properly, for example

There are also no tests that have scope, injected, or even a function fixture (() => something)

sheremet-va · 2026-02-21T14:20:02Z

packages/runner/src/suite.ts

+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')


This is not tested

sheremet-va · 2026-02-21T14:20:11Z

packages/runner/src/suite.ts

+  let [currentTest, ...rest] = tests
+
+  for (const nextTest of rest) {
+    const nextContext = getChainableContext(nextTest)


This is not tested

sheremet-va · 2026-02-21T14:20:21Z

packages/runner/src/suite.ts

+    // Extract fixtures from the next test and extend the current test
+    // This behaves exactly like currentTest.extend(nextFixtures)
+    const currentContext = getChainableContext(currentTest)
+    if (!currentContext) {


This is not tested

sheremet-va · 2026-02-21T14:20:42Z

packages/runner/src/fixture.ts

    return new TestFixtures(registrations)
  }

+  getFixtures(): TestFixtures {


What is this? Why do you need this if you already have access to the instance?

Ujjwaljain16 added 4 commits February 14, 2026 20:31

Merge branch 'main' into feat/merge-tests

0277013

fix(runner): export mergeTests from runner package entry point

6446b39

test: update exports snapshot with mergeTests

7652696

sheremet-va requested changes Feb 15, 2026

View reviewed changes

rekhaaktermim09-afk approved these changes Feb 16, 2026

View reviewed changes

Ujjwaljain16 force-pushed the feat/merge-tests branch 2 times, most recently from 4902540 to d8e6beb Compare February 16, 2026 17:33

Ujjwaljain16 force-pushed the feat/merge-tests branch from 5878ad9 to adf5044 Compare February 16, 2026 17:37

Ujjwaljain16 added 6 commits February 16, 2026 23:11

Merge branch 'main' into feat/merge-tests

2f95529

refactor(runner): simplify mergeTests to use linear extension chain

fa60ae8

fix(runner): resolve context leakage and mergeTests regression

c6e3c77

feat(runner): add mergeTests utility and fix fixture context leakage

02a34e9

docs: fix multiple blank lines lint error

0fbe859

fix(runner): restore hierarchical suite override lookup and isolation

2672a0e

Ujjwaljain16 marked this pull request as draft February 17, 2026 02:07

fix(runner): resolve merge conflicts and fix fixture override leakage…

a131cf9

… in mergeTests

Ujjwaljain16 force-pushed the feat/merge-tests branch from 091af14 to a131cf9 Compare February 17, 2026 16:24

fix(runner): fix typecheck error in hooks.ts by relaxing FixtureProps…

58c9f5b

…Options typing

Ujjwaljain16 force-pushed the feat/merge-tests branch from 57165f3 to 58c9f5b Compare February 17, 2026 16:32

Ujjwaljain16 added 2 commits February 17, 2026 22:02

Merge branch 'main' into feat/merge-tests

8ecefd9

fix(runner): resolve CI regressions and type errors in mergeTests

d71197a

Ujjwaljain16 marked this pull request as ready for review February 17, 2026 17:37

Ujjwaljain16 requested a review from sheremet-va February 17, 2026 17:37

sheremet-va requested changes Feb 18, 2026

View reviewed changes

Ujjwaljain16 added 3 commits February 18, 2026 23:23

refactor(runner): simplify mergeTests implementation and restore base…

ddf97bf

…line architecture

refactor(runner): align FixturePropsOptions with main branch baseline

c39a69e

Merge branch 'upstream/main' into feat/merge-tests

a2f1534

Ujjwaljain16 added 3 commits February 18, 2026 23:54

docs(runner): improve mergeTests JSDoc with more detail

bb33ec0

docs: improve mergeTests documentation with variadic support detail

000fec2

chore: fix linting issues and improve mergeTests JSDoc

1ad69af

Ujjwaljain16 requested a review from sheremet-va February 18, 2026 19:02

sheremet-va requested changes Feb 21, 2026

View reviewed changes

Uh oh!

Comments

Conversation

Ujjwaljain16 commented Feb 14, 2026

Description

Implementation

Override Semantics

Type Support

Tests

Tests

Documentation

Changesets

Uh oh!

Ujjwaljain16 commented Feb 15, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sheremet-va Feb 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Ujjwaljain16 commented Feb 16, 2026

Uh oh!

sheremet-va commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sheremet-va commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Feb 16, 2026

✅ Deploy Preview for vitest-dev ready!

Uh oh!

netlify bot commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for vitest-dev ready!

Uh oh!

sheremet-va left a comment

Choose a reason for hiding this comment

Uh oh!

Ujjwaljain16 commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sheremet-va left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sheremet-va Feb 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sheremet-va Feb 15, 2026 •

edited

Loading

sheremet-va commented Feb 16, 2026 •

edited

Loading

sheremet-va commented Feb 16, 2026 •

edited

Loading

netlify bot commented Feb 16, 2026 •

edited

Loading

Ujjwaljain16 commented Feb 18, 2026 •

edited

Loading

sheremet-va Feb 21, 2026 •

edited

Loading