User manual

Tracing your code and tests to your requirements and specification is a common activity when developing to safety standards (such as ISO 26262 or DO-178C). While you definitely should not be using MATLAB for this, it is not my place to judge; and so we have a tool to support this activity. mh_trace can extract tags put in code and test and generate an easy to parse json file that a different tool can use to generate a traceability report.

The MATLAB language already includes some features (TestTags) to help you annotate tests; consider this example (taken from the MathWorks website):

classdef (TestTags = {'FeatureB'}) ...
        ExampleTagClassTest < matlab.unittest.TestCase
    methods (Test)
        function testF (testCase)
            % test code
        end
    end
    methods (Test, TestTags = {'FeatureC','System'})
        function testG (testCase)
            % test code
        end
    end
    methods (Test, TestTags = {'System','FeatureA'})
        function testH (testCase)
            % test code
        end
    end
end

Running mh_trace will generate a json file (by default mh_trace.json) that shows which tags affect any given function:

{
    "ExampleTagClassTest::testF": {
        "source": {
            "col_start": 17,
            "filename": "ExampleTagClassTest.m",
            "line": 6
        },
        "tags": ["FeatureB"],
        "test": True
    },
    "ExampleTagClassTest::testG": {
        "source": {
            "col_start": 17,
            "filename": "ExampleTagClassTest.m",
            "line": 11
        },
        "tags": ["FeatureB", "FeatureC", "System"],
        "test": True
    },
    "ExampleTagClassTest::testH": {
        "source": {
            "col_start": 17,
            "filename": "ExampleTagClassTest.m",
            "line": 16
        },
        "tags": ["FeatureA", "FeatureB", "System"],
        "test": True
    }
}

You can also generate the tracing information by tag (using the --by-tag option):

{
    "FeatureA": [
        {
            "name": "ExampleTagClassTest::testH",
            "source": {
                "col_start": 17,
                "filename": "ExampleTagClassTest.m",
                "line": 16
            },
            "test": True
        }
    ],
    "FeatureB": [
        {
            "name": "ExampleTagClassTest::testF",
            "source": {
                "col_start": 17,
                "filename": "ExampleTagClassTest.m",
                "line": 6
            },
            "test": True
        },

(The rest is omitted because it's just more of the same...)

If you use project configuration (libraries and entrypoints) then an additional field is present in the json output - "shared" to indicate if this code belongs to a shared library or if it is part of an entry point.

While TestTags can be used to annotate tests, it cannot be used to annotate code. To trace code, MISS_HIT supports a special pragma:

%| pragma Tag("potato-req-1");

You can also give more than one tag in a single Tag pragma:

%| pragma Tag("potato-req-1", "kitten-req-42");

Pragma tag applies to all items scoped logically under the entity that is tagged. For example placing the Tag pragma in a class definition will affect all methods; placing it in a function will also affect all nested functions; and placing it in a compilation unit will affect all functions or methods in that compilation unit.

Note: this pragma can also be used to tag tests. There is no difference between using this pragma and adding a TestTags property to tests.

Most projects have some code for e.g. setting up the workspace or build scripts. This code is not part of the delivery and so should not make it into the requirements traceability report; it can be excluded using the No_Tracing pragma:

%| pragma No_Tracing;

This pragma has identical scoping rules as pragma Tag, and completely removes the affected functions from the json output. If you place it at the top of a file, it excludes all functions in that compilation unit. If a function is affected by both Tags and a No_Tracing pragma then the No_Tracing pragma takes precedence.

By default we produce a file called mh_trace.json. With this option you can change the filename.

Produce tracing by-tag, instead of by-file (the default).

The tool will only extrac tags from the files that MISS_HIT normally processes. So if you have your unit tests excluded from MISS_HIT then you will get no tracing. You could use the common --ignore-config option to work around this; or even better: don't exclude your unit tests.