execute

Class: matlabtest.coder.MATLABCoderTester
Package: matlabtest.coder

Execute generated C/C++ code in formal equivalence tests

Since R2023a

Syntax

execute(tester,testCase)

execute(___,Name=Value)

Description

execute(tester,testCase) executes the generated C/C++ code specified by tester with the same inputs that were specified when generating the C/C++ code in the test case testCase. The function stores the execution results in the ExecutionResults property of tester.

execute(___,Name=Value) specifies options using one or more name-value arguments in addition to the input arguments in previous syntaxes.

Input Arguments

tester — Equivalence tester

matlabtest.coder.MATLABCoderTester object

Equivalence tester, specified as a matlabtest.coder.MATLABCoderTester object.

testCase — Test case

matlab.unittest.TestCase object

Test case, specified as a matlab.unittest.TestCase object.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: Inputs={1,2}

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. Use this argument to execute the function with different inputs than the inputs used to generate the C/C++ code.

Example: Inputs={1,2}

EntryPoint — Entry-point function name

string scalar | character vector

Entry-point function name, specified as a string scalar or character vector. Use this argument when your generated C/C++ code has multiple entry-point functions.

Example: EntryPoint="myAdd"

Examples

Generate C Code from Function with No Inputs and Test for Equivalence

This example shows how to generate C code from a MATLAB^® function that has no inputs and test for equivalence by using the equivalence tester matlabtest.coder.MATLABCoderTester.

The function helloWorld displays a string of text:

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

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

1. Imports the equivalence tester matlabtest.coder.MATLABCoderTester and the constraint matlabtest.constraints.ExecutionMatchesMATLAB.

2. Instantiates the tester for a MEX build target for the helloWorld function.

3. Builds C code from the helloWorld function.

4. Executes the C code with no inputs.

5. Verifies the execution of the C code against the execution of the MATLAB function helloWorld.

classdef tEquivalence < matlab.unittest.TestCase
    methods(Test)
        function tHelloWorld(testCase)
            import matlabtest.coder.MATLABCoderTester
            import matlabtest.constraints.ExecutionMatchesMATLAB
 
            tester = MATLABCoderTester.forMEXCoderConfiguration("helloWorld");
             
            build(tester,testCase);           
            execute(tester,testCase);           
            verifyThat(testCase,tester,ExecutionMatchesMATLAB);
        end
    end
end

Run the tHelloWorld test.

runtests("tEquivalence", ...
    procedureName="tHelloWorld")

Running tHelloWorld
..
Done tHelloWorld
__________


ans = 
  TestResult with properties:

          Name: 'tEquivalence/tHelloWorld'
        Passed: 1
        Failed: 0
    Incomplete: 0
      Duration: 2.7680
       Details: [1×1 struct]

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

Generate C Code from Multiple Functions and Test for Equivalence

This example shows how to generate C code from multiple MATLAB functions and test the functions for equivalence by using matlabtest.coder.MATLABCoderTester.

The function myAdd takes two numbers as inputs, adds them together, and outputs the result.

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

The function mySubtract takes two numbers as inputs, subtracts them, and outputs the result.

function y = mySubtract(a,b) %#codegen
y = b-a;
end

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

1. Imports the equivalence tester matlabtest.coder.MATLABCoderTester and the constraint matlabtest.constraints.ExecutionMatchesMATLAB

2. Instantiates the tester for a MEX build target for the entry-point function myAdd with the build-time inputs set to (0,0)

3. Adds the entry-point function mySubtract with the build-time inputs set to (0,0)

4. Builds C code from the myAdd and mySubtract functions

5. Executes the C code for the entry-point function myAdd with the inputs set to (5,5)

6. Verifies the execution of the C code against the execution of the MATLAB function myAdd

classdef tEquivalence < matlab.unittest.TestCase
    methods(Test)
        function tMyMath(testCase)
            import matlabtest.coder.MATLABCoderTester
            import matlabtest.constraints.ExecutionMatchesMATLAB
             
            tester = MATLABCoderTester.forMEXCoderConfiguration( ...
                "myAdd",Inputs={0,0});           
            addEntryPointFunction(tester,"mySubtract",{0,0});
             
            build(tester,testCase);
 
            execute(tester,testCase,Inputs={5,5},EntryPoint="myAdd");           
            verifyThat(testCase,tester,ExecutionMatchesMATLAB)
        end
    end
end

Run the tMyMath test.

runtests("tEquivalence", ...
    procedureName="tMyMath")

Running tMyMath
..
Done tMyMath
__________


ans = 
  TestResult with properties:

          Name: 'tEquivalence/tMyMath'
        Passed: 1
        Failed: 0
    Incomplete: 0
      Duration: 2.7680
       Details: [1×1 struct]

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

Version History

Introduced in R2023a