Choose an Approach for Equivalence Testing Generated C++ Code

You can write equivalence tests that use MATLAB^® Coder™ to generate and test C++ code from MATLAB source code. Equivalence testing generated C++ code can help mitigate unexpected behavior when you deploy the generated C++ code.

Alternatively, you can write equivalence tests that use MATLAB Compiler SDK™ to generate and test deployable C++ shared libraries from MATLAB source code. Equivalence testing deployable C++ shared libraries can help mitigate unexpected behavior when you deploy the C++ shared library in a C++ application.

This table compares the benefits of writing equivalence tests that generate C++ code and deployable C++ shared libraries.

Approach for Equivalence Testing C++ Code	Benefits	Required Product	Able to Collect Coverage for C++ Code
Define a test in a `matlabtest.coder.TestCase` class	Generate C++ code and test for equivalence with MATLAB source code by using MATLAB Coder. Generate C++ code and use SIL or PIL verification for equivalence with MATLAB source code by using Embedded Coder^®. Generate C++ code once and test it with multiple different input combinations by using test parameters. Specify additional build options when generating C++ code. Use the `coder.config` (MATLAB Coder) function to create an instance of a code generation configuration parameter object and pass the object to the `build` method. Test existing generated C++ code that you generated by using the `codegen` (MATLAB Coder) function.	MATLAB Coder	Yes, but you must build and test a static library using SIL or PIL verification. You must have an Embedded Coder license.
Define a test in a `matlab.unittest.TestCase` class that imports the `matlabtest.coder.MATLABCoderTester` class	Generate C++ code for multiple entry-point functions or signatures using MATLAB Coder. Test each entry-point function or signature for equivalence with MATLAB source code. Generate C++ code once and test it with multiple different input combinations by using test parameters. Specify additional build options when generating C++ code. Use the `coder.config` (MATLAB Coder) function to create an instance of a code generation configuration parameter object and pass the object to the `build` method. Test existing generated C++ code that you generated by using the `codegen` (MATLAB Coder) function.	MATLAB Coder	Yes, but you must build and test a static library using SIL or PIL verification. You must have an Embedded Coder license.
Define a test in a `matlabtest.compiler.TestCase` class	Generate deployable C++ shared libraries using MATLAB Compiler SDK and test for equivalence with MATLAB source code. Generate deployable C++ shared library once and test it with multiple inputs by using test parameters. Generate a multi-function deployable C++ shared library once and test multiple functions by using sequential parameter combinations. Test existing deployable C++ shared libraries that you generated by using the `compiler.build.cppSharedLibrary` (MATLAB Compiler SDK) function.	MATLAB Compiler SDK	No

Generate and Test C++ Code

To generate C++ code from MATLAB source code and test for equivalence:

Define a test class that inherits from the matlabtest.coder.TestCase class.
Create a test in the test class.
In the test, generate the C++ code by using the build method. Specify the language to use in the generated code as C++ by specifying the CodeGenerationArguments as {"-lang:c++"}.
Execute the C++ code by using the execute method.
Qualify the result by comparing the execution of the C++ code to the execution of the MATLAB source code by using methods such as verifyExecutionMatchesMATLAB. For more information, see Table of Qualifications for Equivalence Tests.
Run the test and view the results programmatically, or by using the Test Browser or MATLAB Test Manager.

Suppose that you want to generate code for a function called myAdd, which adds two inputs and outputs the result:

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

This equivalence test builds C++ code for a MEX target with inputs set to (1,2). The test executes the C code with the same inputs used to build the code and verifies that the execution matches the MATLAB execution of the function.

classdef tEquivalenceCpp < matlabtest.coder.TestCase
    methods (Test)     
        function tMyAddCpp(testCase)                                  
            buildResults = build(testCase,"myAdd.m", ...
                CodeGenerationArguments={"-lang:c++"},Inputs={1,2});
            executionResults = execute(testCase,buildResults);
            verifyExecutionMatchesMATLAB(testCase,executionResults);
        end
    end
end

For more information, see Generate C/C++ Code and Test for Equivalence.

To collect coverage for the generated C++ code, configure the tests to generate a static library and use SIL or PIL verification. For more information about running the test, collecting coverage, and viewing the coverage results, see Collect Coverage for Generated C/C++ Code in Equivalence Tests.

Generate and Test C++ Code Using Multiple Entry-Point Functions or Functions with Multiple Signatures

You can generate C++ code from multiple entry-point functions or for functions that have multiple signatures. To generate code in these situations and test for equivalence with the MATLAB source code:

Define a test class that inherits from the matlab.unittest.TestCase class.
Create a test in the test class.
In the test, import the matlabtest.coder.MATLABCoderTester interface and the matlabtest.constraints.ExecutionMatchesMATLAB constraint.
Specify the language to use in the generated code as C++ by using the coder.config (MATLAB Coder) function to create a coder.MexCodeConfig (MATLAB Coder) or coder.EmbeddedCodeConfig (MATLAB Coder) object, referred to as a code generation configuration parameter object. Specify the TargetLang property of the object as "C++".
Construct an instance of the matlabtest.coder.MATLABCoderTester class for your build type and provide one of the functions and build-time inputs by using one of these methods:
Pass the code generation configuration parameter object to the equivalence test class constructor by using the Configuration name-value argument.
Add additional functions or function signatures by using the addEntryPointFunction method.
Generate the C++ code by using the build method.
Execute the C++ code by using the execute method.
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.
Run the test and view the results programmatically, or by using the Test Browser or MATLAB Test Manager.

This SIL equivalence test builds C++ code as a static library, and executes the code with inputs set to (1,2). The test verifies that the execution matches the MATLAB execution of the function.

classdef tFormalEquivalenceCpp < matlab.unittest.TestCase
    methods(Test)
        function tMyAddCpp(testCase)
            import matlabtest.coder.MATLABCoderTester
            import matlabtest.constraints.ExecutionMatchesMATLAB
            
            config = coder.config("lib","ecoder",true);
            config.TargetLang = "C++";
            tester = MATLABCoderTester.forLIBCoderConfiguration( ...
                "myAdd.m",Inputs={0,0},Configuration=config);
            
            build(tester,testCase);
            execute(tester,testCase,Inputs={1,2});
            verifyThat(testCase,tester, ...
                ExecutionMatchesMATLAB);          
        end
    end
end

For more information, see Equivalence Test C/C++ Code for Multiple Entry-Point Functions and Function Signatures.

Generate and Test Deployable C++ Shared Libraries

Since R2024b

To generate deployable C++ shared libraries and test for equivalence with the MATLAB source code:

Define a test class that inherits from the matlabtest.compiler.TestCase class.
Create a test in the test class.
Generate the deployable C++ shared library by using the build method. Specify the artifactType argument as "cppSharedLibrary".
Execute the deployed C++ shared library by using the execute method.
Qualify the result by comparing the execution of the deployed code artifact to the execution of the MATLAB source code by using methods such as verifyExecutionMatchesMATLAB. For more information, see Table of Qualifications for Equivalence Tests.
Run the test and view the results programmatically, or by using the Test Browser or MATLAB Test Manager.

classdef tEquivalenceCppSharedLibrary < matlabtest.compiler.TestCase
    methods (Test)
        function cppSimple(testCase)
            func = which("myAdd.m");
            buildResults = build(testCase,func,"cppSharedLibrary");
            executionResults = execute(testCase,buildResults,{1,2});
            verifyExecutionMatchesMATLAB(testCase,executionResults);
        end
    end
end

For more information, see Generate Deployed Code Artifacts and Test for Equivalence.