feat(runtime): add startOn environment option

[yamachi4416]

🔗 Linked issue

this isn't a direct fix, but it now supports the use case in the issue below.
#1496 #1185

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

I explored whether we could mock the modules used in our global middleware using the existing setupFile mechanism that starts the NuxtApp. However, I realized that this approach couldn't support both scenarios: mocking the module when the NuxtApp starts and mocking it after it has already started.

To resolve this, I introduced a new startOn option. This allows us to choose the timing for starting the NuxtApp, which can now be toggled per test file using @vitest-environment-options.

Reproductions

stackblitz for issue 1185
expected: eventBus $on EVENT XXX, the XXX values match, and app.vue - onEvent() is logged.

eventBus $on EVENT 660
eventBus $on EVENT 660
eventBus $emit EVENT 660
app.vue - onEvent() {msg: 'utils/eventBus'}
index.vue - onEvent() {msg: 'utils/eventBus'

[pkg-pr-new]

Open in StackBlitz

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

commit: e71dfc7

[yamachi4416]

I’ve realized there are some points I haven't fully considered yet, so I’ll revert this to a draft for further refinement. My apologies.

[danielroe]

@yamachi4416 are you on Discord or Bluesky/Twitter? would you mind sending me a DM (nothing bad!)?

[yamachi4416]

It turns out that referencing __vitest_worker__ was indeed a hack, and it didn't work in vitest v4...

[yamachi4416]

I wish I could have supported @vitest-environment-options, but I have created a separate issue for that.