Main Content

Generate Deployed Code Artifacts and Test for Equivalence

This example uses:

You can write equivalence tests that use MATLAB® Compiler SDK™ to:

  • Build a Java® or Python® package, a .NET assembly, a deployable archive, or a deployable C++ shared library. The built package, assembly, or archive is referred to as a deployed code artifact.

  • Execute the deployed code artifact with specified inputs.

  • Verify that the execution of the deployed code artifact and the MATLAB source code match.

You can customize your equivalence test by specifying additional build options and parameterizing the test. You can also build deployed code artifacts outside of a test that you can verify later by using an equivalence test.

Note

  • If you need to deploy C++ code as a MEX function, a static library, or a dynamically linked library, you can author equivalence tests that use MATLAB Coder™ to build and test C++ code for equivalence with the MATLAB source code. For more information, see Choose an Approach for Equivalence Testing Generated C++ Code.

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

Prerequisites

To generate and test Java or Python packages or .NET assemblies, you must install third-party software.

.NET

You can only generate .NET assemblies on Windows® platforms.

Java

You can generate Java packages on Windows, Linux®, and Mac platforms.

Install a version of Java that is compatible with MATLAB Compiler SDK. For information on supported Java versions, see MATLAB Interfaces to Other Languages.

For information on configuring your development environment after installation, see Configure Your Environment for Generating Java Packages (MATLAB Compiler SDK).

Python

You can generate Python packages on Windows, Linux, and Mac platforms.

Install a version of Python that is compatible with MATLAB Compiler SDK. For details, see MATLAB Supported Interfaces to Other Languages. Verify that your installed version of Python is discoverable by using pyenv.

Write Equivalence Tests to Test Deployed Code Artifacts

To write an equivalence test that builds and tests the deployed code artifact, define a test class that inherits from matlabtest.compiler.TestCase. In your test class, include a methods block with the Test attribute to contain the tests. In the methods block, add a function to contain the test.

classdef tDeployment < matlabtest.compiler.TestCase
    methods (Test)
        function equivalenceTest(testCase)
            
        end
    end
end
For more information about test classes, see Class-Based Unit Tests.

Equivalence tests typically do three things:

Suppose that you want to generate a Python package for a function called makesquare, which generates an n-by-n matrix:

function y = makesquare(x)
y = magic(x);
end
This equivalence test executes the function with the input set to 5 and verifies that the execution matches the MATLAB execution of the function.
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

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 build the deployed code artifact once and test it with different parameter combinations.

Parameterize Inputs

You can parameterize inputs to run a single equivalence test multiple times with different inputs.

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

classdef tDeployment < matlabtest.compiler.TestCase
    properties
        BuildResults
    end

    methods (TestClassSetup)
        function buildPackage(testCase)
            testCase.BuildResults = build(testCase,"makesquare.m", ...
                "pythonPackage");
        end
    end

    properties (TestParameter)
        Inputs = {{3},{5}};
    end

    methods (Test)
        function pythonEquivalence(testCase,Inputs)
            executionResults = execute(testCase, ...
                testCase.BuildResults,Inputs);
            verifyExecutionMatchesMATLAB(testCase,executionResults);
        end
    end
end

Parameterize Tests to Verify Multiple Functions

You can write a single equivalence test that verifies multiple functions in the same deployed code artifact by parameterizing the function inputs. If your functions take a different number of inputs, use a sequential parameter combination to pass input sets with the right size to the corresponding function.

Suppose that you want to build a Python package that includes the function makesquare and a function called myAdd, which adds two inputs and outputs the result:

function y = myAdd(a,b)
y = a + b;
end
This equivalence test builds the deployed code artifact with both functions once and tests both functions by using a sequential parameter combination to execute the functions with inputs that match the function signature.
classdef tDeployment < matlabtest.compiler.TestCase
    properties
        BuildResults
    end

    methods (TestClassSetup)
        function buildPackage(testCase)
            functionsToDeploy = ["makesquare.m","myAdd.m"];  
            testCase.BuildResults = build(testCase, ...
                functionsToDeploy,"pythonPackage");
        end
    end

    properties (TestParameter)
        Name = {"makesquare","myAdd"};
        Inputs = {{5},{1,6}};
    end

    methods (Test,ParameterCombination="sequential")
        function pythonEquivalence(testCase,Inputs,Name)
            executionResults = execute(testCase, ...
                testCase.BuildResults,Inputs,Name);
            verifyExecutionMatchesMATLAB(testCase,executionResults);
        end
    end
end
When you run this test, it runs twice. First, it executes makesquare with input set to 5 and verifies the result. It then executes myAdd with inputs set to 1 and 6 and verifies the result.

Build Deployed Code Artifacts with Additional Options

To customize how MATLAB Compiler SDK builds your deployed code artifact in the equivalence test, create a build options object for your desired build type:

This equivalence test builds and tests a Python package from makesquare, specifies the package name, and provides additional files to include in the package.

classdef tDeployment < matlabtest.compiler.TestCase
    methods (Test)
        function pythonEquivalence(testCase)
            func = "makesquare.m";
            buildOpts = compiler.build.PythonPackageOptions(func);
            buildOpts.PackageName = "PackageUnderTest";
            buildOpts.AdditionalFiles = "makesquareData.mat";

            buildResults = build(testCase,buildOpts);
            executionResults = execute(testCase,buildResults,{2});
            verifyExecutionMatchesMATLAB(testCase,executionResults);
        end
    end
end

Test Existing Deployed Code Artifact

You can build a deployed code artifact outside of a test and verify the deployed code artifact by using an equivalence test.

You can only test existing deployed code artifacts whose compiler.build.Results (MATLAB Compiler SDK) objects specify an absolute path for the location of the build files. Use the OutputDir name-value argument to specify an absolute path when you build a deployed code artifact by using one of these functions:

This code shows how to create build results for a Python package outside of a test that you can verify later by using an equivalence test.

func = "makesquare.m";
dir = "C:\Users\jdoe\pythonBuilds";
buildResults = compiler.build.pythonPackage(func,OutputDir=dir);
save("pythonBuild.mat","buildResults")

Note

When you build deployable archives, you must specify the MATLAB function signature JSON file by using the FunctionSignatures (MATLAB Compiler SDK) name-value argument in the compiler.build.ProductionServerArchiveOptions (MATLAB Compiler SDK) function. This code shows how to create build results for a deployable archive equivalence test. 

dir = "C:\Users\jdoe\productionServerArchiveBuilds";
sig = "makesquareSignatures.json";
opts = compiler.build.ProductionServerArchiveOptions("makesquare.m", ...
    FunctionSignatures=sig,OutputDir=dir);
buildResults = compiler.build.productionServerArchive(opts);
save("makesquareBuild.mat","buildResults")
You can use the Production Server Compiler (MATLAB Compiler SDK) to create the JSON file. For more information, see Create Deployable Archive for MATLAB Production Server (MATLAB Compiler SDK). Alternatively, you can manually author the JSON file. For more information, see MATLAB Function Signatures in JSON (MATLAB Production Server).

This equivalence test loads the MATLAB file that contains the Python build results and executes and verifies the results for the given input.

classdef tDeployment < matlabtest.compiler.TestCase
    methods (Test)
        function existingPythonEquivalence(testCase)
            loadedData = load("pythonBuild.mat");
            buildResults = loadedData.buildResults;

            executionResults = execute(testCase,buildResults,{5});
            verifyExecutionMatchesMATLAB(testCase,executionResults);
        end
    end
end

Tip

Testing existing deployed code artifacts can save time during testing because testing existing artifacts eliminates the need to build the artifact when you run the test. However, the deployed code artifact used in the test might not have the latest changes from the MATLAB source code.

Run Tests and View Results

You can run equivalence tests by using the:

For more information, see Run MATLAB Tests.

Note

You cannot run deployed code artifact equivalence tests in parallel.

See Also

Classes

Functions

Related Topics