Add --export-json flag. #347

docs/about.rst

@@ -48,6 +48,7 @@ Main Features
 -  :doc:`Logging framework <./logging/user_guide>` supporting display and file output, different log
    levels, visibility settings of levels and design hierarchy, output formatting
    and multiple loggers. Supports machine readable output formats that for example can be read by a spreadsheet.
+-  Requirements trace-ability through :ref:`JSON Export <json_export>` and :ref:`test attributes <attributes>`.
 -  Optional location preprocessor that traces log and check calls back to file
    and line number.
 -  Outputs JUnit report files for better `Jenkins`_ :ref:`integration <continuous_integration>`.

docs/cli.rst

@@ -273,3 +273,81 @@ Further info:
    * `Announcing Docker Enterprise Edition <https://blog.docker.com/2017/03/docker-enterprise-edition/>`_
    * `Introducing Moby Project: a new open-source project to advance the software containerization movement <https://blog.docker.com/2017/04/introducing-the-moby-project/>`_
 * If you don't want or cannot install docker, you can still use it online. `Play with Docker <https://play-with-docker.com>`_ (PWD) *"is a Docker playground which allows users to run Docker commands in a matter of seconds. It gives the experience of having a free Alpine Linux Virtual Machine in browser, where you can build and run Docker containers and even create clusters"*.
+
+
+.. _json_export:
+
+JSON Export
+-----------
+VUnit supports exporting project information through the ``--export-json`` command
+line argument. A JSON file is written containing the list of all files
+added to the project as well as a list of all tests. Each test has a
+mapping to its source code location.
+
+The feature can be used for IDE-integration where the IDE can know the
+path to all files, the library mapping of files and the source code
+location of all tests.
+
+The JSON export file has three top level values:
+
+  - ``export_format_version``: The `semantic <https://semver.org/>`_ version of the format
+  - ``files``: List of project files. Each file item has ``file_name`` and ``library_name``.
+  - ``tests``: List of tests. Each test has ``location``
+    information. The ``location`` contains the file name as well as
+    the offset and length in characters of the symbol that defines the
+    test.
+
+.. code-block:: json
+   :caption: Example JSON export file (file names are always absolute but the example has been simplified)
+
+   {
+       "export_format_version": {
+           "major": 1,
+           "minor": 0,
+           "patch": 0
+       },
+       "files": [
+           {
+               "library_name": "lib",
+               "file_name": "tb_example_many.vhd"
+           },
+           {
+               "library_name": "lib",
+               "file_name": "tb_example.vhd"
+           }
+       ],
+       "tests": [
+           {
+               "attributes": {},
+               "location": {
+                   "file_name": "tb_example_many.vhd",
+                   "length": 9,
+                   "offset": 556
+               },
+               "name": "lib.tb_example_many.test_pass"
+           },
+           {
+               "attributes": {},
+               "location": {
+                   "file_name": "tb_example_many.vhd",
+                   "length": 9,
+                   "offset": 624
+               },
+               "name": "lib.tb_example_many.test_fail"
+           },
+           {
+               "attributes": {".attr"},
+               "location": {
+                   "file_name": "tb_example.vhd",
+                   "length": 18,
+                   "offset": 465
+               },
+               "name": "lib.tb_example.all"
+           }
+       ]
+   }
+
+
+.. note:: Several tests may map to the same source code location if
+          the user created multiple :ref:`configurations
+          <configurations>` of the same basic tests.

docs/python_interface.rst

@@ -8,6 +8,48 @@ The Python interface of VUnit is exposed through the :class:`VUnit
 
 .. automodule:: vunit.ui
 
+
+.. _attributes:
+
+Attributes
+----------
+The user may set custom attributes on test cases via comments. The
+attributes can for example be used to achieve requirements
+trace-ability. The attributes are exported in the :ref:`JSON Export
+<json_export>`. All user defined attributes must start with a dot
+(``.``) as non-dot attributes are reserved for built-in attributes.
+
+Example
+<<<<<<<
+.. code-block:: vhdl
+   :caption: VHDL Example
+
+   if run("Test 1") then
+       -- vunit: .requirement-117
+   end if;
+
+
+.. code-block:: verilog
+   :caption: SystemVerilog Example
+
+   `TEST_SUITE begin
+       `TEST_CASE("Test 1") begin
+           // vunit: .requirement-117
+        end
+    end
+
+.. code-block:: json
+   :caption: JSON Export has attributes attached to each test. The
+             attributes all have null value to be forward compatible a future
+             where user attributes can have values.
+
+    {
+       "attributes": {
+            ".requirement-117": null
+       }
+    }
+
+
 .. _pre_and_post_hooks:
 
 Pre and post simulation hooks

vunit/test/common.py

@@ -146,13 +146,17 @@ def new_function(*args, **kwargs):
 
 def get_vhdl_test_bench(test_bench_name,
                         tests=None,
-                        same_sim=False):
+                        same_sim=False,
+                        test_attributes=None):
     """
     Create a valid VUnit test bench
 
     returns a string
     """
 
+    if test_attributes is None:
+        test_attributes = {}
+
     tests_contents = ""
     if tests is None:
         pass
@@ -167,6 +171,10 @@ def get_vhdl_test_bench(test_bench_name,
 
             tests_contents += 'run("%s") then\n' % test_name
 
+            if test_name in test_attributes:
+                for attr_name in test_attributes[test_name]:
+                    tests_contents += "-- vunit: %s\n" % attr_name
+
             if idx == last_idx:
                 tests_contents += '    endif;\n'
 
@@ -201,11 +209,13 @@ def get_vhdl_test_bench(test_bench_name,
 def create_vhdl_test_bench_file(test_bench_name,
                                 file_name,
                                 tests=None,
-                                same_sim=False):
+                                same_sim=False,
+                                test_attributes=None):
     """
     Create a valid VUnit test bench and writes it to file_name
     """
     with open(file_name, "w") as fptr:
         fptr.write(get_vhdl_test_bench(test_bench_name=test_bench_name,
                                        tests=tests,
-                                       same_sim=same_sim))
+                                       same_sim=same_sim,
+                                       test_attributes=test_attributes))