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"] }, "ExampleTagClassTest::testG": { "source": { "col_start": 17, "filename": "ExampleTagClassTest.m", "line": 11 }, "tags": ["FeatureB", "FeatureC", "System"] }, "ExampleTagClassTest::testH": { "source": { "col_start": 17, "filename": "ExampleTagClassTest.m", "line": 16 }, "tags": ["FeatureA", "FeatureB", "System"] } }
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 } } ], "FeatureB": [ { "name": "ExampleTagClassTest::testF", "source": { "col_start": 17, "filename": "ExampleTagClassTest.m", "line": 6 } },(The rest is omitted because it's just more of the same...)
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.
Right now there is now way to trace code, as TestTags can only
apply to tests. I have a pragma planned to embedd tags into
code as well.