MATLAB 单元测试

学习一下关于 MATLAB 单元测试的内容，为了维护一份健壮的代码库，单元测试是必不可少的，参考官方文档。

MATLAB 提供的测试主要包括三种风格：

• 基于脚本
• 基于函数
• 基于类

基于脚本的单元测试

可以通过一个脚本对指定功能进行测试，脚本名称必须以 test 开头或结尾，不区分大小写，否则测试文件可能被忽略。

每一代码节（%%）作为一个测试单元，随后的文本视作测试单元的名称，否则MATLAB会提供一个默认名称。 如果脚本中不含代码节，那么整个文件会被视作一个测试单元，测试单元的名称为脚本名称。

在测试单元中主要通过 assert 语句进行检查。 在第一个代码节之前的内容是测试的初始化代码，可以用于配置测试环境，如果这部分出现错误，会导致所有测试单元失败。

执行单元测试的流程为：在每次开始时执行初始化代码，然后跳转到某个测试单元执行，执行结束即退出，不会执行多个测试单元，无论成功或失败。

这种执行方式可以保证一个测试单元的失败不会导致整个测试中断，不同测试单元使用的变量不会相互影响。 但是由于脚本仍然是一个合法的MATLAB文件，我们还是可以直接运行整个文件，这意味着依次执行初始化代码和所有的测试单元，此时某处失败会导致整体中断，不同测试单元之间也会相互干扰。

考虑官网的例子，测试目标为 rightTri.m

function angles = rightTri(sides)

    A = atand(sides(1)/sides(2));
    B = atand(sides(2)/sides(1));
    hypotenuse = sides(1)/sind(A);
    C = asind(hypotenuse*sind(A)/sides(1));

    angles = [A B C];
end

测试脚本 rightTriTest.m 的内容如下

% test triangles
tri = [7 9];
triIso = [4 4];
tri306090 = [2 2*sqrt(3)];
triSkewed = [1 1500];

% preconditions
angles = rightTri(tri);
assert(angles(3) == 90,'Fundamental problem: rightTri not producing right triangle')

%% Test 1: sum of angles
angles = rightTri(tri);
assert(sum(angles) == 180)

angles = rightTri(triIso);
assert(sum(angles) == 180)

angles = rightTri(tri306090);
assert(sum(angles) == 180)

angles = rightTri(triSkewed);
assert(sum(angles) == 180)

%% Test 2: isosceles triangles
angles = rightTri(triIso);
assert(angles(1) == 45)
assert(angles(1) == angles(2))

%% Test 3: 30-60-90 triangle
angles = rightTri(tri306090);
assert(angles(1) == 30)
assert(angles(2) == 60)
assert(angles(3) == 90)

%% Test 4: Small angle approximation
angles = rightTri(triSkewed);
smallAngle = (pi/180)*angles(1); % radians
approx = sin(smallAngle);
assert(approx == smallAngle, 'Problem with small angle approximation')

需要通过 runtests 函数来执行单元测试

result = runtests('rightTriTest');

输出结果如下

Running rightTriTest
..
================================================================================
Error occurred in rightTriTest/Test3_30_60_90Triangle and it did not run to completion.
    ---------
    Error ID:
    ---------
    'MATLAB:assertion:failed'
    --------------
    Error Details:
    --------------
    Error using assert
    Assertion failed.
    Error in rightTriTest (line 31)
    assert(angles(1) == 30)
================================================================================
.
================================================================================
Error occurred in rightTriTest/Test4_SmallAngleApproximation and it did not run to completion.
    ---------
    Error ID:
    ---------
    ''
    --------------
    Error Details:
    --------------
    Error using assert
    Problem with small angle approximation
    Error in rightTriTest (line 39)
    assert(approx == smallAngle, 'Problem with small angle approximation')
================================================================================
.
Done rightTriTest
__________

Failure Summary:

     Name                                        Failed  Incomplete  Reason(s)
    ===========================================================================
     rightTriTest/Test3_30_60_90Triangle           X         X       Errored.
    ---------------------------------------------------------------------------
     rightTriTest/Test4_SmallAngleApproximation    X         X       Errored.

可以进一步通过表格展示结果（这里可以看到，MATLAB根据节标题自动生成测试单元的标题）

table(result)
ans =
  4×6 table
                         Name                         Passed    Failed    Incomplete    Duration       Details
    ______________________________________________    ______    ______    __________    _________    ____________
    {'rightTriTest/Test1_SumOfAngles'            }    true      false       false        0.020942    {1×1 struct}
    {'rightTriTest/Test2_IsoscelesTriangles'     }    true      false       false       0.0032443    {1×1 struct}
    {'rightTriTest/Test3_30_60_90Triangle'       }    false     true        true        0.0054824    {1×1 struct}
    {'rightTriTest/Test4_SmallAngleApproximation'}    false     true        true        0.0064785    {1×1 struct}

这里测试失败的原因是我们编写的测试不恰当，不应该对浮点数直接进行相等比较，而是应该指定容差，修正后的测试脚本 rightTriTest.m 内容如下

% test triangles
tri = [7 9];
triIso = [4 4];
tri306090 = [2 2*sqrt(3)];
triSkewed = [1 1500];

% Define an absolute tolerance
tol = 1e-10;

% preconditions
angles = rightTri(tri);
assert(angles(3) == 90,'Fundamental problem: rightTri not producing right triangle')

%% Test 1: sum of angles
angles = rightTri(tri);
assert(sum(angles) == 180)

angles = rightTri(triIso);
assert(sum(angles) == 180)

angles = rightTri(tri306090);
assert(sum(angles) == 180)

angles = rightTri(triSkewed);
assert(sum(angles) == 180)

%% Test 2: isosceles triangles
angles = rightTri(triIso);
assert(angles(1) == 45)
assert(angles(1) == angles(2))

%% Test 3: 30-60-90 triangle
angles = rightTri(tri306090);
assert(abs(angles(1)-30) <= tol)
assert(abs(angles(2)-60) <= tol)
assert(abs(angles(3)-90) <= tol)

%% Test 4: Small angle approximation
angles = rightTri(triSkewed);
smallAngle = (pi/180)*angles(1); % radians
approx = sin(smallAngle);
assert(abs(approx-smallAngle) <= tol, 'Problem with small angle approximation')

运行

result = runtests('rightTriTest');

输出内容如下

Running rightTriTest
....
Done rightTriTest
__________

通过表格展示结果

table(result)
ans =
  4×6 table
                         Name                         Passed    Failed    Incomplete    Duration       Details
    ______________________________________________    ______    ______    __________    _________    ____________
    {'rightTriTest/Test1_SumOfAngles'            }    true      false       false        0.014323    {1×1 struct}
    {'rightTriTest/Test2_IsoscelesTriangles'     }    true      false       false       0.0045926    {1×1 struct}
    {'rightTriTest/Test3_30_60_90Triangle'       }    true      false       false       0.0045378    {1×1 struct}

直接调用 result = runtests 会查找当前文件夹下所有以 test 开头或结尾的 .m 文件，并执行所有测试。

基于函数的单元测试

可以通过一个函数对指定功能进行测试，函数名称（以及文件名称）必须以 test 开头或结尾，不区分大小写，否则测试文件可能被忽略。

测试函数文件中的主函数的固定写法如下（除了主函数名称，其它内容尽量不要改动）

function tests = exampleTest()
    tests = functiontests(localfunctions);
end

这里使用 localfunctions 获取当前函数文件中的所有局部函数的句柄，每一个局部函数被视作一个测试单元。

测试函数文件中的局部函数的写法也相对固定：名称必须必须以 test 开头或结尾，不区分大小写，函数必须要接收一个名为 testCase 的参数，无返回值。

例如

function testFunctionOne(testCase)
    % Test specific code
end

function testFunctionTwo(testCase)
    % Test specific code
end

MATLAB 允许我们在执行每一个测试单元（也就是调用对应的局部函数）的前后进行必要的操作，比如初始化一些数据，或者清理一些数据，这被称为刷新脚手架函数，包括测试前的 setup 函数和测试后的 teardown 函数，这两个特殊函数同样接收一个名为 testCase 的参数，无返回值。

function setup(testCase)  % do not change function name
    % open a figure, for example
end

function teardown(testCase)  % do not change function name
    % close figure, for example
end

除此之外，还可以在所有测试前后进行必要的操作，这被称为文件脚手架函数，包括测试前的 setupOnce 函数和测试后的 teardownOnce 函数，与刷新脚手架的形式基本相同。

各种脚手架函数都是可选的，建议主要使用刷新脚手架函数，而非文件脚手架函数。

我们需要重点关注 testCase 这个对象：

• 它属于 matlab.unittest.FunctionTestCase 类型，这是一个 handle 类，因此可以用来传递数据；
• 它具有一个完全公开的结构体属性 TestData，可以在脚手架函数中通过向这个结构体添加字段以传递数据。

考虑官网的例子，测试目标为 quadraticSolver.m

function r = quadraticSolver(a,b,c)
    % quadraticSolver returns solutions to the
    % quadratic equation a*x^2 + b*x + c = 0.

    if ~isa(a,'numeric') || ~isa(b,'numeric') || ~isa(c,'numeric')
        error('quadraticSolver:InputMustBeNumeric', ...
            'Coefficients must be numeric.');
    end

    r(1) = (-b + sqrt(b^2 - 4*a*c)) / (2*a);
    r(2) = (-b - sqrt(b^2 - 4*a*c)) / (2*a);
end

测试函数 quadraticSolverTest.m 的内容如下

function tests = quadraticSolverTest()
    tests = functiontests(localfunctions);
end

%% Test Functions
function testRealSolution(testCase)
    actSolution = quadraticSolver(1,-3,2);
    expSolution = [2 1];
    verifyEqual(testCase,actSolution,expSolution)
end

function testImaginarySolution(testCase)
    actSolution = quadraticSolver(1,2,10);
    expSolution = [-1+3i -1-3i];
    verifyEqual(testCase,actSolution,expSolution)
end

注意这里使用了 verifyEqual 函数，要求实际结果和预期值完全相等，我们也可以加上容差（绝对容差或相对容差）

verifyEqual(testCase,1.5,2,AbsTol=1)
verifyEqual(testCase,1.5,2,RelTol=1)

与之类似的函数还有 verifyNotEqual，verifyThat 等， 完整内容可以查看验证、断言及其他鉴定一览表。

对测试函数的调用和前面的测试脚本基本相同

results = runtests('quadraticSolverTest');

运行结果如下

Running quadraticSolverTest
..
Done quadraticSolverTest
__________

需要注意的是，与测试脚本不同，直接调用这个测试函数并不会触发任何测试。

基于类的单元测试

可以通过一个自定义类对指定功能进行测试，类名称（以及文件名称）必须以 test 开头或结尾，不区分大小写，否则测试文件可能被忽略。

测试类需要直接或间接继承 matlab.unittest.TestCase 类型。 测试类的具有 Test 属性的方法被视作单元测试，除此之外，还有几个属性

• TestMethodSetup 和 TestMethodTeardown 方法在每个 Test 方法之前和之后运行。
• TestClassSetup 和 TestClassTeardown 方法在测试类中的所有 Test 方法之前和之后运行。

示例代码如下

classdef FigurePropertiesTest < matlab.unittest.TestCase
    properties
        TestFigure
    end

    methods (TestMethodSetup)
        function createFigure(testCase)
            testCase.TestFigure = figure;
        end
    end

    methods (TestMethodTeardown)
        function closeFigure(testCase)
            close(testCase.TestFigure)
        end
    end

    methods (Test)
        function defaultCurrentPoint(testCase)
            cp = testCase.TestFigure.CurrentPoint;
            testCase.verifyEqual(cp,[0 0], ...
                "Default current point must be [0 0].")
        end

        function defaultCurrentObject(testCase)
            import matlab.unittest.constraints.IsEmpty
            co = testCase.TestFigure.CurrentObject;
            testCase.verifyThat(co,IsEmpty, ...
                "Default current object must be empty.")
        end
    end
end

对比下来，感觉基于脚本或函数的测试已经足够使用了，基于自定义类型的测试在形式上有点复杂了，因此简单了解一下即可。

补充

在目录中直接调用 result = runtests 会查找当前文件夹下所有以 test 开头或结尾的 .m 文件，并执行所有测试， 但是我们有时需要遍历指定目录以及它的子目录中的所有测试文件，并且最好生成测试报告，可以参考下面的代码。

import matlab.unittest.TestRunner;
import matlab.unittest.TestSuite;
import matlab.unittest.plugins.TestReportPlugin;

cd(fileparts(mfilename('fullpath')));

utilsDir = fullfile('utils');   % utils/
baseDir = fullfile('base');     % base/

suite_utils = TestSuite.fromFolder(utilsDir, 'IncludingSubfolders', true);
suite_base = TestSuite.fromFolder(baseDir, 'IncludingSubfolders', true);
suite = [suite_utils, suite_base];

runner = TestRunner.withTextOutput;

runner.addPlugin(TestReportPlugin.producingHTML('TestReport'));

results = runner.run(suite);