C o d e C ov e r a g e R e c eiv e r

R18
 TAFJ-U ni tT e s t F r a m e w o r k

Amendment History:

Revisio
Date Amended Name Description
n
1 June 23rd 2016 T. Aubert Initial version
2 Sept. 12th 2016 T. Aubert Add the xml files description

Page 2
CodeCoverage Receiver

Ta b l e o f C o n t e n t s
Introduction........................................................................................................................... 4

Quick start (command line).................................................................................................. 4

To start the server............................................................................................................ 4

To stop the server............................................................................................................ 4

To create an instance....................................................................................................... 4

To start an instance.......................................................................................................... 4

To stop an instance.......................................................................................................... 4

To delete an instance....................................................................................................... 4

To have a full status of your server.................................................................................. 5

To have a status of one single instance........................................................................... 5

To reset an instance......................................................................................................... 5

To create a report............................................................................................................. 5

Very Quick start (command line).......................................................................................... 5

The code coverage configuration file................................................................................... 6

Using the UI.......................................................................................................................... 7

The inconsistencies.............................................................................................................. 9

Remote management by command line............................................................................... 9

The report........................................................................................................................... 11

The welcome page........................................................................................................ 12

The inconsistencies view............................................................................................... 12

The report details........................................................................................................... 13

XML files........................................................................................................................ 16

Page 3
CodeCoverage Receiver

Intro d u c ti o n
The Code Coverage Receiver (ccr) is a standalone program which will receive informations
via TCP from different running JBC code. This program is able to generate full html report. It
can be managed via a web interface as well as via command lines. The ccr can be
configured to receive informations from different versions on the JBC.

Qui c k s t art ( c o m m a n d lin e )

The Code Coverage Receiver (ccr) has only one binary (ccr / ccr.bat). It is located in the
<home_of_ccr>/bin directory. Before anything, make sure you environment variable
JAVA_HOME points to a jre 1.7.x. From this binary, you can do all the necessary.

To s t a r t t h e s e r v e r
ccr (.bat) start

This will start the server in background.

To s t o p t h e s e r v e r
ccr (.bat) shutdown

Once the server is started, you need to create a new instance (this is effectively what will
receive informations from your JBC programs.

To c r e a t e a n i n s t a n c e
ccr (.bat) create <instance_name> <tcp port> [“start”]

example : ccr create Test 12345 start

If you ommit the start at the end, the instance is created but not started. You can start / stop
and instance like this :

To s t a r t a n i n s t a n c e
ccr (.bat) start <instance name)

example : ccr start Test

To s t o p a n i n s t a n c e
ccr (.bat) stop <instance name>

example : ccr stop Test

To d e l e t e a n i n s t a n c e
ccr (.bat) delete <instance name>

example : ccr delete Test

To h a v e a f u l l s t a t u s o f y o u r s e r v e r
ccr (.bat) status

Page 4
CodeCoverage Receiver

To h a v e a s t a t u s o f o n e s i n g l e i n s t a n c e
ccr (.bat) status <instance_name>

To r e s e t a n i n s t a n c e
ccr (.bat) reset <instance_name>

Resetting an instance means clearing all data received so far (starting fresh).

To c r e a t e a r e p o r t
ccr (.bat) make <instance name> [-p <path of precompile>] [-s <path of sources>] [-d <report
destination path>]

The path of precompile is the path containing all the precompile jars. If it is omitted, the Code
Coverage Receiver will obviously know nothing about the subroutines not having been
executed, and the subroutine coverage ration will always be 100%. However, the line
coverage will be correct.

If the <path of sources> is omitted, the report won't be able to drill down until the sources (not
a big deal for management reporting)

If the <report destination path> is omitted, the report will be created in the default location :
<home_of_ccr>/data/<instance name>/report

Note : Creating a report is time consuming, and it can easily take up to 1-5 minutes
depending your machine. Be patient !

Very Q u i c k s t a r t ( c o m m a n d l i n e )

Here is in few lines how to start from scratch, up to a report.

$ c cr start
$ c cr cr e a t e m yIn s t a n c e 1 2 3 4 5 s t art

Edit your tafj.properties like this :

temn.tafj.runtime.enable.coverage = true
temn.tafj.runtime.coverage.host = localhost (or the ip address of ccr machine)
temn.tafj.runtime.coverage.port = 12345

Run your program (eg EX). One done,

$ c cr m a k e myInsta n c e

Done !

T h e c o d e c o v e r a g e c o n f i g u r a t i o n fil e .

At the root of your Code Coverage Receiver, you will find a file “CCReceiver.properties”.
This file contains few informations to make the server running :

Page 5
CodeCoverage Receiver

vm_options=-Xms256M -Xmx2048M -XX:MaxPermSize=256M

http_port = 7470

instances = Test;running

vm_options is the java VM options used when starting the receiver.

Please consult the internet for more options.

http_port is the main port for all the Receiver. You can change it without any problem, but
make sure your server is stopped otherwise you won't have any other choice to “kill” it.

instances is a coma-separated list if names of instances.

each instance is supposed to have its corresponding <instance> directory in which you will
find <instance>.property file as well as other resources.

Their is no need to configure anything. The default values are all right for a normal activity.

Page 6
CodeCoverage Receiver

U si n g t h e UI

This is possible to manage your receiver via a web interface. For that, open a browser a
browse : http://<ip_of_ccr>:<http_port>/CoverageReceiver

At that stage, you can only Shutdown the receiver or create a new instance.
Let's click on “New Instance ...”

A very simple wizard will guide you through the instance creation. Small note : press <tab>
after having typed something for activating the navigations buttons.

Page 7
CodeCoverage Receiver

Once you clicked finished, your main screen will look like this :

If you read the “Quick start (command line)” chapter, you will recognize all the options on
your screen. No need to comment them again here.

Click on “Start” and … … you are ready to go !

Everything is persisted, so if you shut down the Receiver and restart if afterwards, it will
remain in the exact same status as when you stopped it.

Page 8
CodeCoverage Receiver

The incon sist e n ci e s

As you can see on the previous screen-shots, an instance can be either “running” or
“stopped”, but the side-icons are showing three states.

The second state indicates that there are some inconsistencies in the data received
(or loaded).
This is the “warning” state :

To understand what it means, you need to understand how it is all working.

At the runtime side (when you run your jBC code), there is a special process which collects
the line executed and send them in regular basis to the Code Coverage Receiver. Alongside
with the line numbers, there are 3 other informations sent :
1) The Subroutine name.
2) The total number of lines in this subroutines
3) The $PACKAGE information.

The first one is obvious. The second one is here to be able to generate a report even if you
are not specifying a precompile directory. However, imagine that you run a first time you
program, the Receiver receives a certain total number of lines, then you modify the program
and re-run it without resetting the instance.
In that case, we have an inconsistency. The report will certainly be wrong. Fortunately, we
can see these inconsistencies (see the “report” chapter later in this document).

The situation is the same with the $PACKAGE information. You will see that in the report, the
data are organized by “module” / “component”. If, in the same instance, we receive 2 times
the same routine with a different package, this create an “inconsistency”.

R e m o t e m a n a g e m e n t by c o m m a n d lin e

Since this is possible to manage a Code Coverage Receiver remotely with the UI, this is also
possible to do it command line.
All the commands (exept start) can have the “host:port” information as a prefix.

Example : to add an instance on a remote machine (running ccr !), you can type :
ccr remote_ip:remote_port create instance_name port
Example :
$ c cr 1 0 . 4 1 . 5. 5 1: 7 4 7 0 cr e a t e m y N e wI n s t a n c e 1 2 1 2

The only command which cannot have a remote ip address is “start”. This seems obvious.
However, we can do something like this :

$ c c r l o c a l h o s t: 7 4 8 0 s t a r t

Page 9
CodeCoverage Receiver

This will start the Code Coverage Receiver on the port 7480.

In other words, for the start command, the host “localhost” is forced.

Here is the full syntaxes of all the available commands

[…] means “optional”

<...> means “any” value

“...” means a “strict” value

Start the receiver :

c c r [“loc al h o s t”: < i p > ] s t a r t
Shutdown the receiver :
ccr [ < host >: <ip >] sh utdow n
Return the status of all (or a single) instance :
ccr [ < host >: <ip >] stat us [ <insta nce n a m e >]
List all the instances names :
c c r [ < h o s t > : < i p > ] in s t a n c e s
Create a new Instance :
c c r [ < h o s t > : < i p > ] c r e a t e < i n s t a n c e n a m e > < i n s t a n c e_ po r t > [“s t a r t ”]
Delete an instance :
c c r [ < h o s t > : < i p > ] d el e t e < i n s t a n c e n a m e >
Reset an instance (clear the collected data) :
ccr [ < host >: <ip >] res et < i n st anc e n a m e >
Start an instance :
ccr [ < host >: <ip >] sta rt < i n st a nce n a m e >
Stop an instance :
ccr [ < host >: <ip >] stop < i n st anc e n a m e >
Generate a report (can take few minutes) :
c c r [ < h o s t > : < i p > ] m a k e < i n s t a n c e n a m e > [-p < p r e c o m pil e di r > ] [-s < s o u r c e di r > ] [-d
< d e s ti n a tio n di r > ]

Page 10
CodeCoverage Receiver

Th e rep ort

Once the report is generated (either by command line with the “make” option or from the UI,
you will have a “report” directory containing “static” html pages.

This report is completely detached of anything and can be moved to a new machine.

Also, a zip file of the “report” directory is generated at the same time to make a download
easier.

From the UI (Browser) perspective, the links to the report (for immediate consultation) and to
the zip (for download) appears as shown here :

The zip file can be downloaded from command line with the wget program. The url is

http://<host>:<port>/CoverageReceiver/download/<instance name>/report.zip

eg :

http://localhost:7470/CoverageReceiver/download/myInstance/report.zip

The report url (if generated in default location) is :

http://<host>:<port>/report/<instance name>/report/index.html

Page 11
CodeCoverage Receiver

The w elc o m e pa g e
The welcome page will give an instant view on the coverage as follows :

Note : For the purpose of the documentation, the report has been based on a full component
build of T24 (running all the unitTests). Then, the report has been generated passing AN
OLDER version of the precompiled jars to force some inconsistencies.

You can see that this report has some inconsistencies. By clicking on the “<click for full list>,
you will see all the inconsistencies. Please read the “inconsistencies” chapter for more
details.

T h e i n c o n s i s t e n c i e s vi e w
Here is a view of the inconsistencies :

Page 12
CodeCoverage Receiver

Th e r e p ort d e t ail s
The report is organized by module / component / subroutines.

Here are the different view you will have :

The “full” initial view :

Page 13
CodeCoverage Receiver

One module view

All the components

Page 14
CodeCoverage Receiver

You can sort the column by clicking on them :

One component :

Page 15
CodeCoverage Receiver

Page 16
CodeCoverage Receiver

One routine :

X ML fil e s
In addition to the static html files composing the report, you can find a subdirectory called
“xml”. This directory contains xml files representing the coverage information by module /
component.

Here is an example of the “module” files :

and here an example of the “component” files :

Page 17
CodeCoverage Receiver

Page 18