本页翻译不是最新的。点击此处可查看最新英文版本。

runperf

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

语法

results = runperf

results = runperf(tests)

results = runperf(___,Name,Value)

说明

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

从选定的单元测试中进行性能测试

在您的当前工作文件夹中创建一个基于类的测试，preallocationTest.m，用于对不同的预分配方法进行比较。

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

preallocationTest 类的测量边界是测试方法。每个测试方法的时间测量包括该方法中的所有代码。有关指定测量边界的信息，请参阅 matlab.perftest.TestCase 的 startMeasuring 和 stopMeasuring 方法。

对名称中包含 '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.
   2.4858 seconds testing time.

显示每个测试的平均测量时间。串联 results 数组中两个元素的 Samples 字段的值。然后，使用 varfun 按名称对表格中的条目进行分组并计算均值。

fullTable = vertcat(results.Samples);
varfun(@mean,fullTable,'InputVariables','MeasuredTime','GroupingVariables','Name')

ans =

  2×3 table

                       Name                       GroupCount    mean_MeasuredTime
    __________________________________________    __________    _________________

    preallocationTest/testIndexingWithVariable         6             0.16337     
    preallocationTest/testIndexingOnLHS               13            0.049936     

输入参数

tests — 测试

字符串数组 | 字符向量 | 字符向量元胞数组

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

示例: runperf("myTestFile.m")

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

示例: runperf("mypackage.MyTestClass")

示例: runperf(pwd)

示例: runperf({'mypackage.MyTestClass','myTestFile.m',pwd,'mypackage.subpackage'})

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

名称-值参数

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

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

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

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

测试标识

IncludeSubfolders — 指示是否运行子文件夹中的测试的指示符

false (默认) | true | 0 | 1

指示是否运行子文件夹中测试的指示符，指定为 false 或 true（0 或 1）。默认情况下，框架只运行指定文件夹（而不包含其子文件夹）中的测试。

IncludeSubpackages — 指示是否运行子包中的测试的指示符

false (默认) | true | 0 | 1

指示是否运行子包中的测试的指示符，指定为 false 或 true（0 或 1）。默认情况下，框架只运行指定包（而不包含其子包）中的测试。

IncludeReferencedProjects — 是否包含来自引用工程的测试

false 或 0 (默认) | true 或 1

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

InvalidFileFoundAction — 对无效测试文件采取的操作

"warn" (默认) | "error"

对函数正在处理的文件夹或包中的无效测试文件采取的操作，指定为 "warn" 或 "error"。

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

• "error" - 如果该函数在文件夹或包中发现无效的测试文件，将会引发错误。

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

测试过滤

BaseFolder — 基本文件夹的名称

字符串数组 | 字符向量 | 字符向量元胞数组

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

对于包中定义的测试文件，基本文件夹是顶级包文件夹的父级。

DependsOn — 包含源代码的文件和文件夹的名称

字符串向量 | 字符向量 | 字符向量元胞向量

包含源代码的文件和文件夹的名称，指定为字符串向量、字符向量或字符向量元胞向量。此参量过滤测试套件。为了使测试框架在过滤后的套件中包括测试，定义测试的文件必须依赖指定的源代码。如果没有测试文件依赖源代码，则返回空测试套件。

指定的值必须表示至少一个具有 .m、.p、.mlx、.mlapp、.mat 或 .slx 扩展名的现有文件。无法用不支持的扩展名显式指定文件名。如果指定文件夹名称，框架将提取该文件夹中受支持文件的路径。

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

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

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

Name — 测试名称

字符串数组 | 字符向量 | 字符向量元胞数组

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

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

ParameterProperty — 参数化属性的名称

字符串数组 | 字符向量 | 字符向量元胞数组

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

ParameterName — 参数名称

字符串数组 | 字符向量 | 字符向量元胞数组

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

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

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

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

ProcedureName — 测试过程的名称

字符串数组 | 字符向量 | 字符向量元胞数组

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

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

Superclass — 派生测试类的父类的名称

字符串数组 | 字符向量 | 字符向量元胞数组

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

Tag — 标记的名称

字符串数组 | 字符向量 | 字符向量元胞数组

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

提示

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

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

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

备选方法

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

版本历史记录

在 R2016a 中推出

R2023a: 按源代码依存关系过滤测试套件

您可以按测试文件对指定源代码的依存关系来过滤测试套件。使用 DependsOn 名称-值参量（需要 MATLAB Test）来指定源文件和文件夹。

R2023a: 运行验证需求集的测试

如果您安装了 Requirements Toolbox™ 和 MATLAB Test，则可以使用 runperf 函数来运行验证需求集的测试。要运行测试，请将一个或多个需求集文件指定为一个字符串标量或字符串向量。例如，results = runperf("myRequirementSet.slreqx") 运行验证指定的需求集的测试。

R2023a: 预备测量值的数量已增大

runperf 对测试代码进行预备的次数从 4 次增加到 5 次。这种变化通常会导致满足目标相对误差界限所需的样本更少。

如果您的代码依赖以前的值，您可能需要更新您的代码。例如，如果您使用 warmupTable = results(1).TestActivity(1:4,:) 创建预备测量值表，请将 4 替换为 5。

R2022b: 指定要针对无效测试文件采取的操作

要指定框架在遇到文件夹或包中的无效测试文件时是发出警告还是引发错误，请使用 InvalidFileFoundAction 名称-值参量。

R2022b: 从元胞数组生成的参数名称更具描述性

当您将非空元胞数组分配给参数化属性时，测试框架会根据元胞数组中元素的值、类型和维度生成参数名称。在以前的版本中，如果属性值是字符向量元胞数组，该框架将根据元胞数组中的值生成参数名称。否则，该框架将参数名称指定为 value1、value2、…、valueN。

如果您的代码使用参数名称来创建或过滤测试套件，请用描述性参数名称替换旧的参数名称。例如，通过用描述性参数名称替换 value1 来更新 suite = testsuite(pwd,"ParameterName","value1")。

R2022a: IncludeSubfolders 以同样的方式对待文件夹和包

IncludeSubfolders 名称-值参量以同样的方式对待文件夹和包。例如，runperf(pwd,IncludeSubfolders=true) 运行当前文件夹及其任何子文件夹（包括包文件夹）中的所有测试。在以前的版本中，IncludeSubfolders 会忽略包文件夹。

R2021b: runperf 会忽略未定义测试过程的工程文件

runperf 函数会忽略 MATLAB 工程中未定义测试过程的任何文件。例如，如果抽象的 TestCase 类定义文件使用 Test 分类进行标记，则该函数会忽略它。在以前的版本中，如果对除具体测试文件之外的任何文件使用 Test 分类的工程调用 runperf，则 MATLAB 会生成错误。

R2021b: 在没有 Java 虚拟机 (JVM) 软件的情况下，工程中的测试无法运行

如果 MATLAB 在没有 Java^® 虚拟机 (JVM™) 软件的情况下运行，则 runperf 无法运行 MATLAB 工程中的测试。原因是没有 JVM 软件就无法打开工程。在以前的版本中，当 MATLAB 在没有 JVM 软件的情况下运行时，runperf 基于工程中的测试文件创建一个套件并运行该套件。

R2019a: 在 MATLAB 工程中运行测试

如果您的当前文件夹是工程根文件夹，或您将工程根文件夹的完整路径传递给 runperf 函数，则该函数会运行指定工程中标有 Test 分类的所有测试文件。

R2019a: 从引用工程运行测试

要从引用工程运行测试，请使用 IncludeReferencedProjects 名称-值参量。

R2019a: 性能测试结果以 TimeResult 对象形式返回

runperf 函数返回 matlab.perftest.TimeResult 数组，其中包含指定性能测试的结果。在以前的版本中，该函数返回由 matlab.unittest.measurement.MeasurementResult 对象组成的数组。

R2019a: 支持更高的最大采样测量值数目

运行性能测量时，runperf 采集的默认最大采样测量值数目已从 32 增大到 256。

另请参阅

runtests | matlab.perftest.FrequentistTimeExperiment | matlab.perftest.TimeResult | matlab.unittest.measurement.MeasurementResult | comparisonPlot

主题

• 性能测试框架概述
• 使用脚本或函数测试性能
• 使用类测试性能