execute

Class: matlabtest.compiler.TestCase
Namespace: matlabtest.compiler

Execute deployed code artifacts in equivalence tests

Since R2023a

Syntax

executionResults = execute(testCase,buildResults)

executionResults = execute(testCase,buildResults,inputs)

executionResults = execute(testCase,buildResults,inputs,fcnName)

executionResults = execute(___,PreservingOnFailure=true)

Description

executionResults = execute(testCase,buildResults) executes the function in the build results object buildResults with no inputs by using MATLAB^® Compiler SDK™ in the equivalence test case testCase. Use this syntax if your function has no inputs.

executionResults = execute(testCase,buildResults,inputs) executes the function in the build results object with the inputs specified by inputs.

executionResults = execute(testCase,buildResults,inputs,fcnName) executes the function specified by fcnName. Use this syntax if your deployed code artifact contains multiple functions.

executionResults = execute(___,PreservingOnFailure=true) preserves after a test failure the files that the test creates when it executes the deployed code artifact.

Input Arguments

testCase — Test case

matlabtest.compiler.TestCase object

Test case, specified as a matlabtest.compiler.TestCase object.

buildResults — Build results

compiler.build.Results object

Build results, specified as a compiler.build.Results (MATLAB Compiler SDK) object that has the BuildType property set to javaPackage, pythonPackage, dotNETAssembly, productionServerArchive, or cppSharedLibrary. Generate this object by using the build function or one of these functions:

• compiler.build.dotNETAssembly (MATLAB Compiler SDK)

• compiler.build.javaPackage (MATLAB Compiler SDK)

• compiler.build.pythonPackage (MATLAB Compiler SDK)

• compiler.build.productionServerArchive (MATLAB Compiler SDK)

• compiler.build.cppSharedLibrary (MATLAB Compiler SDK)

inputs — Run-time inputs

cell array

Run-time inputs, specified as a cell array. Each element in the cell array corresponds to an input to the function.

Example: {3,5}

fcnName — Name of function to execute

string scalar | character vector

Name of the function to execute, specified as a string scalar or character vector.

Example: "makesquare"

Output Arguments

executionResults — Execution results

matlabtest.compiler.results.ExecutionResults

Execution results, returned as a matlabtest.compiler.results.ExecutionResults object.

Examples

Generate and Test Python Package for Function with No Inputs

This example shows how to generate a Python^® package from a MATLAB function that has no inputs and test it for equivalence.

The function called helloWorld takes no inputs:

function y = helloWorld 
y = 'Hello World!';
end

This class definition file defines an equivalence test case that inherits from matlabtest.compiler.TestCase. The test case in the methods block defines a test case that:

1. Builds the Python package from the helloWorld function

2. Executes the Python package with no inputs

3. Verifies the execution of the Python package against the execution of the MATLAB function helloWorld

classdef tDeployment < matlabtest.compiler.TestCase
    methods(Test)
        function pythonEquivalence(testCase)
            buildResults = build(testCase,"helloWorld.m", ...
                "pythonPackage");
            executionResults = execute(testCase,buildResults);
            verifyExecutionMatchesMATLAB(testCase,executionResults);
        end
    end
end

Run the pythonEquivalence test.

runtests("tDeployment", ...
    ProcedureName="pythonEquivalence")

Running pythonEquivalence
..
Done pythonEquivalence
__________


ans = 

  TestResult with properties:

          Name: 'tDeployment/pythonEquivalence'
        Passed: 1
        Failed: 0
    Incomplete: 0
      Duration: 78.4746
       Details: [1×1 struct]

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

Generate and Test Python Package for Equivalence

This example shows how to generate a Python package from MATLAB source code and test for equivalence by using MATLAB Compiler SDK.

The function makesquare generates an n-by-n matrix:

function y = makesquare(x)
y = magic(x);
end

This class definition file defines an equivalence test case that inherits from matlabtest.compiler.TestCase. The test case in the methods block defines a test case that:

1. Builds the Python package from the makesquare function

2. Executes the Python package with input set to 5

3. Verifies the execution of the Python package against the execution of the MATLAB function makesquare with the same input

classdef tDeployment < matlabtest.compiler.TestCase
    methods(Test)
        function pythonEquivalence(testCase)
            buildResults = build(testCase,"makesquare.m", ...
                "pythonPackage");
            executionResults = execute(testCase,buildResults,{5});
            verifyExecutionMatchesMATLAB(testCase,executionResults);
        end
    end
end

Run the pythonEquivalence test.

runtests("tDeployment", ...
    ProcedureName="pythonEquivalence")

Running pythonEquivalence
..
Done pythonEquivalence
__________


ans = 

  TestResult with properties:

          Name: 'tDeployment/pythonEquivalence'
        Passed: 1
        Failed: 0
    Incomplete: 0
      Duration: 93.1237
       Details: [1×1 struct]

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

Generate and Test Python Package for Equivalence with Additional Customizations

This example shows how to generate a Python package from MATLAB source code and test for equivalence by using MATLAB Compiler SDK.

The function makesquare generates an n-by-n matrix and the function myAdd takes two inputs and adds them together:

function y = makesquare(x)
y = magic(x);
end

function y = myAdd(a,b)
y = a + b;
end

This class definition file:

• Builds a packaged that contains makesquare and myAdd

• Saves the build results object if the test fails

• Verifies the result with an absolute tolerance

classdef tDeployment < matlabtest.compiler.TestCase
    methods(Test)
        function pythonEquivalence(testCase)
            functionsToDeploy = ["makesquare.m","myAdd.m"];
            buildResults = build(testCase,functionsToDeploy, ...
                "pythonPackage",PreservingOnFailure=true);            
            preserveOnFailure=true;
            executionResults = execute(testCase,buildResults,{5}, ...
                "makesquare",PreservingOnFailure=preserveOnFailure);
            verifyExecutionMatchesMATLAB(testCase,executionResults, ...
                AbsTol=0.0001);
        end
    end
end

Run the pythonEquivalence test.

runtests("tDeployment", ...
    ProcedureName="pythonEquivalence")

Running pythonEquivalence
..
Done pythonEquivalence
__________


ans = 

  TestResult with properties:

          Name: 'tDeployment/pythonEquivalence'
        Passed: 1
        Failed: 0
    Incomplete: 0
      Duration: 93.1237
       Details: [1×1 struct]

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

Limitations

• You cannot generate deployed code artifacts or test them for equivalence in MATLAB Online™.

Version History

Introduced in R2023a

R2024b: Execute deployable C++ shared libraries in equivalence tests

Execute deployable C++ shared libraries in equivalence tests by specifying the buildResults input argument as a compiler.build.Results (MATLAB Compiler SDK) object that has the BuildType property set to cppSharedLibrary.

R2024a: Execute deployable archives in equivalence tests

Execute deployable archives in equivalence tests by specifying the buildResults input argument as a compiler.build.Results (MATLAB Compiler SDK) object that has the BuildType property set to productionServerArchive.