Lobster-cpptest documentation (#116)

Lobster-cpptest documentation has been adopted.

Resolves #57

documentation/manual-lobster_cpptest.md

@@ -0,0 +1,134 @@
+# Tracing to C/C++ tests
+
+## Setup and requirements
+
+You will need a C/C++ file or a directory containing these files.
+* Note: The tool also supports a combination of files and folders.
+
+C/C++ files should have one of these extensions to be evaluated by this tool: `.cpp`, `.cc`, `.c` or `.h`
+
+## Preparing C/C++ test documentation with requirements
+The test functions should be specified with one the following `macros`: 
+        `TEST`,
+        `TEST_P`,
+        `TEST_F`,
+        `TYPED_TEST`,
+        `TYPED_TEST_P`,
+        `TYPED_TEST_SUITE`,
+        `TEST_P_INSTANCE` or
+        `TEST_F_INSTANCE`
+
+In your test you need to also add documentation. For example:
+
+```C++
+/**
+ * @requirement CB-#0815, CB-#0816,
+ * 				CB-#0817
+ * @requirement CB-#0818 CB-#0819
+ * 				CB-#0820
+ */
+TEST(ImplicationTest, BasicTest) {}
+```
+
+* Each test can have multiple test types defined in the documentation part.
+* Test types can be used multiple times in the test documentation and can be written on multiple lines
+
+* These can be simply defined with `/** Test types */` or `/// Test types` format. 
+
+* Test-tags can be separated by commas or spaces.
+
+* Note: The `markers` shall be exactly close to the test functions (without any empty lines)
+
+
+```C++
+/**
+ * @requirement CB-#0815, CB-#0816
+ */
+TEST(ImplicationTest, BasicTest) {}
+```
+
+```C++
+///
+/// @requiredby FOO0::BAR0
+///
+TEST(ImplicationTest, BasicTest) {}
+```
+The regex used for each test-tag is as follows:
+
+@requirement
+: ```r"(CB-#\d+)"```
+: ```r"({provided codebeamer-url in config-file}(?P<number>\d+))"```
+
+@requiredby
+: ```r"(\w*::\w+)"```
+
+@defect
+: ```r"(CB-#\d+)|(OCT-#\d+)"```
+
+
+## Preparing cpptest config-file
+
+You have to provide a config-file which determines which `markers` should be extracted in which output-files.
+The expected `kind` for each output-file should also be specified.
+
+In addition, you have to provide the `codebeamer-url`:
+
+```cpp.config
+{
+	"output": {
+		"unit_tests.lobster" : 
+            {
+                "markers": ["@requirement"],
+                "kind": "req"
+            },
+        "components_tests.lobster" :
+            {
+                "markers": ["@requiredby", "@requirement"],
+                "kind": "imp"
+            }
+	},
+	"codebeamer_url": "https://codebeamer.example.com/test"
+}
+ ```
+
+* Note: If you want to extract the other tests with other `markers`,
+ you can use an empty list as `markers` value. Be aware in this case the tests do not have any references.
+
+```cpp.config
+{
+	"output": {
+		"tests.lobster" : 
+            {
+                "markers": [],
+                "kind": "req"
+            }
+	},
+	"codebeamer_url": "https://codebeamer.example.com/test"
+}
+ ```
+
+
+## Creating lobster files
+
+Run the `lobster_cpptest` tool, pointing it to one or more C/C++ files, or a directory containing one or more C/C++ files. 
+
+For example `lobster_cpptest .` should find all your C/C++ files in the root directory.
+
+You have to also provide a `--config-file` file to configure the behaviour of the tool. 
+A more complete command line might look like:
+
+```sh
+$ lobster-cpptest . --config-file cpp.config
+```
+
+## Example
+
+The LOBSTER unit tests contains a working example:
+
+* Test [test_case.cpp](../test-unit/lobster-cpptest/data/test_case.cpp) containing requirement tags
+
+## Notes & Caveats
+* This tool supports these `markers`: '@requirement', '@requiredby' and '@defect'
+* This tool supports these `kind`: 'req', 'imp' and 'act'
+
+

documentation/manual-lobster_gtest.md

@@ -55,11 +55,11 @@ $ lobster_gtest . --out gtests.lobster
 
 The LOBSTER testsuite contains a working example:
 
-* Bazel [BUILD](../tests/projects/basic/BUILD) file to set up
-* Test [test.cpp](../tests/projects/basic/test.cpp) containing tracing tags
-* Requrements [potato.trlc](../tests/projects/basic/potato.trlc)
+* Bazel [BUILD](../integration-tests/projects/basic/BUILD) file to set up
+* Test [test.cpp](../integration-tests/projects/basic/test.cpp) containing tracing tags
+* Requrements [potato.trlc](../integration-tests/projects/basic/potato.trlc)
   containing tracing the requirements mentioned by the test
-* [Makefile](../tests/projects/basic/Makefile) gluing everything
+* [Makefile](../integration-tests/projects/basic/Makefile) gluing everything
   together
 
 ## Notes & Caveats

documentation/user-manual.md

@@ -56,6 +56,17 @@ void main()
 }
 ```
 
+For C++ tests requirements will be referenced inside the documentation.
+
+The syntax for Codebeamer requirements looks like this:
+
+```C++ TEST
+/**
+ * @requirement CB-#0815 CB-#0816
+ */
+TEST(RequirementTagTest1, RequirementAsComments) {}
+```
+
 A central idea in LOBSTER is to reduce duplication of information, so
 tracing links are *only ever added to artefacts lower in the tracing
 hierarchy*. So in the first example above, we'd add tags to the tests,
@@ -117,6 +128,7 @@ All its final html outputs are to be seen [here](https://github.com/bmw-software
 ### C / C++
 
 * lobster_cpp: DOCUMENTATION TODO
+* [lobster_cpptest](manual-lobster_cpptest.md): for tracing requirements and/or defects from C++ tests.
 * [lobster_gtest](manual-lobster_gtest.md): for tracing tags in
   (executed) googletests.
 

packages/lobster-tool-cpptest/README.md

@@ -6,19 +6,21 @@ and requirements coverage, which is essential for meeting standards
 such as ISO 26262.
 
 This package contains a tool extract tracing tags from ISO C or C++
-source code. This tool is also extracting configurable markers/ test-types 
-from the provided comments in cpp files
+source code. The tracing tags are identified by searching for configurable 
+markers in the comments of the source code.
 
 ## Tools
 
-* `lobster-cpptest`: Extract requirements with dynamic refrences 
-  from comments.
+* `lobster-cpptest`: Extract requirements with specific references 
+  from tests.
 
 ## Usage
 
 This tool supports C/C++ code.
 
-For this you can provide some cpp file with these comments:
+For this you have to provide a C/C++ test documentation with `markers`:
+
+`Markers` can be either `@requirement`, `@requiredby` or `@defect`.
 
 ```cpp
 /**
@@ -29,9 +31,23 @@ For this you can provide some cpp file with these comments:
  */
 TEST(RequirementTagTest1, RequirementsAsMultipleComments) {}
 ```
-You can also provide a config-file which determines which markers 
-should be extracted in which files. In addition you have to provide 
-the codebeamer-url:
+You have to provide a config-file which determines which `markers` should be extracted in which output-files.
+The expected `kind` for each output-file should also be specified.  
+
+* Note: If you want to extract the other tests with other `markers`,
+ you can use an empty list as `markers` value. Be aware in this case the tests do not have any references.
+
+
+```config
+{
+    "markers": [],
+    "kind": "req"
+}
+```
+
+In addition, you have to provide the codebeamer-url:
+
+`Kind` can be either `req`, `imp` or `act`.
 
 ```config
 {
@@ -51,6 +67,8 @@ the codebeamer-url:
 }
  ```
 
+For more information about how to setup cpp and config files take a look at [manual-lobster_cpptest](../../documentation/manual-lobster_cpptest.md)
+
 
 ## Copyright & License information