From 48aa98294e64a73e4bc71e1fbb6b8e830f23e94a Mon Sep 17 00:00:00 2001 From: Ntale Samad Date: Thu, 27 Nov 2025 18:30:49 +0300 Subject: [PATCH 1/6] 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() { Learn more about [dynamic SSG routes with `getStaticPaths()`](/en/guides/routing/#static-ssg-mode). +### Changed: Testing Astro Components Requires SSR 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'], + }, + }, +]); +``` + +Learn more about [testing Astro components with the Container API](/en/guides/testing/). + ## 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! From 3bd46e857e053d4a93e1e62bb0a1831c10aeb2ef Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Fri, 19 Dec 2025 08:52:25 -0400 Subject: [PATCH 2/6] update title Co-authored-by: Florian Lefebvre --- src/content/docs/en/guides/upgrade-to/v6.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 01214419ed5ee..d0a45d902fb6f 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -1242,7 +1242,7 @@ export function getStaticPaths() { Learn more about [dynamic SSG routes with `getStaticPaths()`](/en/guides/routing/#static-ssg-mode). -### Changed: Testing Astro Components Requires SSR Environment +### Changed: Astro components cannot be rendered in Vitest client environments (Container API) From f43ac1ef0e7e596b4de26ccb5d21080ea0150f0e Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Fri, 19 Dec 2025 11:06:01 -0400 Subject: [PATCH 3/6] Apply Florian's suggestions to conform to existing style patterns Co-authored-by: Florian Lefebvre --- src/content/docs/en/guides/upgrade-to/v6.mdx | 22 ++++++-------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index d0a45d902fb6f..798f98e5067d6 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -1246,27 +1246,17 @@ export function getStaticPaths() { -In Astro 5.x, a temporary workaround allowed rendering `.astro` components in Vitest tests using client environments such as `jsdom` or `happy-dom`. +In Astro 5.x, rendering an Astro component on the client was forbidden. However we temporarily allowed this behavoir in Vitest client environments such as `jsdom` or `happy-dom` using the [experimental Container API](/en/reference/container-reference/). -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. +Astro 6.0 removes the ability to render Astro components in Vitest client environments: tests that render Astro components must now run in a server environment like `node`. -#### 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" +If you use Vitest to run tests that render Astro components in client environments like `jsdom` or `happy-dom`, update your Vitest config to use the `node` environment for these: +```ts title="vitest.config.ts" del={5} ins={6} import { defineConfig } from 'vitest/config'; export default defineConfig({ test: { + environment: 'jsdom', environment: 'node', }, }); @@ -1294,7 +1284,7 @@ export default defineWorkspace([ ]); ``` -Learn more about [testing Astro components with the Container API](/en/guides/testing/). +Learn more about [testing Astro components with Vitest and the Container API](/en/guides/testing/#vitest-and-container-api). ### Changed: Integration hooks and HMR access patterns (Integration API) From 290fe02c3a2b24e7e3d81da03f9c5b685011abe9 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Fri, 19 Dec 2025 11:08:53 -0400 Subject: [PATCH 4/6] more general link for more info --- src/content/docs/en/guides/upgrade-to/v6.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 798f98e5067d6..b8f060f4e4075 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -1284,7 +1284,7 @@ export default defineWorkspace([ ]); ``` -Learn more about [testing Astro components with Vitest and the Container API](/en/guides/testing/#vitest-and-container-api). +Learn more about [testing Astro components](/en/guides/testing/). ### Changed: Integration hooks and HMR access patterns (Integration API) From 4b982e8ba965dc79595457f39492b784f97c32ff Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Fri, 19 Dec 2025 13:29:05 -0400 Subject: [PATCH 5/6] remove example since workspaces are deprecated, and are not the only option people might be using --- src/content/docs/en/guides/upgrade-to/v6.mdx | 22 -------------------- 1 file changed, 22 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index b8f060f4e4075..65764fd90ab18 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -1262,28 +1262,6 @@ export default defineConfig({ }); ``` -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'], - }, - }, -]); -``` - Learn more about [testing Astro components](/en/guides/testing/). ### Changed: Integration hooks and HMR access patterns (Integration API) From 0ca28a745f59ce88a16c6ae2bb7b9b6fe6677f09 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Fri, 19 Dec 2025 13:29:38 -0400 Subject: [PATCH 6/6] add missing what should I do back in --- src/content/docs/en/guides/upgrade-to/v6.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/content/docs/en/guides/upgrade-to/v6.mdx b/src/content/docs/en/guides/upgrade-to/v6.mdx index 65764fd90ab18..ddadbcdc0711b 100644 --- a/src/content/docs/en/guides/upgrade-to/v6.mdx +++ b/src/content/docs/en/guides/upgrade-to/v6.mdx @@ -1250,6 +1250,8 @@ In Astro 5.x, rendering an Astro component on the client was forbidden. However Astro 6.0 removes the ability to render Astro components in Vitest client environments: tests that render Astro components must now run in a server environment like `node`. +#### What should I do? + If you use Vitest to run tests that render Astro components in client environments like `jsdom` or `happy-dom`, update your Vitest config to use the `node` environment for these: ```ts title="vitest.config.ts" del={5} ins={6} import { defineConfig } from 'vitest/config';