.github/ISSUE_TEMPLATE/---01-bug-report.yml

@@ -10,7 +10,7 @@ body:
         Thank you for taking the time to file a bug report! Please fill out this form as completely as possible.
 
         ✅ I am using the **latest version of Astro** and all plugins.
-        ✅ I am using a version of Node that Astro supports (`>=18.14.1`)
+        ✅ I am using a version of Node that Astro supports (`v18.17.1` or `v20.3.0` or higher.)
   - type: textarea
     id: astro-info
     attributes:

.github/renovate.json5

@@ -9,6 +9,7 @@
   ],
   "labels": ["dependencies"],
   "rangeStrategy": "bump",
+  "postUpdateOptions": ["pnpmDedupe"],
   "ignorePaths": ["**/node_modules/**"],
   "ignoreDeps": [
     // manually bumping deps

CONTRIBUTING.md

@@ -12,10 +12,12 @@ We welcome contributions of any size and skill level. As an open source project,
 
 ```shell
 node: "^>=18.17.1"
-pnpm: "^8.6.12"
+pnpm: "^9.3.0"
 # otherwise, your build will fail
 ```
 
+We recommend using Corepack, [read PNPM docs](https://pnpm.io/installation#using-corepack).
+
 ### Setting up your local repo
 
 Astro uses pnpm workspaces, so you should **always run `pnpm install` from the top-level project directory**. Running `pnpm install` in the top-level project root will install dependencies for `astro`, and every package in the repo.
@@ -109,6 +111,53 @@ pnpm run test -m "$STRING_MATCH"
 node --test ./test/foo.test.js
 ```
 
+#### Running a single test
+
+Sometimes you want to run a single test case (`it` or `describe`) or a single test file. You can do so by using Node.js.
+
+To run a single test file, for example `test/astro-basic.test.js`:
+
+```shell
+node --test test/astro-basic.test.js
+```
+
+If you wish to run a single test case, you have to postfix `it` and `describe` functions with `.only`:
+
+```diff
+// test/astro-basic.test.js
+- describe("description", () => {
++ describe.only("description", () => {
+-  it("description", () => {
++  it.only("description", () => {})
+})
+```
+
+Then, you have to pass the `--test-only` option to the Node.js:
+
+```shell
+node --test --test-only test/astro-basic.test.js
+```
+
+> [!WARNING]
+>
+> 1. If you have nested `describe`, all of them must postfix with `.only`
+> 2. `--test-only` and `--test` must be placed **before** declaring the path to the file. Failing to do so will test all files
+
+#### Debugging tests in CI
+
+There might be occasions where some tests fail in certain CI runs due to some timeout issue. If this happens, it will be very difficult to understand which file cause the timeout. That's caused by come quirks of the Node.js test runner combined with our architecture.
+
+To understand which file causes the issue, you can modify the `test` script inside the `package.json` by adding the `--parallel` option:
+
+```diff
+{
+-  "test": "astro-scripts test \"test/**/*.test.js\"",
++  "test": "astro-scripts test --parallel \"test/**/*.test.js\"",
+}
+```
+
+Save the change and **push it** to your PR. This change will make the test CI slower, but it will allow to see which files causes the timeout. Once you fixed the issue **revert the change and push it**.
+
 #### E2E tests
 
 Certain features, like HMR and client hydration, need end-to-end tests to verify functionality in the dev server. [Playwright](https://playwright.dev/) is used to test against the dev server.
@@ -127,6 +176,12 @@ Any tests for `astro build` output should use the main `mocha` tests rather than
 
 If a test needs to validate what happens on the page after it's loading in the browser, that's a perfect use for E2E dev server tests, i.e. to verify that hot-module reloading works in `astro dev` or that components were client hydrated and are interactive.
 
+#### Creating tests
+
+When creating new tests, it's best to reference other existing test files and replicate the same setup. Some other tips include:
+
+- When re-using a fixture multiple times with different configurations, you should also configure unique `outDir`, `build.client`, and `build.server` values so the build output runtime isn't cached and shared by ESM between test runs.
+
 ### Other useful commands
 
 ```shell

README.md

@@ -10,7 +10,7 @@
 
 <div align="center">
 
-![Build Status](https://github.com/withastro/astro/actions/workflows/ci.yml/badge.svg)
+[![CI](https://github.com/withastro/astro/actions/workflows/ci.yml/badge.svg)](https://github.com/withastro/astro/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/withastro/astro/blob/main/LICENSE)
 [![npm version](https://badge.fury.io/js/astro.svg)](https://badge.fury.io/js/astro)
 

examples/basics/package.json

@@ -11,6 +11,6 @@
     "astro": "astro"
   },
   "dependencies": {
-    "astro": "^4.8.7"
+    "astro": "^4.10.3"
   }
 }

examples/blog/package.json

@@ -11,9 +11,9 @@
     "astro": "astro"
   },
   "dependencies": {
-    "@astrojs/mdx": "^3.0.1",
+    "@astrojs/mdx": "^3.1.1",
     "@astrojs/rss": "^4.0.6",
-    "@astrojs/sitemap": "^3.1.5",
-    "astro": "^4.8.7"
+    "@astrojs/sitemap": "^3.1.6",
+    "astro": "^4.10.3"
   }
 }

examples/component/package.json

@@ -15,7 +15,7 @@
   ],
   "scripts": {},
   "devDependencies": {
-    "astro": "^4.8.7"
+    "astro": "^4.10.3"
   },
   "peerDependencies": {
     "astro": "^4.0.0"

examples/container-with-vitest/.codesandbox/Dockerfile

@@ -0,0 +1 @@
+FROM node:18-bullseye

examples/container-with-vitest/.gitignore

@@ -0,0 +1,24 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# jetbrains setting folder
+.idea/

examples/container-with-vitest/README.md

@@ -0,0 +1,11 @@
+# Astro + [Vitest](https://vitest.dev/) + Container API Example
+
+```sh
+npm create astro@latest -- --template container-with-vitest
+```
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/astro/tree/latest/examples/with-vitest)
+[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/astro/tree/latest/examples/with-vitest)
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/withastro/astro?devcontainer_path=.devcontainer/with-vitest/devcontainer.json)
+
+This example showcases Astro working with [Vitest](https://vitest.dev/) and how to test components using the Container API.

examples/container-with-vitest/astro.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'astro/config';
+import react from "@astrojs/react"
+
+// https://astro.build/config
+export default defineConfig({
+	integrations: [react()]
+});

examples/container-with-vitest/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@example/container-with-vitest",
+  "type": "module",
+  "version": "0.0.1",
+  "private": true,
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "astro": "^4.10.3",
+    "@astrojs/react": "^3.6.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "vitest": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/react-dom": "^18.3.0",
+    "@types/react": "^18.3.3"
+  }
+}

examples/container-with-vitest/src/components/Card.astro

@@ -0,0 +1,8 @@
+---
+
+---
+
+<div>
+	This is a card
+	<slot />
+</div>

examples/container-with-vitest/src/components/Counter.jsx

@@ -0,0 +1,14 @@
+import { useState } from 'react';
+
+export default function({ initialCount }) {
+	const [count, setCount] = useState(initialCount || 0);
+	return (
+		<div className="rounded-t-lg overflow-hidden border-t border-l border-r border-gray-400 text-center p-4">
+			<h2 className="font-semibold text-lg">Counter</h2>
+			<h3 className="font-medium text-lg">Count: {count}</h3>
+			<button
+				className="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
+				onClick={() => setCount(count + 1)}>Increment</button>
+		</div>
+	)
+}

examples/container-with-vitest/src/components/ReactWrapper.astro

@@ -0,0 +1,5 @@
+---
+import Counter from './Counter.jsx';
+---
+
+<Counter initialCount={5} />

examples/container-with-vitest/src/pages/[locale].astro

@@ -0,0 +1,20 @@
+---
+export function getStaticPaths() {
+	return [{ params: { locale: 'en' } }];
+}
+const { locale } = Astro.params;
+---
+
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+		<meta name="viewport" content="width=device-width" />
+		<meta name="generator" content={Astro.generator} />
+		<title>Astro</title>
+	</head>
+	<body>
+		<h1>Astro</h1>
+		<p>Locale: {locale}</p>
+	</body>
+</html>

examples/container-with-vitest/src/pages/api.ts

@@ -0,0 +1,11 @@
+export function GET() {
+	const json = {
+		foo: 'bar',
+		number: 1,
+	};
+	return new Response(JSON.stringify(json), {
+		headers: {
+			'content-type': 'application/json',
+		},
+	});
+}

examples/container-with-vitest/src/pages/index.astro

@@ -0,0 +1,16 @@
+---
+
+---
+
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+		<meta name="viewport" content="width=device-width" />
+		<meta name="generator" content={Astro.generator} />
+		<title>Astro</title>
+	</head>
+	<body>
+		<h1>Astro</h1>
+	</body>
+</html>

examples/container-with-vitest/test/Card.test.ts

@@ -0,0 +1,15 @@
+import { experimental_AstroContainer as AstroContainer } from 'astro/container';
+import { expect, test } from 'vitest';
+import Card from '../src/components/Card.astro';
+
+test('Card with slots', async () => {
+	const container = await AstroContainer.create();
+	const result = await container.renderToString(Card, {
+		slots: {
+			default: 'Card content',
+		},
+	});
+
+	expect(result).toContain('This is a card');
+	expect(result).toContain('Card content');
+});

examples/container-with-vitest/test/ReactWrapper.test.ts

@@ -0,0 +1,17 @@
+import { loadRenderers } from 'astro:container';
+import { getContainerRenderer } from '@astrojs/react';
+import { experimental_AstroContainer as AstroContainer } from 'astro/container';
+import { expect, test } from 'vitest';
+import ReactWrapper from '../src/components/ReactWrapper.astro';
+
+const renderers = await loadRenderers([getContainerRenderer()]);
+const container = await AstroContainer.create({
+	renderers,
+});
+
+test('ReactWrapper with react renderer', async () => {
+	const result = await container.renderToString(ReactWrapper);
+
+	expect(result).toContain('Counter');
+	expect(result).toContain('Count: <!-- -->5');
+});

examples/container-with-vitest/test/[locale].test.ts

@@ -0,0 +1,16 @@
+import { experimental_AstroContainer as AstroContainer } from 'astro/container';
+import { expect, test } from 'vitest';
+import Locale from '../src/pages/[locale].astro';
+
+test('Dynamic route', async () => {
+	const container = await AstroContainer.create();
+	// @ts-ignore
+	const result = await container.renderToString(Locale, {
+		params: {
+			locale: 'en',
+		},
+		request: new Request('http://example.com/en'),
+	});
+
+	expect(result).toContain('Locale: en');
+});

examples/container-with-vitest/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "astro/tsconfigs/base"
+}

examples/container-with-vitest/vitest.config.ts

@@ -0,0 +1,9 @@
+/// <reference types="vitest" />
+import { getViteConfig } from 'astro/config';
+
+export default getViteConfig({
+	test: {
+		/* for example, use global to avoid globals imports (describe, test, expect): */
+		// globals: true,
+	},
+});

examples/framework-alpine/package.json

@@ -13,7 +13,7 @@
   "dependencies": {
     "@astrojs/alpinejs": "^0.4.0",
     "@types/alpinejs": "^3.13.10",
-    "alpinejs": "^3.13.10",
-    "astro": "^4.8.7"
+    "alpinejs": "^3.14.0",
+    "astro": "^4.10.3"
   }
 }

examples/framework-lit/package.json

@@ -11,9 +11,9 @@
     "astro": "astro"
   },
   "dependencies": {
-    "@astrojs/lit": "^4.0.1",
+    "@astrojs/lit": "^4.3.0",
     "@webcomponents/template-shadowroot": "^0.2.1",
-    "astro": "^4.8.7",
-    "lit": "^3.1.3"
+    "astro": "^4.10.3",
+    "lit": "^3.1.4"
   }
 }