matlab.unittest.plugins.TestReportPlugin.producingDOCX

Class: matlab.unittest.plugins.TestReportPlugin
Package: matlab.unittest.plugins

Constructs plugin that produces .docx report

expand all in page

Syntax

matlab.unittest.plugins.TestReportPlugin.producingDOCX
matlab.unittest.plugins.TestReportPlugin.producingDOCX(docxFile)
matlab.unittest.plugins.TestReportPlugin.producingDOCX(docxFile,Name,Value)

Description

example

matlab.unittest.plugins.TestReportPlugin.producingDOCX constructs a plugin that produces a .docx report of test results in a temporary folder. This syntax is equivalent to matlab.unittest.plugins.TestReportPlugin.producingDOCX([tempname '.docx']).

matlab.unittest.plugins.TestReportPlugin.producingDOCX(docxFile) saves the report to the file docxFile.

example

matlab.unittest.plugins.TestReportPlugin.producingDOCX(docxFile,Name,Value) constructs a plugin with additional options specified by one or more Name,Value pair arguments.

Input Arguments

expand all

Name of the test report that the plugin creates, specified as a character vector ending in .docx.

Example: 'myReportFile.docx'

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: TestReportPlugin.producingDOCX(docxFile,'LoggingLevel',Verbosity.Detailed) creates a plugin that includes diagnostics logged at and below the Detailed level.

Report orientation, specified as 'portrait' or 'landscape'. By default the plugin produces a report with portrait orientation.

Include Command Window text in report, specified as false or true. By default, IncludingCommandWindowText is false and the text output from the Command Window is excluded from the report. To include Command Window text in the report, specify IncludingCommandWindowText as true.

Data Types: logical

Include passing event diagnostics, specified as false or true. By default, IncludingPassingDiagnostics is false and the diagnostics from passing events are excluded from the report. To include diagnostics from passing events in the report, specify IncludingPassingDiagnostics as true.

Data Types: logical

Maximum level at which logged diagnostics are included by the plugin instance, specified as an integer value from 0 through 4, a matlab.unittest.Verbosity enumeration object, or a string scalar or character vector corresponding to one of the predefined enumeration member names. The plugin includes diagnostics that are logged at this level and below. Integer values correspond to the members of the matlab.unittest.Verbosity enumeration.

Numeric RepresentationEnumeration Member NameVerbosity Description
0None

No information

1Terse

Minimal information

2Concise

Moderate amount of information

3Detailed

Some supplemental information

4Verbose

Lots of supplemental information

By default the plugin includes diagnostics logged at the matlab.unittest.Verbosity.Terse level (level 1). To exclude logged diagnostics, specify LoggingLevel as Verbosity.None (level 0).

Logged diagnostics are diagnostics that you supply to the testing framework with a call to the log (TestCase) or log (Fixture) method.

Examples

expand all

Create a test suite from two test files, run the suite, and generate a .docx report of the results.

Create a new file in your working folder named ScriptBasedTest.m containing the following test script. The script includes two failing and incomplete tests.

%% Test double class
expSolution = 'double';
actSolution = ones;
assert(isa(actSolution,expSolution))

%% Test single class
expSolution = 'single';
actSolution = ones('single');
assert(isa(actSolution,expSolution))

%% Test uint16 class
expSolution = 'uint16';
actSolution = ones('uint16');
assert(isa(actSolution,expSolution))

%% Test that fails
assert(false==true);

%% Another test that fails
assert(strcmp('correlation','causation'))

Create a file named ClassBasedTest.m containing the following test class.

classdef ClassBasedTest < matlab.unittest.TestCase
    properties (ClassSetupParameter)
        generator = {'twister','combRecursive','multFibonacci'};
    end
    properties (MethodSetupParameter)
        seed = {0,123,4294967295};
    end
    properties (TestParameter)
        dim1 = struct('small',1,'medium',2,'large',3);
        dim2 = struct('small',2,'medium',3,'large',4);
        dim3 = struct('small',3,'medium',4,'large',5);
        type = {'single','double'};
    end
    methods (TestClassSetup)
        function ClassSetup(testCase,generator)
            orig = rng;
            testCase.addTeardown(@rng,orig)
            rng(0, generator)
        end
    end
    methods (TestMethodSetup)
        function MethodSetup(testCase,seed)
            orig = rng;
            testCase.addTeardown(@rng,orig)
            rng(seed)
        end
    end
    methods (Test, ParameterCombination='sequential')
        function testSize(testCase,dim1,dim2,dim3)
            testCase.verifySize(rand(dim1,dim2,dim3),[dim1 dim2 dim3])
        end 
    end
    methods (Test, ParameterCombination='pairwise')
        function testRepeatable(testCase,dim1,dim2,dim3)
            state = rng;
            firstRun = rand(dim1,dim2,dim3);
            rng(state)
            secondRun = rand(dim1,dim2,dim3);
            testCase.verifyEqual(firstRun,secondRun);
        end
    end
    methods (Test)
        function testClass(testCase,dim1,dim2,type)
            testCase.verifyClass(rand(dim1,dim2,type),type)
        end
    end
end

At the command prompt, create a test suite from both test files.

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

suite = testsuite({'ScriptBasedTest','ClassBasedTest'})
suite = 

  1×284 Test array with properties:

    Name
    ProcedureName
    TestClass
    BaseFolder
    Parameterization
    SharedTestFixtures
    Tags

Tests Include:
   17 Unique Parameterizations, 0 Shared Test Fixture Classes, 0 Tags.

Create a silent test runner, so that there is no information output to the command window. Create a TestReportPlugin that sends output to the file MyTestReport.docx.

runner = TestRunner.withNoPlugins;
docxFile = 'MyTestReport.docx';
plugin = TestReportPlugin.producingDOCX(docxFile);

Add the plugin to the TestRunner and run the suite.

runner.addPlugin(plugin);
result = runner.run(suite)
Generating report. Please wait.
    Preparing content for the report.
    Adding content to the report.
    Writing report to file.
Report has been saved to: C:\work\MyTestReport.docx

result = 

  1×284 TestResult array with properties:

    Name
    Passed
    Failed
    Incomplete
    Duration
    Details

Totals:
   282 Passed, 2 Failed, 2 Incomplete.
   0.73477 seconds testing time.

Open the test report.

open(docxFile)

Create a test suite from a function-based test, run the suite, and generate a report of the results. Include passing diagnostics and the text output to the Command Window.

Create a new file in your working folder named FunctionBasedTest.m containing the following function-based test. The test file includes two failing tests.

%% Main function to generate tests
function tests = FunctionBasedTest
tests = functiontests(localfunctions);
end

%% Test Functions
function passingTest(testCase)
actSolution = 13*3+7*5;
expSolution = 74;
verifyEqual(testCase,actSolution,expSolution)
end

function failingTest(testCase)
actSolution = single(1);
verifyTrue(testCase,actSolution)
end

function anotherPassingTest(testCase)
verifyClass(testCase,string('some text'),'string')
end

function anotherFailingTest(testCase)
verifyTrue(testCase,strcmp('42','everything'))
end

At the command prompt, create a test suite from FunctionBasedTest.m. Create a test runner that displays output to the command window using the default plugin.

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

suite = testsuite('FunctionBasedTest');
runner = TestRunner.withTextOutput;

Create a TestReportPlugin that sends output to the file MyTestReport2.docx. Include passing diagnostics and text output from the Command Window in the report.

docxFile = 'MyTestReport2.docx';
plugin = TestReportPlugin.producingDOCX(docxFile,...
    'IncludingPassingDiagnostics',true,'IncludingCommandWindowText',true);

Add the plugin to the TestRunner and run the suite.

runner.addPlugin(plugin);
result = runner.run(suite);
Running FunctionBasedTest
.
================================================================================
Verification failed in FunctionBasedTest/failingTest.

    ---------------------
    Framework Diagnostic:
    ---------------------
    verifyTrue failed.
    --> The value must be logical. It is of type "single".
    
    Actual single:
             1

    ------------------
    Stack Information:
    ------------------
    In C:\Work\FunctionBasedTest.m (failingTest) at 15
================================================================================
..
================================================================================
Verification failed in FunctionBasedTest/anotherFailingTest.

    ---------------------
    Framework Diagnostic:
    ---------------------
    verifyTrue failed.
    --> The value must evaluate to "true".
    
    Actual logical:
           0

    ------------------
    Stack Information:
    ------------------
    In C:\Work\FunctionBasedTest.m (anotherFailingTest) at 23
================================================================================
.
Done FunctionBasedTest
__________

Failure Summary:

     Name                                  Failed  Incomplete  Reason(s)
    ===================================================================================
     FunctionBasedTest/failingTest           X                 Failed by verification.
    -----------------------------------------------------------------------------------
     FunctionBasedTest/anotherFailingTest    X                 Failed by verification.
    
Generating report. Please wait.
    Preparing content for the report.
    Adding content to the report.
    Writing report to file.
Report has been saved to: C:\Work\MyTestReport2.docx

Open the test report.

open(docxFile)

See Also

Introduced in R2016b

MATLAB Documentation

Support