Main Content

Requirements Traceability for MATLAB Code

You can associate requirements with MATLAB® code and plain-text external code, such as C code, by creating selection-based links with the Requirements Editor or by creating links programmatically at the MATLAB command line. You can also create links to MATLAB code in MATLAB Function (Simulink) blocks. You can verify requirements with MATLAB code by creating links to MATLAB unit tests and running the tests. You can then view and edit links to code in the MATLAB Editor or Requirements Editor.

Create Links to MATLAB Code or Plain-Text External Code

You can create links to MATLAB code or plain-text external code programmatically or by using the Requirements Editor.

When you create links to code, Requirements Toolbox™ creates slreq.TextRange objects that correspond to the selected lines. These slreq.TextRange objects are referred to as line ranges.

To create links programmatically, create the slreq.TextRange object, then use the object as a link source when you create the link. When you create multiple slreq.TextRange objects in the same MATLAB code file or plain-text external code file, the line numbers for the slreq.TextRange objects cannot overlap.

Create Links by Using the Requirements Editor

To create selection-based links to code by using the Requirements Editor:

  1. In the MATLAB Editor, open the MATLAB code file or plain-text external code file.

    Note

    You cannot create links to MATLAB code in MLX files.

  2. Select the lines of code that you want to link.

  3. In the Requirements Editor, load the requirement set that you want to link.

  4. Select the requirement to link.

  5. In the Links section, click Add Link > Link from Selection in MATLAB Editor.

    Alternatively, in the MATLAB Editor, right-click the selected code range and select Requirements > Link to Selection in Requirements Browser.

Create Links Programmatically

Suppose that you want to programmatically create links to a MATLAB function called myAdd.

function y = myAdd(u,v)
y = u + v;
end
You want to link the function to these requirements:

Requirements for the myAdd function, including requirements for the inputs, outputs, and function behavior.

To create links at the MATLAB command line:

  1. Use slreq.createTextRange to create an slreq.TextRange object that represents the lines of code that you want to link to.

    lr = slreq.createTextRange("myAdd.m",2);

  2. Use slreq.find, find, or slreq.getCurrentObject to get a handle to the requirement that you want to link.

    req = slreq.find(Type="Requirement",Summary="Add u and v");

  3. Use slreq.createLink to create the link.

    myLink = slreq.createLink(lr,req);

Create Links to MATLAB Function Blocks

Use the MATLAB Function Block Editor (Simulink) to create links to lines of code in MATLAB Function blocks:

  1. In the Requirements Editor, load the requirement set that you want to link to.

  2. Select the requirement to link.

  3. In the Simulink® model, open the MATLAB Function block.

  4. Select the lines of code that you want to link.

  5. Right-click the selected code range and select Requirements > Link to Selection in Requirements Browser.

Note

Requirements linked to MATLAB code lines inside a MATLAB Function block appear in HTML requirements traceability reports, but do not appear the Simulink Report Generator™ Web View. See Create and Use Web Views of Models (Simulink Report Generator).

Create Links to Requirements in External Documents

To create links from MATLAB code to requirements in external documents:

  1. Select a requirement in one of these external documents:

    • Microsoft® Word

    • Microsoft Excel®

    • IBM®Rational®DOORS®

    • IBM DOORS Next

  2. In the MATLAB Editor, open the MATLAB code file or plain-text external code file.

    Note

    You cannot create links to MATLAB code in MLX files.

  3. Select the lines of code that you want to link.

  4. Right-click the selected code range and select Requirements. Depending on the type of your requirements document, select one of these options:

    • Link to Selection in Word

    • Link to Selection in Excel

    • Link to Selection in DOORS

    • Link to Selected Item(s) in DOORS Next

For more information about configuring Requirements Toolbox to work with these third-party products, see Configure Requirements Toolbox for Interaction with Microsoft Office and IBM DOORS and Configure IBM DOORS Next Session.

Verify Requirements with MATLAB Tests

You can verify requirements with MATLAB code by creating links to class-based and function-based tests, then running the tests.

When you create a link from a requirement to a MATLAB unit test, Requirements Toolbox sets the link type to Verify, which enables the software to verify the requirement. For more information, see Review Requirements Verification Status.

To verify the requirement, run the test at the MATLAB command line or by using the Requirements Editor. To view the verification status in the Requirements Editor, select Columns > Verification Status.

Run Tests by Using the Requirements Editor

To run MATLAB unit tests for a requirement set, for a parent requirement and all of its descendants, or for a single requirement by using the Requirements Editor:

  1. In the Requirements Editor, right-click a requirement set, a parent requirement, or a child requirement that has links to tests and select Run Tests.

  2. In the Run Tests dialog box, confirm that you want to run the linked tests. To omit tests from the run, clear the selection.

    Run Tests dialog box for a requirement set with 2 linked tests.

  3. Click Run Tests.

The verification status of the requirements updates after you run the tests.

Requirements Editor showing 2 verified requirements.

Run Tests at the MATLAB Command Line

Supposed that you want to verify the requirements in the ShortestPath project by running MATLAB tests programmatically.

To run tests linked to a requirement set programmatically:

  1. Open the ShortestPath project.

    slreqShortestPathProjectStart

  2. Load the shortest_path_tests_reqs requirement set and open it in the Requirements Editor.

    rs = slreq.open("shortest_path_tests_reqs");

  3. Run the tests that are linked to the requirement set by using slreq.ReqSet.runTests.

    results = runTests(rs);

  4. View the verification status in the Requirements Editor. Alternatively, view the verification status at the command line by using getVerificationStatus.

    status = getVerificationStatus(rs)
    status = 
             total: 14
            passed: 13
            failed: 0
        unexecuted: 0
         justified: 0
              none: 1
    

View and Edit Links and Linked Line Ranges

You can view linked code ranges in the MATLAB Editor by enabling requirements highlighting. Right-click in the MATLAB Editor and select Requirements > Enable Requirements Highlighting.

To edit links, use the Requirements Editor. For more information, see View and Edit Links.

You can also edit the starting and ending lines for a linked line range in the MATLAB Editor or at the MATLAB command line.

Edit Linked Line Ranges in the MATLAB Editor

To edit the line numbers for a linked line range in the MATLAB Editor:

  1. Right-click a highlighted line range and select Adjust line range.

  2. In the Adjust range dialog box, use the + and - buttons to change the first and last lines of the line range. Alternatively, enter the line number in the field.

    Adjust range dialog box showing lines 1 and 2 as the first and last lines for the line range.

  3. Click OK. The MATLAB Editor updates the highlighting.

Edit Linked Line Ranges Programmatically

To edit the lines for an slreq.TextRange object at the MATLAB command line:

  1. Open the MATLAB code file or plain-text external code file in the MATLAB Editor.

    open("myAdd.m");

  2. Get the existing slreq.TextRange object in the MATLAB code file by passing the file name and the line numbers for the start and end of the line range to the slreq.getTextRange function.

    lr = slreq.getTextRange("myAdd.m",[1 2]);

  3. Modify the line range by using setLineRange.

    setLineRange(lr,1);

  4. The MATLAB Editor updates the code range highlighting. Alternatively, you can confirm the changes by using show, getText, or getLineRange.

Save Links

To save the changes to a link set when you create or edit links to lines of MATLAB code or external code, use one of these approaches:

  • In the MATLAB Editor, right-click and select Requirements > Save Links.

  • In the Requirements Editor, click Show Links. Select the link set, and click Save.

  • At the MATLAB command line, use save.

Delete Links and Unused Line Ranges

You can delete links to MATLAB code in the MATLAB Editor, the Requirements Editor, or at the MATLAB command line.

If you delete links to code ranges in the MATLAB Editor, you can delete the unused line ranges in the MATLAB Editor or at the MATLAB command line.

Delete Links

To delete links in the MATLAB Editor, right-click a highlighted code range and select Requirements > Delete All Links. This deletes all incoming and outgoing links to this code range.

To delete links from the Requirements Editor, see Delete Links and Link Sets.

To delete links at the MATLAB command line, get a handle to an slreq.Link object and use remove. Alternatively, ensure that the file containing the code range is open in the MATLAB Editor, then get an slreq.TextRange object by using slreq.getTextRange. Delete the links to the object by using deleteLinks.

Delete Unused Line Ranges

To delete unused line ranges in the MATLAB Editor, right-click the line containing the line range and select Requirements > Delete line range.

Note

If a line range does not have outgoing links, the MATLAB Editor does not highlight the code line. Note the line number before you delete the link so that you can delete the unused line range. Alternatively, you can use the MATLAB command line to get the line ranges in a file and then delete the unused line ranges.

To delete line ranges at the command line, ensure that the file containing the code range is open in the MATLAB Editor, then get an slreq.TextRange object by using slreq.getTextRange. Delete the code range by using remove.

See Also

| |

Related Topics