TracNav

Getting Started

First, install TRex as described in the Download section.

Opening the TTCN-3 Perspective

To work with TRex it is advisable to switch into the TRex TTCN-3 perspective as follows: Window >> Open Perspective >> TTCN-3

Opening TTCN-3 Files

Individual TTCN-3 files should not be opened using the File >> Open File... dialog but must be placed into a TTCN-3 Project under the Eclipse workspace.

  1. Create a new TTCN-3 project by right clicking in the Navigator on the left and selecting New >> Project >> TTCN-3 Project
  2. Now you can either
    • Add existing TTCN-3 files to this project by
      • drag-and-drop from Windows Explorer or
      • by right clicking in the Navigator and choosing Import >> General >> File System and navigating to the location of your TTCN-3 files.
    • Create a new TTCN-3 file from scratch by selecting New >> TTCN-3 File. In the following dialog you may choose a project ("container") and provide a file name.
      • Import an existing TRex TTCN-3 project.

Editing

You can edit your files as usual including on-the-fly syntax checking.

Furthermore, you have the following advanced features:

  • Text Hover: When placing the mouse on an identifier, some information from the symbol table is displayed for the identifier.
  • Content Assist: When pushing CTRL+SPACE after typing the prefix of an identifier or TTCN-3 keyword, TRex tries to suggest possible completions.
    • Note: This feature is experimental and is not always able to provide suggestions.
  • Code Formatter: Either push CTRL+ALT+F or Right click and select Source >> Format to reformat your TTCN-3 code.
    • Note: This introduces also newlines before and after comments, which is not always desired.

Note: When you open or modify a TTCN-3 file in a TRex TTCN-3 editor, it (and the whole project) is analysed by TRex. This may take a while (up to several minutes for a several ten thousand lines of code test suite) and may require a lot of memory. By default, Eclipse uses 256MB of memory. If you experience out of memory conditions, increase the memory Eclipse uses as described in the FAQ.

Declarations

  1. Select any user-defined TTCN-3 type reference.
  2. Either push F3 or Right click and select Open Declaration to jump to the declaration of this type.

Outline

  1. Use the Outline tab to jump between important structures in the current TTCN-3 module.

References

  1. Right click on any TTCN-3 identifier.
  2. Select Find References.
  3. Navigate the newly opened TTCN-3 References tab.

Metrics

Each time you save a changed TTCN-3 file (supposing the TRex Nature is enabled for your project), metrics are calculated.

  1. Ensure the TTCN-3 Metrics View is visible on the bottom tabs.
    • This may be achieved by: Window >> Open Perspective >> Other... >> TTCN-3
    • Or add it to your current perspective: Window >> Show View >> Other... >> TTCN-3 >> TTCN-3 Metrics View
  2. With the 'TTCN-3 Metrics View' tab open at the bottom. The Metrics for an individual file may be viewed by selecting it in the Navigator on the left. Similarly the Metrics for a number of files may be viewed by selecting the Folder within which they reside; this will collate their Metrics together.

If no metrics are displayed, refer to question "Why are metrics and refactoring suggestions marker not calculated?" from the FAQ.

Refactoring

Inline Template

  1. Position the cursor on a valid template reference identifier and right click to inline a single reference. Alternatively position the cursor on the template name in its definition and right click to inline that template into all of its references.
  2. Select Refactoring >> Inline Template.
  3. Choose whether to remove the template itself after inlining (if no further references) and formatting options.
  4. Check inlining preview to confirm correct operation.

Rename

  1. Position the cursor on any TTCN-3 identifier (e.g. a template identifier name; either definition or reference) and do a right click.
  2. Select Refactoring >> Rename.
  3. Choose the new name for the identifier.
  4. Check renaming preview to confirm correct operation.

Inline Parameters

  1. Position the cursor on the template identifier name in its definition and do a right click.
  2. Select Refactoring >> Inline Parameters.
  3. The template must always be referenced with the same actual parameters (this will be confirmed by the refactoring wizard).
  4. Check inlining preview to confirm correct operation.

Merge Templates

  1. Use the 'Problems' tab to find a suggestion of templates that could be merged.
  2. Double click the problem to jump to the first template.
  3. Position the cursor on the template identifier name in its definition and do a right click.
  4. Select Refactoring >> Merge Templates.
  5. Choose the new name to identify the merged common template.
  6. Check merge preview to confirm correct operation.

Refactoring Suggestions

Each time you save a changed TTCN-3 file (supposing the TRex Nature is enabled for your project), it is analysed to provide refactoring suggestions.

Use the 'Problems' tab to find suggestions for applying refactorings to a template. Yellow warning signs indicate problems which might benefit from refactoring.

By default, TRex groups warnings by type. You case you have chosen a different grouping, you may revert to it as follow: Click on the white triangle on the upper right-hand site of the "Problems" view >> Group By >> Type.

  1. Double click on a problem to jump to the location in the test suite.
  2. Right click on a problem and select Quick Fix to let TRex suggest a solution. (Note: currently Quick Fix does not work for all located problems.)
    1. In the subsequent dialog you may select Find Similar Problems to select several locations where the same fix (i.e. refactoring) shall be applied.
    2. Press OK to apply the suggested fix.

If no refactoring suggestions are displayed, your TTCN-3 file has either really no issues or you shall refer to question "Why are metrics and refactoring suggestions marker not calculated?" from the FAQ.

Disabling/Enabling Metrics and Refactoring Suggestions

The TRex Nature and a corresponding builder are responsible for creating metrics and refactoring suggestions.

A per project property allows to completely disable/enable the builder which performs metrics calculation/issue detection:

  1. Open the project properties (by selecting a project in the Navigator and context menu or main menu Project >> Properties).
  2. Go to the TRex Settings.
  3. Select or deselect Enable Metrics Calculation and Refactoring Rule Detection.
  4. If this setting was previously disabled, it might be possible that you need to trigger metrics calculation/issue detection by applying a change to a TTCN-3 file in your project and subsequently saving that change.

Some refactorings, e.g. Merge templates, require that refactoring suggestion warnings are generated. Hence, you will get an error if you try to apply these refactorings when metrics calculation/issue detection is disabled.

Compiler Integration

Currently, we support only calling Telelogic Tau G2/Tester on Microsoft Windows:

  1. Tell TRex where it can find the t3cg TTCN-3 compiler: Window >> Preferences... >> TRex TTCN-3 >> TAU Integration. There, enter the directory where bin\t3cg.exe is located.
  2. In the Package Explorer, select a TTCN-3 file or a whole project respectively. Afterwards, three icons (of grey and pink color) are selectable from the toolbar . They will invoke the t3cg TTCN-3 compiler: Analyze with TAU Tester, Compile with TAU Tester, Build Test Executable.
    1. In case these icons are not displayed: Go to Window >> Customize Perspective >> Commands and make sure that TAU Actions are enabled.