Getting Started

Getting started with CTM

On this page you can find some simple examples, which should give you a quick start into CTM.
If you want to deepen your CTM knowledge, please see our CTM Guidebook on more configuration options.

Example conditions

In all given examples below we use GitHub issues to define our product requirements:
See our CTM Guidebook which other tools are supported by CTM
❗ All CTM command line calls are given here as ctm <arguments>.
In case you used go get github.com/SAP/quality-continuous-traceability-monitor to obtain your CTM instance, please use quality-continuous-traceability-monitor <arguments> to execute CTM.
Mac and Linux: You could also create a symbolic link as ctm to quality-continuous-traceability-monitor to call CTM by it's abbreviation (ln -s $GOPATH/bin/quality-continuous-traceability-monitor $GOPATH/bin/ctm).

Code annotated requirement mapping

The product's source code is written in Java. Each automated test, that safeguards a product requirement, gets a specific comment which assigns the test to the corresponding product requirement.
```
...
  /** 
   * Overwhelming complex test, which covers my
   * product requirement #1
   */
  // Trace(GitHub:doergn/sourcecodeRepo#1)
  public void testApp() {
      assertTrue(true);
  }
...
```
Note the // Trace(GitHub:doergn/sourcecodeRepo#1) comment which assign this test to product requirement #1

CTM requires a configuration file to run. So we create a text file called myCTMconfig.json with the following content:

{
  "github": {
    "base_url": "https://github.com"
  },
  "workDir": "/tmp/CTM/workdir",
  "outputDir": "/tmp/CTM/reports",
  "log": {
    "level": "INFO"
  },
  "sourcecode": [{
    "local": "/home/doergn/sourcecodeRepo",
    "language": "java"
  }],
  "testReport": [{
    "type": "xunit-xml",
    "local": "/home/doergn/sourcecodeRepo/target/surefire-reports"
  }]
}

Note the sourcecode element which points to the local source code folder. The element testReport points to the local test result report.
Details on the other configuration elements can be found in the CTM Guidebook.

Execute CTM with the just created config file: ctm -c myCTMconfig.json which should generate an output like:

I0817 10:20:56.924698    7759 performance.go:13] Parse java sourcecode (/home/doergn/sourcecodeRepo) took 1.029272ms
I0817 10:20:56.924872    7759 xunit.go:127] Parsing /home/doergn/sourcecodeRepo/target/surefire-reports/TEST-com.mycorp.AppTest.xml
I0817 10:20:56.925226    7759 performance.go:13] Scan xunit XML test reports took 372.21µs
I0817 10:20:56.925253    7759 performance.go:13] Create Traces took 1.251µs
I0817 10:20:56.925312    7759 performance.go:13] Create HTML and JSON reports took 51.785µs

According to the output, CTM started parsing the java sourcecode in /home/doergn/sourcecodeRepo for traceability annotated tests which took it 1.029272ms
Second line shows it started parsing the xunit-xml test report /home/doergn/sourcecodeRepo/target/surefire- reports/TEST-com.mycorp.AppTest.xml as it was obviously the only xunit-xml test result it found in the configured path /home/doergn/sourcecodeRepo/target/surefire-reports (see testReport configuration above)

With the collected data, CTM generated the overall traceability report (json and html) and wrote it into the given outputDir:

/tmp/CTM/reports/ctm_report_all.json

{
  "doergn/sourcecodeRepo#1": {
    "link": "https://github.com/doergn/sourcecodeRepo/issues/1",
    "test_cases": [
    {
        "test_fullname": "com.mycorp.AppTest.testApp",
        "test_name": "testApp",
        "test_class": "com.mycorp.AppTest",
        "passed": true,
        "skipped": false
     }]
  }
}

/tmp/CTM/reports/ctm_report_all.html

You could further improve the generated overall traceability report, by adding the GitHub repository to the sourcecode element:

{
  "github": {
    "base_url": "https://github.com"
  },
  "workDir": "/tmp/CTM/workdir",
  "outputDir": "/tmp/CTM/reports",
  "log": {
    "level": "INFO"
  },
  "sourcecode": [{
    "local": "/home/doergn/sourcecodeRepo",
    "git": {
      "organization": "doergn",
      "repository": "sourcecodeRepo",
      "branch": "master"
    },
    "language": "java"
  }],
  "testReport": [{
    "type": "xunit-xml",
    "local": "/home/doergn/sourcecodeRepo/target/surefire-reports"
  }]
}

The generated overall traceability report will now also contain a link to the corresponding source code in the GitHub repository:

/tmp/CTM/reports/ctm_report_all.json

{
  "doergn/sourcecodeRepo#1": {
    "link": "https://github.com/doergn/sourcecodeRepo/issues/1",
    "test_cases": [
      {
        "test_fullname": "com.mycorp.AppTest.testApp",
        "test_name": "testApp",
        "test_class": "com.mycorp.AppTest",
        "test_source": "https://github.com/doergn/sourcecodeRepo/blob/master/src/test/java/com/mycorp/AppTest.java",
        "passed": true,
        "skipped": false
      }]
    }
}

/tmp/CTM/reports/ctm_report_all.html

Requirement mapping file

What if the product's source code is not written in any of the supported languages? Also some teams don't want/can't add comments to their automated tests. In this case you can pass a requirement mapping file to CTM. The requirement mapping file is a json file which maintains the relations between product requirement and automated test.

Let's create a requirement mapping file and save it as r_mapping.json. The content of the file would be:
```
[
  {
    "source_reference": "com.mycorp.AppTest.testApp()",
    "github_keys": [
      "doergn/sourcecodeRepo#1"
    ]
  }
]
```
Note the brackets () after com.mycorp.AppTest.testApp which indicates testApp is a method/function.

The corresponding CTM configuration file (which we save as myCTMconfig.json) will have the following content:

{
  "github": {
      "base_url": "https://github.com"
  },
  "workDir": "/tmp/CTM/workdir",
  "outputDir": "/tmp/CTM/reports",
  "log": {
      "level": "INFO"
  },
  "mapping": {
      "local": "/tmp/CTM/r_mapping.json"
  },
  "testReport": [{
      "type": "xunit-xml",
      "local": "/home/doergn/sourcecodeRepo/target/surefire-reports"
   }]
}

Note the mapping element, which replaces the sourcecode element from example Code annotated requirement mapping.

Execute CTM with the config file: ctm -c myCTMconfig.json which should generate an output like:

I0817 14:25:19.260275   10311 performance.go:13] Read mapping file took 38.735µs
I0817 14:25:19.260465   10311 xunit.go:127] Parsing /home/dirk/git/sourcecodeRepo/target/surefire-reports/TEST-    com.mycorp.AppTest.xml
I0817 14:25:19.260947   10311 performance.go:13] Scan xunit XML test reports took 509.375µs
I0817 14:25:19.260974   10311 performance.go:13] Create Traces took 1.688µs
I0817 14:25:19.261068   10311 performance.go:13] Create HTML and JSON reports took 87.454µs

As no source code needs to be parsed (the mapping between product requirement and automated test is now in the r_mapping.json file), CTM started right away with parsing the xunit-xml test report /home/doergn/sourcecodeRepo/target/surefire-reports/TEST-com.mycorp.AppTest.xml

The last two log entries Create Traces and Create HTML and JSON reports indicate CTM wrote the overall traceability report (json and html) into the given outputDir:

/tmp/CTM/reports/ctm_report_all.json

{
  "doergn/sourcecodeRepo#1": {
    "link": "https://github.com/doergn/sourcecodeRepo/issues/1",
    "test_cases": [
    {
        "test_fullname": "com.mycorp.AppTest.testApp",
        "test_name": "testApp",
        "test_class": "com.mycorp.AppTest",
        "passed": true,
        "skipped": false
     }]
  }
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Getting Started

Getting started with CTM

Example conditions

Code annotated requirement mapping

Requirement mapping file

Using multiple source code repositories

Using the traceability repository

Adding traceability repository links to requirements

Using CTM to document a certain release

Uh oh!

Uh oh!

Uh oh!

Quick-Navigation

Getting Started

CTM Guidebook

Clone this wiki locally