feat(browser): add render helper for vitest browser mode

[yamachi4416]

🔗 Linked issue

📚 Description

Added a render helper with Suspense support for Vitest Browser Mode on Nuxt.
Initially, I considered wrapping vitest-browser-vue.
However, I decided to implement it on our side instead, as it requires some adjustments and gives us more flexibility.

I would appreciate your feedback.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@nuxt/test-utils@1725

npm i https://pkg.pr.new/vitest-environment-nuxt@1725

commit: 04b509a

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ca7a5b33-3792-4ad5-b2e4-cb6ccc593760

📥 Commits

Reviewing files that changed from the base of the PR and between d8b6a59 and 04b509a.

📒 Files selected for processing (1)

• package.json

🚧 Files skipped from review as they are similar to previous changes (1)

• package.json

---

📝 Walkthrough

Walkthrough

Adds a Nuxt-specific Vitest browser rendering adapter with cleanup, rerendering, locator, container, and unmount support. Extends suspended mounting options and publishes new package entrypoints. Expands the browser example with layouts, pages, composables, runtime configuration, and an API handler. Adds component, page, and workspace browser tests covering rendering, navigation, fetching, mocking, and lifecycle behavior.

Estimated code review effort: 4 (Complex) | ~60 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding a Vitest browser render helper.
Description check	✅ Passed	The description is directly related to the changeset and matches the implemented Vitest Browser Mode render helper.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/app-vitest-browser/app/pages/components/hello.vue`:
- Line 3: The `name` computed property is read-only (getter-only) but is used
with `v-model` on line 11, which requires a writable binding. Modify the `name`
computed property to include a setter function that handles updates to the
value, or alternatively refactor to use a separate `ref` for tracking the name
state while initializing its value from `route.query.name` to maintain the
initial synchronization. The computed property with a setter approach would
allow `v-model` updates to be properly handled while maintaining the route query
synchronization logic.

In `@examples/app-vitest-browser/test/nuxt/components/render-with-fetch.spec.ts`:
- Around line 7-10: The registerEndpoint() call that registers the `/api/hello`
endpoint lacks a corresponding teardown mechanism, leaving the endpoint
registered in the shared registry after the test completes. This causes
cross-test state leakage where the endpoint remains registered for subsequent
tests. Add an afterEach() cleanup hook that unregisters or clears the
`/api/hello` endpoint registration after each test runs to ensure a clean state
between tests and prevent order-dependent test failures.

In `@examples/app-vitest-browser/test/nuxt/components/render.spec.ts`:
- Line 27: The assertion in the render spec test is too strict by matching the
exact JSON string with specific quote marks and spacing in getByText(). Replace
the exact string match with a regex pattern or flexible matcher that tolerates
various whitespace and formatting variations while still validating that the
buildAssetsDir key and /_nuxt/ value are present in the rendered output. This
will prevent false test failures from non-functional formatting changes to the
JSON serialization.

In `@examples/app-vitest-workspace/app3/test/browser/render.spec.ts`:
- Around line 25-27: The 'can rerender' test is currently using `page.render()`
to set up the initial render, which duplicates the page-specific render path
already tested elsewhere and prevents the actual testing of the
`render().rerender()` pattern. Replace the `page.render()` call in this test
with the standard `render()` function to properly initialize the component,
allowing the subsequent `rerender()` call to test the non-page rerender
functionality as intended.

In `@examples/app-vitest-workspace/package.json`:
- Around line 25-27: The package.json is missing an explicit declaration of the
`playwright` dependency which is required as a peer dependency by
`@vitest/browser-playwright@4.1.8`. Although `playwright-core` is present, it
does not satisfy the peer dependency requirement. Add `"playwright": "1.60.0"`
to the devDependencies object in package.json, placing it alongside the existing
entries like `@vitest/browser-playwright`, `happy-dom`, and `playwright-core` to
ensure the required peer dependency is explicitly declared.

In `@package.json`:
- Around line 54-58: The typesVersions entries for "vitest-browser-nuxt" and
"vitest-browser-nuxt/pure" in package.json are pointing to root-level
declaration files (./dist/index.d.mts and ./dist/pure.d.mts), but these files
are actually generated in nested locations under the vitest-browser-nuxt
directory structure. Update the paths for both the "vitest-browser-nuxt" and
"vitest-browser-nuxt/pure" entries in the typesVersions object to point to the
correct nested locations where the declaration files are actually generated
during the build process.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 50490d1a-d8d8-4898-8910-8b8851b22b5c

📥 Commits

Reviewing files that changed from the base of the PR and between e1a0f63 and a041a16.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (33)

• examples/app-vitest-browser/app.vue
• examples/app-vitest-browser/app/app.vue
• examples/app-vitest-browser/app/components/Header.vue
• examples/app-vitest-browser/app/components/MyCounter.vue
• examples/app-vitest-browser/app/components/MyHello.vue
• examples/app-vitest-browser/app/composables/useCounter.ts
• examples/app-vitest-browser/app/composables/useHelloApi.ts
• examples/app-vitest-browser/app/layouts/default.vue
• examples/app-vitest-browser/app/pages/components.vue
• examples/app-vitest-browser/app/pages/components/counter.vue
• examples/app-vitest-browser/app/pages/components/hello.vue
• examples/app-vitest-browser/app/pages/index.vue
• examples/app-vitest-browser/nuxt.config.ts
• examples/app-vitest-browser/server/api/hello.get.ts
• examples/app-vitest-browser/test/nuxt/components/mock-nuxt-import.spec.ts
• examples/app-vitest-browser/test/nuxt/components/mount-suspended.spec.ts
• examples/app-vitest-browser/test/nuxt/components/render-with-fetch.spec.ts
• examples/app-vitest-browser/test/nuxt/components/render.spec.ts
• examples/app-vitest-browser/test/nuxt/components/render.vue.spec.ts
• examples/app-vitest-browser/test/nuxt/pages/render-components-hello.spec.ts
• examples/app-vitest-browser/test/nuxt/pages/render-index.spec.ts
• examples/app-vitest-browser/tsconfig.json
• examples/app-vitest-browser/vitest.config.ts
• examples/app-vitest-workspace/app3/nuxt.config.ts
• examples/app-vitest-workspace/app3/test/browser/render.spec.ts
• examples/app-vitest-workspace/app3/vitest.browser.config.ts
• examples/app-vitest-workspace/app3/vitest.config.ts
• examples/app-vitest-workspace/package.json
• package.json
• src/runtime-utils/utils/suspended.ts
• src/vitest-browser-nuxt/index.ts
• src/vitest-browser-nuxt/pure.ts
• tsdown.config.ts

💤 Files with no reviewable changes (1)

• examples/app-vitest-browser/app.vue

[coderabbitai]

Caution

Failed to replace (edit) comment. This is likely due to insufficient permissions or the comment being deleted.

Error details

{}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/app-vitest-browser/server/api/hello.get.ts`:
- Around line 4-5: The getQuery function does not enforce runtime type
validation, so the name parameter can be undefined, a string, or an array of
strings at runtime, but the code assumes it is always a string. Add a
normalization step after extracting name from the query object to handle these
cases: check if name is undefined or an array, and either provide a default
value (like an empty string or "Guest"), extract the first element if it is an
array, or trim/validate the string value. This ensures the return statement in
the hello.get.ts endpoint always receives a properly handled name value.

In `@package.json`:
- Around line 21-22: The export paths for the "./vitest-browser-nuxt" and
"./vitest-browser-nuxt/pure" subpaths are pointing to dist directories instead
of source directories, which breaks workspace and local development imports
before build artifacts are generated. Change both export paths from
"./dist/vitest-browser-nuxt/..." to "./src/vitest-browser-nuxt/..." to match the
pattern of other top-level exports, allowing the publishConfig.exports to handle
the dist paths for published versions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a58936ad-9640-45f3-ac90-9a68f7d81022

📥 Commits

Reviewing files that changed from the base of the PR and between 1242c5f and fb97146.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (33)

• examples/app-vitest-browser/app.vue
• examples/app-vitest-browser/app/app.vue
• examples/app-vitest-browser/app/components/Header.vue
• examples/app-vitest-browser/app/components/MyCounter.vue
• examples/app-vitest-browser/app/components/MyHello.vue
• examples/app-vitest-browser/app/composables/useCounter.ts
• examples/app-vitest-browser/app/composables/useHelloApi.ts
• examples/app-vitest-browser/app/layouts/default.vue
• examples/app-vitest-browser/app/pages/components.vue
• examples/app-vitest-browser/app/pages/components/counter.vue
• examples/app-vitest-browser/app/pages/components/hello.vue
• examples/app-vitest-browser/app/pages/index.vue
• examples/app-vitest-browser/nuxt.config.ts
• examples/app-vitest-browser/server/api/hello.get.ts
• examples/app-vitest-browser/test/nuxt/components/mock-nuxt-import.spec.ts
• examples/app-vitest-browser/test/nuxt/components/mount-suspended.spec.ts
• examples/app-vitest-browser/test/nuxt/components/render-with-fetch.spec.ts
• examples/app-vitest-browser/test/nuxt/components/render.spec.ts
• examples/app-vitest-browser/test/nuxt/components/render.vue.spec.ts
• examples/app-vitest-browser/test/nuxt/pages/render-components-hello.spec.ts
• examples/app-vitest-browser/test/nuxt/pages/render-index.spec.ts
• examples/app-vitest-browser/tsconfig.json
• examples/app-vitest-browser/vitest.config.ts
• examples/app-vitest-workspace/app3/nuxt.config.ts
• examples/app-vitest-workspace/app3/test/browser/render.spec.ts
• examples/app-vitest-workspace/app3/vitest.browser.config.ts
• examples/app-vitest-workspace/app3/vitest.config.ts
• examples/app-vitest-workspace/package.json
• package.json
• src/runtime-utils/utils/suspended.ts
• src/vitest-browser-nuxt/index.ts
• src/vitest-browser-nuxt/pure.ts
• tsdown.config.ts

💤 Files with no reviewable changes (1)

• examples/app-vitest-browser/app.vue

✅ Files skipped from review due to trivial changes (1)

• examples/app-vitest-browser/vitest.config.ts

🚧 Files skipped from review as they are similar to previous changes (29)

• examples/app-vitest-browser/test/nuxt/components/mount-suspended.spec.ts
• examples/app-vitest-browser/app/composables/useCounter.ts
• examples/app-vitest-workspace/app3/vitest.browser.config.ts
• examples/app-vitest-browser/nuxt.config.ts
• examples/app-vitest-browser/app/components/Header.vue
• examples/app-vitest-browser/tsconfig.json
• examples/app-vitest-browser/app/layouts/default.vue
• examples/app-vitest-browser/test/nuxt/pages/render-index.spec.ts
• src/runtime-utils/utils/suspended.ts
• examples/app-vitest-browser/test/nuxt/components/render.spec.ts
• examples/app-vitest-browser/app/pages/index.vue
• examples/app-vitest-browser/app/components/MyCounter.vue
• examples/app-vitest-workspace/app3/vitest.config.ts
• examples/app-vitest-workspace/app3/nuxt.config.ts
• examples/app-vitest-browser/app/app.vue
• examples/app-vitest-browser/app/components/MyHello.vue
• tsdown.config.ts
• examples/app-vitest-browser/app/composables/useHelloApi.ts
• examples/app-vitest-workspace/app3/test/browser/render.spec.ts
• examples/app-vitest-browser/app/pages/components.vue
• examples/app-vitest-browser/app/pages/components/hello.vue
• examples/app-vitest-browser/test/nuxt/components/render.vue.spec.ts
• examples/app-vitest-browser/test/nuxt/components/render-with-fetch.spec.ts
• examples/app-vitest-browser/test/nuxt/pages/render-components-hello.spec.ts
• examples/app-vitest-browser/app/pages/components/counter.vue
• examples/app-vitest-workspace/package.json
• src/vitest-browser-nuxt/pure.ts
• src/vitest-browser-nuxt/index.ts
• examples/app-vitest-browser/test/nuxt/components/mock-nuxt-import.spec.ts

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/vitest-browser-nuxt/pure.ts`:
- Around line 84-90: The render options are being mutated inside
`overrideOptionsFn`, which causes `options.attachTo` to persist on the caller’s
object and break later `render(...)` calls. Update
`wrapperSuspended`/`overrideOptionsFn` in `pure.ts` so `attachTo` is applied to
a local copy of the options (or passed separately) instead of writing back into
the original `options` object, while preserving the existing `container` and
`baseElement` resolution logic.
- Around line 16-18: The ComponentProps type in pure.ts uses invalid rest
parameter syntax with ...args: never in both conditional branches; update both
occurrences to use an array/tuple type such as never[] so the type alias
type-checks correctly. Locate the change in the ComponentProps<T> definition and
keep the rest of the conditional logic unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e07a30b8-5cfe-4ce9-860f-4ed95f7f39fa

📥 Commits

Reviewing files that changed from the base of the PR and between 6a5da8d and 344b574.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (2)

• package.json
• src/vitest-browser-nuxt/pure.ts