From 48aa98294e64a73e4bc71e1fbb6b8e830f23e94a Mon Sep 17 00:00:00 2001
From: Ntale Samad <swamaduntale98@gmail.com>
Date: Thu, 27 Nov 2025 18:30:49 +0300
Subject: [PATCH] docs: document Vitest SSR environment requirement for Astro 6

---
 src/content/docs/en/guides/upgrade-to/v6.mdx | 54 ++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx
index 59b159dff19e9..6fabbf2e45913 100644
--- a/src/content/docs/en/guides/upgrade-to/v6.mdx
+++ b/src/content/docs/en/guides/upgrade-to/v6.mdx
@@ -924,6 +924,60 @@ export function getStaticPaths() {
 
 <ReadMore>Learn more about [dynamic SSG routes with `getStaticPaths()`](/en/guides/routing/#static-ssg-mode).</ReadMore>
 
+### Changed: Testing Astro Components Requires SSR Environment
+
+<SourcePR number="14895" title="feat: remove Vitest workaround for client environment"/>
+
+In Astro 5.x, a temporary workaround allowed rendering `.astro` components in Vitest tests using client environments such as `jsdom` or `happy-dom`.
+
+Astro 6.0 removes this workaround: tests that render Astro components must now use an SSR environment like `node`. This ensures tests run in an environment that matches Astro's SSR build process.
+
+#### Who is affected?
+
+You are affected **only if all three** of these conditions apply:
+- You use Vitest to run tests, **and**
+- You render `.astro` components (typically via the Container API), **and**
+- Your test environment is set to `jsdom` or `happy-dom`
+
+If you don't render Astro components in your tests, or if you already use the `node` environment, no changes are needed.
+
+#### What should I do?
+
+Update your `vitest.config.ts` to use the `node` environment for tests that render Astro components:
+```ts title="vitest.config.ts"
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+  },
+});
+```
+
+If you need to test both Astro components and browser-specific code, use Vitest's workspace configuration to separate them:
+```ts title="vitest.workspace.ts"
+import { defineWorkspace } from 'vitest/config';
+
+export default defineWorkspace([
+  {
+    test: {
+      name: 'astro-components',
+      environment: 'node',
+      include: ['**/*.astro.test.ts'],
+    },
+  },
+  {
+    test: {
+      name: 'browser',
+      environment: 'happy-dom',
+      include: ['**/*.browser.test.ts'],
+    },
+  },
+]);
+```
+
+<ReadMore>Learn more about [testing Astro components with the Container API](/en/guides/testing/).</ReadMore>
+
 ## Community Resources
 
 Know a good resource for Astro v5.0? [Edit this page](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/upgrade-to/v6.mdx) and add a link below!