Skip to content

Commit 907de18

Browse files
zhangpaopao0609zhangpaopao0609
authored
docs: update CONTRIBUTING.md and test README.md (#5056)
1 parent d42741c commit 907de18

File tree

3 files changed

+67
-139
lines changed

3 files changed

+67
-139
lines changed

‎CONTRIBUTING.md

+38-22
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212

1313
## 进行开发
1414

15-
请使用 `node 18` 与 `pnpm 9` 版本进行开发
15+
请使用 `node 18` 与 `pnpm 9` 版本进行开发。
1616

1717
### 1.初始化子仓库
1818

@@ -32,21 +32,37 @@ pnpm install
3232
pnpm run dev
3333
```
3434

35-
完成以上 3 个步骤，浏览器访问 <http://127.0.0.1:17000> 即可调试该框架的任何内容
35+
完成以上 3 个步骤，浏览器访问 <http://127.0.0.1:17000> 即可调试该框架的任何内容。
3636

3737
## 目录结构
3838

3939
```text
40-
├── script // 构建代码
41-
└── packages // 组件代码
42-
└─ components
43-
└─ componentA
44-
├── _example // 组件示例文档
45-
├── _usage // 组件 live demo
46-
└── __tests__ // 组件测试用例
47-
└─ tdesign-vue-next
48-
└─ site 站点代码
49-
```
40+
.
41+
├── internal // 仅供仓库内使用的包
42+
│ ├── tests // 测试公共逻辑
43+
│ └── utils // 基础 util
44+
├── script // 构建代码
45+
└── packages // 子应用
46+
├── common
47+
│ ├── docs
48+
│ ├── js
49+
│ ├── style
50+
│ │ ├── mobile
51+
│ │ └── web
52+
│ └── test
53+
├── components // 组件
54+
│ ├── componentA
55+
│ │ ├── __tests__ // 组件测试用例
56+
│ │ ├── _example // 组件示例文档
57+
│ │ ├── _example-ts // 组件示例文档
58+
│ │ ├── _usage // 组件 live demo
59+
│ │ └── style // 组件样式
60+
│ ├── style
61+
│ ├── utils
62+
└── tdesign-vue-next // tdesign-vue-next 出口
63+
├── helper // 供 vscode 等 IDE 使用
64+
├── site // 站点
65+
└── test // 测试配置
5066
5167
### 组件页路由配置
5268
@@ -85,11 +101,11 @@ pnpm run dev
85101

86102
### Demo 调试
87103

88-
我们可以通过打开组件的路由页进行开发调试，
104+
我们可以通过打开组件的路由页进行开发调试。
89105

90-
如 `button`，则打开<http://127.0.0.1:17000/vue-next/components/button> 进行开发调试；
106+
如 `button`，则打开<http://127.0.0.1:17000/vue-next/components/button> 进行开发调试。
91107

92-
但当组件的 `Markdown` 文件插入了很多个 `demo` 之后，一些组件生命周期方法调试起来会变得困难，若想对某个 `demo` 单独调试，可以访问路由：`/demos/组件名/demo` 名，
108+
但当组件的 `Markdown` 文件插入了很多个 `demo` 之后，一些组件生命周期方法调试起来会变得困难，若想对某个 `demo` 单独调试，可以访问路由：`/demos/组件名/demo` 名。
93109

94110
如：<http://127.0.0.1:17000/vue-next/demos/button/base>
95111

@@ -99,9 +115,9 @@ pnpm run dev
99115

100116
## 子仓库相关
101117

102-
TDesign 的项目都会以子仓库的形式引入 `tdesign-common` 公共仓库
118+
TDesign 的项目都会以子仓库的形式引入 `tdesign-common` 公共仓库。
103119

104-
公共仓库中包含
120+
公共仓库中包含：
105121
- 部分组件的一些框架无关的公共的工具函数
106122
- `组件库UI`，即 `HTML` 结构和 `CSS` 样式（多框架共用）
107123
- 每个组件的文档页面的内容结构
@@ -147,13 +163,13 @@ import './button.less';
147163

148164
### 分支
149165

150-
遵循使用 `git flow` 规范，新组件分支从 `develop checkout`：[https://nvie.com/posts/a-successful-git-branching-model/](https://nvie.com/posts/a-successful-git-branching-model/)
166+
遵循使用 `git flow` 规范，新组件分支从 `develop checkout`：[https://nvie.com/posts/a-successful-git-branching-model/](https://nvie.com/posts/a-successful-git-branching-model/)。
151167

152-
如果是贡献组件，则从 `develop checkout` 分支如：`feature/button`，记得如果同时要在子仓库开发 `UI`，子仓库也要 `checkout` 同名分支
168+
如果是贡献组件，则从 `develop checkout` 分支如：`feature/button`，记得如果同时要在子仓库开发 `UI`，子仓库也要 `checkout` 同名分支。
153169

154170
> 关于 fork
155171
156-
以下内容处理 `fork` 仓库后，远端仓库的更新如何同步到 `fork` 仓库
172+
以下内容处理 `fork` 仓库后，远端仓库的更新如何同步到 `fork` 仓库。
157173

158174
```bash
159175
# 建立 upstream remote
@@ -172,7 +188,7 @@ git merge upstream/develop
172188

173189
项目使用基于 angular 提交规范：[https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional](https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional)
174190

175-
每次提交会自动触发提交验证
191+
每次提交会自动触发提交验证：
176192

177193
- 使用工具 `commitizen` 协助规范 `git commit` 信息
178194
- `fix` & `feat` 的提交会被用来生成 `changelog`
@@ -190,4 +206,4 @@ git merge upstream/develop
190206

191207
### CSS 规范
192208

193-
组件样式在 `common` 子仓库开发，遵循 [tdesign-common 仓库 UI 开发规范](https://github.com/Tencent/tdesign-common/blob/main/style/web/README.md)
209+
组件样式在 `common` 子仓库开发，遵循 [tdesign-common 仓库 UI 开发规范](https://github.com/Tencent/tdesign-common/blob/main/style/web/README.md)。

‎packages/tdesign-vue-next/test/README.md

+24-112
Original file line numberDiff line numberDiff line change
@@ -5,95 +5,47 @@
55
### 主要 script 命令
66

77
```bash
8-
## 组件单元测试与组件快照测试
9-
npm run test
10-
11-
## 快照更新
12-
npm run test:update
8+
# 组件单元测试与组件快照测试
9+
pnpm run test
10+
# 快照更新
11+
pnpm run test:update
1312
```
1413

1514
### 组件单元测试 `unit`
1615

1716
```bash
18-
19-
npm run test:unit
20-
21-
## 开发环境
22-
npm run test:unit-dev
23-
24-
## 开发环境-指定组件
25-
npm run test:unit-dev button
26-
27-
## 开发环境gui
28-
npm run test:unit-gui
29-
30-
## 开发环境gui-指定组件
31-
npm run test:unit-gui button
32-
33-
## 生成覆盖率报告
34-
npm run test:unit-coverage
17+
# 单测
18+
pnpm run test:unit
19+
# 开发环境
20+
pnpm run test:unit-dev
21+
# 开发环境-指定组件
22+
pnpm run test:unit-dev button
23+
# 开发环境 展示 UI 界面
24+
pnpm run test:unit-gui
25+
# 开发环境 展示 UI 界面-指定组件
26+
pnpm run test:unit-gui button
27+
# 生成覆盖率报告
28+
pnpm run test:unit-coverage
3529
```
3630

3731
### 组件快照测试 `snap`
3832

3933
```bash
40-
npm run test:snap
34+
# 快照
35+
pnpm run test:snap
36+
# 更新快照
37+
pnpm run test:snap-update
4138
```
4239

43-
### 目录结构
44-
45-
```
46-
test 测试目录
47-
|-- e2e UI测试
48-
|-- unit 单元测试
49-
|-- snap 快照测试
50-
|-- ...
51-
```
52-
53-
## 单元测试
54-
55-
```shell
56-
npm run test:unit
57-
```
40+
## 单元测试规范
5841

59-
详情见 [TDesign 单元测试规范](https://github.com/Tencent/tdesign-vue-next/wiki/TDesign-%E5%8D%95%E5%85%83%E6%B5%8B%E8%AF%95%E8%A7%84%E8%8C%83)
42+
详情见 [TDesign 单元测试规范](https://github.com/Tencent/tdesign-vue-next/wiki/TDesign-%E5%8D%95%E5%85%83%E6%B5%8B%E8%AF%95%E8%A7%84%E8%8C%83)。
6043

61-
## 注意事项
62-
63-
## E2E 测试
64-
65-
调研后发现 cypress 可以覆盖 Puppeteer 的 E2E 测试场景，优先选择了 cypress 作为测试框架，它能实现以下功能：
66-
67-
- 开箱即用
68-
- 官方 doc 很多，利于开发与维护
69-
- gui 界面（ env：google 浏览器），可边测边调整
70-
- 自定义 commands
71-
- 自定义 fixture，可 mock 数据
72-
- 支持 ci 运行测试，可上传到 bashBoard
73-
- 关注测试覆盖率（ Chrome 的 coverage ）
74-
- 截图功能，用例失败的场景节点会被截图保存，利于复现
75-
- 录屏功能，每个测试用例都会记录下来（ MP4 ）
76-
- 社区其他的插件支持
77-
78-
## 如何运行
79-
80-
### cli 运行
81-
82-
```shell
83-
npm run cypress
84-
```
85-
86-
### GUI 界面运行
87-
88-
```shell
89-
npm run cypress-gui
90-
```
91-
92-
## 测试规范
44+
## 测试示例
9345

9446
使用 BDD 模式进行开发，必须在流水线里面通过单元测试。
9547

96-
```shell
48+
```ts
9749
describe('测试按钮组件', () => {
9850
beforeEach(() => {
9951
// 打开某个页面
@@ -111,43 +63,3 @@ describe('测试按钮组件', () => {
11163
});
11264

11365
```
114-
115-
## 测试示例
116-
117-
```shell
118-
describe('测试按钮组件', () => {
119-
beforeEach(() => {
120-
// 打开某个页面
121-
cy.visit('/#/components/button');
122-
});
123-
// 测试用例定义
124-
it('case1: 测试三种按钮类型，内容，渲染正确的类型跟内容', function() {
125-
cy.get('.button')
126-
.should(ele => {
127-
expect(ele).to.have.text('按钮1');
128-
});
129-
...
130-
});
131-
it('case2: 测试按钮尺寸，渲染正确的大小', function() {
132-
});
133-
it('case3: 测试带图标按钮，按钮内容里的图标位置', function() {
134-
});
135-
it('case4: 测试loading状态的按钮', function() {
136-
});
137-
});
138-
139-
```
140-
141-
## 注意事项
142-
143-
e2e 测试建议放在 test/e2e/ 目录下面
144-
common script 配置文件（包含测试相关配置文件）
145-
146-
```
147-
src
148-
test 测试目录
149-
|-- e2e // 这里面放 e2e 的测试内容
150-
|-- unit
151-
|-- ssr
152-
|-- ...
153-
```

‎packages/tdesign-vue-next/test/package.json

+5-5
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,12 @@
66
"scripts": {
77
"test": "pnpm test:unit && pnpm test:snap",
88
"test:unit": "vitest run",
9-
"test:update": "vitest run -u && pnpm test:snap-update",
9+
"test:update": "vitest run -u && pnpm test:snap-update",
1010
"test:unit-dev": "vitest",
11-
"test:unit-gui": "vitest --ui",
12-
"test:unit-coverage": "vitest run --coverage",
13-
"test:snap": "cross-env NODE_ENV=test-snap vitest run ",
14-
"test:snap-update": "cross-env NODE_ENV=test-snap vitest run -u"
11+
"test:unit-gui": "vitest --ui",
12+
"test:unit-coverage": "vitest run --coverage",
13+
"test:snap": "cross-env NODE_ENV=test-snap vitest run",
14+
"test:snap-update": "cross-env NODE_ENV=test-snap vitest run -u"
1515
},
1616
"devDependencies": {
1717
"@vue/test-utils": "^2.4.1",

0 commit comments

Comments
 (0)