MISS_HIT includes a simple tool
(mh_trace), that can be used to
extract tracing tags for code and tests. The output is json and
is intended to be used by other tools.
User manual
Introduction
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.
Annotating code
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.
Excluding code
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.
Command-line interface
--json FILE
By default we produce a file
called mh_trace.json. With this option you can change
the filename.
--by-tag
Produce tracing by-tag, instead of by-file (the default).
Limitations
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.