https://www.cqse.eu/de/produkte/teamscale/ueberblick/
Teamscale ist ein Programm zur Codeanalye.


== Test Gap
Test Gap visualisiert, welche Code-Teile getestet werden. Hierfür müssen die entsprechenden Statistiken zur Codeausführung erzeugt und in Teamscale hochgeladen werden. Die allgemeine Dokumentation hierzu findet sich im Admin-Handbuch. In diesem Dokument werden alle Schritte für die Programmiersprache C und C++ beschrieben, dabei sind nur die Schritte 1. und 2. von der Programmiersprache abhängig.

Schritte:
1. Statistiken erzeugen
2. Eingabedatei für Teamscale erzeugen
3. Teamscale vorbereiten
4. Eingabdatei übertragen

1. Statistiken erzeugen
Um Statistiken zur Codeausführung für C und C++-Programme zu erzeugen, muss das Programm mit dem Flag --coverage kompiliert werden. Damit werden zusätzlich zu den .o-Dateien .gcno-Dateien erzeugt.
Anschließend werden bei der Programmausführung automatisch bei den .gcno-Dateien .gcna-Dateien erzeugt. Diese enthalten die Statistiken, welche Codezeile wie häufig durchlaufen wird. Wird neu kompiliert, werden die entsprechenden .gcna-Dateien bei der nächsten Programmausführung zurückgesetzt.

2. Eingabedatei für Teamscale erzeugen
Teamscale unterstützt eine Vielzahl an Dateitypen für die Statistiken. Diese können mit den Programmen gcov, gcovr beziehungsweise lcov erzeugt werden.
a) Mit dem Programm gcov werden gcov-Dateien erzeugt (Format: GCOV):
   gcov -l -r -p main.cpp
   Vorteil: Diese sind gut im Texteditor lesbar und enthalten den gesamten Quelltext.
   Nachteil: Jede Datei muss separat angegeben werden.
   Nachteil: Es werden viele Dateien erzeugt: für jede Quelltext-Datei und jede davon eingebundene Datei (Header-Dateien).
b) Mit gcovr kann eine xml-Datei erzeugt werden (Format: COBERTURA):
   gcovr -r . --xml -o Statistiken.xml
   Vorteil: Es wird nur eine Datei erzeugt.
c) Mit lcov eine info-Datei erzeugen (Format: LCOV)
   lcov -c -d . -o Statistiken.info
   Vorteil: Es wird nur eine Datei erzeugt.
   Vorteil: Sie ist wesentlich kleiner als die xml-Datei
Meine Empfehlung ist, ein lcov-Datei zu erzeugen und, wenn genauere Inforamtionen gewünscht sind, sich die gcov-Datei anzusehen.

3. Teamscale vorbereiten
Die in diesem Abschnitt aufgeführten Schritte müssen nur einmalig durchgeführt werden.
Die (automatisierte) Übertragung der Statistiken soll über die http-Schnittstelle erfolgen. Hierfür muss ein Benutzer eingerichtet werden, über den die Datenmeldung erfolgt.
In Teamscale lassen sich unter Admin → Users Benutzer einrichten. Wichtig ist, dass der neue Benutzer (wir nennen ihn hier build) in der Gruppe „Build“ ist. Außerdem sollte ein Access Key erzeugt werden, dieser ermöglicht eine Übertragung ohne Angabe des Passwortes.

4. Eingabdatei übertragen
Die Eingabedatei wird mit dem Programm curl über die http-Schnittstelle an Teamscale übermittelt. Dazu werden die folgenden Daten verwendet:
* build ist der Nutzername (siehe 3.)
* 1bmX1Ti1KamBjbFBHoMx7AoDvMNFxDrY ist der Access Key für den Nutzer build
* FreeDoko.info ist der Dateiname mit den coverage-Informationen
* freedoko ist die Projekt-ID (nicht der Name)
* LCOV ist das Format der zu übertragenden Datei (hier: FreeDoko.info; siehe auch 2.)
* Ref ist der Name der Partition
* Ref%20Coverage ist der Betreff. Sonderzeichen müssen codiert werden (z.B. ein Leerzeichen mit %20), siehe https://de.wikipedia.org/wiki/URL-Encoding#Relevante_ASCII-Zeichen_in_Prozentdarstellung.
Der Aufruf (auf 3 Zeilen verteilt) lautet dann
curl -X POST -u build:1bmX1Ti1KamBjbFBHoMx7AoDvMNFxDrY \
  -Freport=@FreeDoko.info \
  "http://localhost:8080/p/freedoko/external-report?format=LCOV&partition=Ref&message=Ref%20Coverage"

curl ist ein Programm, mit denen Internetseiten hoch- und runtergeladen werden können. Mit -X POST wird angegeben, dass Daten hochgeladen werden. -u enthält die Anmeldedaten (Benutzername:Passwort). -F gibt an, dass das Ausfüllen eines Formulars simuliert wird. Dabei wird der Name des Formularfeldes (report) und dessen Inhalt (Inhalt der Datei FreeDoko.info) angegeben. Der Seitenaufruf (http…) enthält die ID des Projekts (freedoko), das Format (LCOV), die Partition (Ref) und die Nachricht (Ref Coverage), die in den Aktivitäten angezeigt wird.


== Sonstiges
Die Partitionen ermöglichen eine einfache Strukturierung der Statistiken. So lassen sich zum Beispiel Statistiken von manuellen und automatischen Tests sowie von verschiedenen Branches trennen. In der Konfiguration vom Dashboard kann für jede Test Gap Treemap eingerichtet werden (linkes Symbol edit properties), welche Partitionen berücksichtigt werden sollen.

Die übertragenen Coverage-Dateien sind aufgeführt unter Projects → Projektname (hier FreeDoko) → Actions: External-Analysis Uploads. An der Stelle können einzelne Übertragungen sowie ganze Partitionen gelöscht werden.

Beim Hochladen der Statistiken ist darauf zu achten, dass sie mit der von Teamscale betrachteten Codeversion übereinstimmen. Also erst Programm ausführen, dann Commit durchführen, dann Statistiken übertragen.
Wenn die Statistiken auf einem modifizierten Programm erstellt werden (nicht auf einem Commit / von Teamscale überwachten Commit), kann die Übersicht in Teamscale falsch sein, zum Beispiel wird eine getestete Funktion als nicht getestet gekennzeichnet.

== Offene Fragen
* Ist es möglich, dem Aufruf von curl den Commit-Hash (von git) mitzugeben? Dann kann Teamscale prüfen, dass die übertragenen Daten passen.
* Prüft Teamscale, ob die Statistiken sinnvoll sind? So sollten keine Kommentarzeilen mitgezählt werden. Nicht sinnvolle Statistiken deuten auf eine Abweichung zwischen Code zur Statistik und von Teamscale überwachten Commit hin.


====
* Namenskonventionen für
  - enum ... { xxx };
  - const
  - constexpr
  - #define
* Namenskonventionen für
  - unsigned long xxx();
  - unsigned long xxx;
  gegenüber
  - long xxx();
  - long xxx;
