Feature request: Support `wrapper` option in `mount()` to wrap component under test

[Jungzl]

Is your feature request related to a problem? Please describe.

Currently, when testing Vue components that depend on context providers (e.g., <Suspense>, <RouterView>, pinia stores, or custom provide/inject wrappers), users must manually create a wrapper component via defineComponent + h() to wrap the component under test:

const Wrapped = defineComponent({
  render() {
    return h(MyProvider, null, { default: () => h(Component) })
  }
})
mount(Wrapped)

This is boilerplate-heavy and inconsistent with the ergonomics of other framework testing tools that support a native wrapper pattern.

Describe the solution you'd like

Add a wrapper option to mount() that accepts either a Vue component or a render function:

// Form 1: component object
mount(Component, {
  wrapper: MyProvider,
})

// Form 2: render function — allows passing props to the wrapper
mount(Component, {
  wrapper: ({ default: defaultSlot }) =>
    h(MyProvider, { theme: 'dark' }, { default: defaultSlot }),
})

When a component object is provided, it is rendered with the target component as its default slot:

// Equivalent to:
h(MyProvider, null, { default: () => h(Component) })

When a render function is provided, it receives the target component's default slot and returns a VNode — giving full control over wrapper props and slot composition.

Describe alternatives you've considered

No response

Additional context

This pattern is already well-established in other testing ecosystems:

• React Testing Library: render(<Component />, { wrapper: MyProvider })
• Svelte Testing Library: recently added wrapper support
  feat: add wrapper option testing-library/svelte-testing-library#492
  render(Component, {}, { wrapper: Wrapper, wrapperProps: {...} })

Having this in VTU would directly enable vitest-browser-vue to expose the same wrapper option without needing to construct a wrapper component inline via defineComponent + h(). Since vitest-browser-vue's render() delegates to mount(), a VTU-level wrapper would be a natural fit — just pass through the option and let VTU handle the rest.

[cexbrayat]

Hi @Jungzl

Thanks for the feature request.

My initial feeling is that this is more likely something for Vue Testing Library to support than for Vue Test Utils itself.

For most use cases, mount already provides the lower-level primitives needed here: plugins, provide/inject, slots, global config, and so on. So I’m personally reluctant to add another mount option for what currently looks like a fairly niche use case, especially given the long-term API and maintenance burden.

That said, I’ll keep the feature request open and we can revisit if we see more interest or more concrete use cases where the existing options are not enough.

[Jungzl]

Thanks for your response!

I actually raised the same feature request in vue-testing-library earlier: testing-library/vue-testing-library#331

However, vitest-browser-vue does not use vue-testing-library — it calls mount() from VTU directly as its render primitive. So even if vue-testing-library added a wrapper option, it wouldn't help vitest-browser-vue users. The only way for vitest-browser-vue to expose a wrapper option without maintaining its own defineComponent + h() boilerplate would be for VTU's mount() to support it natively.

[levrik]

I'm also currently blocked by this. While I can manually wrap things, it makes wrapper methods (https://test-utils.vuejs.org/api/#Wrapper-methods) point to the wrapping component, not the one I'm actually testing. Re-wiring that stuff manually is error prone and an wrapper option within VTU would be appreciated. Also other libraries like vitest-browser-vue and vue-testing-library could easily build on top like this without having to figure out this stuff on their own.

My use-case is a dialog manager I built which needs to wrap the whole app so it can provide context for a composable while also being able to render dialogs. This is done from the wrapping component.

On app-level:

<DialogManager>
  ... rest of the app ...
</DialogManager>

And in some component:

const dialog = useDialog(DialogComponent);
dialog.show();