@evertondgn/solid-tooling 0.1.0 → 0.3.0

package/README.md

@@ -1,21 +1,57 @@
 # @evertondgn/solid-tooling
 
-Lint, formatador e base do TypeScript para aplicações SolidJS construídas com
-Vite+. O pacote é distribuído compilado: o Node recusa TypeScript dentro de
-`node_modules`, e o Vite+ carrega a configuração em Node.
+Lint preset, formatter config, TypeScript configs and test configs for SolidJS 2
+applications built with [Vite+](https://viteplus.dev/guide/).
 
-## Instalação
+The package contains the lint, format, TypeScript and test setup of
+[boilerplate_solidjs](https://github.com/everton-dgn/boilerplate_solidjs), a
+SolidJS application template. Applications created from it install the package
+instead of copying the files, so a rule change reaches them through a version
+update.
+
+## Requirements
+
+The application installs three packages next to this one:
+
+| Package                | Why                                                         |
+| ---------------------- | ----------------------------------------------------------- |
+| `vite-plus`            | Runs lint and format, and provides the Oxlint plugin API    |
+| `@inlang/paraglide-js` | The preset registers its lint plugin, resolved from the app |
+| `typescript`           | The preset turns on type-aware linting and type checking    |
+
+`vite-plus` and `@inlang/paraglide-js` are peer dependencies, pinned to the
+exact versions the package is tested with. Install the versions listed in its
+`peerDependencies`. `typescript` is not a peer dependency: the package is tested
+with the version in its `devDependencies`.
+
+`eslint-plugin-solid` comes with the package, so the application does not
+declare it.
+
+The test entries need the test tools the application already runs:
+
+| Entry          | The application installs                                                       |
+| -------------- | ------------------------------------------------------------------------------ |
+| `./vitest`     | `@vitest/browser-playwright`, `@vitest/coverage-v8`, `happy-dom`, `playwright` |
+| `./playwright` | `@playwright/test`, an optional peer dependency pinned like the others         |
+
+## Install
+
+`vp` is the Vite+ CLI. An application built with Vite+ already has `vite-plus`
+and `typescript`, so it only adds this package:
 
 ```bash
 vp add -D @evertondgn/solid-tooling
 ```
 
-A aplicação também declara o `vite-plus` e o `@inlang/paraglide-js`. O Oxlint
-resolve os plugins a partir da configuração da aplicação, e o plugin do
-Paraglide precisa acompanhar a versão que ela usa. O `eslint-plugin-solid` vem
-como dependência do pacote e dispensa declaração.
+An application without `@inlang/paraglide-js` adds it too, in the version the
+package asks for:
 
-## Uso
+```bash
+npm view @evertondgn/solid-tooling peerDependencies
+vp add -D @inlang/paraglide-js@<version>
+```
+
+## Usage
 
 ```ts
 // vite.config.ts
@@ -29,25 +65,296 @@ export default defineConfig({ fmt, lint })
 ```json
 // tsconfig.json
 {
-  "extends": "@evertondgn/solid-tooling/tsconfig.base.json"
+  "extends": "@evertondgn/solid-tooling/tsconfig.base.json",
+  "compilerOptions": {
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["src", "vite.config.ts"]
+}
+```
+
+`vp check`, `vp lint` and `vp fmt` read both configs from `vite.config.ts`.
+
+## Tests
+
+`solidTest` returns the `test` block of `vite.config.ts`, with three Vitest
+projects:
+
+| Project   | Files                            | Environment                                      |
+| --------- | -------------------------------- | ------------------------------------------------ |
+| `node`    | `src/**/*.node.test.{ts,tsx}`    | Node, with stand-ins for the build-only modules  |
+| `dom`     | `src/**/*.dom.test.{ts,tsx}`     | happy-dom at `http://localhost/en`               |
+| `browser` | `src/**/*.browser.test.{ts,tsx}` | Chromium through Playwright, with the CSS loaded |
+
+```ts
+// vite.config.ts
+import { solidTest } from '@evertondgn/solid-tooling/vitest'
+
+export default defineConfig({
+  test: solidTest({ root: import.meta.dirname, plugins: componentPlugins })
+})
+```
+
+`plugins` is a function that returns the Vite plugins the `dom` and `browser`
+projects need to compile components: Solid, routes, icons and i18n. The preset
+calls it once per project, because each project starts its own Vite server and a
+plugin instance keeps the state of one server. The preset also sets the coverage
+thresholds, the reporters and the workers on CI, passes `BASE_URL_TEST`, `HOST`
+and `PORT` to the tests when they are set, and resets the Paraglide locale
+before each browser test.
+
+The `node` project does not load the Solid and routing plugins, so a plugin of
+the preset serves `server-only`, `virtual:file-routes` and
+`virtual:solid-server-function-handler`. Knip does not know `server-only`, a
+virtual module of `@solidjs/vite-plugin`: list it in `ignoreDependencies`.
+
+`definePlaywrightConfig` builds the Playwright config from the application root:
+
+```ts
+// playwright.config.ts
+import { definePlaywrightConfig } from '@evertondgn/solid-tooling/playwright'
+
+export default definePlaywrightConfig({ root: import.meta.dirname })
+```
+
+It reads `BASE_URL_TEST` from `.env.test`, builds the application (`e2e` mode
+for the fixture routes, `production` with `TEST_PRODUCTION_ROUTES=true`), starts
+the preview, and checks the server log for private markers when the suite ends.
+`TEST_PREBUILT=true` reuses an existing production build.
+
+| Option           | Default           | Use                                                                    |
+| ---------------- | ----------------- | ---------------------------------------------------------------------- |
+| `testDir`        | `src/tests/pages` | Folder of the `*.e2e.test.ts` files                                    |
+| `fixtureServers` | none              | Extra servers for the fixture routes, as `{ command, url }`            |
+| `suites`         | none              | Globs of serial suites: `serverLogs`, `markdown` and `publicationLoad` |
+
+Each serial suite gets its own project: `markdown` runs with one worker,
+`serverLogs` runs last as the teardown of the others, and `publicationLoad` runs
+alone, against two servers, with `TEST_PUBLICATION_LOAD=true`.
+
+## Project layout the preset expects
+
+The rules match file paths relative to the folder where lint runs, so run it
+from the application root. They know these locations:
+
+| Path                                          | Meaning                                                  |
+| --------------------------------------------- | -------------------------------------------------------- |
+| `src/`                                        | Application code. The `@/` alias points here             |
+| `src/routes/`                                 | Pages. Each page may have a `seo.ts` module              |
+| `src/components/{atoms,molecules,organisms}/` | UI layers                                                |
+| `src/primitives/`                             | Shared primitives                                        |
+| `src/infra/server/`                           | Backend adapters and server error handling               |
+| `src/theme/`                                  | Global CSS                                               |
+| `src/tests/pages/<Page>/`                     | End-to-end tests, one folder per page                    |
+| `paraglide/`                                  | Generated i18n modules. The `@paraglide/` alias          |
+| `tooling/`                                    | Project scripts and their tests, written for `node:test` |
+
+An application with another layout can still use the preset, but it has to
+override the rules that do not fit. See
+[Changing the preset](#changing-the-preset).
+
+## What the lint preset turns on
+
+- Oxlint plugins: `import`, `jsx-a11y`, `node`, `oxc`, `promise`, `typescript`,
+  `unicorn` and `vitest`.
+- JavaScript plugins: `solid`, `paraglide`, `vite-plus` and the three plugins of
+  this package (`project`, `backend`, `architecture`).
+- Type-aware rules and type checking (`typeAware`, `typeCheck`).
+- Warnings fail the run (`denyWarnings`), and an unused disable directive is an
+  error.
+
+Every rule is listed by name in the preset. No Oxlint category is enabled, so an
+Oxlint update does not add rules on its own.
+
+### Rules of this package
+
+| Rule                                      | What it enforces                                                                                                                                           |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `project/css-modules-import`              | A CSS Module is imported as the default binding `S`                                                                                                        |
+| `project/css-filename`                    | A CSS file imported from `src/` is named `styles.module.css`, or `camelCase.css` inside `src/theme/`                                                       |
+| `project/test-filename`                   | A test file sits in `__tests__` next to its module and is named after it, plus the environment: `Button/__tests__/Button.dom.test.tsx`                     |
+| `project/no-export-list`                  | Exports sit on the declaration. `export { a, b }` is only allowed with `from`                                                                              |
+| `project/seo-module`                      | A route `seo.ts` exports only `seo`. It has no relative value import, no value import from `src/routes/`, no computed `import()` and no `import.meta.glob` |
+| `backend/static-solid-imports`            | No `import()` of `@solidjs/web` or its subpaths                                                                                                            |
+| `backend/static-render-integrity-imports` | No `import()` of the `renderIntegrity` module                                                                                                              |
+| `architecture/layer-imports`              | Lower layers do not import upper ones, and production code does not import tests or `tooling/`                                                             |
+
+These rules read import specifiers as text. They resolve relative paths and the
+`@/`, `@paraglide/` and `/src/` prefixes. An `import()` with a computed path and
+any other alias are not checked, except in `seo.ts`, where a computed `import()`
+is an error.
+
+`architecture/layer-imports` checks these directions:
+
+- The base layer (`src/@types`, `constants`, `helpers`, `data`, `infra`,
+  `theme`, `i18n` and `paraglide/`) does not import primitives, components,
+  routes or entry files.
+- `src/primitives` does not import components, routes or entry files.
+- Atoms do not import molecules or organisms, and molecules do not import
+  organisms.
+- No production file imports a test or `tooling/`.
+
+The entry files are `App`, `Document`, `entry-server`, `entry-client`, `router`
+and `middleware`, at the root of `src/`.
+
+`project/test-filename` accepts these names:
+
+- `Name.<environment>.test.ts(x)` in `src/`, where the environment is `node`,
+  `dom`, `browser` or `e2e`.
+- `Name.test-d.ts(x)` in `src/`, for type tests.
+- `Name.test.ts` in `tooling/`.
+
+`Name` is the folder that holds `__tests__`. A qualifier may follow it:
+`Button.focus.dom.test.tsx`. End-to-end tests are the exception: they live in
+`src/tests/pages/<Page>/` and are named after the page.
+
+### Backend restrictions
+
+Inside `src/`, the preset also restricts what code can reach:
+
+- `console` is not allowed. `src/infra/server/logServerFailure/index.ts` is the
+  only module that may call `console.error`.
+- `fetch`, `XMLHttpRequest`, `WebSocket` and `EventSource` are not allowed.
+  `src/infra/server/requestJson/index.ts` is the only module that may call
+  `fetch`.
+- The Node transports (`http`, `https`, `http2`, `net`, `tls`, `undici`) cannot
+  be imported.
+- `markSafeError` and `SAFE_ERROR` can only be imported in
+  `src/infra/server/publicErrors/index.ts`.
+- `configureServerErrors` from `@solidjs/web`, the
+  `@solidjs/web/server-functions` subpath and `observeRenderFailures` from the
+  application's `renderIntegrity` module can only be imported in
+  `src/infra/server/configureServerErrors/index.ts`.
+- A relative import goes up at most three levels. Use `@/` beyond that.
+
+Test files and `.d.ts` files are exempt from all of these except the relative
+import limit.
+
+## Changing the preset
+
+`lint` and `fmt` are plain objects. Spread them and replace what the application
+needs:
+
+```ts
+// vite.config.ts
+import { fmt } from '@evertondgn/solid-tooling/fmt'
+import { lint } from '@evertondgn/solid-tooling/lint'
+import { defineConfig } from 'vite-plus'
+
+export default defineConfig({
+  fmt,
+  lint: {
+    ...lint,
+    ignorePatterns: [...(lint.ignorePatterns ?? []), 'generated/**'],
+    rules: { ...lint.rules, 'eslint/max-params': 'off' }
+  }
+})
+```
+
+Do not replace `lint.jsPlugins`. It registers the JavaScript plugins listed
+above, and a rule whose plugin is missing from it fails to resolve.
+
+To turn a rule off for some files only, add an entry to `lint.overrides` and
+keep the existing ones:
+
+```ts
+overrides: [
+  ...(lint.overrides ?? []),
+  {
+    files: ['src/tests/pages/Checkout/**'],
+    rules: { 'project/test-filename': 'off' }
+  }
+]
+```
+
+## Entry points
+
+| Entry                    | Content                                                                   |
+| ------------------------ | ------------------------------------------------------------------------- |
+| `./lint`                 | `lint`: the lint preset, with the plugins below registered                |
+| `./fmt`                  | `fmt`: the formatter config                                               |
+| `./tsconfig.base.json`   | Compiler options, without application paths                               |
+| `./tsconfig.app.json`    | The base plus the `types` and `include` of the boilerplate layout         |
+| `./vitest`               | `solidTest(options)`, the `test` block of `vite.config.ts`                |
+| `./playwright`           | `definePlaywrightConfig(options)`, the Playwright config                  |
+| `./vitest-setup/browser` | Setup file of the browser project, loaded by `./vitest`                   |
+| `./playwright-teardown`  | Server log check, loaded by `./playwright`                                |
+| `./project-plugin`       | The `project` rules                                                       |
+| `./backend-plugin`       | The `backend` rules                                                       |
+| `./architecture-plugin`  | The `architecture` rule                                                   |
+| `./solid-plugin`         | Re-export of `eslint-plugin-solid`                                        |
+| `./css-filename`         | `cssFilenameError(path)`, the CSS naming check, for a script outside lint |
+
+An application imports `./lint`, `./fmt`, `./vitest`, `./playwright` and one of
+the TypeScript configs. The plugin entries exist because Oxlint loads plugins by
+specifier, from the application; the setup and teardown entries are loaded by
+the test presets.
+
+## Formatter
+
+`fmt` sets 80 columns, single quotes, no semicolons, no trailing commas, wrapped
+prose in Markdown and sorted imports. It ignores `public/`, `src/assets/`,
+generated route types, SVG and lock files.
+
+## TypeScript base
+
+`tsconfig.base.json` targets ES2024 with bundler resolution, keeps JSX for the
+Solid compiler (`jsxImportSource: @solidjs/web`), emits nothing and turns on the
+unused code and unchecked index checks. It has no `paths`, `include` or `types`.
+
+`tsconfig.app.json` extends the base with the `types` of a boilerplate
+application and an `include` resolved from the application folder with
+`${configDir}`, which needs TypeScript 5.5 or later. Each entry of `types` comes
+from a package the application installs:
+
+| Entry of `types`                        | Package                     |
+| --------------------------------------- | --------------------------- |
+| `node`                                  | `@types/node`               |
+| `vite/client`                           | `vite`                      |
+| `vite-plus/test/globals`                | `vite-plus`                 |
+| `@testing-library/jest-dom/vitest`      | `@testing-library/jest-dom` |
+| `@solidjs/vite-plugin/boundary-modules` | `@solidjs/vite-plugin`      |
+| `@solidjs/vite-plugin/virtual-modules`  | `@solidjs/vite-plugin`      |
+
+The application still declares its `paths`:
+
+```json
+{
+  "extends": "@evertondgn/solid-tooling/tsconfig.app.json",
+  "compilerOptions": {
+    "paths": { "@/*": ["./src/*"], "@paraglide/*": ["./paraglide/*"] }
+  }
 }
 ```
 
-`paths`, `include` e `types` continuam no `tsconfig.json` da aplicação.
+Playwright reads the `tsconfig.json` of the test files with its own loader,
+which does not expand `${configDir}`, so paths declared in the package would
+break the `@/` imports of the end-to-end tests.
+
+## Known limits
+
+- The package ships compiled JavaScript. Node refuses to run TypeScript from
+  `node_modules`, and Vite+ loads `vite.config.ts` in Node.
+- `project/test-filename` has no options. Test folders without a module, such as
+  the page tests in `src/tests/pages/`, are listed inside the package with the
+  names used in boilerplate_solidjs. For any other folder of that kind, turn the
+  rule off in `lint.overrides`, as shown in
+  [Changing the preset](#changing-the-preset).
+- The Paraglide plugin is always registered, so `@inlang/paraglide-js` has to be
+  installed even in an application without translations.
+- Some rule messages point to `docs/architecture.md` and `AGENTS.md`. Those
+  files belong to the application created from boilerplate_solidjs.
+- The test presets expect the boilerplate layout: tests named by suffix
+  (`.node.test`, `.dom.test`, `.browser.test`, `.e2e.test`), page tests in
+  `src/tests/pages/`, Paraglide output in `paraglide/` and `.env.test` at the
+  root.
+
+## Versions
 
-## Entradas
+The package follows semantic versioning. Below 1.0.0, a breaking change raises
+the minor version. Each release is listed in the
+[changelog](https://github.com/everton-dgn/solidjs_base/blob/main/packages/solid-tooling/CHANGELOG.md).
 
-| Entrada                 | Conteúdo                                                    |
-| ----------------------- | ----------------------------------------------------------- |
-| `./lint`                | Preset de lint, com os plugins abaixo já registrados        |
-| `./fmt`                 | Configuração do formatador                                  |
-| `./project-plugin`      | Regras de exports, nomes de arquivos de teste e de CSS, SEO |
-| `./backend-plugin`      | Imports estáticos das APIs privilegiadas do servidor        |
-| `./architecture-plugin` | Dependências entre camadas                                  |
-| `./solid-plugin`        | Reexport do `eslint-plugin-solid`                           |
-| `./css-filename`        | Regra de nome de arquivo CSS, para o script de lint de CSS  |
-| `./tsconfig.base.json`  | Opções do compilador sem caminhos da aplicação              |
+## License
 
-O preset pressupõe o layout das aplicações derivadas do `boilerplate_solidjs`:
-código em `src/`, ferramentas em `tooling/` e as camadas descritas no guia de
-arquitetura da aplicação.
+MIT

package/dist/architecture-plugin.mjs

@@ -41,7 +41,7 @@ const layerImports = defineRule({
 	meta: {
 		type: "problem",
 		schema: [],
-		messages: { forbidden: "A camada {{from}} não pode depender de {{to}} ({{target}}). Consulte as regras de camadas em docs/architecture.md." }
+		messages: { forbidden: "Layer {{from}} must not depend on {{to}} ({{target}}). See the layer rules in docs/architecture.md." }
 	},
 	create(context) {
 		const from = layer(path.relative(context.cwd, context.filename).split(path.sep).join("/"));

package/dist/backend-plugin.mjs

@@ -1,5 +1,5 @@
 import { t as readStaticSpecifier } from "./import-specifier-C7HWhMXB.mjs";
-import { n as RENDER_INTEGRITY_MODULE } from "./constants-DwOmJ9No.mjs";
+import { n as RENDER_INTEGRITY_MODULE } from "./constants-Jqvtbvxu.mjs";
 import { definePlugin, defineRule } from "vite-plus/lint/plugins";
 // src/backendPolicy/plugin.ts
 const RENDER_INTEGRITY = new RegExp(RENDER_INTEGRITY_MODULE, "u");
@@ -26,11 +26,11 @@ const backendPlugin = definePlugin({
 	rules: {
 		"static-solid-imports": staticImportRule({
 			matches: (specifier) => specifier === "@solidjs/web" || specifier.startsWith("@solidjs/web/"),
-			message: "Use import estático de @solidjs/web e seus subcaminhos para preservar as restrições de APIs privilegiadas."
+			message: "Use a static import for @solidjs/web and its subpaths: the import restrictions on markSafeError and configureServerErrors cannot check import()."
 		}),
 		"static-render-integrity-imports": staticImportRule({
 			matches: (specifier) => RENDER_INTEGRITY.test(specifier),
-			message: "Use import estático de renderIntegrity para preservar a restrição de observeRenderFailures."
+			message: "Use a static import for renderIntegrity: the import restriction on observeRenderFailures cannot check import()."
 		})
 	}
 });

package/dist/{constants-DwOmJ9No.mjs → constants-Jqvtbvxu.mjs}

@@ -1,7 +1,7 @@
 // src/backendPolicy/constants.ts
 const RELATIVE_IMPORT_RESTRICTION = {
 	regex: String.raw`^(\.\./){4,}`,
-	message: "Imports relativos podem subir no máximo três níveis. Use o alias @/ para caminhos mais distantes."
+	message: "Relative imports may go up at most three levels. Use the @/ alias for more distant paths."
 };
 const RENDER_INTEGRITY_MODULE = String.raw`(?:^|/)renderIntegrity(?:/index(?:\.ts)?)?$`;
 export { RENDER_INTEGRITY_MODULE as n, RELATIVE_IMPORT_RESTRICTION as t };

package/dist/css-filename.mjs

@@ -5,8 +5,8 @@ import path from "node:path";
 function cssFilenameError(file) {
 	const normalized = file.split("\\").join("/");
 	const basename = path.posix.basename(normalized);
-	if (normalized.startsWith("src/theme/")) return /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*$/u.test(basename.slice(0, -4)) ? void 0 : "Use nomeCamelCase.css dentro de src/theme/.";
-	return basename === "styles.module.css" ? void 0 : "Use styles.module.css fora de src/theme/, inclusive nas rotas.";
+	if (normalized.startsWith("src/theme/")) return /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*$/u.test(basename.slice(0, -4)) ? void 0 : "Use camelCaseName.css inside src/theme/.";
+	return basename === "styles.module.css" ? void 0 : "Use styles.module.css outside src/theme/, including in routes.";
 }
 const cssFilename = defineRule({
 	meta: {

package/dist/lint.mjs

@@ -1,4 +1,4 @@
-import { n as RENDER_INTEGRITY_MODULE, t as RELATIVE_IMPORT_RESTRICTION } from "./constants-DwOmJ9No.mjs";
+import { n as RENDER_INTEGRITY_MODULE, t as RELATIVE_IMPORT_RESTRICTION } from "./constants-Jqvtbvxu.mjs";
 // src/backendPolicy/index.ts
 const NETWORK = [
 	"fetch",
@@ -16,21 +16,21 @@ const GLOBALS = [
 const SAFE_ERRORS = {
 	name: "@solidjs/web",
 	importNames: ["markSafeError", "SAFE_ERROR"],
-	message: "Use createPublicError; somente publicErrors autoriza erros públicos."
+	message: "Use createPublicError; only publicErrors may mark an error as public."
 };
 const SERVER_ERROR_HOOK = {
 	name: "@solidjs/web",
 	importNames: ["configureServerErrors"],
-	message: "Mantenha o registro da política em configureServerErrors."
+	message: "Only src/infra/server/configureServerErrors/index.ts may import this: server error handling is configured in that module."
 };
 const SERVER_CONFIG = ["@solidjs/web/server-functions", "@solidjs/web/server-functions/server"].map((name) => ({
 	name,
-	message: "Mantenha o registro da política em configureServerErrors."
+	message: "Only src/infra/server/configureServerErrors/index.ts may import this: server error handling is configured in that module."
 }));
 const RENDER_OBSERVER = {
 	regex: RENDER_INTEGRITY_MODULE,
 	importNames: ["observeRenderFailures"],
-	message: "Somente configureServerErrors declara que as falhas de render são observadas."
+	message: "Only configureServerErrors may declare that render failures are observed."
 };
 const TRANSPORTS = [
 	"http",
@@ -41,7 +41,7 @@ const TRANSPORTS = [
 	"undici"
 ].flatMap((name) => [name, `node:${name}`]).map((name) => ({
 	name,
-	message: "Integre transportes de backend em um adapter protegido."
+	message: "Node transports cannot be imported in src/. Use requestJson for HTTP, or an adapter in src/infra/server/ wrapped in protectServerOperation."
 }));
 function imports({ paths, patterns = [] }) {
 	return { "eslint/no-restricted-imports": ["error", {
@@ -59,7 +59,7 @@ function globals({ names, properties = names }) {
 		"eslint/no-restricted-properties": ["error", ...GLOBALS.flatMap((object) => properties.map((property) => ({
 			object,
 			property,
-			message: property === "console" ? "Registre falhas somente por logServerFailure." : "Use requestJson ou um adapter de backend protegido."
+			message: property === "console" ? "Log failures only through logServerFailure." : "Call the backend through requestJson, or through an adapter in src/infra/server/ wrapped in protectServerOperation."
 		})))]
 	};
 }

package/dist/playwright-teardown.d.mts

@@ -0,0 +1 @@
+export default function checkServerLog(): Promise<void>;

package/dist/playwright-teardown.mjs

@@ -0,0 +1,23 @@
+import { env } from "node:process";
+import { readFile } from "node:fs/promises";
+import { stripVTControlCharacters } from "node:util";
+// src/playwright/teardown.ts
+const PRIVATE_MARKER = /PRIVATE_[A-Z0-9_]+/u;
+async function checkLog({ file, baseUrl }) {
+	if (!file || !baseUrl) throw new Error("Server log file is not configured");
+	const log = stripVTControlCharacters(await readFile(file, "utf8"));
+	const { host } = new URL(baseUrl);
+	if (!log.includes(host)) throw new Error(`Server log does not show the preview startup: ${file}`);
+	if (PRIVATE_MARKER.test(log)) throw new Error(`Server log contains a private marker: ${file}`);
+}
+async function checkServerLog() {
+	await checkLog({
+		file: env.SERVER_LOG_FILE,
+		baseUrl: env.BASE_URL_TEST
+	});
+	if (env.TEST_PUBLICATION_LOAD === "true") await checkLog({
+		file: env.SERVER_LOG_SECONDARY,
+		baseUrl: env.PUBLICATION_SECONDARY_URL
+	});
+}
+export { checkServerLog as default };

package/dist/playwright.d.mts

@@ -0,0 +1,18 @@
+import { PlaywrightTestConfig } from "@playwright/test";
+type FixtureServer = {
+  command: string;
+  url: string;
+};
+type SerialSuites = {
+  serverLogs?: string;
+  markdown?: string;
+  publicationLoad?: string;
+};
+type PlaywrightOptions = {
+  root: string;
+  testDir?: string;
+  fixtureServers?: FixtureServer[];
+  suites?: SerialSuites;
+};
+export declare function definePlaywrightConfig({ root, testDir, fixtureServers, suites }: PlaywrightOptions): PlaywrightTestConfig;
+export {};

package/dist/playwright.mjs

@@ -0,0 +1,158 @@
+import path from "node:path";
+import { env, loadEnvFile } from "node:process";
+import { fileURLToPath } from "node:url";
+import { defineConfig, devices } from "@playwright/test";
+import { loadEnv } from "vite-plus";
+// src/playwright/index.ts
+const STARTUP_TIMEOUT = 12e4;
+const SECONDARY_PORT_OFFSET = 2;
+const MAX_PORT = 65535;
+const CI_WORKERS = 2;
+const SECONDARY_LOG = "test-results/server-publication-secondary.log";
+const PREBUILT_GUARD = "if [ -e .vercel/output/static/.vite ]; then echo 'TEST_PREBUILT found an e2e build; run vp run build first' >&2; exit 1; fi && ";
+function readRunMode(suites) {
+	const mode = {
+		isProduction: env.TEST_PRODUCTION_ROUTES === "true",
+		isPublicationLoad: env.TEST_PUBLICATION_LOAD === "true",
+		shouldBuild: env.TEST_PREBUILT !== "true"
+	};
+	if (mode.isPublicationLoad && mode.isProduction) throw new Error("TEST_PUBLICATION_LOAD requires fixture routes");
+	if (mode.isPublicationLoad && !suites.publicationLoad) throw new Error("TEST_PUBLICATION_LOAD requires a publicationLoad suite");
+	if (!mode.shouldBuild && !mode.isProduction) throw new Error("TEST_PREBUILT requires production routes");
+	return mode;
+}
+function readBaseUrl(mode) {
+	if (!env.BASE_URL_TEST) throw new Error(".env.test must define BASE_URL_TEST");
+	const baseUrl = new URL(env.BASE_URL_TEST);
+	if (!baseUrl.port) throw new Error("BASE_URL_TEST must include an explicit port");
+	if (mode.isPublicationLoad && Number(baseUrl.port) + SECONDARY_PORT_OFFSET > MAX_PORT) throw new Error("BASE_URL_TEST leaves no port for the secondary server");
+	return env.BASE_URL_TEST;
+}
+function readWorkers(mode) {
+	if (mode.isPublicationLoad) return 1;
+	return env.CI ? CI_WORKERS : void 0;
+}
+function secondaryUrl(baseUrl) {
+	const url = new URL(baseUrl);
+	url.port = String(Number(url.port) + SECONDARY_PORT_OFFSET);
+	return url;
+}
+function buildProjects({ mode, suites }) {
+	if (mode.isPublicationLoad) return [{
+		name: "publication-load",
+		testMatch: suites.publicationLoad
+	}];
+	if (mode.isProduction) return [{ name: "chromium" }];
+	const teardown = suites.serverLogs ? { teardown: "server-logs" } : {};
+	const projects = [{
+		name: "chromium",
+		testIgnore: ["**/*.production.e2e.test.ts", ...[
+			suites.serverLogs,
+			suites.publicationLoad,
+			suites.markdown
+		].filter((suite) => suite !== void 0)],
+		...teardown
+	}];
+	if (suites.markdown) projects.push({
+		name: "markdown",
+		testMatch: suites.markdown,
+		fullyParallel: false,
+		workers: 1,
+		...teardown
+	});
+	if (suites.serverLogs) projects.push({
+		name: "server-logs",
+		testMatch: suites.serverLogs,
+		fullyParallel: false
+	});
+	return projects;
+}
+function buildServers({ root, mode, fixtureServers, baseUrl, serverLog }) {
+	const buildMode = mode.isProduction ? "production" : "e2e";
+	const build = mode.shouldBuild ? `vp run build --mode ${buildMode} && ` : PREBUILT_GUARD;
+	const shared = {
+		cwd: root,
+		reuseExistingServer: false
+	};
+	const server = {
+		...shared,
+		timeout: STARTUP_TIMEOUT
+	};
+	const fixtures = mode.isProduction ? [] : fixtureServers.map((fixture) => ({
+		...fixture,
+		...shared
+	}));
+	const { hostname, port } = new URL(baseUrl);
+	const secondary = secondaryUrl(baseUrl);
+	return [
+		...fixtures,
+		{
+			...server,
+			command: `${build}mkdir -p test-results && vp run start --strictPort > ${serverLog} 2>&1`,
+			env: {
+				HOST: hostname,
+				PORT: port,
+				NODE_ENV: "production"
+			},
+			url: baseUrl
+		},
+		...mode.isPublicationLoad ? [{
+			...server,
+			command: `vp run start --strictPort > ${SECONDARY_LOG} 2>&1`,
+			env: {
+				HOST: hostname,
+				PORT: secondary.port,
+				NODE_ENV: "production"
+			},
+			url: secondary.href
+		}] : []
+	];
+}
+function definePlaywrightConfig({ root, testDir = "src/tests/pages", fixtureServers = [], suites = {} }) {
+	loadEnvFile(path.join(root, ".env.test"));
+	const mode = readRunMode(suites);
+	const buildMode = mode.isProduction ? "production" : "e2e";
+	Object.assign(env, loadEnv(buildMode, root, "VITE_"));
+	const baseUrl = readBaseUrl(mode);
+	const serverLog = `test-results/server-${buildMode}.log`;
+	env.SERVER_LOG_FILE = path.join(root, serverLog);
+	if (mode.isPublicationLoad) {
+		env.PUBLICATION_SECONDARY_URL = secondaryUrl(baseUrl).href;
+		env.SERVER_LOG_SECONDARY = path.join(root, SECONDARY_LOG);
+	}
+	const reportFolder = mode.isProduction ? "production" : "e2e";
+	return defineConfig({
+		testDir: path.join(root, testDir),
+		testMatch: mode.isProduction ? "**/*.production.e2e.test.ts" : "**/*.e2e.test.ts",
+		outputDir: path.join(root, mode.isProduction ? "test-results/e2e-production" : "test-results/e2e"),
+		globalTeardown: fileURLToPath(new URL("playwright-teardown.mjs", import.meta.url)),
+		fullyParallel: !mode.isPublicationLoad,
+		forbidOnly: true,
+		workers: readWorkers(mode),
+		reporter: [["list"], ["html", {
+			outputFolder: path.join(root, "playwright-report", reportFolder),
+			open: "never",
+			onlyFailures: Boolean(env.CI)
+		}]],
+		use: {
+			...devices["Desktop Chrome"],
+			channel: env.CI ? "chrome" : void 0,
+			baseURL: baseUrl,
+			locale: "en-US",
+			screenshot: "only-on-failure",
+			trace: "retain-on-failure"
+		},
+		projects: buildProjects({
+			mode,
+			suites
+		}),
+		webServer: buildServers({
+			root,
+			mode,
+			fixtureServers,
+			baseUrl,
+			serverLog
+		})
+	});
+}
+export { definePlaywrightConfig };

package/dist/project-plugin.mjs

@@ -7,7 +7,7 @@ const noExportList = defineRule({
 	meta: {
 		type: "suggestion",
 		schema: [],
-		messages: { inlineExport: "Declare o export junto da declaração (export function, export const, export type) em vez de usar export { ... }. Lista de exports só vale em reexport com from." }
+		messages: { inlineExport: "Export on the declaration itself (export function, export const, export type) instead of using export { ... }. An export list is only allowed in a re-export with from." }
 	},
 	create(context) {
 		return { ExportNamedDeclaration(node) {
@@ -32,10 +32,10 @@ const seoModule = defineRule({
 		type: "problem",
 		schema: [],
 		messages: {
-			onlySeo: "O seo.ts exporta só o objeto seo. O corpo da página fica no index.tsx, porque o seo.ts entra no bundle inicial pelo route (AGENTS.md, Módulos de página).",
-			localImport: "O seo.ts não importa módulos locais como valor: o que ele importa entra no bundle inicial junto com o route. Mantenha o corpo da página no index.tsx (AGENTS.md, Módulos de página).",
-			computedImport: "O seo.ts não usa import() com caminho calculado: a regra não consegue conferir se o destino é local. Mantenha o corpo da página no index.tsx (AGENTS.md, Módulos de página).",
-			globImport: "O seo.ts não usa import.meta.glob: o Vite o converte em imports dos módulos que o padrão casa. Mantenha o corpo da página no index.tsx (AGENTS.md, Módulos de página)."
+			onlySeo: "seo.ts may export only seo. The route manifest loads the route export of every page in the initial bundle, and seo.ts goes with it, so keep the page body in index.tsx (see the page modules section of AGENTS.md).",
+			localImport: "seo.ts must not import values from relative paths or from src/routes/: whatever it imports goes into the initial bundle. Use import type, or keep the code in index.tsx (see the page modules section of AGENTS.md).",
+			computedImport: "seo.ts must not use import() with a computed path: the rule cannot tell whether the target is local. Keep the page body in index.tsx (see the page modules section of AGENTS.md).",
+			globImport: "seo.ts must not use import.meta.glob: Vite turns it into imports of every module the pattern matches. Keep the page body in index.tsx (see the page modules section of AGENTS.md)."
 		}
 	},
 	create(context) {
@@ -155,13 +155,13 @@ function testFilenameError(file) {
 	});
 	const candidate = dotted ? `${DOTTED_SUBJECT}${basename.slice(dotted.length)}` : basename;
 	const match = normalized.startsWith("tooling/") ? /^(?<subject>[^.]+)(?<qualifiers>(?:\.[a-z][a-zA-Z0-9]*)*)\.test\.ts$/u.exec(candidate) : /^(?<subject>[^.]+)(?<qualifiers>(?:\.[a-z][a-zA-Z0-9]*)*)(?:\.(?<environment>node|dom|browser|e2e)\.test|\.test-d)\.tsx?$/u.exec(candidate);
-	if (!match?.groups) return "Use Nome[.qualificador].ambiente.test.ts(x) ou Nome[.qualificador].test-d.ts(x) para tipos em src, ou Nome[.qualificador].test.ts em tooling.";
+	if (!match?.groups) return "In src/, name the test Name[.qualifier].<node|dom|browser|e2e>.test.ts(x), or Name[.qualifier].test-d.ts(x) for a type test. In tooling/, use Name[.qualifier].test.ts.";
 	const { environment } = match.groups;
 	const subject = dotted ?? match.groups.subject;
-	if (inPages && environment !== "e2e") return "Testes de páginas devem usar o ambiente e2e.";
-	if (environment === "e2e" && (!inPages || !subjects[directory])) return "Coloque testes e2e em src/tests/pages/NomeDaPagina e declare a página no mapeamento.";
-	if (!expected) return "Coloque o teste em __tests__ junto ao módulo ou declare sua suíte no mapeamento de tooling/test-filename.ts.";
-	if (!subject || !expected.includes(subject)) return `Use o nome exato do assunto testado: ${expected.join(", ")}. Qualificadores usam ponto e camelCase.`;
+	if (inPages && environment !== "e2e") return "Page tests must use the e2e environment.";
+	if (environment === "e2e" && (!inPages || !subjects[directory])) return "Place e2e tests in src/tests/pages/<Page>/. The accepted pages are listed in @evertondgn/solid-tooling; for another page, turn off project/test-filename for its folder in lint.overrides.";
+	if (!expected) return "Place the test in a __tests__ folder inside the module folder, as in Button/__tests__/Button.dom.test.tsx. For a test folder without a module, turn off project/test-filename for its files in lint.overrides.";
+	if (!subject || !expected.includes(subject)) return `Use the exact name of the subject under test: ${expected.join(", ")}. Qualifiers use a dot and camelCase.`;
 }
 const testFilename = defineRule({
 	meta: {
@@ -183,7 +183,7 @@ const cssModulesImport = defineRule({
 	meta: {
 		type: "suggestion",
 		schema: [],
-		messages: { useS: "Importe CSS Modules como S: import S from \"./styles.module.css\"." }
+		messages: { useS: "Import CSS Modules as S: import S from \"./styles.module.css\"." }
 	},
 	create(context) {
 		return { ImportDeclaration(node) {

package/dist/vitest-setup/browser.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/vitest-setup/browser.mjs

@@ -0,0 +1,5 @@
+import { baseLocale, setLocale } from "@paraglide/runtime.js";
+import { beforeEach } from "vite-plus/test";
+// src/vitest/setup/browser.ts
+beforeEach(() => setLocale(baseLocale, { reload: false }));
+export {};

package/dist/vitest.d.mts

@@ -0,0 +1,7 @@
+import { TestUserConfig, ViteUserConfig } from "vite-plus";
+type SolidTestOptions = {
+  root: string;
+  plugins: () => ViteUserConfig['plugins'];
+};
+export declare function solidTest({ root, plugins }: SolidTestOptions): TestUserConfig;
+export {};

package/dist/vitest.mjs

@@ -0,0 +1,129 @@
+import path from "node:path";
+import { env } from "node:process";
+import { fileURLToPath } from "node:url";
+import { playwright } from "vite-plus/test/browser-playwright";
+// src/vitest/index.ts
+const CI_WORKERS = 2;
+const STUB_PREFIX = "\0solid-tooling-stub:";
+const NODE_STUBS = /* @__PURE__ */ new Map([
+	["server-only", "export default undefined"],
+	["virtual:file-routes", "export const pageRoutes = []\nexport default []"],
+	["virtual:solid-server-function-handler", "export const endpoint = '/_server'"]
+]);
+const TEST_ENV_KEYS = [
+	"BASE_URL_TEST",
+	"HOST",
+	"PORT"
+];
+function packageFile(name) {
+	return fileURLToPath(new URL(name, import.meta.url));
+}
+function nodeStubs() {
+	return {
+		name: "solid-tooling:node-stubs",
+		enforce: "pre",
+		resolveId: (id) => NODE_STUBS.has(id) ? `${STUB_PREFIX}${id}` : void 0,
+		load: (id) => id.startsWith(STUB_PREFIX) ? NODE_STUBS.get(id.slice(20)) : void 0
+	};
+}
+function readTestEnv() {
+	return Object.fromEntries(TEST_ENV_KEYS.flatMap((key) => {
+		const value = env[key];
+		return value === void 0 ? [] : [[key, value]];
+	}));
+}
+function solidTest({ root, plugins }) {
+	return {
+		pool: "threads",
+		maxWorkers: env.CI ? CI_WORKERS : void 0,
+		css: false,
+		globals: true,
+		restoreMocks: true,
+		unstubGlobals: true,
+		unstubEnvs: true,
+		expect: {
+			requireAssertions: true,
+			poll: { interval: 10 }
+		},
+		env: readTestEnv(),
+		coverage: {
+			provider: "v8",
+			reporter: ["text", "html"],
+			thresholds: {
+				lines: 80,
+				functions: 80,
+				branches: 75,
+				statements: 80
+			},
+			include: ["src/**/*.{ts,tsx}"],
+			exclude: [
+				"src/**/*.d.ts",
+				"src/**/{constants,types,@types}/**",
+				"src/**/{constants,types}.{ts,tsx}",
+				"src/**/__tests__/**",
+				"src/tests/**",
+				"src/App.tsx",
+				"src/Document.tsx",
+				"src/entry-server.tsx",
+				"src/entry-client.tsx",
+				"src/router.ts"
+			]
+		},
+		reporters: env.GITHUB_ACTIONS ? ["default", "github-actions"] : ["verbose"],
+		projects: [
+			{
+				plugins: [nodeStubs()],
+				test: {
+					name: {
+						label: "node",
+						color: "cyan"
+					},
+					environment: "node",
+					include: ["src/**/*.node.test.{ts,tsx}"]
+				}
+			},
+			{
+				plugins: plugins(),
+				test: {
+					name: {
+						label: "dom",
+						color: "magenta"
+					},
+					environment: "happy-dom",
+					environmentOptions: { happyDOM: { url: "http://localhost/en" } },
+					include: ["src/**/*.dom.test.{ts,tsx}"]
+				}
+			},
+			{
+				plugins: plugins(),
+				resolve: { alias: [{
+					find: /^@paraglide\//u,
+					replacement: `${path.join(root, "paraglide")}/`
+				}] },
+				test: {
+					css: true,
+					name: {
+						label: "browser",
+						color: "yellow"
+					},
+					setupFiles: [packageFile("vitest-setup/browser.mjs")],
+					include: ["src/**/*.browser.test.{ts,tsx}"],
+					browser: {
+						enabled: true,
+						headless: true,
+						trace: {
+							mode: "retain-on-failure",
+							tracesDir: path.join(root, "test-results/browser-traces")
+						},
+						provider: playwright({
+							contextOptions: { locale: "en-US" },
+							launchOptions: env.CI ? { channel: "chrome" } : {}
+						}),
+						instances: [{ browser: "chromium" }]
+					}
+				}
+			}
+		]
+	};
+}
+export { solidTest };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@evertondgn/solid-tooling",
-  "version": "0.1.0",
-  "description": "Lint, formatter and TypeScript presets for SolidJS applications built with Vite+.",
+  "version": "0.3.0",
+  "description": "Lint, formatter, TypeScript and test presets for SolidJS applications built with Vite+.",
   "author": "Éverton Toffanetto",
   "license": "MIT",
   "repository": {
@@ -19,7 +19,8 @@
   "type": "module",
   "files": [
     "dist",
-    "tsconfig.base.json"
+    "tsconfig.base.json",
+    "tsconfig.app.json"
   ],
   "exports": {
     "./architecture-plugin": "./dist/architecture-plugin.mjs",
@@ -27,10 +28,15 @@
     "./css-filename": "./dist/css-filename.mjs",
     "./fmt": "./dist/fmt.mjs",
     "./lint": "./dist/lint.mjs",
+    "./playwright": "./dist/playwright.mjs",
+    "./playwright-teardown": "./dist/playwright-teardown.mjs",
     "./project-plugin": "./dist/project-plugin.mjs",
     "./solid-plugin": "./dist/solid-plugin.mjs",
+    "./vitest": "./dist/vitest.mjs",
+    "./vitest-setup/browser": "./dist/vitest-setup/browser.mjs",
     "./package.json": "./package.json",
-    "./tsconfig.base.json": "./tsconfig.base.json"
+    "./tsconfig.base.json": "./tsconfig.base.json",
+    "./tsconfig.app.json": "./tsconfig.app.json"
   },
   "publishConfig": {
     "access": "public"
@@ -39,21 +45,27 @@
     "build": "vp pack",
     "dev": "vp pack --watch",
     "test": "vp run test-rules",
-    "test:tarball": "vp run test-tarball",
-    "prepublishOnly": "vp pack"
+    "test:tarball": "vp run test-tarball"
   },
   "dependencies": {
     "eslint-plugin-solid": "0.19.0"
   },
   "peerDependencies": {
     "@inlang/paraglide-js": "3.2.2",
-    "vite-plus": "1.6.0"
+    "vite-plus": "1.6.0",
+    "@playwright/test": "1.65.0"
   },
   "devDependencies": {
     "@inlang/paraglide-js": "3.2.2",
     "@types/node": "24.19.2",
     "typescript": "7.0.2",
     "valibot": "1.5.0",
-    "vite-plus": "1.6.0"
+    "vite-plus": "1.6.0",
+    "@playwright/test": "1.65.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    }
   }
 }

package/tsconfig.app.json

@@ -0,0 +1,21 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "types": [
+      "node",
+      "vite/client",
+      "vite-plus/test/globals",
+      "@testing-library/jest-dom/vitest",
+      "@solidjs/vite-plugin/boundary-modules",
+      "@solidjs/vite-plugin/virtual-modules"
+    ]
+  },
+  "include": [
+    "${configDir}/src",
+    "${configDir}/env.ts",
+    "${configDir}/solid-env.d.ts",
+    "${configDir}/vite.config.ts",
+    "${configDir}/playwright.config.ts",
+    "${configDir}/tooling/**/*.ts"
+  ]
+}