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!