Unit Test External C Code with MATLAB Coder - MATLAB & Simulink (original) (raw)

This example shows how to test external C code by using MATLAB® unit tests with MATLAB® Coder™.

If you want to test C code, you can use MATLAB Coder to bring the code into MATLAB. You can then write unit tests by using the MATLAB testing framework. You can write richer, more flexible tests by taking advantage of the advanced numerical computing and visualization capabilities of MATLAB.

This example shows how to:

  1. Bring your C code into MATLAB as a MEX function that you generate with MATLAB Coder.
  2. Write a unit test by using the MATLAB testing framework.
  3. Run the test on the MEX function.

If you have Embedded Coder®, you can run unit tests on generated standalone code by using the unit tests with software-in-the-loop (SIL) execution or processor-in-the-loop (PIL) execution.

Example Background

This example uses a Kalman filter to demonstrate how to run unit tests using MATLAB Coder. In this example, the tests determine whether the trajectory of an object and its Kalman estimate are within a specified tolerance.

visualization.png

This example uses these files:

The unit tests in TestKalmanFilter.m are class-based unit tests. For more information, see Class-Based Unit Tests.

Although you want to test the MEX function, the unit tests in TestKalmanFilter call the original MATLAB function from which you generated the MEX function. When MATLAB Coder runs the tests, it replaces the calls to the MATLAB function with calls to the MEX function. You cannot run these tests directly in MATLAB because MATLAB does not recognize the coder.ceval calls in callKalmanFilter.

Run Unit Tests by Using the MATLAB Coder App

Generate Code

To open the MATLAB Coder app, on the MATLAB Toolstrip Apps tab, under Code Generation, click the MATLAB Coder app icon.

Configure the app to generate MEX code for the function callKalmanFilter by following these steps:

  1. Open the Entry Pointspane by clicking the Entry Pointsbutton in the MATLAB Coder toolstrip.
  2. Type or select callKalmanFilter as an entry point function.
  3. Expand the function signature and specify that the input argument 2 is a 2-by-310 array of doubles.
  4. In the MATLAB Coder toolstrip, select Build Type > MEX.

configure_mex.png

The unit tests load the variable position from position.mat and pass position to callKalmanFilter. Therefore, the input to callKalmanFilter must have the properties that position has. In the MATLAB workspace, if you load position.mat, you see that position is a 2-by-310 array of doubles.

Because the callKalmanFilter function integrates external C code, you must specify the C source and header files by following these steps:

  1. Click Settings to open the MEX Code Generation Settings dialog box.
  2. On the Custom Code configuration pane, on the Header file tab, enter #include "kalmanfilter.h".
  3. On the Custom Code configuration pane. in the Additional source files box, enter kalmanfilter.c.

configuration_dialog.png

To generate a MEX function, on the MATLAB Coder toolstrip, click the Generate Code and Build button.

generate_mex.png

Run Unit Tests on MEX Function

To run units tests on the MEX function, expand the Verify Using MEX button in the MATLAB Coder toolstrip. Make sure that Use Generated Code is selected. Click Run File: Select MATLAB file to run ... and select the test file run_unit_tests_kalman.m.

verify_using_mex.png

When the app runs the test file, it replaces calls to callKalmanFilter in the unit test with calls to callKalmanFilter_mex. The unit tests run on the MEX function instead of the original MATLAB function. The app displays the test output in the Command Window. The unit tests pass because the error does not exceed the tolerance specified in run_unit_tests_kalman.m.

To see what happens when the the the unit tests fail, decrease the tolerances in the test file run_unit_tests_kalman.m. Then, click the Verify Using MEX button in the MATLAB Coder toolstrip.

Run Unit Tests at the Command Line

You can use the command-line workflow to run unit tests on external C code by using the coder.runTest function with the test file that runs the unit tests.

Generate Code

Because the callKalmanFilter function integrates external C code, you must create a MEX configuration object and specify the C source and header files.

cfg = coder.config('mex'); cfg.CustomSource = 'kalmanfilter.c'; cfg.CustomHeaderCode = '#include "kalmanfilter.h"';

Generate a MEX function using the codegen function. Specify that the input to callKalmanFilter is a 2-by-310 array of doubles by using the coder.typeof function..

codegen -config cfg -args {coder.typeof(0,[2 310])} callKalmanFilter

Code generation successful.

Run Unit Tests on the MEX Function

Run the units tests on the MEX function by using the coder.runTest function. Specify that the test file is run_unit_tests_kalman and that the function is callKalmanfilter. When coder.runTest runs the test file, it replaces calls to callKalmanFilter in the unit test with calls to callKalmanFilter_mex. The unit tests run on the MEX function instead of the original MATLAB function.

coder.runTest("run_unit_tests_kalman","callKalmanFilter")

ans = 1×2 TestResult array with properties:

Name
Passed
Failed
Incomplete
Duration
Details

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

See Also

coder.runTest

Topics