How can I add test description to results/test report in matlab unit test framework?

I am using Matlab unittesting framework and I would like to know what is the best way to add the test description in the test results with this framework.

How can I add a test description as part of the results table ( the comment or any string of as shown in class method This test check that A plus B is 3? So I would like to have something like below.

   ans =

  1×6 table

            Name            Passed    Failed    Incomplete    Duration       Details     Description
    ____________________    ______    ______    __________    _________    ____________

    {'myClass/addAandB'}    true      false       false       0.0002881    {1×1 struct}   This test check that A plus B is 3

Let's say that I have the following class

classdef myClass < matlab.unittest.TestCase
    properties
        A;
        B;
    end
    methods (TestClassSetup)
        function assignVars(testCase)
            testCase.A = 1;
            testCase.B = 2;
        end
    end
    methods (TestClassTeardown)
    end
    methods (TestMethodSetup)
    end
    methods (TestMethodTeardown)
    end
    %% Function that perform the tests
    methods(Test,TestTags = {'A'})
       function y = addAandB(testCase)
        % This test check that A plus B is 3
            y = testCase.A + testCase.B;
       end
    end
end

and I am running it with the following script

%% House keeping
clear all;
close all;
%% Imports
import matlab.unittest.TestRunner;
import matlab.unittest.TestSuite;
import matlab.unittest.plugins.TestReportPlugin;
import matlab.unittest.plugins.DiagnosticsRecordingPlugin;
import matlab.unittest.plugins.XMLPlugin;
import matlab.unittest.plugins.TAPPlugin
import matlab.unittest.plugins.ToFile


%% Run unit test for sanity check and performance
loggingLevel    = 4;
% Define tests to run
suiteToRun = testsuite('myClass','Tag','A');
% Create runner for test cases and attach plugins
runner          = matlab.unittest.TestRunner.withNoPlugins;
% Enable plugin to create test report
mkdir('./testsResults');
testReportName  = 'unitTestReport';
runner.addPlugin(DiagnosticsRecordingPlugin('IncludingPassingDiagnostics',true,'OutputDetail',loggingLevel,'LoggingLevel',loggingLevel))
runner.addPlugin( matlab.unittest.plugins.TestReportPlugin.producingHTML(['./testsResults/' testReportName '.html'],'IncludingPassingDiagnostics',true,'LoggingLevel',loggingLevel))
runner.addPlugin(matlab.unittest.plugins.XMLPlugin.producingJUnitFormat(['./testsResults/' testReportName '.xml'],'OutputDetail',loggingLevel));
runner.addPlugin(matlab.unittest.plugins.TAPPlugin.producingOriginalFormat(ToFile(['./testsResults/' testReportName '.tap']),'OutputDetail',loggingLevel));
testResults = runner.run(suiteToRun);
% Show results
table(testResults)
if(exist(['./testsResults/' testReportName '.html'],'file'))
    uiopen(['./testsResults/' testReportName '.html/index.html'],1);
end
% Ensure no error happened during run
assertSuccess(testResults)

Which will produce the following output in matlab command

> In test (line 21) 
Generating test report. Please wait.
    Preparing content for the test report.
    Adding content to the test report.
    Writing test report to file.
Test report has been saved to:
 C:\LocalData\myTest\testsResults\unitTestReport.html\index.html

ans =

  1×6 table

            Name            Passed    Failed    Incomplete    Duration       Details   
    ____________________    ______    ______    __________    _________    ____________

    {'myClass/addAandB'}    true      false       false       0.0002881    {1×1 struct}


ans = 

  TestResult with properties:

          Name: 'myClass/addAandB'
        Passed: 1
        Failed: 0
    Incomplete: 0
      Duration: 2.8810e-04
       Details: [1×1 struct]

Totals:
   1 Passed, 0 Failed, 0 Incomplete.
   0.0002881 seconds testing time.

Also, is this possible to have this description in the tst report as well ( i.e. html report)

Thanks in advance!

Answer 1

[Yash]

Hi Javier,

As per my knowledge, there isn't a built-in way to include a custom description directly in the table output of the test results or in the HTML report produced. The testing framework focuses on the test results themselves, such as pass/fail status, duration, and diagnostic details.

However, the following workaround is possible:

1) Create a custom function to append descriptions to the results table.

function resultsWithDescription = appendDescriptionsToResults(testResults)
    % Define a cell array with descriptions matching the test method names
    descriptions = {
        'myClass/addAandB', 'This test check that A plus B is 3';
    };

    % Convert descriptions to a table
    descriptionsTable = cell2table(descriptions, 'VariableNames', {'Name', 'Description'});

    % Convert testResults to a table
    testResultsTable = table(testResults);

    % Merge the descriptions with the test results
    resultsWithDescription = outerjoin(testResultsTable, descriptionsTable, 'Keys', 'Name', 'MergeKeys', true);
end

2) Call this function after running the tests and before displaying the table in the script.

testResults = runner.run(suiteToRun);

% call the function to append description to testResults
testResultsWithDescription = appendDescriptionsToResults(testResults);

% Show results with descriptions
disp(testResultsWithDescription);

3) To add description to the HTML report, use the "log" function and the description will appear in the HTML report if the plugin is configured with the "IncludingPassingDiagnostics" option set to "true". (This is already set to true in the script)

%% Function that perform the tests
methods(Test,TestTags = {'A'})
   function y = addAandB(testCase)
    % This test check that A plus B is 3
        testCase.log(matlab.unittest.Verbosity.Detailed, 'This test check that A plus B is 3');
        y = testCase.A + testCase.B;
   end
end

Output of "testResultWithDescription":

HTML report with description:

I hope this workaround was helpful!

[Javier Cuadros]

THanks Yash I will try to apply this!