Update the test case writing specification

doc/env_cn.md

@@ -109,32 +109,90 @@ BRTParser 使我们专门为 BPU 验证所设计的能够自动抓取、解析
 
 目前，我们使用 FTQ 环境驱动了 uFTB 子预测器，并编写了时序精确的 uFTB 参考模型。FTQ 环境的具体实现和使用方法都可以在这个测试用例中获取，详见 `test_src/uFTB-with-ftq`。
 
-## 验证示例
+## 编写测试用例
 
-本仓库基于uFTB模块提供了验证示例，其中包含了：如何编写测试用例、发送激励、定义功能覆盖率、生成测试报告等。
+参与验证的同学需要编写测试用例，以验证 BPU 子模块的功能正确性，在本仓库中，所有的测试用例都需要被放置在 `tests` 目录下。
 
-### 编写TestCase
+我们基于 pytest 提供了一套测试用例的运行框架，可以方便地编写测试用例、定义功能覆盖率、生成测试报告等，因此在编写测试用例时，需要遵循本节中介绍的一些规范。
 
+### 运行测试
 
+我们已经为 uFTB 提供了两个基础的测试用例，每个测试用例被放置在 `tests` 目录下单独的子目录中，子目录名称即为测试用例的名称。在运行测试这两个测试用例之前，请确保 uFTB 模块己经被正确编译，并且测试用例需要的依赖已经被安装。
 
-#### 创建测试函数
-
-本验证环境基于Pytest进行搭建，因此如何编写test请参考[对应文档](https://open-verify.cc/mlvp/docs/quick-start/frameworks/pytest/)。
-
-在本示例中，编写了如下test：
+之后，便可运行相应测试用例。以运行 `uFTB_raw` 测试用例为例，只需在 `tests` 目录下运行如下命令即可：
 
 ```bash
-
+make TEST=uFTB_raw run
 ```
 
-#### 发送激励
+该命令会自动运行 `uFTB_raw` 测试用例，并生成波形、覆盖率和测试报告等信息。测试报告会被保存在 `tests/report` 目录中，可通过浏览器打开 `tests/report/report.html` 查看本次测试报告内容，其余文件也会在 `tests` 目录下生成。
+
+若需要一次性运行所有测试用例，可以运行如下命令：
+
+```bash
+make run
+```
+
+此时生成的测试报告会包含所有测试用例的测试结果。
+
+### 添加测试用例
+
+在编写自己的测试用例时，只需要在 `tests` 目录下新建一个子目录以作为新测试用例的目录，子目录的名称命名为测试用例的名称。你可以在该目录下添加任意的代码文件，只需要保证测试用例的入口文件为 `test_xxx.py`，在该文件中，测试用例的入口函数也需要被命名为 `test_xxx`。你可以编写一个或多个入口文件和入口函数。
+
+在每个入口函数中，需要遵循如下的格式：
+
+```python
+
+import mlvp.funcov as fc
+from mlvp.reporter import set_func_coverage, set_line_coverage
+
+def test_xxx(request):
+    # 创建 DUT，并指定本次测试的波形文件和覆盖率文件名称
+    # 请注意，每个测试函数所对应的波形文件及覆盖率文件名称应该互不相同，否则会导致文件被覆盖
+    my_dut = DUTxxx(waveform_filename="my_test.fst", coverage_filename="my_test_coverage.dat")
+
+    # 指定功能覆盖规则
+    g1 = fc.CovGroup("group1")
+    # ...
+    g2 = fc.CovGroup("group2")
+    # ...
 
 
+    # 测试运行代码
+    # ...
 
-#### 运行测试
+    # 结束测试，并录入覆盖率信息，覆盖率文件名称应该与上述指定的覆盖率文件名称相同
+    my_dut.finalize()
+    set_func_coverage(request, [g1, g2])
+    set_line_coverage(request, "my_test_coverage.dat")
+```
 
+测试用例编写完成后，可以直接在 `tests` 目录运行：
 
+```python
+make TEST=xxx run
+```
 
-#### 生成测试报告
+即可自动完成测试用例的运行、波形生成、覆盖率统计和测试报告生成等工作。
 
+### 日志输出
 
+在 mlvp 库中，提供了一个专用的日志记录器(logger)，我们推荐使用该 logger 来记录测试过程中的信息。
+
+具体地，你可以使用如下的方式来记录日志：
+
+```python
+from mlvp import logger
+
+logger.debug("This is a debug message", extra={"log_id": "dut"})
+logger.info("This is an info message")
+logger.warning("This is a warning message", extra={"log_id": "interface"})
+logger.error("This is an error message")
+logger.critical("This is a critical message")
+```
+
+如果需要改变日志记录格式、日志级别以及写入文件等信息，可通过调用 `mlvp` 库中的 `setup_logging` 函数进行设置：
+
+```python
+def setup_logging(log_level=logging.INFO, format=default_format, log_file=None)
+```

tests/README.md

@@ -0,0 +1,19 @@
+# 测试用例
+
+请在本目录下创建测试用例，每个测试用例为一个单独的目录，目录名即为测试用例名。
+
+使用如下命令运行测试用例：
+
+```bash
+make TEST=<测试用例名> run
+```
+
+或一次性运行所有测试用例：
+
+```bash
+make run
+```
+
+测试报告会被保存在 `tests/report` 目录中，可通过浏览器打开 `tests/report/report.html` 查看本次测试报告内容，其余文件也会在本目录中生成。
+
+创建测试用例的详细规范请参见 [编写测试用例](../doc/env_cn.md#编写测试用例)。