@modern-js/main-doc 2.51.0 → 2.53.0

package/docs/zh/apis/app/runtime/testing/render.mdx

@@ -1,71 +0,0 @@
----
-title: render
----
-# render
-
-用于在测试用例中渲染组件，完成测试。
-
-## 使用姿势
-
-```ts
-import { render } from '@modern-js/runtime/testing';
-```
-
-## 函数签名
-
-```ts
-type Options = {
-  container: DOMElement;
-  baseElement: DOMElement;
-  hydrate: boolean;
-  warpper: React.ComponentType<{children: ReactNode}>;
-  queries: any;
-};
-
-type RenderResult = {
-  {...queries}: any;
-  container: DOMElement;
-  baseElement: DOMElement;
-  debug: function;
-  rerender: function;
-  unmount: function;
-  asFragment: function;
-}
-
-function render(ui: React.ReactElement<any>, options: Options): RenderResult;
-```
-
-### 参数
-
-- `ui`：需要被渲染的 React 组件。
-- `options`：render 可选配置。
-  - `container`：表示组件所要挂载到的 DOM 节点，默认是会创建一个 `div` 元素，并自动添加到 `document.body` 上。这个 `div` 元素就是组件要挂载的节点。默认值是 `document.body.append(document.createElement('div'))`。
-  - `baseElement`：用于指定 `queries` 中使用到的 `basename`。如果指定了 `container`, 则默认值为 `container` 的值，否则就是 `document.body`。
-  - `hydrate`：如果设置为 `true`，则会使用 [ReactDOM.hydrate](https://zh-hans.react.dev/reference/react-dom/hydrate) 渲染组件。默认值为 `false`。
-  - `wrapper`：是一个 react 组件，可用于自定义渲染逻辑。
-  - `queries`：自定义一些自己的 `queries`。
-
-### 返回值
-
-- `{...queries}`：所有可用的 [queries](https://testing-library.com/docs/queries/about/)。
-- `container`：挂载 React 组件的 DOM 节点。
-- `baseElement`
-- `debug`
-- `rerender`：如果想测试一个已渲染的组件在其 props 更新时的一些场景，可以使用 rerender 来现实。
-- `unmount`：会卸载掉已渲染的组件。如果想测试组件卸载后的情况（如，绑定的事件是否在 unmount 阶段被卸载掉），那么这个 API 是很帮助的。
-- `asFragment`：返回当前渲染的组件的 [DocumentFragment](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) 对象。可用于测试 react 事件触发后 DOM 结构的响应。
-
-## 示例
-
-```ts
-import { render } from '@modern-js/runtime/testing';
-import App from './App';
-
-test('renders a message', () => {
-  const { container, getByText } = render(<App />);
-  expect(getByText('Hello, world!')).toBeInTheDocument();
-  expect(container.firstChild).toMatchInlineSnapshot(`
-    <h1>Hello, World!</h1>
-  `);
-});
-```

package/docs/zh/apis/app/runtime/testing/renderApp.mdx

@@ -1,32 +0,0 @@
----
-title: renderApp
----
-# renderApp
-
-`render` 函数用于测试普通组件，`renderApp` 函数用于测试应用组件。
-
-## 使用姿势
-
-```ts
-import { renderApp } from '@modern-js/runtime/testing';
-```
-
-应用组件指包含一些 Modern.js 上下文的组件，如 App 根组件，使用了 Model 的 Container 等。对于这类组件的测试，可以使用 `renderApp` 函数，会自动按照当前 `modern.config.js` 配置，包裹上对应的上下文信息。
-
-## 函数签名
-
-`renderApp` 和 [render](./render.mdx) 完全一致。
-
-## 示例
-
-```ts
-import { renderApp } from '@modern-js/runtime/testing';
-import App from './App';
-
-describe('test', () => {
-  it('test App', () => {
-    const { getByText } = renderApp(<App />);
-    expect(getByText('Hello Modern!')).toBeInTheDocument();
-  });
-});
-```

package/docs/zh/configure/app/testing/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "testing 测试",
-  "position": 10
-}

package/docs/zh/configure/app/testing/transformer.mdx

@@ -1,19 +0,0 @@
----
-title: testing.transformer
-sidebar_label: transformer
-sidebar_position: 1
----
-# transformer
-
-- **类型：** `'babel-jest' | 'ts-jest'`
-- **默认值：** `babel-jest`
-
-:::caution Caution
-请先在当前应用项目根目录使用 [new](/apis/app/commands#modern-new) 启用测试功能。
-:::
-
-配置执行测试时的编译工具，默认使用 `babel-jest`。可配置为 [babel-jest](https://www.npmjs.com/package/babel-jest) 或 [ts-jest](https://github.com/kulshekhar/ts-jest)。
-
-:::info 补充信息
-`babel-jest` 可以编译 TS 文件，但没有类型校验。如果你希望运行测试用例的时，能对 TS 类型进行校验，可以使用 `ts-jest`。
-:::

package/docs/zh/configure/app/tools/jest.mdx

@@ -1,40 +0,0 @@
----
-sidebar_label: jest
----
-
-# tools.jest
-
-- **类型：** `Object | Function`
-- **默认值：** `{}`
-
-:::caution 注意
-需要先通过 `pnpm run new` 启用 单元测试 功能。
-
-:::
-
-对应 [Jest](https://jestjs.io/docs/configuration) 的配置，当为 `Object` 类型时，可以配置 Jest 所支持的所有底层配置 。
-
-```js title=modern.config.js
-export default defineConfig({
-  tools: {
-    jest: {
-      testTimeout: 10000,
-    },
-  },
-});
-```
-
-值为 `Function` 类型时，默认配置作为第一个参数传入，需要返回新的 Jest 配置对象。
-
-```js title=modern.config.js
-export default defineConfig({
-  tools: {
-    jest: options => {
-      return {
-        ...options,
-        testTimeout: 10000,
-      };
-    },
-  },
-});
-```

package/docs/zh/guides/advanced-features/testing.mdx

@@ -1,47 +0,0 @@
----
-sidebar_position: 14
----
-
-# 使用 Jest 测试
-
-Modern.js 默认集成了 [Jest](https://jestjs.io/) 的测试能力。
-
-我们首先需要执行 `pnpm run new` 启用「单元测试 / 集成测试」功能：
-
-```bash
-? 请选择你想要的操作 启用可选功能
-? 请选择功能名称 启用「单元测试 / 集成测试」功能
-```
-
-执行上述命令后，`package.json` 中将会自动添加 `"test": "modern test"` 命令。
-
-在 `modern.config.ts` 中注册 `@modern-js/plugin-testing` 插件后即可使用测试功能：
-
-```ts title="modern.config.ts"
-import { testingPlugin } from '@modern-js/plugin-testing';
-
-export default defineConfig({
-  ...,
-  plugins: [..., testingPlugin()],
-});
-```
-
-## 测试文件
-
-Modern.js 默认识别的测试文件路径为：`<rootDir>/src/**/*.test.[jt]s?(x)` 和 `<rootDir>/tests/**/*.test.[jt]s?(x)`。
-
-如果你需要自定义 test 目录，可通过 [tools.jest](/configure/app/tools/jest) 进行配置。
-
-## 使用姿势
-
-Modern.js test 支持使用 [testing-library](https://testing-library.com/docs/) 相关包 API，可直接通过 `@modern-js/runtime/testing` 进行导入:
-
-```ts
-import { render, screen } from '@modern-js/runtime/testing';
-```
-
-其他 Modern.js 支持的 testing API 可参考[这里](/apis/app/runtime/testing/cleanup)。
-
-## transform
-
-Modern.js 测试默认使用 [babel-jest](https://www.npmjs.com/package/babel-jest) 进行源码编译，如果你需要使用 [ts-jest](https://github.com/kulshekhar/ts-jest)，可以通过 [testing.transform](/configure/app/testing/transformer) 进行配置。

package/docs/zh/guides/topic-detail/changesets/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "包版本管理",
-  "position": 5
-}

package/docs/zh/guides/topic-detail/changesets/add.mdx

@@ -1,126 +0,0 @@
----
-sidebar_position: 2
----
-
-# 添加 Changesets
-
-当我们开发完成时，需要添加一个 changeset 声明当前变更，用于后续版本发布。
-
-## 信息
-
-一个 changeset 包含的内容包括：
-
-- 本次变更涉及哪些包的变更。
-
-- 本次变更需要升级的版本号类型，类型符合 [semver](https://semver.org/) 规范。
-
-- 本次变更的 changelog 信息。
-
-## 步骤
-
-:::info
-以下示例命令都以 pnpm 作为包管理工具进行，如果需要使用其他包管理工具，请按需求进行替换。
-
-:::
-
-### Modern.js Module
-
-#### 在根目录执行 change 命令
-
-```bash
-pnpm run change
-```
-
-#### 选择本次变更需要升级的版本号类型
-
-![选择版本类型](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-select-version.png)
-
-#### 填入 changelog 信息，并点击两次回车：
-
-![写入变更信息](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-input-changelog.png)
-
-执行完成后，将在项目的 `.changeset` 目录创建对应的 changeset 文件，文件内容如下：
-
-```markdown
----
-'module-changeset': patch
----
-
-feat: test module solution changeset
-```
-
-该文件中包含了 changeset 的所有信息。
-
-### Monorepo 工程方案
-
-我们假设 monorepo 中存在三个模块包，分别为 `module-1`，`module-2`，`module-3`。
-
-#### 在根目录执行 change 命令
-
-```bash
-pnpm run change
-```
-
-#### 选择本次需要升级的包列表
-
-Changesets 会根据当前代码变更(`git diff Head...baseBranch`)，将 Monorepo 中的 package 分为两类，`changed packages` 和 `unchanged packages`，方便用户进行选择。
-
-使用空格键选择对应的包或者分类即可，选择完成后点击回车：
-
-![选择升级包](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-select-packages.png)
-
-#### 分别选择不同版本类型对应的包
-
-changeset 会询问 `major` 和 `minor` 类型，如果存在包未选择这两种类型，将会默认使用 `patch` 类型。
-
-![选择升级包版本类型](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-auto-select-patch.png)
-
-#### 填入 changelog 信息
-
-![写入变更信息](https://lf3-static.bytednsdoc.com/obj/eden-cn/zq-uylkvT/ljhwZthlaukjlkulzlp/changeset-input-changelog-monorepo.png)
-
-执行完成后，将在项目的 `.changeset` 目录创建对应的 changeset 文件，文件内容如下：
-
-```markdown
----
-'module-2': minor
-'module-3': patch
----
-
-feat: test-changeset
-```
-
-该文件中包含了 changeset 的所有信息，不同的包也会根据选择的版本类型进行标记。
-
-## 参数
-
-change 命令支持以下参数：
-
-- `--empty`： 添加一个空的 changeset。
-
-```bash
-pnpm run change --empty
-```
-
-执行完成后，将在项目的 `.changeset` 目录创建空的 changeset 文件，文件内容如下：
-
-```markdown
----
----
-```
-
-- `--open`： 使用该参数时，在填写 changelog 步骤会打开系统默认编辑器进行填写。
-
-## 注意事项
-
-- 不是所有的变更都需要 changeset
-
-如果当前变更是修改仓库的一些基础设施，比如 CI、测试等，就不需要添加 changeset 或者可以添加一个空的 changeset。
-
-- 一个 pull reuqest 可以提交多个 changeset
-
-当一个 pull request 存在多个功能开发或者问题修复时，可以多次执行 `pnpm run change` 添加多个 changeset 文件，每个文件选择对应功能的包和添加变更信息即可。
-
-- 创建 changeset 时，需要选择该功能相关的所有包
-
-在 Monorepo 中创建 changeset 时，需要选中和该功能相关的所有变更包，避免出现发版时部分包未发布的情况。

package/docs/zh/guides/topic-detail/changesets/changelog.mdx

@@ -1,238 +0,0 @@
----
-sidebar_position: 6
----
-
-# 自定义 changelog 生成
-
-Changesets 默认会使用 `@changesets/cli/changelog` 生成 Changelog 信息，如果默认的 changelog 信息不能满足需求，可以自定义 changelog 的生成。
-
-## 自定义 changelog 内容
-
-changelog 信息主要包含以下两种信息：
-
-- changeset 中写入的 changelog 信息。
-
-- 本次版本升级关联包的版本变更信息。
-
-自定义逻辑主要实现两个函数，`getReleaseLine` 和 `getDependencyReleaseLine`，分别用来定义上述这两种信息。
-
-### getReleaseLine
-
-#### Params
-
-- changeset
-
-```ts
-export type VersionType = 'major' | 'minor' | 'patch' | 'none';
-
-export type Release = { name: string; type: VersionType };
-
-export type Changeset = {
-  id: string; // changeset 的文件名称
-  commit?: string; // changeset 提交时的 commit id 信息
-  summary: string; // changeset 内容信息
-  releases: Array<Release>; // 当前计算出的 changeset 升级包名称及类型信息
-};
-```
-
-- type
-
-当前包对应的升级版本类型，类型为上述 `VersionType`。
-
-#### 返回值
-
-changelog 内容。
-
-#### 默认实现
-
-`@changesets/cli/changelog` 默认处理逻辑为将 `summary` 信息按照换行符 `\n` 分割，第一样前面增加 `-` 作为列表开头，其他内容作为第一行内容的补充整理在列表下方。
-
-```ts
-async function getReleaseLine(changeset, type) {
-  const [firstLine, ...futureLines] = changeset.summary
-    .split('\n')
-    .map(l => l.trimRight());
-
-  let returnVal = `- ${
-    changeset.commit ? `${changeset.commit}: ` : ''
-  }${firstLine}`;
-
-  if (futureLines.length > 0) {
-    returnVal += `\n${futureLines.map(l => `  ${l}`).join('\n')}`;
-  }
-
-  return returnVal;
-}
-```
-
-### getDependencyReleaseLine
-
-#### Params
-
-- changesets
-
-当前关联的所有 changeset 信息，类型为 `getReleaseLine` changeset 类型数组。
-
-- dependenciesUpdated
-
-```ts
-type ModCompWithPackage = {
-  name: string; // 依赖模块名称
-  type: VersionType; // 依赖模块的升级类型
-  oldVersion: string; // 依赖模块当前版本号
-  newVersion: string; // 依赖模块新版本号
-  changesets: string[]; // 关联的 changeset id 列表
-  packageJson: PackageJSON; // 依赖模块完整的 package.json 内容
-  dir: string; // 依赖模块的路径(绝对路径)
-};
-
-type DependenciesUpdated = ModCompWithPackage[];
-```
-
-#### 返回值
-
-changelog 内容。
-
-#### 默认实现
-
-`@changesets/cli/changelog` 默认会使用 changesets 信息展示对应的 `Updated dependencies + commit id`，以列表形式展示。然后根据 `dependenciesUpdated` 信息展示对应的依赖包包名和新版本号，作为列表的子列表项。
-
-```ts
-async function getDependencyReleaseLine(changesets, dependenciesUpdated) {
-  console.log('getDependencyReleaseLine', changesets, dependenciesUpdated);
-  if (dependenciesUpdated.length === 0) return '';
-
-  const changesetLinks = changesets.map(
-    changeset =>
-      `- Updated dependencies${
-        changeset.commit ? ` [${changeset.commit}]` : ''
-      }`,
-  );
-
-  const updatedDepenenciesList = dependenciesUpdated.map(
-    dependency => `  - ${dependency.name}@${dependency.newVersion}`,
-  );
-
-  return [...changesetLinks, ...updatedDepenenciesList].join('\n');
-}
-```
-
-展示效果为：
-
-```markdown
-- Updated dependencies [f0438ab]
-- Updated dependencies [f0438ab]
-  - module-3@2.0.0
-  - module-1@0.2.0
-```
-
-## 配置
-
-Changesets 配置文件中 `changelog` 字段用于标记 changelog 信息的获取途径。
-
-该配置可以为字符串，直接声明获取 changelog 信息模块的模块名称或者路径。
-
-该配置还支持配置数组，数组中第一个元素为获取 changelog 信息模块的模块名称或者路径，第二个元素为传入对应函数的参数值，会作为 `getReleaseLine` 和 `getDependencyReleaseLine` 函数的第三个参数传入。
-
-### 配置相对路径
-
-changelog 配置如果为相对路径为 `.changesets` 目录下的相对路径。
-
-例如创建 `.changeset/my-changelog-config.js` 文件，定义如下内容：
-
-```ts title=".changeset/my-changelog-config.js"
-async function getReleaseLine(changeset, type) {}
-
-async function getDependencyReleaseLine(changesets, dependenciesUpdated) {}
-
-module.exports = {
-  getReleaseLine,
-  getDependencyReleaseLine,
-};
-```
-
-`changlog` 配置为 `./my-changelog-config.js` 即可:
-
-```json title=".changesets/config.json"
-{
-  "changelog": "./my-changelog-config.js",
-   ...
-}
-```
-
-### 使用 Modern.js Module
-
-自定义 changelog 还可以使用 Modern.js Module 方案进行管理，提供通用方案。
-
-#### 使用 `npx @modern-js/create@latest` 创建 Modern.js Module
-
-```md
-? 请选择你想创建的工程类型：Npm 模块
-? 请填写项目名称：custom-changelog
-? 请选择开发语言：TS
-? 请选择包管理工具：pnpm
-```
-
-#### 实现自定义内容
-
-```ts title="src/index.ts"
-export async function getReleaseLine() {}
-
-export async function getDependencyReleaseLine() {}
-```
-
-#### 将模块发布到 NPM
-
-#### 在目标仓库根目录安装对应模块，例如 `custom-changelog`
-
-#### 配置 changeset 的 changelog 配置为包名称
-
-```json title=".changesets/config.json"
-{
-  "changelog": "custom-changelog",
-   ...
-}
-```
-
-### 使用 Monorepo 工程方案
-
-如果你当前仓库为 Monorepo 工程方案，可以直接使用模块子项目进行管理。
-
-#### 执行 `pnpm run new` 创建模块子项目
-
-```md
-? 请选择你想创建的工程类型：Npm 模块
-? 请填写子项目名称：custom-changelog
-? 请填写子项目目录名称：custom-changelog
-? 请选择开发语言：TS
-```
-
-#### 实现自定义内容
-
-```ts title="src/index.ts"
-export async function getReleaseLine() {}
-
-export async function getDependencyReleaseLine() {}
-```
-
-#### 在 Monorepo 根目录添加子项目模块依赖，例如 `custom-changelog`
-
-```json title="package.json"
-{
-  "devDependencies": {
-    "custom-changelog": "workspace:*",
-    ...
-  }
-}
-```
-
-#### 配置 changeset 的 changelog 配置为包名称
-
-```json title=".changesets/config.json"
-{
-  "changelog": "custom-changelog",
-   ...
-}
-```
-
-该模块发布到 NPM 后，依然可以和模块类型一样供其他仓库使用。