Write Generated C/C++ Code Equivalence Tests

To write an equivalence test that generates and tests C/C++ code, define a test class that inherits from matlabtest.coder.TestCase. In your test class, include a methods block with the Test attribute. In the methods block, add a function to contain the test.

classdef tEquivalence < matlabtest.coder.TestCase
    methods (Test)
        function equivalenceTest(testCase)
            
        end
    end
end

Equivalence tests typically do three things:

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

classdef tEquivalence < matlabtest.coder.TestCase
    methods(Test)
        function tMyAdd(testCase)
            buildResults = build(testCase,"myAdd",Inputs={1,2});
            executionResults = execute(testCase,buildResults);
            verifyExecutionMatchesMATLAB(testCase,executionResults)
        end
    end
end

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

Parameterize Equivalence Tests

Equivalence tests use the MATLAB test framework, which means you can use MATLAB test customizations such as parameterizations. Parameterized tests allow you to test different parameter combinations with less code than if you coded each combination separately. For more information, see Create Basic Parameterized Test. Parameterizing equivalence tests allows you to generate the C/C++ code once and test it with different parameter combinations.

This example equivalence test generates the C code once by using class-level properties and test setup methods, but executes the code multiple times with different inputs by using parameterization.

classdef tEquivalenceParameterized < matlabtest.coder.TestCase
    properties
        buildResults
    end
    
    methods (TestClassSetup)        
        function generateCode(testCase)
            testCase.buildResults = build(testCase,"myAdd", ...
                Inputs={1,2});
        end        
    end

    properties (TestParameter)
    	runTimeInputs = {{1,2},{3,5}};
    end

    methods (Test)
        function tMyAdd(testCase,runTimeInputs)
            executionResults = execute(testCase, ...
                testCase.buildResults,Inputs=runTimeInputs);
            verifyExecutionMatchesMATLAB(testCase,executionResults)
        end
    end
end

Generate C/C++ Code with Additional Options

To customize how MATLAB Coder builds your C/C++ code in the equivalence test, create an instance of a code generation configuration parameter object for your desired build type by using coder.config (MATLAB Coder) and pass the object to the build method.

This example equivalence test generates a dynamically linked library of C++ code with dynamic memory allocation disabled. The test then executes the C++ code and verifies that the generated code is functionally equivalent to the MATLAB code.

classdef tEquivalenceBuildOptions < matlabtest.coder.TestCase
    methods (Test)
        function tMyAdd(testCase)
            cfg = coder.config("dll",ecoder=true);
            cfg.TargetLang = "C++";
            cfg.EnableDynamicMemoryAllocation = false;

            buildResults = build(testCase,"myAdd",Inputs={1,2}, ...
                Configuration=cfg);
            executionResults = execute(testCase,buildResults);
            verifyExecutionMatchesMATLAB(testCase,executionResults)
        end
    end
end

buildResults = build(testCase,"myAdd", ...
    Inputs={1,2},CodeGenerationArguments={"-lang:c++"});

Test Existing Generated C/C++ Code

You can generate C/C++ code outside of a test and verify the code by using an equivalence test. To test existing generated C/C++ code for equivalence, use codegen (MATLAB Coder) to generate C/C++ code and pass the file path for the MEX function to the execute method.

This example code shows how to generate code for the myAdd function outside of a test:

codegen myAdd -args {1,2}

classdef tEquivalenceExistingCode < matlabtest.coder.TestCase
    methods (Test)
        function tMyAdd(testCase)
            mexPath = "C:\Users\jdoe\generatedCodeTests\codegen" + ...
                "\mex\myAdd\myAdd_mex.mexw64";
            executionResults = execute(testCase,mexPath,Inputs={5,5});
            verifyExecutionMatchesMATLAB(testCase,executionResults)
        end
    end
end

Execute and Verify in SIL or PIL Mode

With Embedded Coder, you can verify generated C/C++ code with software-in-the-loop (SIL) and processor-in-the-loop (PIL) execution. For more information about SIL and PIL execution, see Code Verification Through Software-in-the-Loop and Processor-in-the-Loop Execution (Embedded Coder).

classdef tEquivalenceSIL < matlabtest.coder.TestCase
    methods (Test)
        function tMyAddSIL(testCase)
            buildResults = build(testCase,"myAdd",Inputs={1,2}, ...
                Configuration="lib");
            executionResults = execute(testCase,buildResults);
            verifyExecutionMatchesMATLAB(testCase,executionResults)
        end
    end
end

classdef tEquivalencePIL < matlabtest.coder.TestCase 
      methods(Test)
           function tMyAddPIL(testCase)
                cfg = coder.config("lib","ecoder",true);
                cfg.VerificationMode = "PIL";
                cfg.Hardware = coder.hardware("ARM Cortex-M3 (QEMU)");
 
                buildOut = build(testCase,"myAdd.m",Inputs={1,2}, ...
                    Configuration=cfg);
                executionOut = execute(testCase,buildOut);
                verifyExecutionMatchesMATLAB(testCase,executionOut);
           end
      end    
end

Run Tests and View Results

You can run equivalence tests by using the:

For more information, see Run MATLAB Tests.