feat: New test package

.gitignore

@@ -51,6 +51,8 @@ node_modules/
 
 # Build outputs
 dist/
+.astro/
+**/src/env.d.ts
 build/
 .inox-tools/
 *.js.map

docs/astro.config.ts

@@ -75,6 +75,16 @@ export default defineConfig({
 						},
 					],
 				},
+				{
+					label: 'Tools for Authors',
+					collapsed: false,
+					items: [
+						{
+							label: 'Astro Tests',
+							link: '/astro-tests',
+						},
+					],
+				},
 				{
 					label: 'Modular Station',
 					collapsed: false,

docs/src/content/docs/astro-tests.mdx

@@ -0,0 +1,354 @@
+---
+title: Astro Test Utils
+packageName: '@inox-tools/astro-tests'
+description: Utilities for testing your own Astro integrations and libraries based on Astro's own testing tools.
+---
+
+TODO: Some introduction
+
+## How to install
+
+import { PackageManagers } from 'starlight-package-managers';
+
+<PackageManagers dev pkg="@inox-tools/astro-tests" />
+
+## Fixtures
+
+### `config`
+
+<p>**Type:** `AstroConfig`</p>
+
+The final config passed to [Astro's programatic CLI entrypoints](https://docs.astro.build/en/reference/cli-reference/#advanced-apis-experimental). This configuration can be overriden on each method call.
+Will be automatically passed to the methods below:
+
+- [`startDevServer()`](#startdevserver)
+- [`build()`](#build)
+- [`preview()`](#preview)
+- [`sync()`](#sync)
+
+### `startDevServer`
+
+{(
+
+<p>
+	<strong>Type: </strong>
+	<code dir="auto" style="padding-right: 0;">
+		(inlineConfig:
+	</code>
+	<a href="https://docs.astro.build/en/reference/cli-reference/#astroinlineconfig">
+		<code dir="auto" style="padding-right: 0;">
+			AstroInlineConfig
+		</code>
+	</a>
+	<code dir="auto" style="padding-left: 0;">
+		) =&gt; Promise&lt;DevServer&gt;
+	</code>
+</p>
+)}
+
+Starts a dev server at an available port.
+
+This server can't be running at the same time for thein same fixture as .preview() since they share ports.
+Be sure to call devServer.stop() before test exit.
+
+Equivalent to running [`astro dev`](https://docs.astro.build/en/reference/cli-reference/#astro-dev).
+
+### `build`
+
+{(
+
+<p>
+	<strong>Type: </strong>
+	<code dir="auto" style="padding-right: 0;">
+		(inlineConfig:
+	</code>
+	<a href="https://docs.astro.build/en/reference/cli-reference/#astroinlineconfig">
+		<code dir="auto" style="padding-right: 0;">
+			AstroInlineConfig
+		</code>
+	</a>
+	<code dir="auto" style="padding-left: 0;">
+		) =&gt; Promise&lt;void&gt;
+	</code>
+</p>
+)}
+
+Builds into current folder (will erase previous build).
+
+Equivalent to running [`astro build`](https://docs.astro.build/en/reference/cli-reference/#astro-build).
+
+### `preview`
+
+{(
+
+<p>
+	<strong>Type: </strong>
+	<code dir="auto" style="padding-right: 0;">
+		(inlineConfig:
+	</code>
+	<a href="https://docs.astro.build/en/reference/cli-reference/#astroinlineconfig">
+		<code dir="auto" style="padding-right: 0;">
+			AstroInlineConfig
+		</code>
+	</a>
+	<code dir="auto" style="padding-left: 0;">
+		) =&gt; Promise&lt;PreviewServer&gt;
+	</code>
+</p>
+)}
+
+Starts a preview server.
+
+This server can't be running at the same time for thein same fixture as .dev() since they share ports.
+Be sure to call server.stop() before test exit.
+
+Equivalent to running [`astro preview`](https://docs.astro.build/en/reference/cli-reference/#astro-preview).
+
+### `sync`
+
+{(
+
+<p>
+	<strong>Type: </strong>
+	<code dir="auto" style="padding-right: 0;">
+		(inlineConfig:
+	</code>
+	<a href="https://docs.astro.build/en/reference/cli-reference/#astroinlineconfig">
+		<code dir="auto" style="padding-right: 0;">
+			AstroInlineConfig
+		</code>
+	</a>
+	<code dir="auto" style="padding-left: 0;">
+		) =&gt; Promise&lt;void&gt;
+	</code>
+</p>
+)}
+
+Synchronizes the Astro project and configuration with the generated code, populating the `src/env.d.ts` file and the `.astro` directory.
+
+Equivalent to running [`astro sync`](https://docs.astro.build/en/reference/cli-reference/#astro-sync).
+
+### `clean`
+
+<p>
+  **Type:** `() => Promise<void>`
+</p>
+
+Deletes the generated files from the fixture directory. Specifically, it deletes:
+
+- The output directory (`outDir` config)
+- The cache directory (`cacheDir` config)
+- The `.astro` directory generated in the project
+- the `.astro` directory generated in the `node_modules`
+
+### `resolveUrl`
+
+<p>**Type:** `(url: string) => string`</p>
+
+Resolves a relative URL to the full url of the running server.
+
+This can only be called after either [`.startDevServer()`](#startdevserver) or [`.preview()`](#preview) is called.
+
+### `fetch`
+
+{(
+
+<p>
+	<strong>Type: </strong>
+	<code dir="auto" style="padding-right: 0;">
+		(url: string, opts?:{' '}
+	</code>
+	<a href="https://developer.mozilla.org/en-US/docs/Web/API/RequestInit">
+		<code dir="auto" style="padding-left: 0;padding-right: 0;">
+			RequestInit
+		</code>
+	</a>
+	<code dir="auto" style="padding-left: 0;padding-right: 0;">
+		) =&gt; Promise&lt;
+	</code>
+	<a href="https://developer.mozilla.org/en-US/docs/Web/API/Response">
+		<code dir="auto" style="padding-left: 0;padding-right: 0;">
+			Response
+		</code>
+	</a>
+	<code dir="auto" style="padding-left: 0;">
+		&gt;
+	</code>
+</p>
+)}
+
+Send a request to the given URL. If the URL is relative, it will be resolved relative to the root of the server (without a base path).
+
+This can only be called after either [`.startDevServer()`](#startdevserver) or [`.preview()`](#preview) is called.
+
+### `pathExists`
+
+<p>**Type:** `(path: string) => boolean`</p>
+
+Checks whether the given path exists on the build output (`outDir` config).
+
+### `readFile`
+
+<p>
+  **Type:** `(path: string) => Promise<string>`
+</p>
+
+Read a file from the build (relative to `outDir` config).
+
+### `editFile`
+
+<p>
+  **Type:** `(path: string, updater: string | ((content: string) => string)) => Promise<() => void>`
+</p>
+
+Edit a file in the fixture directory.
+
+The first parameter is a path relative to the root of the fixture.
+
+The second parameter can be the new content of the file or a function that takes the current content and returns the new content.
+
+This function returns a Promise that resolves to another function. This resolved function can be called to revert the changes.
+
+All changes made with `editFile` are automatically reverted before the [process exits](https://nodejs.org/api/process.html#event-exit).
+
+### `resetAllFiles`
+
+<p>**Type:** `() => void`</p>
+
+Reset all changes made with [`.editFile()`](#editfile)
+
+### `readdir`
+
+<p>
+  **Type:** `(path: string) => Promise<string[]>`
+</p>
+
+Read a directory from the build output (relative to `outDir` config).
+
+This is a convenience wrapper around [readdir from Node's FS Promise API](https://nodejs.org/api/fs.html#fspromisesreaddirpath-options).
+
+### `glob`
+
+<p>
+  **Type:** `(pattern: string) => Promise<string[]>`
+</p>
+
+Find entries in the build output matching the glob pattern.
+
+The glob syntax used is from [`fast-glob`](https://www.npmjs.com/package/fast-glob#pattern-syntax).
+
+### `loadNodeAdapterHandler`
+
+{(
+
+<p>
+	<strong>Type: </strong>
+	<code dir="auto" style="padding-right: 0;">
+		() =&gt; Promise&lt;(req:{' '}
+	</code>
+	<a href="https://nodejs.org/api/http.html#class-httpincomingmessage">
+		<code dir="auto" style="padding-left: 0;padding-right: 0;">
+			http.IncomingMessage
+		</code>
+	</a>
+	<code dir="auto" style="padding-left: 0;padding-right: 0;">
+		, res:{' '}
+	</code>
+	<a href="https://nodejs.org/api/http.html#class-httpserverresponse">
+		<code dir="auto" style="padding-left: 0;padding-right: 0;">
+			http.ServerResponse
+		</code>
+	</a>
+	<code dir="auto" style="padding-left: 0;">
+		) =&gt; void&gt;
+	</code>
+</p>
+)}
+
+Load the handler for an app built using the [Node Adapter](https://docs.astro.build/en/guides/integrations-guide/node/).
+
+The handler is the same as a listener for the [`request` event](https://nodejs.org/api/http.html#event-request) from Node's native HTTP module.
+
+### `loadTestAdapterApp`
+
+<p>
+  **Type:** `() => Promise<TestApp>`
+</p>
+
+#### `TestApp`
+
+```ts
+type TestApp = {
+	render: (req: Request) => Promise<Response>;
+	toInternalApp: () => App;
+};
+```
+
+A minimal proxy to the underlying Astro App using the test adapter.
+
+##### `render`
+
+Renders a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) from the given [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request).
+
+##### `toInternalApp`
+
+Returns the underlying [Astro App](https://github.com/withastro/astro/blob/ca54e3f819fad009ac3c3c8b57a26014a2652a73/packages/astro/src/core/app/index.ts#L77-L518).
+
+:::danger
+This class is internal, undocumented and highly unstable. Use it at your own risk.
+:::
+
+## Test Adapter
+
+An [Astro Adapter](https://docs.astro.build/en/guides/server-side-rendering/) that exposes the rendering process to be called directly.
+
+It also collects information about the build passed to the adapter to be inspected.
+
+None of the options are required.
+
+### `env`
+
+<p>
+  **Type:** `Record<string, string | undefined>`
+</p>
+
+Server-side environment variables to be used by [`astro:env`](https://docs.astro.build/en/reference/configuration-reference/#experimentalenv).
+
+### `setRoutes`
+
+{(
+
+<p>
+	<strong>Type: </strong>
+	<code dir="auto" style="padding-right: 0;">
+		(routes:{' '}
+	</code>
+	<a href="https://docs.astro.build/en/reference/integrations-reference/#routedata-type-reference">
+		<code dir="auto" style="padding-left: 0;padding-right: 0;">
+			RouteData
+		</code>
+	</a>
+	<code dir="auto" style="padding-left: 0;">
+		[]) =&gt; Promise&lt;void&gt;
+	</code>
+</p>
+)}
+
+A callback function that will receive the final value of the project routes.
+
+## Utilities
+
+### No Node checker
+
+A Vite plugin to ensure no module in the final bundle relies on the built-in Node modules.
+
+If the generated bundle contains any reference to a Node module the build will fail.
+
+The checked modules are those from the built-in module list provided as [part of `node:modules`](https://nodejs.org/api/module.html#modulebuiltinmodules), both with an without the `node:` prefix, as well as the [prefix-only modules](https://nodejs.org/api/modules.html#built-in-modules-with-mandatory-node-prefix).
+
+## TODOs
+
+- Send a PR to Astro Docs fixing the signature of the `dev`, `build`, `preview` and `sync` APIs;
+- Send a PR to Astro Docs fixing the documentation of `AstroInlineConfig`;
+- Send a PR to Astro Docs documenting the `DevServer`;
+- Send a PR to Astro Docs documenting the `PreviewServer`;

packages/astro-tests/README.md

@@ -0,0 +1,15 @@
+<p align="center">
+    <img alt="InoxTools" width="350px" src="https://github.com/Fryuni/inox-tools/blob/main/assets/shield.png?raw=true"/>
+</p>
+
+# Astro Test Tools
+
+Test tooling and utilities based on Astro's own internal testing tools.
+
+See [docs](https://inox-tools.fryuni.dev/astro-tests).
+
+## Install
+
+```js
+npm install @inox-tools/astro-tests
+```