Equivalence Test C/C++ Code for Multiple Entry-Point Functions and Function Signatures

This example uses:

You can write equivalence tests that use MATLAB^® Coder™ to generate C/C++ code and test for equivalence with the MATLAB source code. For more information, see Generate C/C++ Code and Test for Equivalence.

You can also generate C/C++ code from multiple entry-point functions or with multiple signatures and then test each function or signature for equivalence with MATLAB source code.

Note

You must have MATLAB Coder to run equivalence tests for generated C/C++ code for MEX targets and Embedded Coder^® for LIB and DLL targets.

An entry-point function is a top-level MATLAB function from which you generate code. When you generate code with multiple entry-point functions, you can use a single MEX function to call multiple functions. For more information, see Generate Code for Multiple Entry-Point Functions (MATLAB Coder).
A function signature describes the acceptable syntaxes and allowable data types for a function. If your entry-point function has inputs, you must specify the properties of the inputs to generate a MEX function. In this case, the generated MEX function works only with the signature of the entry-point function that you specify during code generation. For more information, see Generate Code for Functions with Multiple Signatures (MATLAB Coder).

If you need to deploy C++ shared libraries, you can write equivalence tests that use MATLAB Compiler SDK™ to generate and test deployable C++ shared libraries from MATLAB source code. For more information, see Choose an Approach for Equivalence Testing Generated C++ Code.

Write Equivalence Tests for Multiple Entry-Point Functions

To generate and test C/C++ code for multiple entry-point functions:

Define a test class that inherits from matlab.unittest.TestCase.
Import the matlabtest.coder.MATLABCoderTester interface and the matlabtest.constraints.ExecutionMatchesMATLAB constraint.
Construct an instance of matlabtest.coder.MATLABCoderTester for your build type and provide one of the functions and build-time inputs.
Add additional functions and their build-time inputs by using addEntryPointFunction.
Generate the C/C++ code by using build.
Execute the C/C++ code by using execute and specify which function to execute. You can provide run-time inputs or re-use the build-time inputs.
Qualify the result against the MATLAB execution of the function with the same inputs.

You can also use the equivalence test customizations described in Generate C/C++ Code and Test for Equivalence.

Suppose that you have two functions called myAdd and mySubtract and you want to generate C/C++ code from both functions at the same time:

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

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

This equivalence test generates a MEX file from both functions and executes and verifies the functions against the MATLAB execution of the functions.

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

            execute(tester,testCase,Inputs={5,5},EntryPoint="myAdd");
            verifyThat(testCase,tester,ExecutionMatchesMATLAB);
            
            execute(tester,testCase,Inputs={2,3}, ...
                EntryPoint="mySubtract");
            verifyThat(testCase,tester,ExecutionMatchesMATLAB);
        end
    end
end

Tip

By default, the test case generates code in a temporary directory. To preserve the generated files, use the PreserveInFolder name-value argument in the creation method when you construct an instance of matlabtest.coder.MATLABCoderTester. When the equivalence test fails, MATLAB preserves the generated files regardless of whether or not you use this name-value argument.

Write Equivalence Tests for Functions with Multiple Signatures

To generate and test C/C++ code for functions with multiple signatures, in the test function:

Construct an instance of matlabtest.coder.MATLABCoderTester for your build type and provide the name of the function. Specify its signature by providing build-time inputs.
Specify additional signatures for the function by adding different build-time inputs for the function by using addEntryPointFunction.
Generate the C/C++ code.
Execute the C/C++ code. You can provide run-time inputs or re-use the initial build-time inputs.
Qualify the result against the MATLAB execution of the function with the same inputs by using the verifyThat method and the matlabtest.constraints.ExecutionMatchesMATLAB constraint..

You can also use equivalence test customizations described in Generate C/C++ Code and Test for Equivalence.

Suppose that you want to generate code for myAdd so that it can accept inputs of type double and int8. This example equivalence test generates a MEX file from the function with both signatures and verifies both signatures against the MATLAB execution.

classdef tEquivalenceMultisignature < matlab.unittest.TestCase
    methods(Test)
        function tMyAdd(testCase)
            import matlabtest.coder.MATLABCoderTester;
            import matlabtest.constraints.ExecutionMatchesMATLAB;
            
            tester = MATLABCoderTester.forMEXCoderConfiguration( ...
                "myAdd.m",Inputs={0,0});
            addEntryPointFunction(tester,"myAdd.m",{int8(0),int8(0)});
            
            build(tester,testCase);

            execute(tester,testCase,Inputs={5,5});
            verifyThat(testCase,tester,ExecutionMatchesMATLAB);
            
            execute(tester,testCase,Inputs={int8(2),int8(3)});
            verifyThat(testCase,tester,ExecutionMatchesMATLAB);
        end
    end
end

Run Tests and View Results

You can run equivalence tests by using the:

runtests function at the MATLAB command line
Run Tests button in the MATLAB Editor toolstrip in the Editor tab
Run button in the Test Browser
Run button in the MATLAB Test Manager
Run button in the Code Quality Dashboard

For more information, see Run MATLAB Tests.