feat(test): support inline Rstest projects (#48)

Author: 9aoy

README.md

@@ -113,6 +113,54 @@ For example, import Rstest APIs without adding `@rstest/core` as a direct depend
 import { expect, test } from 'rstack/test';
 ```
 
+## Test projects
+
+`define.test()` accepts an Rstest configuration. For a single project, Rstack automatically applies the `define.app()` configuration, or falls back to `define.lib()`:
+
+```ts
+import { define } from 'rstack';
+
+define.app({
+  // Rsbuild configuration
+});
+
+define.test({
+  testEnvironment: 'happy-dom',
+});
+```
+
+For multiple test environments in the same app or library, use inline projects:
+
+```ts
+import { define } from 'rstack';
+import { defineInlineProject } from 'rstack/test';
+
+define.app({
+  // Shared by all inline projects
+});
+
+define.test({
+  projects: [
+    defineInlineProject({
+      name: 'node',
+      include: ['./tests/node/**/*.test.ts'],
+      testEnvironment: 'node',
+    }),
+    defineInlineProject({
+      name: 'dom',
+      include: ['./tests/dom/**/*.test.tsx'],
+      testEnvironment: 'happy-dom',
+    }),
+  ],
+});
+```
+
+Rstack applies the shared app or library adapter to every inline project without an explicit `extends`. String project entries are passed to Rstest unchanged and load their own configuration.
+
+Run all projects with `rs test`, or select one with `rs test --project dom`.
+
+See [`examples/rstest-inline-projects`](./examples/rstest-inline-projects) for a complete React SSR example.
+
 ## Credits
 
 Rstack CLI is inspired by:

examples/documentation/docs/api/_meta.json

@@ -1 +1 @@
-["index", "commands"]
+["index", "commands", "testing"]

examples/documentation/docs/api/testing.mdx

@@ -0,0 +1,105 @@
+# Testing
+
+Rstack uses [Rstest](https://rstest.rs/) for testing. The value passed to `define.test()` is an Rstest configuration, similar to using Rstest's `defineConfig()` directly.
+
+Test APIs and configuration helpers are available from `rstack/test`:
+
+```ts
+import { defineInlineProject, expect, test } from 'rstack/test';
+```
+
+## Single project
+
+For a single test project, pass the Rstest options directly:
+
+```ts title="rstack.config.ts"
+import { define } from 'rstack';
+
+define.app({
+  // Rsbuild configuration
+});
+
+define.test({
+  testEnvironment: 'happy-dom',
+  setupFiles: ['./tests/rstest.setup.ts'],
+});
+```
+
+Unless `extends` is provided explicitly, Rstack automatically extends the test configuration from `define.app()`. If there is no app configuration, it falls back to `define.lib()`.
+
+## Inline projects
+
+Use Rstest inline projects when one app or library needs multiple test configurations, such as separate Node.js and DOM test environments:
+
+```ts title="rstack.config.ts"
+import { define } from 'rstack';
+import { defineInlineProject } from 'rstack/test';
+
+define.app({
+  // Shared by both inline projects
+});
+
+define.test({
+  coverage: {
+    enabled: true,
+  },
+  projects: [
+    defineInlineProject({
+      name: 'node',
+      include: ['./tests/node/**/*.test.ts'],
+      testEnvironment: 'node',
+    }),
+    defineInlineProject({
+      name: 'dom',
+      include: ['./tests/dom/**/*.test.tsx'],
+      testEnvironment: 'happy-dom',
+      setupFiles: ['./tests/rstest.setup.ts'],
+    }),
+  ],
+});
+```
+
+Rstack applies the shared `define.app()` or `define.lib()` adapter to every inline project that does not define its own `extends`. Function-based app or library configuration is resolved once and shared by all inline projects.
+
+Run all projects:
+
+```bash
+rs test
+```
+
+Run one project by name:
+
+```bash
+rs test --project dom
+```
+
+See [`examples/rstest-inline-projects`](https://github.com/rstackjs/rstack-cli/tree/main/examples/rstest-inline-projects) for a complete example that tests React server rendering in Node.js and client rendering in happy-dom.
+
+## Custom `extends`
+
+An inline project can opt out of automatic app or library inheritance by providing `extends` explicitly:
+
+```ts
+import { defineInlineProject } from 'rstack/test';
+
+const customProject = defineInlineProject({
+  name: 'custom',
+  extends: customAdapter(),
+});
+```
+
+If the root `define.test()` configuration provides `extends`, Rstack leaves the complete test configuration unchanged.
+
+## External projects
+
+String project entries are passed to Rstest unchanged:
+
+```ts
+import { define } from 'rstack';
+
+define.test({
+  projects: ['./legacy/rstest.config.ts'],
+});
+```
+
+External string projects load their own Rstest configuration and do not inherit the current `define.app()` or `define.lib()` configuration. Use inline projects when projects should share the current Rstack build configuration.

examples/rstest-inline-projects/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@examples/rstest-inline-projects",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "rs build",
+    "dev": "rs dev",
+    "preview": "rs preview",
+    "test": "rs test"
+  },
+  "dependencies": {
+    "react": "catalog:",
+    "react-dom": "catalog:"
+  },
+  "devDependencies": {
+    "@rsbuild/plugin-react": "catalog:",
+    "@testing-library/dom": "catalog:",
+    "@testing-library/react": "catalog:",
+    "@types/node": "catalog:",
+    "@types/react": "catalog:",
+    "@types/react-dom": "catalog:",
+    "happy-dom": "catalog:",
+    "rstack": "workspace:*",
+    "typescript": "catalog:"
+  }
+}

examples/rstest-inline-projects/rstack.config.ts

@@ -0,0 +1,25 @@
+import { define } from 'rstack';
+import { defineInlineProject } from 'rstack/test';
+
+define.app(async () => {
+  const { pluginReact } = await import('@rsbuild/plugin-react');
+
+  return {
+    plugins: [pluginReact()],
+  };
+});
+
+define.test({
+  projects: [
+    defineInlineProject({
+      name: 'ssr',
+      include: ['./tests/ssr.test.tsx'],
+      testEnvironment: 'node',
+    }),
+    defineInlineProject({
+      name: 'dom',
+      include: ['./tests/dom.test.tsx'],
+      testEnvironment: 'happy-dom',
+    }),
+  ],
+});

examples/rstest-inline-projects/src/App.tsx

@@ -0,0 +1,8 @@
+export default function App() {
+  return (
+    <main>
+      <h1>Rstack React SSR</h1>
+      <p>Rendered on the server and hydrated in the browser.</p>
+    </main>
+  );
+}

examples/rstest-inline-projects/src/index.tsx

@@ -0,0 +1,8 @@
+import { hydrateRoot } from 'react-dom/client';
+import App from './App';
+
+const root = document.getElementById('root');
+
+if (root) {
+  hydrateRoot(root, <App />);
+}

examples/rstest-inline-projects/tests/dom.test.tsx

@@ -0,0 +1,9 @@
+import { expect, test } from 'rstack/test';
+import { render, screen } from '@testing-library/react';
+import App from '../src/App';
+
+test('renders the app in a DOM environment', () => {
+  render(<App />);
+
+  expect(screen.getByRole('heading', { name: 'Rstack React SSR' })).toBeTruthy();
+});

examples/rstest-inline-projects/tests/ssr.test.tsx

@@ -0,0 +1,10 @@
+import { expect, test } from 'rstack/test';
+import { renderToString } from 'react-dom/server';
+import App from '../src/App';
+
+test('renders the app on the server', () => {
+  const html = renderToString(<App />);
+
+  expect(html).toContain('Rstack React SSR');
+  expect(html).toContain('Rendered on the server');
+});

examples/rstest-inline-projects/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "lib": ["DOM", "ES2023"],
+    "jsx": "react-jsx",
+    "target": "ES2023",
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["rstack/types", "node"],
+    "moduleDetection": "force",
+    "moduleResolution": "bundler",
+    "verbatimModuleSyntax": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "strict": true
+  },
+  "include": ["src", "tests", "rstack.config.ts"]
+}