Prerequisites

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

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

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

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.

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

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

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

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")

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")

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

Run Tests and View Results

You can run equivalence tests by using the:

For more information, see Run MATLAB Tests.