Frequently Asked Questions (FAQ)
Installation & Setup
What are Teamscale's system requirements?
Please refer to the system requirements page.
Is Teamscale available as docker image?
Yes. Please see our Docker Hub page.
Does the Teamscale server need internet access?
No. Teamscale will only connect to servers you explicitly tell it about (e.g., your source code repositories or issue tracker).
Do I need to change my build for Teamscale's code analysis?
No. As Teamscale connects directly to your version control systems like Git, the code analysis operates independently.
Is it expected that the size of the storage directory grows during a rollback?
Yes, during a rollback, it is possible that larger amounts of temporary data are created. It may take some time until the regular storage cleanup has freed up the disk space again.
You charge for users. What is a user and how do you count them?
The license price is based on the number of Teamscale users. A user is both an active named user logging into the Teamscale UI or using the REST API, and a developer whose code is analyzed by Teamscale (called committer). As active users and committers will typically overlap a lot, we count both separately and use the maximum of both numbers as the user count. Additionally, we only count users or committers that have been active during the last 90 days. So if you had users who tried Teamscale but did not stick with the tool, they will not affect your license cost.
A committer is a developer who has committed any code that is analyzed by Teamscale in the last 90 days. If only parts of your repository are analyzed by Teamscale, e.g.
src/main is analyzed but not
src/prototype, only the commits that contain changes to the analyzed code contribute to the number of committers. Teamscale applies different heuristics to resolve duplicates if developers used multiple names when committing code:
- Different committer names but the same mail address count as one committer
- Name order:
Doe, Janecount as one committer
If a developer used multiple names that cannot be mapped by Teamscale automatically, you can provide aliases to Teamscale. Aliases allow you to map multiple committer names to one Teamscale user. If
Jane Doe also committed as
ID_112347 you can add
ID_112345 as alias in her Teamscale user profile. All commits of
Jane Doe and
ID_112347 will now belong to the same committer.
You can view all committers and their aliases in the System > System Information view by clicking on Active committers.
Do I have to pay for bots and technical users that commit code?
No, you do not have to pay for bots and technical users. Teamscale excludes some well-known technical users such as the GitHub Merge Bot and the default SAP usernames
SAP*. But it is not possible for Teamscale to identify all technical users automatically. Contact our support to let us know which technical users you have. We will take this into account when billing.
How often are Teamscale updates published?
Usually, there are weekly patch releases for the last 2-3 release lines (e.g.,
5.8.x). Feature releases are published roughly every six weeks.
Does only the latest Teamscale release receive updates?
No, we try to support the last 2-3 release lines (e.g.,
5.8.x). However, we recommend to update to the latest version, as this includes the full feature set. Bug fixes for older releases will also be contained in newer releases.
Which kinds of updates require a re-analysis of the Teamscale project?
There are two kinds of Teamscale releases:
- Patch releases, which usually don't require a re-analysis
- Feature releases, which require a re-analysis.
See also next question.
How do I know if I'm installing a feature or a patch release?
- Patch releases only change the last digit of the version number (e.g., 5.8.0 → 5.8.5).
- Feature updates change the first and/or the middle digit, e.g.,
- 5.8.0 → 5.9.0
- 5.8.0 → 6.0.0
How can I find out which version of Teamscale I have?
- If Teamscale is running, click on in the upper right corner, then click
- If Teamscale is not running, please check the
set VERSIONline in the file
Where can I find more about the features & bug fixes contained in a specific release?
Do I need a new license to update Teamscale?
No, Teamscale updates are free!
Why is a re-analysis necessary?
When you change important settings for a project or its analysis profile, many analysis results will change, e.g. findings, metrics, coverage, ... In order to get consistent metric trends, Test Gap results and to avoid hard-to-explain jumps in metric values, Teamscale re-analyzes the complete history of the project (as far back as configured in the project settings). This ensures you always have a consistent and explainable view on your data.
How do I avoid downtime after Teamscale updates?
We recommend to set up a shadow instance running on another port (see file
config/teamscale.properties). As soon as the new instance has finished re-analyzing the projects, the old instance can be shut down and the port of the new instance can be set to match the old one. This process is even easier when a tool like NGINX is configured as a reverse proxy.
Can I transfer my test coverage to the new instance?
Yes, by importing a project backup that was created on the old Teamscale instance.
Users & Authorization
What are the default credentials (username, password) for the very first login?
Please change your admin password before you make Teamscale available to others.
Can I configure Teamscale to synchronize users from my LDAP / Active Directory?
Yes. Please see the article on importing users.
Does Teamscale support Single sign-on (SSO)?
Yes. Teamscale supports authentication via SAML 2.0 and OpenID Connect.
How often does Teamscale synchronize with LDAP?
By default, Teamscale does not automatically synchronize with LDAP, but this can be configured for each connection in Admin > Settings > LDAP.
Can I configure users manually?
Yes. Teamscale comes with a built-in user management system. Please see the Users perspective.
What is an Access Key?
The Access Key has to be used instead of your password when the authorization takes place outside of Teamscale's Web UI (e.g., from your IDE or when using the REST API).
Where can I get my Access Key?
In Teamscale's Web UI, click on your avatar in the upper right corner, then choose Access Keys.
Configuration & Customization
Can I add multiple repositories to a single Teamscale project?
Yes, the number of repositories per project is unrestricted.
Can I configure a project to contain multiple programming languages?
Yes, simply create a new analysis profile and select your target languages in the first step.
Can Teamscale analyze branches?
Yes, each Teamscale project can be configured to analyze all repository branches that you are interested in.
Does Teamscale analyze deleted branches?
It depends on when the branch was deleted, but Teamscale can often reconstruct deleted branches. Teamscale will then analyze these deleted branches just like regular branches.
Can I configure which branch should be considered the "main" branch?
Yes. The Default branch name can be set in the project configuration.
Can I exclude certain parts of my repository from analysis?
Yes. This is possible with the Include & Exclude File Patterns options in the project configuration.
Can I exclude certain files of my repository based on the file content?
Yes. This is possible with the Content Exclude option in the project configuration.
Can I add my own metrics to Teamscale?
Yes. Teamscale supports two kind of so-called external metrics:
- External code metrics that can be calculated individually per code file
- External non-code metrics (e.g., build execution times)
Can I implement my own checks?
Yes. Please take a look at Teamscale's custom check framework.
I already have my own code analyzer. Can I integrate its results to Teamscale?
Yes. To get started, please check this sample file with generic findings.
Why does Teamscale only calculate a handful of metrics? Why not more?
We deliberately only include metrics that are easy and actionable.
Can I see an overall rating or grade for the quality of my code?
While you can assess related metrics using threshold configurations, we deliberately don't calculate an overall score or grade for analyzed systems. This is because in our view, this would mean aggregating unrelated things, such as code clones and code documentation.
Test Coverage & Test Gap Analysis
Does Test Gap Analysis work with multiple test stages (e.g. Unit Tests and Manual Tests)?
Yes. You can have any number of coverage sources as the test gap analysis offers a holistic view. Teamscale supports all forms of tests, including - but not limited to - unit test, component tests, automated UI tests, manual and exploratory tests.
The coverage sources can be distinguished using the partition label you specify during the coverage upload to Teamscale. In Teamscale, you can select at any time which coverage sources you would like to view and you can even aggregate coverage from multiple sources to answer questions like "Which code changes did we test in none of our test stages?"
Can I see the results for a specific combination of coverage sources (e.g. Exploratory Developer Tests and User Acceptance Tests)?
Yes. You can specify which coverage sources ("partitions") should be taken into account for the analysis in all relevant views. In Teamscale, you can select at any time which coverage sources you would like to view and you can even aggregate coverage from multiple sources to answer questions like "Which code changes did we test in none of our test stages?"
In the Test Gap treemap, what do the individual rectangles mean?
Each rectangle represents a method of your system. The size of the rectangles corresponds to the length of the respective methods, so larger rectangles denote longer methods.
What do the colors in the Test Gap treemap mean?
- Gray: The method was not changed since the baseline (except refactorings).
- Red: The method was added but remained untested.
- Yellow: The method existed before the baseline, but remained untested after its latest modification.
- Green: The method (or some parts of it) was tested in its current version.
Does the Test Gap analysis also work for manual tests?
Yes. Please refer to our how-to for setting up the Test Gap analysis for manual tests.
How do I record test coverage for manual tests?
Please refer to our how-to for setting up the Test Gap analysis for manual tests for an in-depth explanation.
How does the Test Gap analysis know which test case or individual tester caused the test coverage?
It does not, because it doesn't need to. The Test Gap analysis shows you code areas that were recently changed but not yet tested. For this task, it is unimportant which test case or which individual tester caused the test coverage as we are not interested in the tested code changes. All untested code changes are untested regardless of who did the testing or which test cases were used. By definition, any bugs that are still present in these untested code changes cannot have been found by any of your tests.
If you are interested in an analysis that makes use of the link between test case and test coverage, have a look at the Test Impact analysis.
I uploaded test coverage to branch A, but want to see its coverage on branch B. Is this possible?
Yes. The coverage will be visible for branch B as soon as A is merged into B.
I uploaded test coverage for Teamscale project X, but project Y contains (nearly) the same code. Can I see the coverage for project Y, too?
Yes. This is called "cross-annotation" and can be set in the respective views or widget. The coverage of methods that are identical (source location & method content) in both projects will also be visible for project Y.
Why does my coverage tool report different numbers than Teamscale?
There are two main reasons why that may happen:
- Teamscale always takes all source lines into account, some coverage tools only count those that were loaded at runtime.
- Teamscale may deem certain lines as coverable or uncoverable where your tool has a different opinion. For an in-depth explanation, please refer to our blog post on the subject.
Does Teamscale transmit code to CQSE (or some other online destination)?
If you have an on-premise installation, all of your code and analysis data stay on your network and only you decide where the analysis results will be transmitted (e.g., to the IDE integrations of your developers). When using Teamscale's Cloud offering, the code will be transferred to and processed on a server of CQSE. To make sure that your data is safe, we have many security measures in place.
Has Teamscale ever been audited with respect to security?
Yes. We (and also some of our customers) run regular security audits and penetration tests against Teamscale. The results are used to improve both Teamscale and our development processes.
What separates Teamscale from other static code analyzers?
- Teamscale has an incremental analysis engine (see next question).
- Teamscale is more than a static analyzer. It is a software intelligence platform, which means that it can aggregate data from multiple sources (repositories, issue tracker, build artifacts, etc.).
What does "incremental analysis" mean?
Incremental analysis means that Teamscale analyzes commit by commit, as opposed to, for example, running as batch tool and analyzing the whole system again and again. Amongst other things, this means that Teamscale can
- give feedback almost in realtime after a commit was made,
- distinguish between old and new findings, and
- can display freely selectable trends.
Where does the analysis happen?
All analyses are performed on the Teamscale server. This means that, for example, there is no slowdown of your build, and that the analysis settings are independent of local IDE settings.
Does Teamscale's analysis need the compiled binaries (e.g.,
.class files for Java)?
No. Teamscale analyzes the source code directly and thus doesn't have to wait for a build to happen.
Why & when is a re-analysis of the projects needed?
As Teamscale can show you the full history of your data, a re-analysis is required if the analysis parameters change. This avoids ambiguity, e.g., due to spikes in metrics trends that were only introduced by a configuration change. Correspondingly, a re-analysis is required if changes to Teamscale's analysis configuration were made.
How fast do I get feedback after a commit?
After a commit was pushed to the repository, a typical analysis takes only a couple of seconds. For large commits like merges, it might also take a couple of minutes, but usually not longer than 5 minutes.
Does Teamscale only analyze the changed files per commit?
While most of the analysis works on a per-file basis, Teamscale always knows the full system context. This means that, for example, the clone detection will recognize copy-and-pasted code in a new file that was copied from an existing, but untouched file.
Can I choose the start and end date of trends?
Yes. You can freely choose the start and end date for all charts and views.
Findings & Findings Management
What exactly is a "finding"?
Generally speaking, a finding refers to a piece of code that is not as good as it could be. This can, for example, be a bug in your code, or a violation against your coding guidelines.
Teamscale reports thousands of findings for my system, is this normal?
It is very common to see a huge number of overall findings, especially for long-lived systems. Please also see the next question.
How can I filter the findings?
For example in the Findings perspective, by
- filtering based on the finding's group or specific type
- focusing on findings that were recently introduced by setting a baseline.
Can I configure which findings should be treated as "critical" / "non-critical"?
Yes, the severity of every finding type can be set to "red" (critical), "yellow" (non-critical), or "off" (no reporting).
I don't want Teamscale to report a certain type of finding anymore. How can I do that?
You can turn off the finding type in the analysis profile that your project uses (Projects > Analysis Profiles).
Can I permanently ignore a finding?
Yes. You can mark the finding as "tolerated" or "false positive" in the findings details view. See also next question.
What happens if someone marks a finding as "tolerated" or "false-positive"?
The finding will no longer by reported by Teamscale, which includes future changes to the file, as well as potential merges to other branches.
Will findings marked as "tolerated" / "false-positive" be reported again after a Teamscale update?
No. As long as you export a project backup with your previous Teamscale version, the excluded findings will still be excluded after the update.
Can I see which findings have already been marked as "tolerated" or "false-positive"?
Yes. Please see the respective tabs in the Findings perspective.
Can I configure which users should be allowed to mark findings as "tolerated" / "false positive"?
Yes. Users need the Flag Yellow Findings and/or Flag Red Findings permission (e.g., via the Project Administrator role).
Can I see which commit introduced a specific finding?
Yes. In the findings detail view, the introduction commit is linked, along with the introduction diff.
After I removed a finding, will Teamscale still know it existed?
Yes. As Teamscale analyzed the full repository history, removed findings will be known to Teamscale.
Who develops Teamscale?
Teamscale is build by the great team at CQSE GmbH.
I found a bug or have a feature request, how can I report it?
Please don't hesitate to contact email@example.com for all of your questions.
I have a question, where can I find answers?
In case this documentation didn't answer your question, we are happy to help.
In which programming language is Teamscale written?
Teamscale's backend is written in Java, whereas the Web UI is build with TypeScript.
Is it "TeamScale" or "Teamscale"?
It's Teamscale, so no CamelCase notation, please 😉