主要内容

runperf

运行一组测试以进行性能测量

说明

results = runperf 将运行您的当前文件夹中用来进行性能测量的所有测试,并返回 matlab.perftest.TimeResult 对象的数组。results 中的每个元素对应于测试套件中的一个元素。

性能测试框架使用不定数量的测量值运行测试,使样本均值达到 0.95 (95%) 置信水平的 0.05 (5%) 相对误差界限的目标。它会运行这些测试 5 次来预备该代码,然后运行 4 到 256 次来采集符合统计目标的测量值。如果运行 256 次测试之后,样本均值无法达到 0.95 置信水平的 0.05 相对误差界限的目标,则该框架将停止运行测试并显示一条警告消息。在这种情况下,TimeResult 对象中包含 5 次预备运行和 256 次测量运行的信息。

runperf 函数提供了一种简单方法来运行一组测试以进行性能试验。

results = runperf(tests) 运行一组指定的测试。

示例

results = runperf(___,Name,Value) 通过由一个或多个名称-值参量指定的附加选项运行一组测试。

示例

示例

全部折叠

在您的当前文件夹中,创建一个基于脚本的测试 onesTest.m,它使用三种不同的方法来初始化 3000×1000 的全 1 矩阵。

rows = 3000;
cols = 1000;

%% Ones Function
X = ones(rows,cols);

%% Loop Assignment Without Preallocation
for r = 1:rows
    for c = 1:cols
        X(r,c) = 1;
    end
end

%% Loop Assignment With Preallocation
X = zeros(rows,cols);
for r = 1:rows
    for c = 1:cols
        X(r,c) = 1;
    end
end

运行脚本作为性能测试。返回的 results 变量是 1×3 TimeResult 数组。数组中的每个元素都对应于 onesTest.m 中定义的一个测试。

results = runperf("onesTest")
Running onesTest
.......... .......... .......
Done onesTest
__________


results = 

  1×3 TimeResult array with properties:

    Name
    Valid
    Samples
    TestActivity

Totals:
   3 Valid, 0 Invalid.
   23.1678 seconds testing time.

显示第二个测试的测量结果,该测试循环进行赋值,未进行预分配。

results(2)
ans = 

  TimeResult with properties:

            Name: 'onesTest/LoopAssignmentWithoutPreallocation'
           Valid: 1
         Samples: [4×7 table]
    TestActivity: [9×12 table]

Totals:
   1 Valid, 0 Invalid.
   22.8078 seconds testing time.

显示完整的测试测量值表。性能测试框架运行 5 次进行预备,然后运行 4 次进行测量(由 Objective 列中的 sample 表示)。您的结果可能有所不同。

results(2).TestActivity
ans =

  9×12 table

                       Name                        Passed    Failed    Incomplete    MeasuredTime    Objective         Timestamp             Host        Platform                 Version                            TestResult                         RunIdentifier            
    ___________________________________________    ______    ______    __________    ____________    _________    ____________________    ___________    ________    __________________________________    ______________________________    ____________________________________

    onesTest/LoopAssignmentWithoutPreallocation    true      false       false          2.5463        warmup      14-Oct-2022 13:51:36    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b
    onesTest/LoopAssignmentWithoutPreallocation    true      false       false          2.5294        warmup      14-Oct-2022 13:51:38    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b
    onesTest/LoopAssignmentWithoutPreallocation    true      false       false          2.4956        warmup      14-Oct-2022 13:51:41    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b
    onesTest/LoopAssignmentWithoutPreallocation    true      false       false          2.5369        warmup      14-Oct-2022 13:51:43    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b
    onesTest/LoopAssignmentWithoutPreallocation    true      false       false           2.535        warmup      14-Oct-2022 13:51:46    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b
    onesTest/LoopAssignmentWithoutPreallocation    true      false       false          2.5856        sample      14-Oct-2022 13:51:49    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b
    onesTest/LoopAssignmentWithoutPreallocation    true      false       false          2.5344        sample      14-Oct-2022 13:51:51    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b
    onesTest/LoopAssignmentWithoutPreallocation    true      false       false           2.542        sample      14-Oct-2022 13:51:54    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b
    onesTest/LoopAssignmentWithoutPreallocation    true      false       false          2.4653        sample      14-Oct-2022 13:51:56    MY-HOSTNAME     win64      9.14.0.2081372 (R2023a) Prerelease    1×1 matlab.unittest.TestResult    47ea2cab-5c34-4393-ba91-9715fb919d9b

显示第二个测试的测量时间均值。要排除在预备运行中采集的数据,请使用 Samples 属性中的值。

mean(results(2).Samples.MeasuredTime)
ans =

    2.5318

为了比较脚本中的不同初始化方法,请基于 results 创建一个摘要统计量表。在此示例中,ones 函数是将矩阵值全部初始化为 1 的最快方法。性能测试框架为此测试进行了四次测量运行。

T = sampleSummary(results)
T =

  3×7 table

                       Name                        SampleSize      Mean       StandardDeviation      Min        Median         Max   
    ___________________________________________    __________    _________    _________________    ________    _________    _________

    onesTest/OnesFunction                              4         0.0052392       8.9302e-05        0.005171    0.0052078    0.0053703
    onesTest/LoopAssignmentWithoutPreallocation        4            2.5318         0.049764          2.4653       2.5382       2.5856
    onesTest/LoopAssignmentWithPreallocation           4          0.023947       0.00046027        0.023532     0.023921     0.024415

通过创建一个从 matlab.perftest.TestCase 派生的测试类来比较各种预分配方法的性能。

在当前文件夹的名为 preallocationTest.m 的文件中创建 preallocationTest 测试类。该类包含四个 Test 方法,对应于创建由 1 组成的向量的不同方法。当您使用 runperf 函数运行上述任一方法时,该函数会测量在该方法内运行代码所花费的时间。

classdef preallocationTest < matlab.perftest.TestCase
    methods (Test)
        function testOnes(testCase)
            x = ones(1,1e7);
        end

        function testIndexingWithVariable(testCase)
            id = 1:1e7;
            x(id) = 1;
        end

        function testIndexingOnLHS(testCase)
            x(1:1e7) = 1;
        end

        function testForLoop(testCase)
            for i = 1:1e7
                x(i) = 1;
            end
        end
    end
end

对名称中包含 "Indexing" 的所有测试运行性能测试。您的结果可能有所不同,而且如果 runperf 不满足统计目标,您可能会看到一条警告消息。

results = runperf("preallocationTest","Name","*Indexing*")
Running preallocationTest
.......... .......... .......... ..
Done preallocationTest
__________
results = 
  1×2 TimeResult array with properties:

    Name
    Valid
    Samples
    TestActivity

Totals:
   2 Valid, 0 Invalid.
   3.011 seconds testing time.

要比较预分配方法,请基于 results 创建一个汇总统计量表。在此示例中,testIndexingOnLHS 方法是将向量值全部初始化为 1 的更快方法。

T = sampleSummary(results)
T=2×7 table
                       Name                       SampleSize      Mean      StandardDeviation      Min        Median       Max   
    __________________________________________    __________    ________    _________________    ________    ________    ________

    preallocationTest/testIndexingWithVariable        17          0.1223         0.014378         0.10003     0.12055     0.15075
    preallocationTest/testIndexingOnLHS                5        0.027557        0.0013247        0.026187    0.027489    0.029403

输入参数

全部折叠

测试,指定为字符串数组、字符向量或字符向量元胞数组。使用此参量指定测试内容。例如,您可以指定测试文件、测试类、包含测试文件的文件夹、包含测试类的命名空间或包含测试文件的工程文件夹。

示例: runperf("myTestFile.m")

示例: runperf(["myTestFile/test1" "myTestFile/test3"])

示例: runperf("myNamespace.MyTestClass")

示例: runperf(pwd)

示例: runperf({'myNamespace.MyTestClass','myTestFile.m',pwd,'myNamespace.innerNamespace'})

示例: runperf("C:\projects\project1")

名称-值参数

全部展开

Name1=Value1,...,NameN=ValueN 的形式指定可选参量对组,其中 Name 是参量名称,Value 是对应的值。名称-值参量必须出现在其他参量之后,但参量对组的顺序无关紧要。

示例: runperf(tests,Name="productA_*") 运行名称以 "productA_" 开头的测试元素。

在 R2021a 之前,使用逗号分隔每个名称和值,并用引号将 Name 引起来。

示例: runperf(tests,"Name","productA_*") 运行名称以 "productA_" 开头的测试元素。

测试标识

全部展开

在子文件夹中运行测试的选项,指定为数值或逻辑值 0 (false) 或 1 (true)。默认情况下,框架只运行指定文件夹(而不包含其子文件夹)中的测试。

在内部命名空间中运行测试的选项,指定为数值或逻辑值 0 (false) 或 1 (true)。默认情况下,框架只运行指定命名空间(而不包含其内部命名空间)中的测试。

包含来自引用工程的测试的选项,指定为数值或逻辑值 0 (false) 或 1 (true)。有关引用工程的详细信息,请参阅大型工程组件化

对函数正在处理的文件夹或命名空间中的无效测试文件采取的操作,指定为以下值之一:

  • "warn" - 该函数对文件夹或命名空间中的每个无效测试文件发出警告,并在有效文件中运行测试。

  • "error" - 如果该函数在文件夹或命名空间中发现无效的测试文件,将会抛出错误。

无效的测试文件是框架无法运行的测试文件。示例包括:包含语法错误的测试文件、基于函数但缺失局部函数的测试文件,以及具有 Test 方法但向该方法传递了未定义的参数化属性的文件。

测试过滤

全部展开

包含测试文件的基本文件夹的名称,指定为字符串数组、字符向量或字符向量元胞数组。此参量过滤测试套件。要使测试框架包含经过过滤的套件中的一个测试,Test 元素必须包含在 BaseFolder 指定的基本文件夹之一中。如果没有 Test 元素与基本文件夹匹配,将返回空测试套件。使用通配符 (*) 以匹配任何数量的字符。使用问号字符 (?) 只匹配一个字符。

对于命名空间中定义的测试文件,基本文件夹是顶级命名空间文件夹的父级。

包含源代码的文件和文件夹的名称,指定为字符串向量、字符向量或字符向量元胞向量。此参量通过仅包括依赖指定源代码的测试来过滤测试套件。如果没有测试依赖源代码,则返回空测试套件。

指定的值必须表示至少一个现有文件。如果指定文件夹,框架将提取该文件夹中文件的路径。

您必须有 MATLAB® Test™ 许可证才能使用 DependsOn。有关通过源代码依赖关系选择测试的详细信息,请参阅 matlabtest.selectors.DependsOn (MATLAB Test)

示例: DependsOn=["myFile.m" "myFolder"]

示例: DependsOn=["folderA" "C:\work\folderB"]

测试的名称,指定为字符串数组、字符向量或字符向量元胞数组。此参量过滤测试套件。要使测试框架包含经过过滤的套件中的一个测试,Test 元素的 Name 属性必须匹配 Name 指定的名称之一。如果 Test 元素都没有匹配的名称,将返回空测试套件。使用通配符 (*) 以匹配任何数量的字符。使用问号字符 (?) 只匹配一个字符。

对于一个给定的测试文件,测试的名称唯一地标识测试内容的最小可运行部分。测试名称包括命名空间名称、文件名(不包括扩展名)、过程名称和关于参数化的信息。

定义测试使用的参数的测试类属性的名称,指定为字符串数组、字符向量或字符向量元胞数组。此参量过滤测试套件。要使测试框架包含经过过滤的套件中的一个测试,Test 元素的 Parameterization 属性必须包含 ParameterProperty 指定的至少一个属性名称。如果 Test 元素都没有匹配的属性名称,将返回空测试套件。使用通配符 (*) 以匹配任何数量的字符。使用问号字符 (?) 只匹配一个字符。

测试使用的参数的名称,指定为字符串数组、字符向量或字符向量元胞数组。MATLAB 根据定义参数的测试类属性生成参数名称。例如:

  • 如果属性值是元胞数组,则 MATLAB 根据元胞数组元素的值、类型和维度,基于元胞数组的元素生成参数名称。

  • 如果属性值是结构体,则 MATLAB 将根据结构体字段生成参数名称。

ParameterName 参量过滤测试套件。要使测试框架包含经过过滤的套件中的一个测试,Test 元素的 Parameterization 属性必须包含 ParameterName 指定的至少一个参数名称。如果 Test 元素都没有匹配的参数名称,将返回空测试套件。使用通配符 (*) 以匹配任何数量的字符。使用问号字符 (?) 只匹配一个字符。

测试过程的名称,指定为字符串数组、字符向量或字符向量元胞数组。此参量过滤测试套件。要使测试框架包含经过过滤的套件中的一个测试,Test 元素的 ProcedureName 属性必须匹配 ProcedureName 指定的过程名称之一。如果 Test 元素都没有匹配的过程名称,将返回空测试套件。使用通配符 (*) 以匹配任何数量的字符。使用问号字符 (?) 只匹配一个字符。

在基于类的测试中,测试过程的名称是包含该测试的 Test 方法的名称。在基于函数的测试中,它是包含测试的局部函数的名称。在基于脚本的测试中,它是从测试部分标题生成的名称。与测试套件元素的名称不同,测试过程的名称不包括任何命名空间名称、文件名或关于参数化的信息。

派生测试类的父类的名称,指定为字符串数组、字符向量或字符向量元胞数组。此参量过滤测试套件。要使测试框架包含经过过滤的套件中的一个测试,Test 元素的 TestClass 属性必须指向从 Superclass 指定的类之一派生的一个测试类。如果没有 Test 元素与类匹配,将返回空测试套件。

测试使用的标记的名称,指定为字符串数组、字符向量或字符向量元胞数组。此参量过滤测试套件。要使测试框架包含经过过滤的套件中的一个测试,Test 元素的 Tags 属性必须包含 Tag 指定的至少一个标记名称。如果 Test 元素都没有匹配的标记名称,将返回空测试套件。使用通配符 (*) 以匹配任何数量的字符。使用问号字符 (?) 只匹配一个字符。

提示

  • 要自定义性能测试的统计目标,请使用 TimeExperiment 类来构造和运行性能测试。

  • 当您在测试中使用共享测试脚手架并将 runperf 函数的输入指定为字符串数组或字符向量元胞数组时,测试框架会对数组进行排序,以减少共享脚手架的设置和拆解操作。因此,测试运行的顺序可能不同于输入数组中元素的顺序。有关详细信息,请参阅 sortByFixtures

  • 编写基于类的测试时,可以将测试作为独立应用程序运行(需要 MATLAB Compiler™)。当前不支持编译性能测试。有关详细信息,请参阅编译 MATLAB 单元测试

备选方法

要显式创建测试套件,您可以使用 testsuite 函数或 matlab.unittest.TestSuite 方法,它会创建一个套件。然后,您可以使用指定的 TimeExperimentrun 方法运行性能测试。

版本历史记录

在 R2016a 中推出

全部展开