pytest-pure-report 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 pytest-pure-report
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,675 @@
1
+ Metadata-Version: 2.4
2
+ Name: pytest-pure-report
3
+ Version: 1.0.0
4
+ Summary: A beautiful HTML report plugin for pytest, with comprehensive statistics and interactive features.
5
+ Author-email: Test Automation Team <test@example.com>
6
+ License: MIT License
7
+
8
+ Copyright (c) 2024 pytest-pure-report
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+
28
+ Project-URL: Homepage, https://github.com/example/pytest-pure-report
29
+ Project-URL: Bug Tracker, https://github.com/example/pytest-pure-report/issues
30
+ Classifier: Framework :: Pytest
31
+ Classifier: Programming Language :: Python :: 3
32
+ Classifier: Programming Language :: Python :: 3.8
33
+ Classifier: Programming Language :: Python :: 3.9
34
+ Classifier: Programming Language :: Python :: 3.10
35
+ Classifier: Programming Language :: Python :: 3.11
36
+ Classifier: Programming Language :: Python :: 3.12
37
+ Classifier: License :: OSI Approved :: MIT License
38
+ Classifier: Operating System :: OS Independent
39
+ Requires-Python: >=3.8
40
+ Description-Content-Type: text/markdown
41
+ License-File: LICENSE
42
+ Requires-Dist: pytest>=7.0.0
43
+ Dynamic: license-file
44
+
45
+ # pytest-pure-report
46
+
47
+ 美观、实用的 pytest HTML 报告插件,提供清晰的测试统计和丰富的交互功能。
48
+
49
+ ## 功能特性
50
+
51
+ ### 统计与可视化
52
+ - 完整的测试状态统计:通过、失败、错误、跳过、预期失败、意外通过、未执行
53
+ - 饼图直观展示通过率,堆叠条形图展示各测试类的用例分布
54
+ - 智能统计公式:总用例数、已收集、有效用例数、通过率
55
+
56
+ ### 自定义与设计
57
+ - 自定义 Logo(支持本地图片或远程 URL)
58
+ - 自定义报告标题和测试环境标识
59
+ - 现代化浅色主题,清晰可读的布局
60
+ - 全屏自适应布局,适配不同尺寸屏幕(小屏自动转为上下布局)
61
+
62
+ ### 测试结果(左右结构)
63
+ - 参考 Allure 报告的左右结构布局:左侧为测试用例树,右侧为用例详情
64
+ - 点击左侧测试用例后,右侧展示该用例的完整详情
65
+ - 支持 Allure 装饰器(feature/story/title),自动构建层级路径
66
+ - 按功能模块 > 用户故事分组展示,支持展开/折叠
67
+ - 搜索过滤:按名称搜索,按状态筛选
68
+ - 合并显示位置字段:`文件路径>类名>方法名`
69
+
70
+ ### 执行过程(Execution)
71
+ - 每个测试用例的执行过程按阶段分组展示:
72
+ - **前置处理(Set up)**:fixture 中 yield 之前的步骤
73
+ - **测试步骤(Test Body)**:测试用例主体执行过程
74
+ - **后置处理(Tear down)**:fixture 中 yield 之后的步骤
75
+ - fixture 无嵌套内容时不显示展开箭头,有内容时可点击展开
76
+ - pure.step 步骤可点击展开,显示该步骤执行期间捕获的日志和附件
77
+
78
+ ### 媒体支持
79
+ - 支持测试截图,支持缩略图预览和大图查看(可配置 always/fail_only/never)
80
+ - 支持测试录屏,支持在线播放(可配置 always/fail_only/never)
81
+ - 支持 Playwright Trace 录制与可视化回放(可配置 always/fail_only/never)
82
+ - 按用例独立录制,每个用例生成一个 trace zip 文件
83
+ - 报告中每个用例卡片下显示「🎬 Trace 记录」区段(无 trace 时自动隐藏)
84
+ - 点击「查看 Trace」按钮在新标签页打开 Playwright Trace Viewer,可前后穿梭于测试每个操作,直观查看页面快照、DOM、网络请求、控制台日志等
85
+ - 自动复制 Playwright 自带 Trace Viewer SPA 资源到报告目录,支持离线查看
86
+
87
+ ### 交互功能
88
+ - 返回顶部按钮,方便快速导航
89
+ - 失败用例显示完整错误堆栈和执行原因
90
+
91
+ ### pure 公共 API(推荐使用)
92
+ - 完全参考 `allure` 的 API 设计,提供装饰器、上下文管理器和动态函数
93
+ - **操作步骤**:通过 `pure.step` 记录步骤(自动捕获异常状态、自动识别阶段、自动捕获步骤级日志和附件)
94
+ - **断言结果**:在原生 `assert` 后调用 `pure.record*` 即可在报告中展示
95
+ - **附件**:通过 `pure.attach` 添加文本/JSON/图片等附件(自动关联到当前步骤)
96
+ - **标签**:通过 `pure.feature` / `pure.story` / `pure.severity` 等装饰器添加标签(用于层级分组,不在详情中单独展示)
97
+ - 用法简单、零侵入,不调用也不会影响测试执行
98
+
99
+ ## 安装
100
+
101
+ ```bash
102
+ # 从本地安装(开发模式)
103
+ cd pytest-pure-report
104
+ pip install -e .
105
+
106
+ # 或者从 PyPI 安装(如果已发布)
107
+ pip install pytest-pure-report
108
+ ```
109
+
110
+ ## 快速开始
111
+
112
+ ### 基本使用
113
+
114
+ 安装插件后,运行 pytest 时会自动生成报告:
115
+
116
+ ```bash
117
+ pytest test_cases/
118
+ ```
119
+
120
+ ### 指定报告目录
121
+
122
+ ```bash
123
+ pytest test_cases/ --report-dir=outputs/reports
124
+ ```
125
+
126
+ ### 指定测试环境
127
+
128
+ ```bash
129
+ pytest test_cases/ --env=test
130
+ ```
131
+
132
+ ### 自定义 Logo
133
+
134
+ 支持本地图片路径或远程 URL:
135
+
136
+ ```bash
137
+ # 使用本地图片
138
+ pytest test_cases/ --logo=assets/logo.png
139
+
140
+ # 使用远程 URL
141
+ pytest test_cases/ --logo=https://example.com/logo.png
142
+ ```
143
+
144
+ ### 自定义标题
145
+
146
+ ```bash
147
+ pytest test_cases/ --title="API 自动化测试报告"
148
+ ```
149
+
150
+ ### 完整示例
151
+
152
+ ```bash
153
+ pytest test_cases/ \
154
+ --report-dir=outputs/reports \
155
+ --report-filename=test_report.html \
156
+ --env=prod \
157
+ --logo=assets/logo.png \
158
+ --title="自动化测试报告" \
159
+ -v
160
+ ```
161
+
162
+ ## 配置选项
163
+
164
+ ### 命令行选项
165
+
166
+ | 选项 | 说明 | 默认值 |
167
+ |------|------|--------|
168
+ | `--report-dir` | 报告输出目录 | `pure_report` |
169
+ | `--report-filename` | 报告文件名 | 自动生成时间戳文件名 |
170
+ | `--env` | 测试环境标识 | `test` |
171
+ | `--logo` | 自定义 Logo 路径(支持本地文件或 http/https URL) | 无 |
172
+ | `--title` | 自定义报告标题 | 自动化测试报告 |
173
+
174
+ ### pytest.ini 配置
175
+
176
+ 在项目根目录创建 `pytest.ini` 文件:
177
+
178
+ ```ini
179
+ [pytest]
180
+ report_dir = outputs/reports
181
+ report_filename = test_report.html
182
+ env = test
183
+ logo = assets/logo.png
184
+ title = 自动化测试报告
185
+ screenshot_scope = fail_only
186
+ video_scope = never
187
+ trace_scope = never
188
+ ```
189
+
190
+ ### 环境变量配置
191
+
192
+ ```bash
193
+ # 设置测试环境
194
+ export TEST_ENV=prod
195
+
196
+ # ========== 浏览器信息(仅 UI 测试需要设置,接口测试无需设置) ==========
197
+ # 注意:浏览器信息为按需显示,只有设置了 BROWSER_TYPE 才会在报告中渲染浏览器行。
198
+ # 未设置 BROWSER_TYPE 时(如接口测试),报告将不显示浏览器、模式、分辨率等信息。
199
+
200
+ # 设置浏览器类型(chromium, firefox, webkit)—— 设置后报告才显示浏览器信息
201
+ export BROWSER_TYPE=chromium
202
+
203
+ # 设置无头模式(true 或 false)—— 未设置时默认为 false(有头模式)
204
+ export HEADLESS=true
205
+
206
+ # 设置浏览器窗口分辨率 —— 未设置时报告不显示分辨率
207
+ export BROWSER_WIDTH=1920
208
+ export BROWSER_HEIGHT=1080
209
+
210
+ # ========== 媒体捕获配置 ==========
211
+ # 设置截图捕获策略(always/fail_only/never)
212
+ export SCREENSHOT_SCOPE=fail_only
213
+
214
+ # 设置录屏捕获策略(always/fail_only/never)
215
+ export VIDEO_SCOPE=never
216
+
217
+ # 设置 Trace 录制策略(always/fail_only/never)
218
+ export TRACE_SCOPE=never
219
+
220
+ # 设置截图和录屏文件路径
221
+ export SCREENSHOT_PATH=/path/to/screenshots
222
+ export VIDEO_PATH=/path/to/videos
223
+
224
+ # 设置 trace 文件路径
225
+ export TRACE_PATH=/path/to/traces
226
+
227
+ # 运行测试
228
+ pytest test_cases/
229
+ ```
230
+
231
+ ### 配置优先级
232
+
233
+ 配置项按以下优先级生效(高优先级覆盖低优先级):
234
+
235
+ **命令行参数 > 环境变量 > pytest.ini 配置 > 默认值**
236
+
237
+ ### 截图、录屏和 Trace 配置
238
+
239
+ | 配置项 | 说明 | 默认值 |
240
+ |--------|------|--------|
241
+ | `SCREENSHOT_SCOPE` | 截图捕获策略 | `fail_only` |
242
+ | `VIDEO_SCOPE` | 录屏捕获策略 | `never` |
243
+ | `TRACE_SCOPE` | Trace 录制策略 | `never` |
244
+ | `SCREENSHOT_PATH` | 截图文件目录 | `outputs/screenshots` |
245
+ | `VIDEO_PATH` | 录屏文件目录 | `outputs/videos` |
246
+ | `TRACE_PATH` | Trace 文件目录 | `outputs/traces` |
247
+
248
+ **截图/录屏/Trace 策略说明:**
249
+
250
+ - `always`:所有用例都捕获/录制
251
+ - `fail_only`:仅失败用例捕获/保留(默认截图策略;trace 录制后通过用例会自动删除)
252
+ - `never`:不捕获/录制
253
+
254
+ ### Trace 录制说明
255
+
256
+ Trace 是 Playwright 提供的测试过程可视化能力,开启后会录制测试执行全过程,打包为 `.zip` 文件,包含:
257
+
258
+ | 录制内容 | 说明 |
259
+ |---|---|
260
+ | **Snapshots(页面快照)** | 每个操作后的 DOM 状态,可前后穿梭查看页面在任意时刻的样子 |
261
+ | **Screenshots(截图)** | 每个操作自动截图 |
262
+ | **Network(网络)** | 所有 HTTP 请求/响应详情(含 headers、body) |
263
+ | **Console logs** | 浏览器控制台输出 |
264
+ | **Source(源码)** | 每个操作对应的代码位置(可点击跳转) |
265
+ | **Action log(动作日志)** | 所有 Playwright 操作的时间线(含选择器、耗时、错误) |
266
+
267
+ **按用例录制**:每个用例独立录制一个 trace zip 文件,文件按用例名分子目录存储:
268
+ ```
269
+ traces/
270
+ ├── test_login_success/
271
+ │ └── test_login_success_1790662054676.zip
272
+ ├── test_enter_via_avatar_click/
273
+ │ └── test_enter_via_avatar_click_1790662059536.zip
274
+ ```
275
+
276
+ **报告集成**:报告中每个用例卡片下会显示「🎬 Trace 记录」区段(绿色背景),点击「查看 Trace」按钮在新标签页打开 Playwright Trace Viewer 进行可视化回放。
277
+
278
+ **Trace Viewer 部署**:报告生成时会自动复制 Playwright 自带的 Trace Viewer SPA 资源到报告目录的 `trace-viewer/` 子目录,无需额外安装。由于 Trace Viewer 依赖 Service Worker,必须通过 HTTP 服务器访问报告(直接用 file:// 协议打开会显示友好提示):
279
+
280
+ ```bash
281
+ # 进入报告目录启动 HTTP 服务器
282
+ cd outputs/pure_reports/<timestamp>
283
+ python -m http.server 8000
284
+
285
+ # 浏览器访问报告,点击用例卡片下的「查看 Trace」按钮
286
+ # http://localhost:8000/test_report_<timestamp>.html
287
+ ```
288
+
289
+ ## 报告结构
290
+
291
+ ### 整体布局
292
+
293
+ 报告采用全屏自适应布局,主要区域包括:
294
+ - **报告头部**:Logo、标题、环境标识
295
+ - **测试结果概览**:统计卡片、饼图、堆叠条形图
296
+ - **测试结果区域**(左右结构,参考 Allure):
297
+ - **左侧面板**:测试用例树(按 feature > story 分组),支持搜索和状态筛选
298
+ - **右侧面板**:选中用例的详情面板
299
+
300
+ ### 用例详情面板
301
+
302
+ 点击左侧测试用例后,右侧展示:
303
+ - **位置**:`文件路径>类名>方法名`
304
+ - **优先级**:从 pure.severity 标签提取
305
+ - **结果**:passed/failed/error/skipped 等
306
+ - **耗时**:用例执行总耗时
307
+ - **参数(Parameters)**:参数化用例的参数列表(可折叠)
308
+ - **执行过程(Execution)**:按阶段分组展示
309
+ - **前置处理(Set up)**:fixture 列表(可展开查看嵌套步骤)
310
+ - **测试步骤(Test Body)**:pure.step 步骤列表(可展开查看步骤日志/附件)
311
+ - **后置处理(Tear down)**:fixture 列表(可展开查看嵌套步骤)
312
+ - **断言结果**:表格展示断言详情
313
+ - **截图/录屏**:按配置展示
314
+ - **Trace 记录**:按配置展示(开启 trace 时,每个用例独立录制,无 trace 时自动隐藏)
315
+ - **错误信息**:失败用例的错误堆栈
316
+
317
+ ## 测试状态说明
318
+
319
+ ### 状态含义
320
+
321
+ - **passed**: 正常通过:断言全部成功,无异常,运行完整
322
+ - **failed**: 断言失败:用例执行完毕,但断言不成立或主动调用 pytest.fail()
323
+ - **error**: 执行异常:测试未完整运行(setup/teardown/导入/运行时抛出未捕获异常)
324
+ - **xfail**: 预期失败:标记了 @pytest.mark.xfail,且实际结果确实是失败
325
+ - **xpassed**: 意外通过:标记了 @pytest.mark.xfail,但实际运行成功了
326
+ - **skipped**: 主动跳过:通过 @skip/skipif/xfail(condition=True) 跳过,未执行测试体
327
+ - **deselected**: 收集阶段剔除:被 -k、--ignore、--collect-only 或配置文件过滤,未进入执行流程
328
+
329
+ ### 统计公式
330
+
331
+ - **总用例数(Total)** = passed + failed + error + xfail + xpassed + skipped + deselected
332
+ - **已收集用例数(Selected)** = passed + failed + error + xfail + xpassed + skipped
333
+ - **有效用例数(Executed)** = passed + failed + error
334
+ - **通过率(Pass Rate)** = passed / (passed + failed + error) × 100%
335
+
336
+
337
+ ## 示例测试用例
338
+
339
+ ### 参数化测试用例
340
+
341
+ ```python
342
+ import pytest
343
+
344
+ class TestLogin:
345
+ @pytest.fixture(params=[
346
+ {"name": "登录页面URL正确", "url": "/login"},
347
+ {"name": "用户名输入框存在", "selector": "#username"},
348
+ {"name": "密码输入框存在", "selector": "#password"},
349
+ ])
350
+ def test_case(self, request):
351
+ return request.param
352
+
353
+ def test_login_page_load(self, test_case):
354
+ """测试登录页面加载"""
355
+ print(f"测试用例: {test_case['name']}")
356
+ assert True
357
+ ```
358
+
359
+ ### 普通测试用例
360
+
361
+ ```python
362
+ import pytest
363
+
364
+ class TestExample:
365
+ def test_passed(self):
366
+ """测试通过的用例"""
367
+ assert True
368
+
369
+ def test_failed(self):
370
+ """测试失败的用例"""
371
+ assert False, "故意失败"
372
+
373
+ @pytest.mark.skip(reason="跳过原因")
374
+ def test_skipped(self):
375
+ """测试跳过的用例"""
376
+ assert True
377
+
378
+ @pytest.mark.xfail(reason="已知问题")
379
+ def test_xfail(self):
380
+ """预期失败的用例"""
381
+ assert False
382
+
383
+ def test_with_logs(self):
384
+ """带有日志输出的用例"""
385
+ print("这是一条输出日志")
386
+ assert True
387
+ ```
388
+
389
+ ### 截图和录屏
390
+
391
+ 在 `conftest.py` 中配置 `page` fixture,测试失败时自动捕获截图和录屏:
392
+
393
+ ```python
394
+ import os
395
+ import time
396
+ import pytest
397
+
398
+ @pytest.fixture(scope="function")
399
+ def page():
400
+ """浏览器页面 fixture"""
401
+ from playwright.sync_api import sync_playwright
402
+ with sync_playwright() as p:
403
+ browser = p.chromium.launch(headless=True)
404
+ page = browser.new_page()
405
+ yield page
406
+ browser.close()
407
+
408
+ @pytest.hookimpl(hookwrapper=True)
409
+ def pytest_runtest_makereport(item, call):
410
+ """测试失败时自动截图"""
411
+ outcome = yield
412
+ report = outcome.get_result()
413
+
414
+ if report.when == "call" and report.failed:
415
+ page = item.funcargs.get("page")
416
+ if page:
417
+ screenshot_dir = os.path.join(os.getcwd(), "outputs", "screenshots")
418
+ os.makedirs(screenshot_dir, exist_ok=True)
419
+ screenshot_path = os.path.join(screenshot_dir, f"{item.name}_{int(time.time()*1000)}.png")
420
+ page.screenshot(path=screenshot_path)
421
+ ```
422
+
423
+ ## 使用注意事项
424
+
425
+ 1. **不使用 -s 参数**:为了让报告能够捕获测试中的 print 和 log 输出,请不要使用 `-s`(禁用输出捕获)参数
426
+ 2. **日志配置**:确保 pytest 的日志捕获功能正常工作(使用 `--log-cli-level` 设置日志级别)
427
+ 3. **编码问题**:报告文件使用 UTF-8 编码,确保测试代码中的中文输出也是 UTF-8 编码
428
+ 4. **参数化名称**:参数化用例中如果包含 `name` 字段,将自动作为用例名称显示
429
+ 5. **浏览器信息(按需显示)**:浏览器信息仅在显式设置 `BROWSER_TYPE`(环境变量或命令行参数)时才在报告中显示。接口测试等不涉及浏览器的场景无需设置,报告将自动隐藏浏览器、模式、分辨率等信息。命令行参数优先级高于环境变量
430
+ 6. **执行过程**:测试用例的执行过程按「前置处理 / 测试步骤 / 后置处理」三个阶段分组展示。fixture 无嵌套内容时不显示展开箭头;pure.step 步骤可点击展开查看该步骤执行期间捕获的日志和附件
431
+ 7. **截图文件名**:截图文件名需遵循 `<test_name>_<timestamp>.png` 格式,报告插件会自动匹配并显示
432
+ 8. **录屏文件名**:录屏文件名需遵循 `<test_name>_<timestamp>.webm` 格式,报告插件会自动匹配并显示
433
+ 9. **Trace 录制**:Trace 仅在使用 Playwright 浏览器测试时可用。开启 `TRACE_SCOPE` 后,每个用例独立录制一个 trace zip 文件,按用例名分子目录存储在 `TRACE_PATH` 目录下。报告生成时会自动复制 Playwright 自带 Trace Viewer SPA 到 `report_dir/trace-viewer/` 子目录,点击用例卡片下的「查看 Trace」按钮可在新标签页打开 Trace Viewer 进行可视化回放。由于 Trace Viewer 依赖 Service Worker,必须通过 HTTP 服务器访问报告(如 `python -m http.server 8000`),直接用 file:// 协议打开会显示友好提示
434
+
435
+
436
+ ## pure 公共 API 使用指南
437
+
438
+ `pure` 是本插件提供的一套完全参考 `allure` 的公共 API,用于在报告中展示
439
+ **操作步骤**、**断言结果** 和 **附件**。
440
+ 所有 API 均为可选调用,不写也不影响测试执行。
441
+
442
+ ### 导入方式
443
+
444
+ ```python
445
+ from pytest_pure_report import pure
446
+ ```
447
+
448
+ ### API 一览
449
+
450
+ | API | 作用 |
451
+ |-----|------|
452
+ | `pure.step(title)` | 步骤(装饰器 + 上下文管理器,自动捕获状态、日志和附件) |
453
+ | `pure.fixture(name)` | fixture 装饰器(自动追踪 setup/teardown) |
454
+ | `pure.attach(body, ...)` | 添加附件(文本/JSON/图片等,自动关联到当前步骤) |
455
+ | `pure.attach.file(source, ...)` | 添加文件附件(自动关联到当前步骤) |
456
+ | `pure.record(...)` | 记录一条断言结果(通用 API,pure 扩展) |
457
+ | `pure.record_equal(...)` | 便捷方法:相等断言 |
458
+ | `pure.record_contains(...)` | 便捷方法:包含断言 |
459
+ | `pure.record_visible(...)` | 便捷方法:元素可见性断言 |
460
+ | `pure.title(title)` | 装饰器:用例标题 |
461
+ | `pure.feature(*names)` | 装饰器:feature 标签(用于层级分组) |
462
+ | `pure.story(*names)` | 装饰器:story 标签(用于层级分组) |
463
+ | `pure.severity(level)` | 装饰器:优先级 |
464
+ | `pure.tag(*tags)` | 装饰器:标签 |
465
+ | `pure.link(url, name)` | 装饰器:链接 |
466
+ | `pure.dynamic` | 运行时动态信息 |
467
+ | `pure.severity_level` | 优先级常量枚举 |
468
+ | `pure.attachment_type` | 附件类型常量枚举 |
469
+
470
+ ### 1. step(装饰器 + 上下文管理器)
471
+
472
+ 与 `allure.step` 完全一致,支持两种写法:
473
+
474
+ ```python
475
+ from pytest_pure_report import pure
476
+
477
+ # 上下文管理器
478
+ with pure.step("打开登录页面"):
479
+ page.goto("/login")
480
+
481
+ # 装饰器(自动用函数名作 step 标题,自动提取参数)
482
+ @pure.step("输入用户名和密码")
483
+ def fill_credentials(page, username, password):
484
+ page.fill("#username", username)
485
+ page.fill("#password", password)
486
+
487
+ # 装饰器也可以不传参数,使用函数名作标题
488
+ @pure.step
489
+ def open_login_page(page):
490
+ page.goto("/login")
491
+ ```
492
+
493
+ step 内部自动捕获异常状态:
494
+ - 无异常 → `passed`
495
+ - `AssertionError` → `failed`
496
+ - 其他异常 → `broken`(并重新抛出)
497
+
498
+ step **自动识别阶段**(setup / call / teardown),无需手动指定:
499
+ - fixture 中 yield 之前 → `setup`
500
+ - test 函数中 → `call`
501
+ - fixture 中 yield 之后 → `teardown`
502
+
503
+ step **自动捕获步骤级日志和附件**:
504
+ - 步骤执行期间通过 loguru 输出的日志自动捕获到 `step_data['log']`
505
+ - 步骤执行期间通过 `pure.attach` 添加的附件自动关联到 `step_data['attachments']`
506
+ - 报告中步骤行可点击展开,显示该步骤的日志和附件
507
+ - 支持嵌套步骤(父步骤的子步骤独立记录)
508
+
509
+ ### 2. fixture(自动追踪)
510
+
511
+ 与 `allure.fixture` 一致,装饰 fixture 函数,插件通过 pytest hook 自动追踪阶段:
512
+
513
+ ```python
514
+ import pytest
515
+ from pytest_pure_report import pure
516
+
517
+ @pytest.fixture
518
+ @pure.fixture("登录")
519
+ def login(page):
520
+ with pure.step("打开登录页面"):
521
+ page.goto("/login")
522
+ yield page
523
+ with pure.step("关闭浏览器"):
524
+ page.context.close()
525
+
526
+ # 也可不传参数
527
+ @pytest.fixture
528
+ @pure.fixture
529
+ def page():
530
+ ...
531
+ ```
532
+
533
+ ### 3. 断言记录(pure 扩展)
534
+
535
+ 与原生 `assert` 配合,在报告中展示断言对比:
536
+
537
+ ```python
538
+ # 通用 API
539
+ assert actual == expected
540
+ pure.record("描述", actual, expected, type="==")
541
+
542
+ # 便捷方法(自动判断 passed)
543
+ pure.record_equal(page.title(), "GitLink", "验证页面标题")
544
+ pure.record_contains(resp.text, "success", "验证响应包含 success")
545
+ pure.record_visible(is_visible, "验证元素可见")
546
+ ```
547
+
548
+ ### 4. 附件
549
+
550
+ 与 `allure.attach` 一致,附件自动关联到当前步骤(如果在 `pure.step` 上下文内调用):
551
+
552
+ ```python
553
+ # 文本附件
554
+ pure.attach("hello world", name="问候", attachment_type=pure.attachment_type.TEXT)
555
+
556
+ # JSON 附件
557
+ pure.attach('{"key": "value"}', name="数据", attachment_type=pure.attachment_type.JSON)
558
+
559
+ # 文件附件
560
+ pure.attach.file("path/to/screenshot.png", name="截图")
561
+ ```
562
+
563
+ ### 5. 标签装饰器
564
+
565
+ 与 allure 完全一致,用于测试用例树的层级分组:
566
+
567
+ ```python
568
+ @pure.feature("登录")
569
+ @pure.story("成功登录")
570
+ @pure.severity(pure.severity_level.CRITICAL)
571
+ @pure.tag("smoke")
572
+ @pure.title("验证用户使用正确账号可以登录")
573
+ @pure.link("https://gitlink.org.cn/issue/1", name="issue-1")
574
+ def test_login_success(page):
575
+ ...
576
+ ```
577
+
578
+ ### 6. 运行时动态信息(Dynamic)
579
+
580
+ 与 `allure.dynamic` 一致,在运行时动态修改信息:
581
+
582
+ ```python
583
+ def test_something(page):
584
+ pure.dynamic.title("动态标题")
585
+ pure.dynamic.tag("dynamic-tag")
586
+ pure.dynamic.severity(pure.severity_level.BLOCKER)
587
+ ```
588
+
589
+ ### 报告展示效果
590
+
591
+ - **执行过程(Execution)**:按「前置处理(Set up)/ 测试步骤(Test Body)/ 后置处理(Tear down)」分组展示。
592
+ - fixture 行:有嵌套内容时可点击展开,无内容时显示为简单行(不显示展开箭头)
593
+ - pure.step 步骤行:有日志/附件/错误时可点击展开查看详情
594
+ - 每行显示「状态图标、步骤标题、参数、耗时」
595
+ - **断言结果** 表格:展示「断言描述、断言类型、预期值、实际值、结果」列,并显示「全部通过 N 条」或「X/N 通过 N 条」汇总
596
+ - **附件**:步骤执行期间的附件显示在对应步骤的展开区域内;步骤外的附件显示在所属阶段区段
597
+
598
+ ### 完整示例
599
+
600
+ ```python
601
+ import pytest
602
+ from pytest_pure_report import pure
603
+
604
+ @pure.feature("登录")
605
+ class TestLogin:
606
+
607
+ @pytest.fixture
608
+ @pure.fixture("登录")
609
+ def login(self, page):
610
+ with pure.step("打开登录页面"):
611
+ page.goto("/login")
612
+ yield page
613
+
614
+ @pure.story("成功登录")
615
+ @pure.severity(pure.severity_level.CRITICAL)
616
+ @pure.title("验证用户使用正确账号可以登录")
617
+ def test_login_success(self, page, login):
618
+ with pure.step("验证用户头像可见"):
619
+ is_visible = page.locator(".currentImg").is_visible()
620
+ assert is_visible
621
+ pure.record_visible(is_visible, "验证用户头像可见")
622
+ ```
623
+
624
+ 更详细的 API 说明请参考 [`pure.py` 源码文档](src/pytest_pure_report/pure.py)。
625
+
626
+
627
+ ## 项目结构
628
+
629
+ ```
630
+ pytest-pure-report/
631
+ ├── pyproject.toml # 项目配置文件
632
+ ├── README.md # 项目文档
633
+ ├── LICENSE # 许可证
634
+ ├── tests/ # 测试文件
635
+ ├── images/ # 图标资源
636
+ ├── example/ # 示例文件
637
+ │ └── test_report_*.html # 示例报告
638
+ └── src/
639
+ └── pytest_pure_report/
640
+ ├── __init__.py # 包初始化
641
+ ├── models.py # 数据模型(TestResult)
642
+ ├── generator.py # 报告生成器(HTML 生成)
643
+ ├── pure.py # pure 公共 API(step/attach/record 等)
644
+ └── plugin.py # pytest 插件(钩子和命令行选项)
645
+ ```
646
+
647
+ ## 开发
648
+
649
+ ### 本地开发
650
+
651
+ ```bash
652
+ # 进入项目目录
653
+ cd pytest-pure-report
654
+
655
+ # 安装开发依赖
656
+ pip install -e .
657
+
658
+ # 运行测试(在项目根目录执行)
659
+ pytest tests/ -v
660
+
661
+ # 构建包(可选)
662
+ python -m build
663
+ ```
664
+
665
+ ## 许可证
666
+
667
+ MIT License
668
+
669
+ ## 贡献
670
+
671
+ 欢迎提交 Issue 和 Pull Request!
672
+
673
+ ---
674
+
675
+ **pytest-pure-report** - 让测试报告更美观、更实用!