@bleedingdev/modern-js-main-doc 3.2.0-ultramodern.0

package/docs/zh/guides/basic-features/testing/playwright.mdx

@@ -0,0 +1,112 @@
+# Playwright
+
+Playwright 是一个测试框架，它允许你使用单一的 API，自动的在 Chromium、Firefox 和 WebKit 环境中运行测试用例，你可以使用它来**编写 E2E 测试**。
+
+在 Modern.js 中使用 Playwright 需要先安装依赖，可以执行以下命令：
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command={{ npm: "npm init playwright", yarn: "yarn create playwright", pnpm: "pnpm create playwright" }} />
+
+
+上述命令会自动安装 Playwright 依赖，并通过一系列提示帮助你在项目中安装和配置，包括添加一个 `playwright.config.ts` 文件。
+
+:::info
+参考 Playwright 官方文档，[安装 Playwright](https://playwright.dev/docs/intro#installation) 查阅更详细的指南。
+:::
+
+按照默认配置创建后，可以在项目中看到以下文件：
+
+```ts title="tests/example.spec.ts"
+import { test, expect } from '@playwright/test';
+
+test('has title', async ({ page }) => {
+  await page.goto('https://playwright.dev/');
+
+  // Expect a title "to contain" a substring.
+  await expect(page).toHaveTitle(/Playwright/);
+});
+
+test('get started link', async ({ page }) => {
+  await page.goto('https://playwright.dev/');
+
+  // Click the get started link.
+  await page.getByRole('link', { name: 'Get started' }).click();
+
+  // Expects page to have a heading with the name of Installation.
+  await expect(
+    page.getByRole('heading', { name: 'Installation' }),
+  ).toBeVisible();
+});
+```
+
+这是默认的测试文件，现在创建一些新的页面，并测试它们。
+
+## 创建 E2E 测试
+
+首先创建两张 Modern.js 的页面。
+
+```tsx title="routes/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Index = () => (
+  <div>
+    <h1>Home</h1>
+    <Link to="/about">About</Link>
+  </div>
+);
+
+export default Index;
+```
+
+```tsx title="routes/about/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Index = () => (
+  <div>
+    <h1>About</h1>
+    <Link to="/">Home</Link>
+  </div>
+);
+
+export default Index;
+```
+
+接下来，添加测试用例，来保证你页面的链接能够正常工作。
+
+```ts title="tests/example.spec.ts"
+import { test, expect } from '@playwright/test'
+ 
+test('should navigate to the about page', async ({ page }) => {
+  // Start from the index page (the baseURL is set via the webServer in the playwright.config.ts)
+  await page.goto('http://localhost:8080/')
+  // Find an element with the text 'About' and click on it
+  await page.click('text=About')
+  // The new URL should be "/about" (baseURL is used there)
+  await expect(page).toHaveURL('http://localhost:8080/about')
+  // The new page should contain an h1 with "About"
+  await expect(page.locator('h1')).toContainText('About')
+})
+```
+
+## 运行测试用例
+
+Playwright 需要你的 Modern.js 服务器保持运行。我们推荐在生产环境产物下运行你的测试用例，你可以执行 `pnpm run build` 和 `pnpm run serve` 在本地模拟生产环境。
+
+```bash
+info    Starting production server...
+
+  > Local:    http://localhost:8080/
+  > Network:  http://10.94.59.30:8080/
+```
+
+当项目正常构建运行后，可以在另一个终端内执行 `npx playwright test`，运行 Playwright 用例：
+
+```bash
+Running 3 tests using 3 workers
+  3 passed (2.0s)
+
+To open last HTML report run:
+
+  npx playwright show-report
+```

package/docs/zh/guides/basic-features/testing/rstest.mdx

@@ -0,0 +1,163 @@
+# Rstest
+
+[Rstest](https://rstest.rs) 是由 Rspack 团队开发的测试框架，基于 Rspack 构建，具备很快的测试执行速度。
+
+本指南介绍如何在 Modern.js 中集成 Rstest，并用于 web app 测试。
+
+## 快速开始
+
+先安装基础依赖：
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command="add @rstest/core @modern-js/adapter-rstest -D" />
+
+然后创建 `rstest.config.ts`：
+
+```ts title="rstest.config.ts"
+import { defineConfig } from '@rstest/core';
+import { withModernConfig } from '@modern-js/adapter-rstest';
+
+export default defineConfig({
+  extends: withModernConfig(),
+});
+```
+
+`@modern-js/adapter-rstest` 可以让 Rstest 继承你现有的 Modern.js 配置，使测试环境和应用配置保持一致。
+
+更多配置项可以参考 [Rstest 配置文档](https://rstest.rs/config)。
+
+你可以通过 `npx rstest` 运行测试，也可以在 `package.json` 中添加脚本：
+
+```json title="package.json"
+{
+  "scripts": {
+    "test": "rstest"
+  }
+}
+```
+
+## 测试 Web UI
+
+在 Modern.js 中测试 Web UI，通常有两种方案：
+
+- 使用 Rstest 的 browser mode，直接在真实浏览器中运行测试。大多数场景更推荐这种方式，但目前仍处于实验性阶段。
+- 使用 `happy-dom` 和 Testing Library 提供一个模拟 DOM 环境，这种方式也符合 `@modern-js/adapter-rstest` 默认的 web 测试环境。
+
+我们整体更推荐 browser mode，因为它使用的是真实浏览器 API 和行为，能覆盖模拟 DOM 难以完整支持的场景，同时在排查 UI 行为问题时也更容易调试。
+
+### Browser mode（实验性）
+
+如果你希望直接在真实浏览器中测试，而不是使用模拟 DOM，可以安装 browser mode 相关依赖：
+
+<PackageManagerTabs command="add @rstest/browser @rstest/browser-react playwright -D" />
+
+然后在 `rstest.config.ts` 中启用 browser mode：
+
+```ts title="rstest.config.ts"
+import { defineConfig } from '@rstest/core';
+import { withModernConfig } from '@modern-js/adapter-rstest';
+
+export default defineConfig({
+  extends: withModernConfig(),
+  browser: {
+    enabled: true,
+    provider: 'playwright',
+  },
+});
+```
+
+示例测试如下：
+
+```tsx title="__tests__/page.browser.test.tsx"
+import { BrowserRouter as Router } from '@modern-js/runtime/router';
+import { page } from '@rstest/browser';
+import { render } from '@rstest/browser-react';
+import { expect, test } from '@rstest/core';
+import Page from '../routes/page';
+
+test('Page', async () => {
+  await render(
+    <Router>
+      <Page />
+    </Router>,
+  );
+
+  await expect.element(
+    page.getByRole('heading', { level: 1, name: 'Home' }),
+  ).toBeVisible();
+});
+```
+
+关于 browser mode 的更多配置、Locator API 和断言能力，可以直接参考 [Rstest 文档](https://rstest.rs/guide/browser-testing/)。
+
+### 使用 `happy-dom` 模拟 DOM
+
+先安装 DOM 测试相关依赖：
+
+<PackageManagerTabs command="add happy-dom @testing-library/react @testing-library/dom -D" />
+
+然后在 `rstest.config.ts` 中启用 `happy-dom`：
+
+```ts title="rstest.config.ts"
+import { defineConfig } from '@rstest/core';
+import { withModernConfig } from '@modern-js/adapter-rstest';
+
+export default defineConfig({
+  extends: withModernConfig(),
+  testEnvironment: 'happy-dom',
+});
+```
+
+先创建一个简单页面用于测试：
+
+```tsx title="routes/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Page = () => (
+  <div>
+    <h1>Home</h1>
+    <Link to="/about">About</Link>
+  </div>
+);
+
+export default Page;
+```
+
+然后添加测试用例：
+
+```tsx title="__tests__/page.test.tsx"
+import { BrowserRouter as Router } from '@modern-js/runtime/router';
+import { expect, test } from '@rstest/core';
+import { render, screen } from '@testing-library/react';
+import Page from '../routes/page';
+
+test('Page', () => {
+  render(
+    <Router>
+      <Page />
+    </Router>,
+  );
+
+  expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined();
+});
+```
+
+## 运行测试用例
+
+执行上面的 `test` 命令即可运行测试：
+
+```bash
+✓ __tests__/page.test.tsx (1)
+  ✓ Page
+
+ Test Files 1 passed
+      Tests 1 passed
+   Duration 510ms (build 145ms, tests 365ms)
+```
+
+## Node Mode
+
+如果你需要测试 `bff` 等 server-side logic，建议直接参考 [Rstest 文档](https://rstest.rs) 中关于 node mode 的说明。
+
+Modern.js 主要面向 web app，因此这里重点介绍的是 Web UI 测试，以及更贴近真实运行环境的 browser mode。

package/docs/zh/guides/basic-features/testing/vitest.mdx

@@ -0,0 +1,100 @@
+# Vitest
+
+Vitest 是由 Vite 驱动的测试框架，和 React Testing Library 配合可以用于单元测试。
+
+在 Modern.js 中使用 Vitest 需要先安装依赖，可以执行以下命令：
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command={{ 
+  npm: "npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom", 
+  yarn: "yarn add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom", 
+  pnpm: "pnpm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom",
+  bun: "bun add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom"
+}} />
+
+接下来，你需要创建一个 Vitest 配置文件 `vitest.config.ts`，内容如下：
+
+```ts title="vitest.config.ts"
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+ 
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: 'jsdom',
+  },
+})
+```
+
+更多关于 Vitest 配置的信息，可以参考 [Vitest 配置文档](https://vitest.dev/config/#configuration)。
+
+你可以选择性的将 `vitest` 命令添加到 `package.json` 中：
+
+```json title="package.json"
+{
+  "scripts": {
+    "test": "vitest"
+  }
+}
+```
+
+运行该命令后，Vitest 会自动监听你的文件变化，并重新运行用例。
+
+## 创建单元测试
+
+首先，创建一个简单的页面用于测试：
+
+```tsx title="routes/page.tsx"
+import { Link } from '@modern-js/runtime/router';
+
+const Index = () => (
+  <div>
+    <h1>Home</h1>
+    <Link to="/about">About</Link>
+  </div>
+);
+
+export default Index;
+```
+
+添加测试用例，检测页面中是否有预期的文本：
+
+```tsx title="__tests__/page.test.tsx"
+import { expect, test } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { BrowserRouter as Router } from '@modern-js/runtime/router';
+import Page from '../routes/page';
+
+test('Page', () => {
+  render(
+    <Router>
+      <Page />
+    </Router>,
+  );
+  expect(screen.getByRole('heading', { level: 1, name: 'Home' })).toBeDefined();
+});
+```
+
+上述用例中，我们从 `@modern-js/runtime/router` 引入了 `<Router>` 组件，这是因为 React Router 在渲染部分路由相关组件时，必须要有对应的上下文。
+
+:::note
+直接在 Modern.js 应用中运行时，`<Router>` 组件会自动注入。
+:::
+
+## 运行测试用例
+
+执行上述 `test` 命令，运行测试用例：
+
+```bash
+✓ src/__tests__/page.test.tsx (1)
+  ✓ Page
+
+Test Files  1 passed (1)
+    Tests  1 passed (1)
+  Start at  15:37:12
+  Duration  999ms (transform 119ms, setup 0ms, collect 365ms, tests 33ms, environment 421ms, prepare 44ms)
+
+
+PASS  Waiting for file changes...
+```

package/docs/zh/guides/concept/_meta.json

@@ -0,0 +1 @@
+["entries", "builder", "server"]

package/docs/zh/guides/concept/builder.mdx

@@ -0,0 +1,60 @@
+---
+sidebar_position: 2
+---
+
+# 构建工具
+
+Modern.js 构建是基于 [Rsbuild](https://v2.rsbuild.rs/) 实现的，使用 Rspack 作为打包工具。
+
+:::tip 什么是 Rsbuild
+Rsbuild 是基于 Rspack 的构建工具，是一个增强版的 Rspack CLI，更易用、开箱即用。
+:::
+
+## 构建架构
+
+从构建的角度看，Modern.js 分为三层架构，从上到下依次是：
+
+- 研发框架：Modern.js。
+- 构建工具：Rsbuild。
+- 打包工具：Rspack。
+
+import Mermaid from '@site/src/components/Mermaid';
+
+<Mermaid>
+{`
+flowchart TD
+    Framework("研发框架: Modern.js")
+    BuildTool("构建工具: Rsbuild")
+    Bundler("打包工具: Rspack")
+
+    Framework --> BuildTool
+    BuildTool --> Bundler
+
+    style Framework fill:#FDE68A,stroke:#F59E0B,stroke-width:2px
+    style BuildTool fill:#86EFAC,stroke:#10B981,stroke-width:2px
+    style Bundler fill:#93C5FD,stroke:#3B82F6,stroke-width:2px
+
+`}
+
+</Mermaid>
+
+## 构建文档
+
+Rsbuild 的文档地址为：https://v2.rsbuild.rs/
+
+在该文档中，你可以了解到 Rsbuild 的详细介绍，同时也可以找到各个构建能力的完整使用指南。
+
+如果你想要了解某些构建配置的使用，建议你优先阅读 Modern.js 文档，因为 Modern.js 中的构建配置和默认值与 Rsbuild 并不完全相同。
+
+## 构建插件
+
+在 Modern.js 中，你可以注册 Rspack 插件或 Rsbuild 插件：
+
+- Rspack 插件：通过 [tools.bundlerChain](/configure/app/tools/bundler-chain) 配置。
+- Rsbuild 插件：通过 [builderPlugins](/configure/app/builder-plugins) 配置。
+
+## 构建能力
+
+Rsbuild 提供了丰富的构建能力，包括 JavaScript 编译、CSS 编译、静态资源处理、代码热更新、代码压缩、TS 类型检查等几十种能力。
+
+我们推荐你阅读 [「Rsbuild - 功能导航」](https://v2.rsbuild.rs/zh/guide/start/features) 来了解 Rsbuild 提供的所有构建能力。