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.

Comments in testIDEA

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.