The client viewer functionality provides you, as a developer, a way to inspect your TICS Client run results in the centrally hosted TICS Viewer, without you having to install the webserver or database components. By instructing your TICS client to upload it's results you unlock the full interactive and visual experience offered by the TICS Viewer, as opposed to the limited text-based reporting offered by TICS Client. Additionally, by uploading the results you can check whether your code changes pass the company-defined quality gate.
In order to be able to inspect your client results in the viewer, you have to specify the
-viewer flag when invoking TICS client.
For instance, to check your local code changes in directory
/dev/myproject for project
MYPROJECT you could run:
TICS -project MYPROJECT -viewer /dev/myproject
-project auto, or you are running with the
-noproject option, then the TICS Client will fail.
[INFO 3016] message that you can use to inspect the results:
[INFO 3014] The data for the client run changes of project 'MYPROJECT' can be viewed at the following URLs: Explorer ======== https://localhost/tiobeweb/TICS/Explorer.html#axes=ClientData(nPFYkTr57NanLcVRIhjiVw),Project(MYPROJECT),Branch(main),Window(-1),File()&x=Delta(tqiCodingStd,Run(-2)),Delta(loc,Run(-2)) Quality gate result =================== https://localhost/tiobeweb/TICS/Explorer.html#axes=ClientData(nPFYkTr57NanLcVRIhjiVw),Project(MYPROJECT),Branch(main),Window(-1),File()&x=Delta(tqiCodingStd,Run(-2)),Delta(loc,Run(-2))&zqgs=1&
You can (control-)click an URL to open it in your browser if your terminal supports this, otherwise you have to copy and paste the URL.
Note that the URLs returned by TICS contain a so-called client-data token (in this case
which is a unique identifier generated specifically for your client run.
This ensures that the results are only visible to you and do not interfere with the normal TICSQServer analysis results of MYPROJECT that are visible to everyone.
Furthermore, because a token is generated for every TICS run and results are not overwritten, you can also inspect results of earlier runs.
The viewer represents the client-data token in the breadcrumb with the icon. As long as this breadcrumb item is there, you will see client-specific results; if you remove the breadcrumb item, you will see the data that is based on the regular TICSQServer runs again. The client data is combined with the base project data: a run is inserted for the time on which TICS client ran. Any runs in the base project that come after this date will not be visible in the client view. This means that the view referred to by the client-data token is immutable; the metric data will in principle not change when new TICSQServer runs will be done later for the project. Most functionality of the viewer, including most metrics, the chart, treemap, annotated source, and search also works in client views. However, for an overview of the limitations, see below.
To get more information about the client run that you are looking at in the viewer, you can select ' Run Info' option in the client data filter's context menu (only works in the Dashboard and Explorer).
As stated, by default a new random client-data token is generated every time you do a TICS run. However, it is also possible to specify a custom token that you then reuse for different TICS runs. Any previous results for that a specific token & project/branch combination will be overwritten. Specifying a custom token can be useful for several reasons:
(only alphanumerical characters and underscores are permitted).
For instance, to upload result for project MYPROJECT for a token named 'my_tag' you would execute:
TICS -project MYPROJECT -viewer -cdtoken my_tag /dev/myprojectThe custom token will be prefixed by your system username, to prevent collisions with other developer wanting to use the same tag.
It is also possible to do a quality gate check via the
-calc GATE is a
metric alias matching all metrics
that are part of your quality gates, as follows:
The following command line invocation runs TICS for all metrics covered
by your quality gate on your code in
/dev/myproject. The metrics
run are equal to the metrics in your quality gate. TICS then uses the viewer
to determine whether your code passes the quality gate.
TICS -project MYPROJECT -calc GATE /dev/myproject
When the TICS client determines the metrics to run, it now queries the viewer for which quality gates are applicable for this project, and runs these metrics. Then, at the end, it provides a quality gate to check your files against.
For instance, let's give as an example that your quality gate checks whether
any new level 1 Coding Standard and Compiler Warning violations are introduced.
In that case, using the option
-calc GATE will be equivalent to
using the option
GATE are that a viewer needs to be available,
a project needs to be used, and a quality gate is set. If not met, TICS
will fail with an error message.
Note that running with
-calc ALL will skip over fetching the
metrics from the enabled quality gates. This is because any metric which would
be enabled by running
GATE will already be enabled by
ALL. For instance, let's assume the following is configured in your
CODINGSTANDARD: ENABLED: 1 COMPILERWARNING: ENABLED: 1 FANOUT: ENABLED: 1 AVGCYCLOMATICCOMPLEXITY: ENABLED: 1 MAXCYCLOMATICCOMPLEXITY: ENABLED: 1
In the case you run
TICS -calc ALL, it will always run all of these
metrics. So it is not necessary to check the metrics of quality gates on top of
this. It would not change any of the actions being done by TICS. It also saves
performance since then it's superfluous to check the QG.
If a quality gate is configured for the project,
and you have specified the option
-calc GATE, this will output something along the lines of:
2021-04-07 10:37:18: [INFO 3017] The viewer quality gate(s) for project MYPROJECT have failed. Failed quality gate details: * Gate: Gate 1 Condition: TQI should be at least 60.00%, but actual value is 32.70% * Gate: Gate 2 Condition: Coding Standard Violations for levels 1, 2, 3 should be equal to 0 for each file, but was not for 20 files
In order to have the exit status indicate the status of the gate, you can use the
the exit status is 0 if and only if all gates pass.
Quality gate conditions that are based on delta metrics (relative conditions) can also be checked,
since the client data is combined with the base project data.
Quality gate conditions that are defined on metrics that are not included in the client run
will not take part in the the quality gate evaluation.
They will not be shown as part of the TICS
[INFO 3017] log entry.
In the quality gate status dialog in the viewer,
they will be shown as skipped,
as indicated by a gray flag ().
To enable the client viewer functionality,
no configuration changes are needed in the TICS Viewer Administration or TICS configuration.
As a developer, you just have to specify the parameter
As a manager, you can automatically have all TICS clients upload their data without the need to specify
-viewer by configuring
SERVER.yaml => WEBSERVER => CLIENTVIEWER.
If for some reason you want TICS client to ignore this setting, you can specify the parameter
Some client viewer parameters can also be configured in TICSConfig.
SERVER.yaml => WEBSERVER => PORTALURL).
The TICS Viewer should be reachable from the machine that runs TICS client.
You cannot upload results for source code that does not have a base project.
Also, this base project must have at least one run.