feat(experimental): support merge reports for non-sharded multi-environment runs (take 2)

[hi-ogawa]

Description

• Closes Support merging reports for non-sharded multi-environment runs #9954
• Closes feat: support merge reports for non-sharded multi-environment runs #9967 (supersedes)

Alternative take for #9967 (comment)

Usage example

Set --label when creating blobs:

vitest run --reporter=blob --label=linux
vitest run --reporter=blob --label=macos

Or via test config:

// vitest.config.ts
export default defineConfig({
  test: {
    label: process.platform
    reporters: ['blob'],
  },
})

The label is included in the default blob filename (blob-linux.json) to avoid collisions. When merging, each labeled run is shown separately:

$ vitest --merge-reports
 ✓  linux  src/basic.test.ts (2 tests)
 ✓  macos  src/basic.test.ts (2 tests)

How it works

test.label is a core config option — not a blob reporter option. It generalizes the existing __typecheck__ pattern: createFileTask salts File.id with the label and stores it in File.meta.label. State deduplication treats (filepath, projectName, meta.typecheck, meta.label) as the identity key, so same-filepath files with different labels coexist naturally — with no changes to readBlobs, no project cloning, and no ID rewriting at merge time.

The blob reporter uses the label only for one thing: deriving the default output filename as blob-(label)-(shard).json.

Reporters read meta.label and display a badge at all times — not just during --merge-reports. A run with --label=linux will show the badge live as tests execute, in the same way a run with a named project shows the project badge. --merge-reports is simply the context where having multiple labeled runs side-by-side becomes useful.

The difference from #9967

Concern	#9967 (label as project.name)	This PR (label as File.meta)
Mechanism	Clone TestProject per label at read time	Salt File.id + File.meta.label during test run
readBlobs changes	Significant — label discovery, ID rewrite, env module rewrite	None
file.projectName	Mutated to include label	Unchanged
Pattern	Browser-mode clone pattern	__typecheck__ generalization
Config option	[["blob", { label }]] reporter option	test.label top-level option

Demo

I setup CI to upload html reports for test/cli and test/core. It's viewable on newly introduced viewer #10023.

https://viewer.vitest.dev/?url=https://github.com/vitest-dev/vitest/actions/runs/23789865129/artifacts/6196385971

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• It's really useful if your PR references an issue where it is discussed ahead of time. If the feature is substantial or introduces breaking changes without a discussion, PR might be closed.
• Ideally, include a test that fails without this PR but passes with it.
• Please, don't make changes to pnpm-lock.yaml unless you introduce a new test example.
• Please check Allow edits by maintainers to make review process faster. Note that this option is not available for repositories that are owned by Github organizations.

Tests

• Run the tests with pnpm test:ci.

Documentation

• If you introduce new functionality, document it. You can run documentation with pnpm run docs command.

Changesets

• Changes in changelog are generated from PR name. Please, make sure that it explains your changes in an understandable manner. Please, prefix changeset messages with feat:, fix:, perf:, docs:, or chore:.

[netlify]

✅ Deploy Preview for vitest-dev ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	8a88777
🔍 Latest deploy log	https://app.netlify.com/projects/vitest-dev/deploys/69d5ac16afba1400085652a7
😎 Deploy Preview	https://deploy-preview-10031--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.

[Copilot]

Pull request overview

Adds a first-class test.label concept to disambiguate identical test files across multiple environment runs (e.g. OS/Node matrix) so blob reports can be merged without collisions, and makes reporters/UI surface that label consistently.

Changes:

• Introduces test.label config + --label CLI option, propagating it into serialized config and TaskMeta.
• Salts file IDs with { typecheck, label } via generateFileHash/createFileTask, and updates state deduplication to treat (filepath, projectName, meta.typecheck, meta.label) as the identity.
• Updates blob reporter default filenames, default/summary reporters, UI, docs, tests, and CI workflow to generate/merge labeled blob reports.

Reviewed changes

Copilot reviewed 37 out of 37 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
test/test-utils/index.ts	Extends error tree helpers to optionally key modules by label for merge-report assertions.
test/core/vite.config.ts	Emits blob reports in CI when a label env var is set and passes test.label.
test/cli/vitest.config.ts	Emits blob reports in CI when a label env var is set and passes test.label.
test/cli/test/test-specifications.test.ts	Updates parametrized test API usage and expected stable IDs.
test/cli/test/reporters/merge-reports.test.ts	Adds merge-reports coverage for labeled runs (and projects+labels).
test/cli/test/reporters/__snapshots__/html.test.ts.snap	Updates snapshot to new hashed task IDs.
test/cli/test/reported-tasks.test.ts	Updates expectations for new hashed test specification IDs.
packages/ws-client/src/state.ts	Aligns file deduplication key with (projectName, typecheck, label) for WS client state.
packages/vitest/src/types/global.ts	Adds label?: string to TaskMeta typing.
packages/vitest/src/typecheck/collect.ts	Uses createFileTask to unify ID/meta generation for typecheck collection.
packages/vitest/src/runtime/config.ts	Adds label to serialized runtime config shape.
packages/vitest/src/node/types/config.ts	Adds label to InlineConfig and resolved config typing.
packages/vitest/src/node/test-specification.ts	Allows hashing specs with { typecheck, label } meta.
packages/vitest/src/node/state.ts	Updates file collection deduplication to include meta.label.
packages/vitest/src/node/reporters/summary.ts	Displays label badge in the summary reporter output.
packages/vitest/src/node/reporters/blob.ts	Includes label in default blob filename to avoid collisions.
packages/vitest/src/node/reporters/base.ts	Displays label badge in default reporter prefixes and failure headers.
packages/vitest/src/node/project.ts	Propagates root vitest label into project resolved config and spec creation API.
packages/vitest/src/node/core.ts	Preserves file meta (incl. label) when creating specifications during merge-reports replay.
packages/vitest/src/node/config/serializeConfig.ts	Serializes label into worker/runtime config.
packages/vitest/src/node/cli/cli-config.ts	Adds --label <label> CLI option.
packages/ui/client/composables/explorer/utils.ts	Stores file label into UI explorer tree nodes.
packages/ui/client/composables/explorer/types.ts	Extends FileTreeNode with optional label.
packages/ui/client/components/views/ViewTestReport.vue	Treats label as a well-known meta field in the report view.
packages/ui/client/components/FileDetails.vue	Displays a label badge in file details header.
packages/ui/client/components/explorer/ExplorerItem.vue	Displays a label badge next to file items in explorer.
packages/ui/client/components/explorer/Explorer.vue	Wires label into explorer item props.
packages/runner/src/utils/collect.ts	Salts file hashes with { typecheck, label } and plumbs meta through createFileTask.
packages/runner/src/types/runner.ts	Adds label to runner config typing.
packages/runner/src/collect.ts	Passes config.label into createFileTask meta during collection.
docs/guide/reporters.md	Documents using --label for multi-environment blob merges.
docs/guide/improving-performance.md	Updates CI sharding example to include labels and avoid artifact collisions.
docs/guide/cli.md	Notes default blob output path includes shard + label.
docs/guide/cli-generated.md	Adds generated CLI docs entry for --label.
docs/config/label.md	New config reference page for test.label.
docs/.vitepress/config.ts	Adds label to config nav.
.github/workflows/ci.yml	Uploads labeled blob artifacts per matrix entry and adds a merge-reports job producing HTML.

[sheremet-va]

I like the approach, but I feel like meta.label might be too generic. Typecheck is a static one where users can't even modify meta, and in benchmark you don't have access to meta.

Should we make it more internal to avoid clashes with user meta? It could also be removed from json.meta: #10078

[hi-ogawa]

Agree meta.label can definitely crash. I'll rename it to sound like something vitest owned.

[hi-ogawa]

Hash was aligned so pre-parse mode was broken. I consolidated ast-collect with the same createFileTask from runner package.

[hi-ogawa]

We discussed that

• receive the label via blob reporter option ['blob', { label: ... }]
• stash this as core level internal config by extracting it during resolveConfig
• during the original test run, this label shouldn't show up as label for builtin reporters.