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

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

@@ -0,0 +1,111 @@
+# Playwright
+
+Playwright is a testing framework that allows you to run tests automatically in Chromium, Firefox, and WebKit environments using a single API. You can use it to **write E2E tests**.
+
+To use Playwright in Modern.js, you need to install the dependencies first. You can run the following commands:
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command={{ npm: "npm init playwright", yarn: "yarn create playwright", pnpm: "pnpm create playwright" }} />
+
+The above commands will automatically install Playwright dependencies and help you install and configure it in your project through a series of prompts, including adding a `playwright.config.ts` file.
+
+:::info
+Refer to the official Playwright documentation at [Install Playwright](https://playwright.dev/docs/intro#installation) for a more detailed guide.
+:::
+
+After creating with the default configuration, you can see the following files in your project:
+
+```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();
+});
+```
+
+This is the default test file. Now create some new pages and test them.
+
+## Create E2E Tests
+
+First, create two Modern.js pages.
+
+```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;
+```
+
+Next, add test cases to ensure the links on your pages work properly.
+
+```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')
+})
+```
+
+## Run Test Cases
+
+Playwright requires your Modern.js server to be running. We recommend running your test cases under production builds; you can run `pnpm run build` and `pnpm run serve` to simulate the production environment locally.
+
+```bash
+info    Starting production server...
+
+  > Local:    http://localhost:8080/
+  > Network:  http://10.94.59.30:8080/
+```
+
+After the project is successfully built and running, you can run Playwright cases in another terminal by executing `npx playwright test`:
+
+```bash
+Running 3 tests using 3 workers
+  3 passed (2.0s)
+
+To open last HTML report run:
+
+  npx playwright show-report
+```

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

@@ -0,0 +1,163 @@
+# Rstest
+
+[Rstest](https://rstest.rs) is a testing framework developed by the Rspack team and built on top of Rspack for fast test execution.
+
+This guide explains how to integrate Rstest with Modern.js for web app testing.
+
+## Quick Start
+
+Install the base dependencies first:
+
+import { PackageManagerTabs } from '@theme';
+
+<PackageManagerTabs command="add @rstest/core @modern-js/adapter-rstest -D" />
+
+Then create `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` lets Rstest inherit your existing Modern.js config so your test setup stays aligned with your app.
+
+For more configuration details, refer to the [Rstest configuration documentation](https://rstest.rs/config).
+
+You can run tests with `npx rstest`, or add a script in `package.json`:
+
+```json title="package.json"
+{
+  "scripts": {
+    "test": "rstest"
+  }
+}
+```
+
+## Testing Web UI
+
+For web UI tests in Modern.js, there are two common approaches:
+
+- Use Rstest browser mode, which runs tests in a real browser. This is the recommended option in most cases, although it is currently experimental.
+- Use a simulated DOM environment with `happy-dom` and Testing Library. This matches the default web test environment provided by `@modern-js/adapter-rstest`.
+
+We generally recommend browser mode because it uses real browser APIs and behavior, supports cases that simulated DOM environments cannot fully cover, and offers a better debugging experience when UI behavior does not match expectations.
+
+### Browser mode (experimental)
+
+If you want to test in a real browser instead of a simulated DOM, install the browser mode dependencies:
+
+<PackageManagerTabs command="add @rstest/browser @rstest/browser-react playwright -D" />
+
+Then enable browser mode in `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(),
+  browser: {
+    enabled: true,
+    provider: 'playwright',
+  },
+});
+```
+
+Example test:
+
+```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();
+});
+```
+
+For more browser mode setup, Locator APIs, and assertions, refer to the [Rstest documentation](https://rstest.rs/guide/browser-testing/).
+
+### DOM simulation with `happy-dom`
+
+Install the DOM testing dependencies:
+
+<PackageManagerTabs command="add happy-dom @testing-library/react @testing-library/dom -D" />
+
+Update `rstest.config.ts` to use `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',
+});
+```
+
+First, create a simple page for testing:
+
+```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;
+```
+
+Then add a test case:
+
+```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();
+});
+```
+
+## Running Test Cases
+
+Execute the `test` command above to run your tests:
+
+```bash
+✓ __tests__/page.test.tsx (1)
+  ✓ Page
+
+ Test Files 1 passed
+      Tests 1 passed
+   Duration 510ms (build 145ms, tests 365ms)
+```
+
+## Node Mode
+
+If you need node mode tests for server-side logic such as `bff`, refer to the [Rstest documentation](https://rstest.rs) directly.
+
+Modern.js mainly targets web apps, so this guide focuses on web UI testing and browser mode.

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

@@ -0,0 +1,100 @@
+# Vitest
+
+Vitest is a testing framework driven by Vite, which can be used for unit testing in combination with React Testing Library.
+
+To use Vitest in Modern.js, you need to install the dependencies first. You can run the following commands:
+
+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"
+}} />
+
+Next, you need to create a Vitest configuration file `vitest.config.ts` with the following content:
+
+```ts title="vitest.config.ts"
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+ 
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: 'jsdom',
+  },
+})
+```
+
+For more information about Vitest configuration, you can refer to the [Vitest configuration documentation](https://vitest.dev/config/#configuration).
+
+You can optionally add the `vitest` command to `package.json`:
+
+```json title="package.json"
+{
+  "scripts": {
+    "test": "vitest"
+  }
+}
+```
+
+After running this command, Vitest will automatically watch your file changes and rerun the test cases.
+
+## Create Unit Tests
+
+First, create a simple page for testing:
+
+```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;
+```
+
+Add a test case to check if the page has the expected text:
+
+```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();
+});
+```
+
+In the above test case, we imported the `<Router>` component from `@modern-js/runtime/router` because React Router requires the corresponding context when rendering some route-related components.
+
+:::note
+When running directly in the Modern.js application, the `<Router>` component will be automatically injected.
+:::
+
+## Run Test Cases
+
+Execute the above `test` command to run the test cases:
+
+```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/en/guides/concept/_meta.json

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

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

@@ -0,0 +1,60 @@
+---
+sidebar_position: 2
+---
+
+# Build Engine
+
+Modern.js internally encapsulates [Rsbuild](https://v2.rsbuild.rs/), using Rspack as the bundler.
+
+::: tip What is Rsbuild?
+Rsbuild is a build tool based on Rspack. It is an enhanced Rspack CLI, easy-to-use, and ready-to-use out of the box.
+:::
+
+## Build Architecture
+
+From the building perspective, Modern.js can be divided into three-layers, from top to bottom:
+
+- Upper-level framework: Modern.js.
+- Build tool: Rsbuild.
+- Bundler: Rspack.
+
+import Mermaid from '@site/src/components/Mermaid';
+
+<Mermaid>
+{`
+flowchart TD
+    Framework("Upper-level Framework: Modern.js")
+    BuildTool("Build Tool: Rsbuild")
+    Bundler("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>
+
+## Build Documentation
+
+The documentation address of Rsbuild is: https://v2.rsbuild.rs/
+
+In this documentation, you can learn about the detailed introduction of Rsbuild, and you can also find complete usage guides for various building capabilities.
+
+If you want to understand the use of build configurations, it is recommended that you read the Modern.js documentation first, because the build configurations and defaults in Modern.js are not exactly the same as Rsbuild.
+
+## Build Plugins
+
+In Modern.js, you can register Rspack plugins or Rsbuild plugins:
+
+- Rspack plugins: Configured through [tools.bundlerChain](/configure/app/tools/bundler-chain).
+- Rsbuild plugins: Configured through [builderPlugins](/configure/app/builder-plugins).
+
+## Build Capabilities
+
+Rsbuild provides rich build capabilities, including JavaScript compilation, CSS compilation, static assets processing, code hot update, code compression, TS type checking, and dozens of other capabilities.
+
+We recommend that you read [「Rsbuild - All Features」](https://v2.rsbuild.rs/guide/start/features) to learn about all the features provided by Rsbuild.