diff --git a/doc/env_cn.md b/doc/env_cn.md index e087e3c..6baf341 100644 --- a/doc/env_cn.md +++ b/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) +``` diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..2f7144d --- /dev/null +++ b/tests/README.md @@ -0,0 +1,19 @@ +# 测试用例 + +请在本目录下创建测试用例,每个测试用例为一个单独的目录,目录名即为测试用例名。 + +使用如下命令运行测试用例: + +```bash +make TEST=<测试用例名> run +``` + +或一次性运行所有测试用例: + +```bash +make run +``` + +测试报告会被保存在 `tests/report` 目录中,可通过浏览器打开 `tests/report/report.html` 查看本次测试报告内容,其余文件也会在本目录中生成。 + +创建测试用例的详细规范请参见 [编写测试用例](../doc/env_cn.md#编写测试用例)。