# Teamscale Integration for IntelliJ
Teamscale integrates with IntelliJ IDEA and many other IntelliJ IDEs, such as WebStorm and PyCharm.
Before installing the Teamscale Integration for IntelliJ, make sure its system requirements are met.
# Download & Installation
The IntelliJ plugin has been tested and used on IntelliJ IDEA, WebStorm and PyCharm IDEs, but should also work on other IntelliJ IDEs. To download and install the Teamscale IntelliJ IDEA plug-in, perform the following steps:
- Inside an IDE browse the JetBrains Plugin Repositories via File > Settings > Plugin > Browse Repositories.
- In the dialog box, search for
Teamscale Integration. On the right view, click the Install button.
- Restart the IDE to conclude the installation.
- If the plug-in installed properly, you should see a Teamscale entry in the main menu bar
# Configuring a Teamscale Server Connection
You need to perform the following actions to configure a Teamscale server:
Open the IntelliJ settings via the menu File > Settings.
Expand Tools (1) and select Teamscale (2) on the left hand side.
Use the + button to add a new Teamscale server (3).
In the details (4) fill in a descriptive Name for the server, its URL, and your Username and Access Key
By clicking on the Get Key button, you can navigate to the Teamscale web interface and generate a personal access key.
Click the Validate Connection (5) button to ensure successful connection the Teamscale server. Click Apply and OK to save the settings.
# Enable Plugin for IDE
The plugin can be enabled for the IDE (i.e. for all opened projects). When turned on, plugin can communicate with Teamscale and fetch quality results. Activate this by clicking Teamscale > Show Findings from Pre-Commit Branch. Ensure that this option is checked.
# Connecting an IDE Project to a Teamscale Project
In addition to enabling the Teamscale Integration, it needs to know which Teamscale project the IDE project corresponds to. This mapping is done in the Project Mappings settings page. To access the mapping settings page, you have to perform the following steps:
Click File > Settings. (Alternatively, you can click Teamscale > Configure Plugin ....)
Expand Tools > Teamscale > Project Mappings. This will open the following dialog:
In the dialog, check the option Enable Teamscale for this project.
Select the appropriate Teamscale server and project values.
Create prefix mappings by clicking on the Auto-create Prefix Mappings button.
Click Apply and OK to save settings.
# File Mappings
Under normal circumstances, the plugin automatically determines how to map the module files to the files in the Teamscale project. If the automatic mapping failed, a message is shown. To manually configure mappings between the local and the server's structure, you can add them in the module settings:
- Open the mapping settings page as mentioned above.
- Uncheck the option (Re)create prefix mappings.
- Create a mapping by clicking the + sign on the right side. Enter the mappings prefixes in the upcoming dialog. The Local Prefix is a part of your local directory structure. The Teamscale Prefix is a part of the project directory structure on the Teamscale server.
To check if everything is configured correctly, open the Findings tool window via the menu (View > Tool Windows > Findings):
Now you can select any resource that has findings and wait for findings to appear in the Findings tool window. The symbol on the top of the left hand side of the tool window will indicate the server's reachability state. Hover the mouse over the icon to get additional information. A click on the icon opens up the Teamscale settings.
# Refresh Findings
In order to get an updated view of the findings of a selected folder or a file after changes in a file system, for instance by switching to a new repository or branch, click the Refresh findings button in the Findings tool window.
# Pre-Commit Analysis
The IntelliJ plug-in can be used to analyze changes prior to committing them to the repository. This functionality is called pre-commit analysis. Only the files changed since the last commit that is present on the Teamscale server are uploaded and analyzed by pre-commit analysis. To compute the delta, Teamscale connects to the version control system configured for the IDE project. Currently, supported version-control systems are Git and SVN. You can trigger the pre-commit analysis by selecting Teamscale > Upload Project for Pre-Commit Analysis (as shown in the screenshot) from or via the shortcut »Alt+Shift+P«.
IntelliJ reports the findings delta after a few seconds in the Pre-Commit Results tool window as shown in this screenshot:
The new findings are also shown in the complete findings list as shown on the left side in the screenshot, however, the Pre-Commit Results view allows you to focus on the new findings.
Under the hood, Teamscale handles the pre-commit upload as if it would be a new branch in the repository. After the upload, Teamscale shows findings from this virtual branch. To show findings from real repository branches again (e.g., after you switched to a different branch), disable the »Fetch Pre-Commit Results« toggle in the Teamscale menu.
Note that, by default, Teamscale enforces some limits to such a pre-commit upload. These limits exist so that one overly large pre-commit upload does not disproportionately delay other analyses of other commits, whether pre-commits by other users or regular. For example, pre-commit only works if your local branch is not too far ahead of what your Teamscale server has already seen and analyzed. More information is available here .
# Enabling Debug Logging
While the plugin runs within the IDE, it collects various kinds of information about its state and operations. One might come across situations in which a feature does not work as expected. In such events, Debug Logging provides additional information and can therefore help us to analyze and solve the problem.
Debug Logging has been available since plugin version 5.3.0 for features like fetching findings and project mappings computation. To enable it, go to Help > Diagnostic Tools > Debug Log Settings. Then, enter the desired log categories, one per line, from the following options:
com.teamscale.ide.intellij.findings: Fetching findings.
com.teamscale.ide.netbeans.mappings: Mapping calculation.
com.teamscale.ide.intellij.precommit: Uploading data for pre-commit analysis and fetching the results.
com.teamscale.ide.intellij.vcs: Determining changes and branch information from the local version-control system (VCS).
If you are using an old version of IntelliJ you might have to prefix the packages with a # in the Debug Log Settings.
If you need more detailed logging at the level of core method calls, their arguments, and return values, append
to the respective category. This automatically logs non-trace debug information as well. For example
An example of a valid configuration is shown in the screenshot below: