如何在matlab.unittest.TestCase的PDF测试报告中添加测试用例注释

问题场景 #

现有继承matlab.unittest.TestCase的测试类tests_HIL_ADF，包含多个Simulink模型测试函数。当前通过TestReportPlugin生成的PDF报告仅记录测试执行结果，需要为每个测试函数添加前置注释，并让注释显示在报告对应测试条目下。

测试类代码 #

classdef tests_HIL_ADF < matlab.unittest.TestCase
    methods(Test)
        function SC001_SN001_SN002(testCase)
            global in_test;
            load('SC001_SN001_SN002_in.mat');
            load('SC001_SN001_SN002_out.mat');
            simulation_out = sim('my_open_simulink_model',400);
            sim_out = struct(simulation_out);
            oracle = struct(OUT_Test);
            time = (1:1:length(oracle.Data.Q_Valid));
            import matlab.unittest.diagnostics.FigureDiagnostic
            f = figure;
            plot(time, sim_out.Data.Q_Valid, time, oracle.Data.Q_Valid); 
            grid on
            legend("Simulation Output", "Oracle");
            testCase.verifyEqual(uint8(sim_out.Data.Q_Valid(time)), ...
                uint8(oracle.Data.Q_Valid), 'RelTol', 0.1, "Q_Valid");
            close(f);
            f = figure;
            plot(time, sim_out.Data.Train_Info_Q_Valid(time), time, ...
                oracle.Data.Train_Info_Q_Valid); grid on
            legend("Simulation Output", "Oracle");
            testCase.verifyEqual(uint8(sim_out.Data.Train_Info_Q_Valid(time)), ...
                uint8(oracle.Data.Train_Info_Q_Valid),'AbsTol',1, "Train_Info_Q_Valid");
            close(f);
        end
        % 更多测试函数
    end
end

报告生成脚本 #

import matlab.unittest.TestRunner
import matlab.unittest.TestSuite
import matlab.unittest.plugins.TestReportPlugin
import matlab.unittest.plugins.CodeCoveragePlugin
import matlab.unittest.plugins.codecoverage.CoverageReport
global in_test;
suite = TestSuite.fromFile('tests_HIL_ADF.m');
runner = TestRunner.withTextOutput;
pdfFile = strcat('tests_HIL_ADF.pdf');
plugin = TestReportPlugin.producingPDF(pdfFile,'LoggingLevel', 4);
runner.addPlugin(plugin);
result = runner.run(suite)

解决方案 #

方法一：利用函数块注释自动生成描述 #

MATLAB单元测试框架会自动提取测试函数上方的块注释作为测试的描述信息，直接显示在PDF报告中。修改测试类如下：

classdef tests_HIL_ADF < matlab.unittest.TestCase
    methods(Test)
        %{
        测试场景：SC001_SN001_SN002
        验证内容：Q_Valid与Train_Info_Q_Valid信号的仿真输出和基准数据一致性
        容差设置：Q_Valid使用相对误差0.1，Train_Info_Q_Valid使用绝对误差1
        %}
        function SC001_SN001_SN002(testCase)
            global in_test;
            load('SC001_SN001_SN002_in.mat');
            load('SC001_SN001_SN002_out.mat');
            simulation_out = sim('my_open_simulink_model',400);
            sim_out = struct(simulation_out);
            oracle = struct(OUT_Test);
            time = (1:1:length(oracle.Data.Q_Valid));
            import matlab.unittest.diagnostics.FigureDiagnostic
            f = figure;
            plot(time, sim_out.Data.Q_Valid, time, oracle.Data.Q_Valid); 
            grid on
            legend("Simulation Output", "Oracle");
            testCase.verifyEqual(uint8(sim_out.Data.Q_Valid(time)), ...
                uint8(oracle.Data.Q_Valid), 'RelTol', 0.1, "Q_Valid");
            close(f);
            f = figure;
            plot(time, sim_out.Data.Train_Info_Q_Valid(time), time, ...
                oracle.Data.Train_Info_Q_Valid); grid on
            legend("Simulation Output", "Oracle");
            testCase.verifyEqual(uint8(sim_out.Data.Train_Info_Q_Valid(time)), ...
                uint8(oracle.Data.Train_Info_Q_Valid),'AbsTol',1, "Train_Info_Q_Valid");
            close(f);
        end
        % 其他测试函数同理添加块注释
    end
end

无需修改报告生成脚本，重新运行测试即可在PDF报告中看到对应测试条目下的注释内容。

方法二：通过日志输出手动添加描述 #

如果需要更灵活的控制，可以在测试函数开头添加日志输出，利用报告的日志记录功能展示注释：

classdef tests_HIL_ADF < matlab.unittest.TestCase
    methods(Test)
        function SC001_SN001_SN002(testCase)
            % 输出注释内容到日志
            testCase.log(matlab.unittest.Verbosity.Detailed, ...
                "测试场景：SC001_SN001_SN002\n" + ...
                "验证内容：Q_Valid与Train_Info_Q_Valid信号的仿真输出和基准数据一致性\n" + ...
                "容差设置：Q_Valid使用相对误差0.1，Train_Info_Q_Valid使用绝对误差1");
            
            % 原有测试代码
            global in_test;
            load('SC001_SN001_SN002_in.mat');
            load('SC001_SN001_SN002_out.mat');
            simulation_out = sim('my_open_simulink_model',400);
            sim_out = struct(simulation_out);
            oracle = struct(OUT_Test);
            time = (1:1:length(oracle.Data.Q_Valid));
            import matlab.unittest.diagnostics.FigureDiagnostic
            f = figure;
            plot(time, sim_out.Data.Q_Valid, time, oracle.Data.Q_Valid); 
            grid on
            legend("Simulation Output", "Oracle");
            testCase.verifyEqual(uint8(sim_out.Data.Q_Valid(time)), ...
                uint8(oracle.Data.Q_Valid), 'RelTol', 0.1, "Q_Valid");
            close(f);
            f = figure;
            plot(time, sim_out.Data.Train_Info_Q_Valid(time), time, ...
                oracle.Data.Train_Info_Q_Valid); grid on
            legend("Simulation Output", "Oracle");
            testCase.verifyEqual(uint8(sim_out.Data.Train_Info_Q_Valid(time)), ...
                uint8(oracle.Data.Train_Info_Q_Valid),'AbsTol',1, "Train_Info_Q_Valid");
            close(f);
        end
    end
end

确保报告生成脚本中的LoggingLevel设置为4（对应Detailed级别），日志内容会被写入PDF报告的测试条目下。

方法三：自定义报告模板（进阶） #

如果需要高度自定义报告样式，可以导出并修改默认的PDF报告模板：

1. 导出默认模板：执行plugin = TestReportPlugin.producingPDF('output.pdf','TemplatePath','./custom_template')，会在指定路径生成模板文件
2. 修改模板：打开MLX格式的模板文件，在测试条目的对应位置添加提取测试函数注释的逻辑
3. 使用自定义模板：重新运行报告生成脚本时指定TemplatePath为修改后的模板路径

这种方法需要熟悉MATLAB报告生成的模板语法，适合复杂的自定义需求。

内容的提问来源于stack exchange，提问作者Marco Montanaro