Comments in test cases
The YAML test specification allows comments in test specifications, but
they are intended for human readers only, and are ignored by
parsers. To preserve comments in test specifications,
testIDEA has a modified parser, which saves comments.
However, to be able to save comments back to YAML file to proper
locations, comments are attached to items in test
specifications. This also means, that there are additional rules
for writing comments, which extend the official YAML syntax. These
rules are not complex, but they are important when editing test
specifications in text editor. testIDEA takes care about
proper formatting automatically. If you are not editing test cases
in text editor, you can skip the next four sections (End of line
comments, ...) and continue
reading Comments in testIDEA below.
End of line comments
End of line comments are written after YAML tokens on the same line.
These comments are attached to the last scalar on the same
line.
Example:
locals: # comment for section 'locals'
x: int # comment for type 'int'
y: MyType # comment for type 'MyType'
New line comments
New line comments are written before the token. There are no YAML token in
this line. These comments are attached to the first token on the
next line.
Example:
# comment for section 'locals'
locals:
# comment for var x
x: int
# comment for var y
y: MyType
Mixed comments
For mixed comment the same rules apply for end of line and new
line comments.
Example:
# comment for section 'locals'
locals: # comment for section 'locals'
# comment for var x
x: int # comment for type 'int'
# comment for var y
y: MyType # comment for type 'MyType'
Ignored comments
Comments in flow sequences are ignored. Use block format when
you want to comment items.
Examples:
Comments will be preserved in this case
tags:
- tagA, # eol comment A
- tagB, # eol comment B
- tagC # eol comment C
Flow style on the other hand, ignores comments and formatting:
tags: [tagA, # ignored comment A
tagB, # ignored comment B
tagC # ignored comment C
] # ignored comment C
When saved, the following is written to file:
tags: [tagA, tagB, tagC]
Comments in the last line of test specification have no scalar
to be attached to, so they are ignored and therefore not written to
output when the test specification is saved.
testIDEA supports viewing and editing of comments in test
specifications. Comments are shown in UI as tooltips of input
field decorations, and can also be edited by clicking these
decorations.
When we move mouse cursor to decoration icon, the comment is
displayed in tooltip as shown in the image.
If there is no comment, nothing happens.
The comment edit dialog opens, when we click active decoration icon:
To visually present status of comment for each test specification
item, decoration icons can have one of four states, as shown in
the image below:
Description of comment states:
- non-editable empty comment - fields, which are empty
are not written to test specification, so there can be no
comment attached to them. Until we enter some value into the
input field, comments are disabled.
- existing editable comment - comment is already
specified, we can see it as decoration tooltip and edit it by
clicking the decoration icon.
- existing non-editable comment - comment is
specified, we can see it as decoration tooltip but we can not
edit it, because it is specified in base test specification.
To edit it, we have to select the base test specification,
where it is defined.
- empty, but editable comment - comment is not
specified, but we can edit it by clicking the decoration
icon.
If an item with comment is deleted from test specification, then
the comment is also deleted. It is not possible to preserve comments
without data. For example, if we specify test ID and its comment, and
then decide to delete the id, the comment is also deleted.
Most edit fields contain data for simple YAML tags. These
fields have only one decoration icon on the right. Fields, which
refer to structured items, for example the 'Function' field, have
additional decoration icon on the left. If we are editing test
specifications in testIDEA only, then it does not matter,
which decoration we use. If location of the comment in YAML test
specification is important, we can enter the comment, then copy the test
case to the clipboard and paste it a text editor. There we can see the
exact location of the comment.
Comments in tables
To set a comment for item in a table, first select the line in the table,
then click the decoration icon on the left side of the table. If a
table item has a comment assigned, it is marked with blue dot. To see a
comment, select a line and move cursor above the comment decoration
icon on the left side, as shown in the image below.
Decoration icons on the left side refer to the locals:
section in a test case. The top icon contains comment for
the locals tag itself. The bottom icon contains comment for
the selected variable declaration.
Decoration icons on the right side refer to the init:
section in a test case. The top icon contains comment for
the init tag itself. The bottom icon contains comment for
the selected variable initialization.
Limitations of testIDEA
When tags or function parameters are edited in testIDEA,
comments are not preserved for list items. This means that in
these two cases it is possible to write comments in
text editor, but they are not visible or
editable in testIDEA. If you modify these two fields in
testIDEA, comments for list items are lost. Example:
The following was written in text editor:
tags: # part of regression tests
- moduleA # communication functions
- moduleB # math functions
func:
- f # test for midnight
- - 24 # hours
- 00 # minutes
This was later modified in testIDEA. The following was saved:
tags: # part of regression tests
- moduleA
- moduleB
func:
- f # test for midnight
- - 24
- 00
Note, that other comments than ones for tag items and parameters
were preserved.
All other items in test specification preserve comments.