1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
= Log Processing
The logs generated by the test executor, although they are ASCII text files, are perfect for machine processing, but not for analyzing by humans. To make these log files more readable log formatting tools are provided. All of these programs require the same license feature, `LOGFORMAT`. The programs are designed so that they can be used either individually or bundled together with UNIX pipelines.
* `Logmerge` is useful for test suites that are run in parallel mode. It can merge the logs of different PTC into one single file based on the timestamps.
* `Logfilter` can be used for post filtering large log files based on the kind of logged events. It can be specified to keep or remove the event type(s).
* `Logformat` breaks the sent and received data structures into lines and indents the fields according to their hierarchy. Moreover, if the test suite was executed in single mode, the log formatter splits the logs of each test case into separate files.
* `Repgen` can present not only the formatted log files but the description and TTCN–3 source code of test cases as well as the output of other network monitor programs, like `tcpdump`, in HTML format. The test results can be easily viewed by any JavaScript capable Web browser.
== The `logmerge` Utility
The `logmerge` utility, which can be found in `$TTCN3_DIR/bin`, merges all files given in the command argument into a single output file. The output of logmerge is sorted based on the timestamps found in the log files.
The command line syntax is:
[source,subs="+quotes"]
*ttcn3_logmerge [ -o _outfile_ ] [ file.log ] …*
or
[source,subs="+quotes"]
*ttcn3_logmerge -v*
Available command line switches are:
* `*-o _outfile_*`
+
Merges all input log files into `outfile`. If the `outfile` exists its contents will be overwritten. This switch is optional, if it is omitted, merged logs will be printed to standard output.
* `*-v*`
+
Prints `version` and license key information and exits. Each line of the input files should contain an event in the following format: +
`<timestamp> <rest of the event>`
Merging log files with different types of timestamps, for example with timestamp format `Time` and `DateTime`, results in warning message(s), and only files with same format are merged. Merging log files with timestamp format `Seconds` is not. If a file contains one or more timestamp(s) that is in wrong order, the resulting order will be incorrect too. In this case a warning message will be printed to the standard error.
The output of the utility is the following:
[source,subs="specialchars,quotes"]
<timestamp> <component id> <rest of the event>
where `<component id>` is taken from the name of the respective input file. If the name of the input file is not in the format `<ets name>.<host>-<component id>.log`, the whole input file name will be used as `<component id>`. Events spreading over multiple lines are also handled properly.
== The `logfilter` Utility
The `logfilter` utility, which can be found in `$TTCN3_DIR/bin`, filters the input log file given in the command line argument based on the event types in the file, and filter parameters given in the program argument. The output is then written to an output file if specified, or to the standard output. The program is useful only if the variable `LogEventTypes` is set to `yes` in section `[LOGGING]` of the configuration file.
The command line syntax is:
[source,subs="+quotes"]
*ttcn3_logfilter [ -o _outfile_ ] {eventtype(+__|__-)}[input.log]*
or
[source,subs="+quotes"]
*ttcn3_logfilter -v _|_ -h _|_ -l*
Available command line switches are:
* `*-h*`
+
Prints `help` on using the utility.
* `*-l*`
+
Prints the `list` of supported event types.
* `*-o _outfile_*`
+
Puts its output into `outfile`. If the `outfile` exists, its contents will be overwritten. This switch is optional, if it is omitted, the output will be printed to standard output.
* `*-v*`
+
Prints `version` and license key information and exits.
The utility can handle one file at a time, giving more input files results an error. If no input file is given, it reads the log from standard input. `Logfilter` can be efficiently used as the middle stage of a pipeline, combined with `logmerge` and `logformat`.
Event types to be included or excluded should be given without the `TTCN` prefix, that is, as they appear in the log file. Undefined event type(s), that are not listed in the link:https://gitlab.eclipse.org/eclipse/titan/titan.core/tree/master/usrguide/referenceguide[TITAN Programmer's Technical Reference for TITAN TTCN-3 Test Executor], specified as filter parameters will cause warning message(s), but will not cause the utility to quit. If there are parameters specified both to include and to exclude one or more event types, the program will quit with an error message, because in this case it is not well defined how to handle other event types. All possible error and warning messages will be printed to standard error.
== The `logformat` Utility
The `logformat` utility, which can be found in `$TTCN3_DIR/bin`, reads the unformatted log file generated by test executor from its standard input. It can split up the log into several files based on the lines that are automatically logged at the beginning or end of each test case. Furthermore, `logformat` formats the sent and received messages in the log file. The structured values are indented and each field is put into a new line according to the braces and commas.
The command line syntax is:
[source,subs="+quotes"]
*ttcn3 logformat [ -i _n_ ] [ -o _outfile_ ] [ -s ] [ -n ][ file.log ] …*
or
[source,subs="+quotes"]
*ttcn3 logformat -v*
The switches denoted by square brackets are optional. The following command line options are available (listed in alphabetical order):
* `*-i _n_*`
+
Sets the depth of each indentation level to `_n_` characters. The default value is `_4_`. If the sent or received PDU is too complex and has too deeply nested fields, this number can be decreased to get more readable output.
* `*-o _outfile_*`
+
Places the output into file `outfile`. If the `-s` flag is also set, only those parts of the log files will be written into this file that were logged outside the test cases, that is, in control part or on PTCs. If this option is omitted, the formatted log will be printed to standard output.
* `*-s*`
+
If this option is set, the entries that were recorded during the execution of a particular test case will be saved in a separate file in `logformat`’s working directory. The name of this file will be identical to the name of the test case. If the same test case is executed several times after each other, the results of repeated test runs will be collected after each other. If the output file contained some data before `logformat` was started, for example the results of previous test run, the output file will be emptied and the old logs will be destroyed. +
`logformat` recognizes any types of timestamps that can be set in the `[LOGGING]` section of the configuration file. +
WARNING: This option is useless when formatting the log files of PTCs, because these logs do not contain the name of the testcase the PTC belongs to.
* `*-n*`
+
If this option is set, newline and tab control characters are not modified, they are printed as \n and \t.
* `*-v*`
+
Prints `version` and license key information and exits.
`logformat` formats all files that are given as arguments and concatenates them after each other. If no files are given, it reads the log from standard input.
== The HTML Report Generator
The HTML report generator called `repgen` can be found in `$TTCN3_DIR/bin`. The program requires one command line argument that contains the name of its configuration file. The behavior of `repgen` can be configured only through this file. If the switch `-h` is given instead of the name of the configuration file, `repgen` prints a sample configuration file to its standard output.
The configuration file of `repgen` is a simple text file which contains a sequence of directives. Its usual suffix is `.ts`. Each directive starts with a special keyword beginning with a hash mark (#) character. The first part of configuration file should contain global settings, the description of test cases can be added after that.
The following table summarizes all global settings:
[width="100%",cols="30%,70%",options="header",]
|===
|Keyword |Meaning
|`#Title` |The name of the ETS. This string will be used as title in the resulting HTML pages.
|`#Tab length` |The report generator replaces all tabulator characters with spaces in the TTCN–3 test cases and log files. This parameter sets how many spaces a single tab character should be replaced with. The default value is `_8_`.
|`#Column width`| The report generator breaks the long lines of the ATS and the external monitor logs. The resulting lines in HTML output will not be longer than this limit. The default value is `_80_` characters.
|`#TTCN-3 code` |The name of the directory that contains the TTCN–3 source files of the test suite. All files will be searched in this directory whose name ends with `.ttcn`. `repgen` collects the source code of test cases that are listed in the remainder of this configuration file. The referenced functions, templates and other definitions are not collected. An absolute or a relative path may be entered, the starting point is always the `repgen`’s working directory, for this and the following three parameters. The same directory may be used for many purposes because the file names do not clash.
|`#TTCN-3 log` |The name of the directory that contains the log file(s) of the test executor. The report generator splits and formats the log files using the log formatter `logformat`. All files will be formatted in this directory whose name ends with .log. If the log of one test case can be found more than once in the log file(s), for example, because of repeated test execution, the resulting HTML page will contain the log of one execution. The others will be lost.
|`#Other log` |The name of the directory that contains the log files of the external monitor programs, for example `tcpdump`. Each file should contain the messages (network packets) recorded during the execution of one test case. The log files in this directory must be named as `<testcase name>.dump` where `<testcase name>` stands for the name of the corresponding test case. All files must be in ASCII format. `logformat` will simply copy them into the destination directory and will not change their content.
|`#Destination` |The name of the destination directory where the files of the resulting HTML report should be stored by `repgen`. The starting page will be `<title>-report.html` in this directory and the other files will be stored under sub-directory `<title>-report`, where `<title>` stands for the string set as the value of parameter `#Title`. Note that each space and dash in this name will be replaced by an underscore character.
|===
After the global settings, the name and description of all test cases after each other (in arbitrary order) can be listed. +
NOTE: `repgen` processes the source code and logs only for those test cases that are listed in the configuration file. The TTCN–3 code and logs of other test cases will be silently ignored. A test case can be specified using the following keywords:
[width="100%",cols="30%,70%",options="header",]
|===
|Keyword |Meaning
|`#Testcase` |The name of the test case. It must be the same as in the TTCN–3 code.
|`#Purpose` |A short summary of the test case describing in one sentence what it does. It must not be longer than one line. These short descriptions will be listed on the HTML page that lists the results of all test cases in one table.
|`#Description` |This section should contain the detailed description of the test case. It may continue through several lines, until the next `#Testcase` directive. Figures or message sequence charts can be drawn using ASCII characters, but images cannot be embedded.
|===
For browsing the HTML reports the only thing needed is to open the starting page, the file `<title>-report.html` in the destination directory, with a JavaScript capable web browser. The reports should work with any versions of Netscape and Microsoft Internet Explorer on any platforms. The reports can be viewed locally or remotely using any web server.
The starting page consists of two list boxes and four buttons (in addition to the title and the Ericsson logo). The test case can be selected in the left list box. After selecting a test case the available descriptions and logs will be shown on the right list box. The following items can be selected: +
* *Detailed description*
* *TTCN–3 code*
* *TTCN–3 executor’s log*
* *Other type of log* +
If one or more items for the test case are missing from input files, the missing option will not be shown. Select or unselect the available descriptions and logs one-by-one independently by clicking on them.
After selecting a test case and its items the ”Show” button at bottom should be pressed to view the selected logs and descriptions. A new browser window will be opened for each test case and the selected items will be shown in vertically split frames. The text in each frame can be scrolled independently. Of course, the `logformat` tool is unable to figure out the relation between the TTCN–3 source code and the produced log events.
In the root window, it is possible to walk through the available test cases step-by-step using the buttons *Previous* and *Next*. The button *Summary* will bring up another window that lists all test cases, their short descriptions and verdicts in a single table to get a quick overview about the test results.
.*Example:* In the following is an example configuration file of `logformat`. We included the descriptions of the first three test cases only.
[source]
----
#Title ROHC
#Tab length 8
#Column width 80
#TTCN-3 code /home/ethpkr/ROHC
#TTCN-3 log /home/ethpkr/ROHC/log
#Other log ./
#Destination ./
#Testcase CTC01
#Purpose Mode transition from Unidirectional to Optimistic mode.
#Description
Comp->IRs, Comp->IR_DYNs, Comp->UO-0s, Decomp->Feedback(mode
transition u->o), Comp->UO-0s
#Testcase CTC02
#Purpose Feedback processing in Unidirectional mode.
#Description
Testing the compressor’s feedback processing capabilities in U
mode.
#Testcase CTC03
#Purpose Operation in Optimistic mode (NACK).
#Description
Testing the compressor’s operation in Bidirectional Optimistic
mode. Preamble: taking the compressor to SO state and O mode.
After that a NACK is sent as an answer to a received compressed
packet. The answer for that should be an IR with dynamic chain
or UOR-2 or an IR-DYN packet.
[...]
----
NOTE: `repgen` was designed to present the results of non-parallel test cases. In case of parallel test execution, the logs of PTCs cannot be browsed, only the MTC log.
WARNING: During its run `repgen` will start the other log formatter program `logformat`. That is why `repgen` works correctly only if the directory `$TTCN3_DIR/bin` is included to the path.
|
