coder.runTest

Run test replacing calls to MATLAB functions with calls to MEX functions

Syntax

coder.runTest(test,fcn)

coder.runTest(test,fcns,mexfcn)

coder.runTest(test,mexfile)

Description

coder.runTest(test,fcn) runs test replacing calls to fcn with calls to the compiled version of fcn. test is the file name for a MATLAB^® function, script, or class-based unit test that calls the MATLAB function fcn. The compiled version of fcn must be in a MEX function that has the default name. The default name is the name specified by fcn followed by _mex.

coder.runTest(test,fcns,mexfcn) replaces calls to the specified MATLAB functions with calls to the compiled versions of the functions. The MEX function mexfcn must contain the compiled versions of all of the specified MATLAB functions.

coder.runTest(test,mexfile) replaces a call to a MATLAB function with a call to the compiled version of the function when the compiled version of the function is in mexfile. mexfile includes the platform-specific file extension. If mexfile does not contain the compiled version of a function, coder.runTest runs the original MATLAB function. If you do not want to specify the individual MATLAB functions to replace, use this syntax.

Examples

Run Test File Replacing One Function

Use coder.runTest to run a test file. Specify replacement of one MATLAB function with the compiled version. You do not provide the name of the MEX function that contains the compiled version. Therefore, coder.runTest looks for a MEX function that has the default name.

In a local, writable folder, create a MATLAB function, myfun.

function y = myfun(u,v) %#codegen
y = u+v;
end

In the same folder, create a test function, mytest1, that calls myfun.

function mytest1
c = myfun(10,20);
disp(c);
end

Run the test function in MATLAB.

mytest1

    30

Generate a MEX function for myfun.

codegen myfun -args {0,0}

In the current folder, codegen generates a MEX function that has the default name, myfun_mex.

Run coder.runTest. Specify that you want to run the test file mytest1. Specify replacement of myfun with the compiled version in myfun_mex.

coder.runTest('mytest1','myfun')

    30

The results are the same as when you run mytest1 at the MATLAB command line.

Replace Multiple Functions That You Specify

Use coder.runTest to run a test file. Specify replacement of two functions with calls to the compiled versions. Specify the MEX function that contains the compiled versions of the functions.

In a local writable folder, create a MATLAB function, myfun1.

function y = myfun1(u) %#codegen
y = u;
end

In the same folder, create another MATLAB function, myfun2.

function y = myfun2(u, v) %#codegen
y = u + v;
end

In the same folder, create a test function that calls myfun1 and myfun2.

function mytest2
c1 = myfun1(10);
disp(c1)
c2 = myfun2(10,20);
disp(c2)
end

Run the test function.

mytest2

    10

    30

Generate a MEX function for myfun1 and myfun2. Use the -o option to specify the name of the generated MEX function.

codegen -o mymex  myfun1 -args {0} myfun2 -args {0,0}

Run coder.runTest. Specify that you want to run mytest2. Specify that you want to replace the calls to myfun1 and myfun2 with calls to the compiled versions in the MEX function mymex.

coder.runTest('mytest2',{'myfun1','myfun2'},'mymex')

    10

    30

The results are the same as when you run mytest2 at the MATLAB command line.

Replace Functions That Have Compiled Versions in Specified MEX File

Use coder.runTest to run a test that replaces calls to MATLAB functions in the test with calls to the compiled versions. Specify the file name for the MEX function that contains the compiled versions of the functions.

In a local writable folder, create a MATLAB function, myfun1.

function y = myfun1(u) %#codegen
y = u;
end

In the same folder, create another MATLAB function, myfun2.

function y = myfun2(u, v) %#codegen
y = u + v;
end

In the same folder, create a test function that calls myfun1 and myfun2.

function  mytest2
c1 = myfun1(10);
disp(c1)
c2 = myfun2(10,20);
disp(c2)
end

Run the test.

mytest2

    10

    30

Generate a MEX function for myfun1 and myfun2. Use the -o option to specify the name of the generated MEX function.

codegen -o mymex  myfun1 -args {0} myfun2 -args {0,0}

Run coder.runTest. Specify that you want to run mytest2. Specify that you want to replace calls to functions called by mytest2 with calls to the compiled versions in mymex. Specify the complete MEX file name including the platform-specific extension. Use mexext to get the platform-specific extension.

coder.runTest('mytest2',['mymex.', mexext])

    10

    30

The results are the same as when you run mytest2 at the MATLAB command line.

Run Class-Based Unit Test

Run coder.runTest with a class-based unit test.

Write the function addOne, which adds 1 to the input.

function y = addOne(x)
%#codegen
y = x + 1;
end

Write a classed-based unit test that verifies the value returned by addOne when the input is 1 and when the input is pi.

classdef TestAddOne < matlab.unittest.TestCase
    
    methods (Test)
        
        function reallyAddsOne(testCase)
            x = 1;
            y = addOne(x);
            testCase.verifyEqual(y,2);
        end
        
        function addsFraction(testCase)
            x = pi;
            y = addOne(x);
            testCase.verifyEqual(y,x+1);
        end
    end
end

Run the class-based unit test, replacing calls to addOne with calls to addOne_mex.

coder.runTest('TestAddOne', 'addOne')

Running TestAddOne
..
Done TestAddOne
__________


testbenchResult = 

  1×2 TestResult array with properties:

    Name
    Passed
    Failed
    Incomplete
    Duration
    Details

Totals:
   2 Passed, 0 Failed, 0 Incomplete.
   0.28516 seconds testing time.

Input Arguments

test — File name for test function, script, or class-based unit test

character vector | string scalar

File name for MATLAB function, script, or class-based unit test that calls the MATLAB functions for which you want to test the generated MEX. coder.runTest replaces the calls to the functions with calls to the generated MEX.

Example: 'mytest'

fcn — Name of MATLAB function to replace

character vector | string scalar

Name of MATLAB function to replace when running test. coder.runTest replaces calls to this function with calls to the compiled version of this function. fcn cannot be a function in a namespace.

Example: 'myfun'

fcns — Names of MATLAB functions to replace

character vector | string scalar | cell array of character vectors | array of strings

Names of MATLAB functions to replace when running test. coder.runTest replaces calls to these functions with calls to the compiled versions of these functions. fcns cannot be functions in namespaces.

Specify one function as a character vector or a string scalar.

Example: 'myfun'

Example: "myfun"

Specify multiple functions as a cell array of character vectors or an array of strings. Before using coder.runTest, compile these functions into a single MEX function.

Example: {'myfun1','myfun2','myfun3'}

Example: ["myfun1","myfun2"]

mexfcn — MEX function name

character vector | string scalar

Name of a MEX function generated for one or more functions.

Generate this MEX function using the MATLAB Coder™ app or the codegen function.

Example: 'mymex'

mexfile — MEX file name with extension

character vector | string scalar

The file name and platform-specific extension of a MEX file for one or more functions. Use mexext to get the platform-specific MEX file extension.

Generate this MEX file using the MATLAB Coder app or the codegen function.

Example: ['myfunmex.',mexext]

Example: ["myfunmex."+mexext]

Tips

• coder.runTest does not return outputs. To see test results, in the test, include code that displays the results.

• To compare MEX and MATLAB function behavior:

  • Run the test in MATLAB.

  • Use codegen to generate a MEX function.

  • Use coder.runTest to run the test replacing the call to the original function with a call to the compiled version in the MEX function.

• Before using coder.runTest to test multiple functions, compile the MATLAB functions into a single MEX function.

• If you use the syntax coder.runTest(test, mexfile), use mexext to get the platform-specific MEX file name extension. For example:

  coder.runTest('my_test', ['mymexfun.', mexext])

• If errors occur during the test, you can debug the code using call stack information.

• You can combine MEX generation and testing in one step by running codegen with the -test option. For example, the following code generates a MEX function for myfunction and calls the test file myfunction_test, replacing calls to myfunction with calls to myfunction_mex.

  codegen myfunction -test myfunction_test 

Version History

Introduced in R2012a