Teamscale Documentation

Appearance

How to Set Up External Tools & Formats ​

Clang Static Analyzer ​

The Open Source LLVM clang compiler includes a static analyzer that performs dataflow analysis on C/C++ code. Analysis is started using the scan-build script, which wraps the make process. To enable output in plist format (which we require), the option -plist must be passed to the scan-build command. Additionally, you might want to enable additional checkers using the -enable-checker command. To obtain a list of all available checkers, run the following command:

bash
clang -cc1 -analyzer-checker-help

Note that it is sufficient to provide a package/category to the analyzer to enable more checks. A typical invocation of the static analyzer might look like this:

bash
scan-build -plist
-enable-checker alpha
-enable-checker core
-enable-checker cplusplus
-enable-checker deadcode
-enable-checker security
-enable-checker unix
make

To upload analysis results, you should use the external-report service as described in our article on external uploads.

Clang-Tidy ​

While Clang-Tidy is integrated as an internal analysis tool, the Clang-Tidy binaries are generally not shipped with Teamscale. Our docker-image distributions contain the correct clang-tidy version, but distributions based on zip-files do not contain clang-tidy. Instead, you will need to install clang-tidy 15.0.7 on your machine. More details are described here.

Cppcheck ​

While Cppcheck is integrated as an internal analysis tool, the Cppcheck binaries are generally not shipped with Teamscale. Our docker-image distributions contain the correct Cppcheck version, but distributions based on zip-files do not contain Cppcheck. Instead, you will need to install cppcheck-2.7 on your machine.

You will need to have the python 3 on the PATH to execute the MISRA checks of Cppcheck. This is included in our docker-image distributions as well.

More details are described here.

FindBugs and SpotBugs ​

FindBugs is an Open Source bug pattern search tool working on the byte code of Java programs. This means that in order to use FindBugs, you have to first compile the code.

SpotBugs is the successor of FindBugs, which is no longer maintained. Since SpotBugs reports are compatible with the FindBugs report format, they can be uploaded with the same analysis-tool name (FINDBUGS). To upload analysis results, you should use the external-report service as described here.

Flake8 ​

While Flake8 is integrated as an internal analysis tool, Flake8 files are generally not shipped with Teamscale. Our docker-image distributions contain the correct Flake8 version, but distributions based on zip-files do not contain it. Instead, you will need to install Flake8 on your machine.

The required Flake8 and plugin versions are:

  • flake8 6.1.0
    • includes mccabe 0.7.0, pycodestyle 2.11.1, and pyflakes 3.1.0
  • flake8-bugbear 23.11.26

In addition, you will need to have a Python 3 distribution installed with the python3 executable on the PATH to. This is included in our docker-image distributions as well.

JaCoCo ​

JaCoCo is an Open Source code coverage tool for Java. Teamscale allows to upload XML coverage reports produced by JaCoCo. Please refer to our Java test coverage guide for instructions on how to set up JaCoCo for your tests.

To upload JaCoCo coverage data, you should use the external-report service as described here.

Cobertura ​

Cobertura is an Open Source code coverage tool for Java. Teamscale allows to upload XML coverage reports produced by Cobertura. You can generate an XML report with the Cobertura Ant task cobertura-report by setting the parameter format to xml as follows:

xml
<cobertura-report format="xml"
	destdir="${coveragereport.dir}"
	srcdir="${src.dir}" />

For further details on the usage of the Cobertura Ant tasks, please refer to the Cobertura user manual.

To upload Cobertura coverage data, you should use the external-report service as described here.

gcov ​

The tool gcov measures line coverage for C/C++ code compiled with the GCC compiler. To determine the code coverage, the code must be compiled using the switch --coverage. This creates files with the extension gcno during compilation. During execution of the code, the coverage data is stored into files with ending gcda. The program gcov is then used to convert the coverage data into readable files with the extension gcov as follows:

bash
gcov -o <OBJ_DIR> -l -p <SOURCE_FILES>

Here the <OBJ_DIR> is the directory containing the object files. For projects with many subdirectories it should be noted that the parameter must point directly to the directory containing the matching object. The relative path of the source files is not used. The parameters -l and -p are used to ensure that files with the same name but different directories do not collide.

Alternatively, the python script gcovr can be used to execute gcov for complex project layouts. To preserve the gcov files, the parameter --keep must be used. Please note that gcovr does not support merging of coverage files (see gcovr FAQ and this StackOverflow question, which is needed when code is executed in more than one test run. If you have to merge coverage files consider using lcov (also see this StackOverflow question).

To upload coverage results to Teamscale, you should use the external-report service as described here.

ESLint ​

While ESLint binaries are shipped with Teamscale, you will need to install the necessary NodeJS runtime on your machine. You will need to have the NodeJS binaries on the PATH and restart Teamscale before you can enable ESLint for your project.

The bundled ESLint distribution includes:

  • @angular-eslint/eslint-plugin@17.1.1
  • @angular-eslint/eslint-plugin-template@17.1.1
  • @angular-eslint/template-parser@17.1.1
  • @typescript-eslint/eslint-plugin@5.59.9
  • @typescript-eslint/parser@5.59.9
  • eslint@8.42.0
  • eslint-plugin-jsx-a11y@6.8.0
  • eslint-plugin-react@7.32.2
  • eslint-plugin-security@2.1.0
  • typescript@5.1.3

Teamscale comes with an ESLint configuration that defaults to ESLint's default values. You can still provide a custom ESLint config file in the analysis profile to adjust the rule's settings to your needs.

Configuration file security

For security reasons, Teamscale only reads ESLint configuration files from Teamscale's config directory. Additionally, only json, yml and yaml are allowed as valid ESLint configuration file extension by default. To enable JavaScript configuration files (e.g., .eslintrc.js), you can set -Dcom.teamscale.allow-executable-lint-config-file=true in the jvm.properties file.

This is discouraged because it can potentially lead to code execution on the Teamscale server via the configuration file.

TSLint ​

Removed

TSLint support has been removed with Teamscale 8.2. Most of the TSLint checks are available via ESLint now. See the TSLint deprecation blog for an overview of ESLint checks that replace TSLint checks.

abaplint ​

AbapLint binaries (version @abaplint/cli@2.95.33) are now shipped and dedicated to being used with Teamscale.

Teamscale comes with an AbapLint configuration that defaults to AbapLint's default values. You can adjust the rules settings to your needs in the Analysis Profile Edit View.

AbapLint is able to analyze ABAP files according to the version of the ABAP language. As Teamscale communicates with SAP systems, it is now able to lint ABAP files providing the appropriate language version. If you desire to use a different language version, locate its corresponding version type from AbapLint and provide it to the analysis profile using the option ABAPLint language version.

Additionally, you can import an AbapLint configuration file (abaplint.json) in the Analysis Profile View. This creates a new analysis profile that uses the settings from the configuration file.

If you like to use a fixed language version for the newly created analysis profile, you can provide it in the version field of the syntax section in the AbapLint configuration file. Otherwise, the field should be left blank. The value will be parsed into the option ABAPLint language version of the analysis profile.

NodeJS

ABAPLint requires that NodeJS version 16 or higher is deployed on your system and globally available by putting it to the PATH variable.

PC-lint/FlexeLint ​

PC-lint is a static analysis tool for C/C++ that covers a wide range of checks. To import PC-lint analysis results in Teamscale, you need to generate an XML report using the +xml parameter from PC-lint. For details, please refer to the documentation of PC-lint.

The check descriptions in Teamscale are up-to-date with PC-lint version 9.00L (i.e., Teamscale can import and display findings from a report generated by this PC-lint version).

Pylint ​

Pylint is an Open Source code analysis tool for Python working directly on the source code.

The check descriptions in Teamscale are up-to-date with pylint 3.0.3 (i.e., Teamscale can import and display findings from a report generated by this version). To import Pylint analysis results into Teamscale, you need to create the generated report using a special format. This can be achieved by using the following command line call:

bash
pylint --score=no --reports=no --msg-template='line: {line}, messageId: {msg_id}, message: {msg}, absolutePath: {abspath}, messageName: {symbol}' /path/to/python/files > report.json

This command generates a plain text format which can be uploaded to Teamscale, for example with the Teamscale Python client’s upload_report method, manually via the external uploads view for your project or simply using curl via the REST interface. Please ensure to use the above message template without any changes.

Please note that while Pylint is capable of generating a JSON report, this cannot be used for Teamscale as does not contain all information necessary to seamlessly integrate the report into Teamscale.

Parasoft C/C++test ​

The reports from Parasoft C/C++test are fully self-contained. The content and structure, however, depend completely on the configuration of the tool. Hence, before the first import of such a report, the findings need to be made known to Teamscale using the following steps:

  1. Create a new analysis profile (e.g., called CppWithParasoft) with Parasoft C/C++test enabled in the tools section
  2. Call the following service to upload the report and update the analysis profile:
bash
curl -X POST -F report=@parasoft.xml 'http://<teamscale-url>/api/external-findings/descriptions/from-parasoft-report?analysis-profile=CppWithParasoft'
  1. The analysis profile should now be updated with rules and can be adjusted if needed
  2. Create a project with the updated analysis profile

PowerShell Script Analyzer (PSScriptAnalyzer) ​

While the PowerShell Script Analyzer is integrated as an internal analysis tool, its binaries are generally not shipped with Teamscale. Our docker-image distributions contain the correct version of PowerShellScriptAnalyzer, but distributions based on zip-files do not contain the tool. Instead, you will need to install PowerShell and PSScriptAnalyzer version 1.21.0 on your Teamscale server. More details are described here.

XCode Test Coverage ​

Test coverage for XCode projects is recorded in an XCResult bundle in a binary format. Teamscale supports importing the contained line-based test coverage by exporting it in a textual format using the xccov command line tool. For XCode 13.3 and above the coverage can be exported in a textual format using the following command:

bash
xcrun xccov view --archive path/to/some.xcresult

For XCode 13.2 and below the XCode tooling cannot produce a comprehensive report with line coverage information for all files in a project, the following shell script must be used to obtain a coverage report that can be imported into Teamscale:

bash
#!/bin/bash
if [ $# -eq 0 ]
  then
  echo "Please provide path to xccovarchive directory"
  exit 1
fi
archive="$1"

coverage=""
files=$(xcrun xccov view --archive --file-list "$archive")
while read -r file; do
  coverage+="$file"
  coverage+=$'\n'
  coverage+="$(xcrun xccov view --archive "$archive" --file "$file"):"
  coverage+=$'\n'
done <<< "$files"
echo "${coverage}"

In both cases the command will output the coverage report to standard out. You can pipe the output into a file which can then be uploaded via the REST API as described here.

Note that the Teamscale Upload tool provides an easy to use automatic conversion of the XCResult bundle. Any *.xcresult, *.xcresult.tar, *.xcresult.tar.gz or *.xcresult.tgz file can be passed as a report with format XCODE to the tool and it will perform automatic conversion to the right format before upload.

XCode XCTest test execution data ​

Besides coverage, XCTest result files (*.xcresult) also contain test execution data. To import this data to Teamscale, the following command can be used to generate a report in JSON format:

bash
xcrun xcresulttool get --path <xcresult-file> --format json

The generated *.json file should contain an explicit testsRef ID, e.g. 0~pYxLsSwT2harDbBkwHOemYmrig4tejMoZIDzYaRhN1_YDV6VNk01K24YhzwGOQTd5yIr4raTPhFhE3DPlKwG_Q==. This ID should be used in the following script to obtain the final report file:

bash
xcrun xcresulttool get --path <xcresult-file> --format json --id "<id>"

This resulting *.json file can then be uploaded to Teamscale as a XCode JSON test execution report. This can be done analogously to test execution reports as described here.

Mapping of status "Expected Failure"

Currently Teamscale does not support the test execution status "Expected Failure" as a separate status category. The test cases with this outcome are stored as "Successful". The reason is that if a test case fails expectedly, then it behaves as specified.

BullseyeCoverage ​

See our detailed guide on C/C++ test coverage.

SwiftLint ​

SwiftLint is a tool to check Swift code for adherence to style guide and conventions. While SwiftLint is executed directly by Teamscale, the binaries are not shipped with the Teamscale distribution. To enable SwiftLint, you need to install SwiftLint on the Teamscale analysis server and ensure that the swiftlint executable is on the path.