[Previous] [Next] [Contents] [Index]

    Tutorial: The Basics of ITEX on UNIX

This tutorial is intended as an easy introduction to ITEX for the newcomer. It is also assumed that you have some basic knowledge about UNIX. In addition, to find ITEX meaningful to use, you have to understand TTCN.

Note:  UNIX version

This is the UNIX version of the tutorial. The Windows version can be found in Tutorial: The Basics of ITEX in Windows.

Note: 

This document is an ITEX primer and is not intended to provide a tutorial on TTCN. The volume ITEX Methodology Guidelines introduces some basic TTCN features presented with the aid of a simple example.

Table of Contents 

Purpose of This Tutorial

The purpose of this tutorial is to make you familiar with the basic functions of ITEX. The sections in this chapter are to be read sequentially. You will start by setting up the ITEX environment. Then you will create a TTCN test suite, edit the tables in the test suite and apply some basic ITEX tools.

It is assumed that you know how to use UNIX but that you have no or little previous knowledge about ITEX. However, to understand the full use of ITEX, you should have knowledge of TTCN. The volume ITEX Methodology Guidelines introduces some essential TTCN features, presented with the aid of a simple example.

Setting Up the ITEX Environment

It is assumed that ITEX (or Telelogic Tau) has been installed correctly, according to the instructions in the Installation Guide. The Telelogic Tau installation directory is pointed out by the environment variable $telelogic. This variable has to be set correctly in your UNIX environment.

  1. The ITEX commands are made available if you add the Telelogic Tau bin directory to the environment variable PATH:

    2. setenv PATH ${PATH}:$telelogic/bin
  2. Also set the environment variable MANPATH to include the ITEX and the X11 man directories, to make the manual pages available:

    3. setenv MANPATH \ ${MANPATH}:$telelogic/itex/man:$telelogic/X11/man

If you type man itex, the UNIX manual entry for ITEX will be displayed. It describes the switches that may be used to set the default settings of the dialog options.

To be able to use the on-line help, you need an HTML viewer. The Telelogic Tau Help Viewer is provided in the release but Netscape and Internet Explorer are also supported.

The default is to show the on-line help with the provided Telelogic Tau Help Viewer, but the setup may have been changed by the system manager.

Starting ITEX

Once the ITEX software has been installed, you can start it from a UNIX shell tool (e.g. an X-term) by the command itex:

After a few seconds, the Organizer window is displayed. The Organizer is the main window from which you have access to the tools in the Telelogic Tau environment.

Figure 29 : The Organizer main window

Extracted pic [22]

A welcome window, where you may read the licensing agreement for Telelogic Tau, will also be displayed. The window disappears as soon as you click the Continue button or perform any action in the Organizer.

The Organizer consists of a main window and a log window. In the main window, five areas -- known as chapters -- are displayed by default:

You may freely use these chapters to hold a number of documents and chapters may also be renamed, deleted and created -- the actual use is a matter of personal taste.

More information about customizing the chapters can be found in Customizing the Organizer Chapters.

Creating a TTCN Test Suite Document

What You Will Learn

Setting the Source and Target Directory

You will begin by setting the source and target directory in the Organizer. The source directory is where your new documents will be saved by default. The target directory is where generated files are put. Both of these directories must already exist -- they cannot be created in the Organizer.


Extracted pic [31]
  1. Double-click the source directory icon in the Organizer window.
    • You may also select the source directory icon and then select Edit from the Edit menu in the Organizer or select Set Directories from the File menu.

Figure 30 : The Set Directories dialog

Extracted pic [24]

  1. Select the source directory by writing the path in the text field or by browsing in the dialog that is opened when you click the folder button. Make sure that you have write access to the directory.
  2. In the same way, you can change the target directory.
  3. Click OK in the Set Directories dialog.

Creating a New Test Suite

When you have set the source and target directories, you should create a new TTCN document of type test suite or modular test suite:

  1. Select the chapter TTCN Test Specification in the Organizer.
  2. Select Add New from the Edit menu in the Organizer.

    3. The Add New dialog is opened. In the dialog you should set the document type and name.

Figure 31 : Add New dialog

Extracted pic [1]

  1. Select TTCN and Test Suite or Modular Test Suite in the New document type list.
  2. Type Example_A in the New document name field.
  3. Make sure that the option Show in editor is selected.
  4. Click the OK button.

    5. A new TTCN document of type test suite or modular test suite is created in the source directory. At the same time, a TTCN icon is created in the Organizer. After that, the ITEX Browser window is opened. The Browser will show the new test suite in a collapsed format.

Figure 32  : The Browser window with a collapsed modular test suite

Extracted pic [3]

Using the Browser

What You Will Learn

Expanding and Collapsing the Test Suite

The Browser displays the test suite in a collapsed format, which is indicated by the three dots after the items in the test suite.

To expand the entire test suite:

  1. Select the top node in the Browser, that is Example_A.
  2. Select Expand Tree from the View menu.

Shortcut: 

  • <Shift+e> (Expand Tree)

Figure 33 : The Browser window with the expanded
modular test suite and no selected items

Extracted pic [4]

  1. Deselect the test suite by selecting Deselect All from the pop-up menu.

Shortcut: 

  • <Ctrl+\> (Deselect All)

To collapse the test suite:

Shortcut: 

  • c (Collapse)
  • e (Expand -- does not have the same effect as Expand Tree)
  • <Shift+e> (Expand Tree)

Note that Expand and Collapse only work on a single selection. If more than one item or if no item is selected, the Collapse, Expand and Expand Tree commands are dimmed. In the following, it is assumed that the test suite is completely expanded in the Browser.

You should also note that items in bold font represent the static (structural) parts of the test suite that cannot be opened or edited. The items in normal, plain font represent TTCN tables, which of course can be opened and edited.

Building a Test Suite

You are now going to add a simple TTCN table to your test suite.

To add a PCO Type to Example_A in the Browser:

  1. Select PCO Type Declarations in the Declarations Part.
  2. Select Add from the Browser Edit menu.

    3. Note that Add only works when a single item is selected.

Shortcut: 

  • <Ctrl+Shift+Ins> (Add)

  1. Rename the PCO type NoName by opening the pop-up menu on NoName and selecting Rename from it.

Shortcut: 

  • First click on NoName, then press r (Rename).

  1. In a similar manner as described above, you should also add the following items:

Figure 34 : The Browser window showing some of the newly added items

Extracted pic [7]

The next step is to edit the tables that you just added.

Using the Table Editor

What You Will Learn

Opening the Table Editor

The Table Editor window is opened when you double-click on a table in the Browser window.

Figure 35 : The test case TEST_CASE_1 which has not yet been edited

Extracted pic [8]

Editing the Test Case Table

As you can see, the TEST_CASE_1 table, or any other table, consists of fields where text may be inserted and edited. You are now going to edit the contents of TEST_CASE_1:

  1. Click in the Purpose field and type some text, for example:
    This is an example test case for the ITEX tutorial    .
  2. Type some text in the Description field, e.g. Example test case.
    3. It is also possible to type text in the other fields but you do not have to do that in this tutorial. Note that the Group field is not editable. The contents of this field is always kept updated by ITEX from the Browser structure.
  3. Press <Ins> or <Insert>.

    4. A new, automatically numbered, empty line is added to the body of the table.
  4. Type L! SENT in the Behaviour description field of the new line.

Note: 

The misspelling of SEND is intentional!

  1. Type S1 in the Constraints Ref field.
  2. Press <Ins> or <Insert> to add another new line.
  3. Type +TEST_STEP_1 in the Behaviour Description field of row 2.

    4. Note that the text is automatically indented.

Figure 36  : The test case TEST_CASE_1 when it has been edited
The misspelling of "SEND" is intentional.

Extracted pic [9]

Copying and Pasting Text and Table Rows

Before you close the editor you may want to try to copy and paste text and rows in the table:

Shortcut: 

  • <Ctrl+x> (Cut a row)
  • <Ctrl+c> (Copy a row)
  • <Ctrl+v> (Paste a row)
  • <Ctrl+Meta+v> (Paste After)
  • <Ctrl+Shift+v> (Paste Last)
  • <Ctrl+Right arrow> (moves the input focus right)
  • <Ctrl+Left arrow> (moves the input focus left)
  • <Ctrl+Down arrow> (moves the input focus down)
  • <Ctrl+Up arrow> (moves the input focus up)

Note: 

There are two paste buffers: one for plain text and one for table rows.

When you have finished copying and pasting, make sure that the contents of the table are exactly as in Figure 36.

Closing the Table Editor

Completing the Test Suite

Now you should edit the other tables that you have already added to the test suite. Do this in a similar manner as described above, by using the tables in the following figures as models.

  1. Edit the tables in the Declarations Part of the test suite, that is the PCO type LOWER_PCO, the PCO called L and the PDUs called SEND and RECEIVE:

Figure 37 : The PCO type LOWER_PCO

Extracted pic [25]

Figure 38 : The PCO L

Extracted pic [26]

Figure 39 : The PDU SEND

Extracted pic [27]

Figure 40 : The PDU RECEIVE

Extracted pic [28]

  1. Edit the tables in the Constraints Part of the test suite, that is the PDU constraints called S1 and R1:

Figure 41 : The PDU constraint S1

Extracted pic [5]

Figure 42 : The PDU constraint R1

Extracted pic [29]

  1. Edit the test step called TEST_STEP_1 in the Dynamic Part of the test suite:

Figure 43 : The test step TEST_STEP_1

Extracted pic [12]

  1. Close all Table Editors when you have finished editing.
  2. Save the test suite by selecting Save in the File menu.

Analyzing the Test Suite

What You Will Learn

Analyzing the Test Suite

You are now going to analyze the test suite:

  1. Select Analyze from the Browser Tools menu.

    2. The Analyzer dialog is opened. You do not have to change the settings in this tutorial.

Figure 44 : The Analyzer dialog

Extracted pic [6]

  1. Click Analyze.

    2. The log window is opened. If you have edited the test suite as described above, the log should show a single error message:

Figure 45 : The ITEX log window showing one error

Extracted pic [14]

Finding and Correcting the Error

To find the erroneous table:

  1. Select the test case name in the log.

Figure 46 : Selecting text in the ITEX log

Extracted pic [15]

  1. Select Find Table from the Browser Tools menu.

    2. The table will be found and displayed. In the first behaviour line you can see that you have written SENT instead of SEND.

    Note that the error line is marked in red. In the Browser, the erroneous table is also marked with a red bar.
  2. Correct the error, i.e. change SENT to SEND.
  3. Analyze the table by selecting Analyze from the Table Editor Tools menu.

    4. You will now have a small test suite that is syntactically correct. This means that the red markings will disappear.

    You may also close the log window.

Creating TTCN Tables in Other Ways

The methods described below make it faster and more efficient to create TTCN tables. They also avoid annoying spelling errors and reduces the amount of text that needs to be typed.

What You Will Learn

Copying and Pasting

You shall now practice another way of creating a TTCN table, namely by copying and pasting it.

  1. Find the PDU called SEND in the Browser.
  2. Copy the SEND PDU by using the popup menu.
  3. Find the PDU Constraint called S1.
  4. Open the pop-up menu on S1 and select Paste Before from it.

    5. The SEND copy is pasted before S1.

Editing the New Table

  1. Open the new SEND table.

    2. The Table Editor window is opened displaying the table. As you can see, the PDU Type field and the Field names are filled in. Now you just have to change the name and insert values in Field_1 and Field_2.
  2. Type a new name in the Constraint Name field, e.g. S2.
  3. Give Field_1 the value 3 and Field_2 the value TRUE in the Field Value column.
  4. Analyze the entire test suite as described in Analyzing the Test Suite.

Using the Data Dictionary

This section contains an example of an efficient way of creating test cases. Start by creating a new test case:

  1. Create a new test case.
  2. Name the test case, for example TEST_CASE_2.
  3. Open the test case.
  4. Select Add Send Statement from the Table Editor Data Dictionary menu. The Add Send dialog is opened.

Figure 47 : Add Send dialog

Extracted pic [16]

  1. Click on S2 in the Constraints list.
  2. Click OK.

    3. A send statement has now been automatically generated.
  3. Select the generated line in the Table Editor by clicking in the Nr column.
  4. Select Add Attach Statement from the Table Editor Data Dictionary menu. The Add Attach dialog is opened.

Figure 48 : Add Attach dialog

Extracted pic [23]

  1. Click OK.

    2. A new line has been added to the table.

Deleting the Tables

For the remainder of the tutorial you will not need the two tables that you have just created. You should therefore delete them.

  1. Select Deselect All from the pop-up menu in the Browser.
  2. Select TEST_CASE_2.
  3. Select the PDU Constraint S2, while at the same time pressing <Ctrl>.
  4. Select Delete from the Edit menu. The items are deleted.

Selecting Browser Items

The Selector is a tool that you may use when you want to make selections of Browser items. Before you apply the Selector, the Browser must already contain a selection.Then you can specify, with the Selector, if you want to increase, decrease or replace the existing selection.

Based on the selections in the Browser, you can make sub Browsers. A sub Browser works as the normal ITEX Browser, but it does not contain the entire test suite -- only selected parts.

What You Will Learn

Selection 1

Suppose that you wish to select all the tables in the test suite that reference the PDU called SEND:

  1. Deselect the entire test suite.
  2. Select the single PDU called SEND.
  3. Select Selector from the Browser Tools menu.

    4. The Selector dialog is opened:

Figure 49 : The Selector dialog

Extracted pic [30]

  1. Select the Extend option in Select Mode.
  2. Choose the Referenced by option in the Relations box.

    3. You do not have to change any other options.
  3. Click the Select button.

    4. Now take a look at the Browser. You should see that not only is the SEND PDU selected but also the constraint S1 and the test case TEST_CASE_1. Only these objects reference the SEND PDU. (You may have to scroll the Browser to see them all.)

Selection 2

As another example, suppose that you wish to find all behaviour tables that have the character 1 included in their identifier and have a PASS verdict in the table:

  1. Select the entire test suite.
  2. Select Selector from the Browser Tools menu.

    3. The Selector dialog is opened.
  3. Type 1 in the Name restriction field.

    4. This means that the names of the tables that you want to select should include the character 1.
  4. Select Test Case Dynamic Behaviour, Test Step Dynamic Behaviour and Default Dynamic Behaviour in the Type Restriction box.
  5. Type PASS in the Content restriction field.

    6. This means that there must be at least one occurrence of the word PASS in the selected tables.
  6. Select Restrict in the Select mode box.

    7. In other words, the intention is to select all behaviour tables that have a 1 in their names and that have a PASS substring in the contents of the table.

    The Analyze status and Relations options should not be set.
  7. Click the Select button.

    8. Only TEST_STEP_1 is selected in the Browser window.

Selection 3

Compare the result of the selection above with the following:

  1. Select the entire test suite.
  2. Apply the Selector with almost the same options as described above.
  3. Click the Selector button.

    4. This time, both TEST_CASE_1 and TEST_STEP_1 are selected, because a PASS substring does not appear in the test case.

Creating a Sub Browser

It might be suitable at this point to create a sub Browser of the selection that you have just created (i.e. just the items TEST_CASE_1 and TEST_STEP_1):

Figure 50 : A sub Browser which only contains TEST_CASE_1 and TEST_STEP_1.

Extracted pic [17]

Generating Overview Tables

To complete the test suite, you also have to generate the Test Suite Overview tables -- that is the Test Suite Structure, the Test Case Index, the Test Step Index and the Default Index tables -- and the TTCN Module Overview -- that is the TTCN Module Structure and the Index tables.

None of these tables are editable. Instead, you have to make the changes in the corresponding tables. The reason for this is that the overview tables should be consistent with the TTCN document.

To generate the overview:

  1. Select Generate Overview from the Browser Tools menu.

    2. The Generate Document Overview dialog is opened.

    ITEX also generates the page numbers. You can set the start page number in this dialog, but you do not have to do that in this tutorial.
  2. Click the Generate button in the dialog.
  3. Open the Test Case Index table.

    4. You will see that the Description field has been generated from the additional Description field in the header of the test case. To make changes, you have to edit the tables from which the overview was generated and then generate the overview again.
  4. Close the Test Case Index table.

Printing the Test Suite

You should by now have a test suite that is syntactically correct and which includes an up to date overview. If you want to, you can print it.

Printing the Entire Test Suite

To print the whole test suite:

  1. Select the entire test suite.
  2. Select Print from the Browser's File menu.

    3. The Print Document dialog is opened.
  3. Make sure that Output Device names a printer that is recognized by your system.

    4. You do not have to change any other settings in this tutorial.
  4. Click the Print button if you want to print the entire test suite.

Printing Parts of the Test Suite

It is also possible to print parts of the test suite.

To print, say, just the Constraint tables:

  1. Select only S1 and R1.
  2. Select Print from the Browser File menu.

    3. The Print Document dialog is opened.
  3. Make sure that Output Device names a printer that is recognized by your system.

    4. You do not have to change any other settings in this tutorial.
  4. Click the Print button if you want to print the Constraint tables.

Creating Reports

The Reporter tool is used for presenting status information on selected items in the Browser. The information may for example be analysis status and modification date.

To make a list of the full amount of information:

  1. Select the entire test suite.
  2. Select Reporter from the Browser Tools menu.

    3. The Reporter dialog is opened.

Figure 51  : The Reporter dialog

Extracted pic [18]

  1. Set the options as shown in Figure 51, that is select all options in the list of actions, normal verbosity and the formatting nl + tab. The latter means that each list entry will be printed on a new line and the components in the list entry will be separated by tabs.
  2. Click the Reporter button.

    3. The options set in the dialog will produce the full amount of information available, a portion of which is illustrated below:

Figure 52 : Test suite information

Extracted pic [19]

You may also find it practical to apply the Find Table tool to text that is marked in the log window:

  1. Mark the name of a table in the log window
  2. Select Find Table from the Browser Tools menu.

    3. The table is found and opened.

Exporting and Importing

What You Will Learn

Exporting a Test Suite to MP Format

You shall now convert the test suite to TTCN-MP format:

  1. Select the entire test suite in the Browser window.
  2. Select Convert to MP from the File menu.

    3. The Convert to MP dialog is opened, in which you may specify the name of the new document and where it is to be saved.

Figure 53 : The Convert to MP dialog

Extracted pic [20]

  1. Select the directory path in the Directories box.
  2. Type the file name that you wish the exported file to be called. In this example the file name is Example_suite.mp.

    3. Note the suffix .mp (used by convention). You are now ready to convert the file.
  3. Click Convert to export the test suite.

    4. The TTCN-MP file for the test suite can now be found in the file Example_suite.mp. You can check it if you like.

Importing a Test Suite from MP Format

Your next task is to import the TTCN-MP file that you have just exported. Do not close the existing open test suite -- you need that later.

  1. Select Convert to GR from the Generate menu in the Organizer. The Convert to GR dialog is opened:

Figure 54 : The Convert to GR dialog

Extracted pic [2]

  1. Select Convert TTCN MP to TTCN GR.
  2. Click the folder icon of the Source MP file name field. The Select Source MP file dialog is opened.
  3. Click the file that you want to convert, when you have found it in the Files list. In this case the file is Example_suite.mp.
  4. Click the OK button.
  5. Click the folder icon of the Destination directory for generated TTCN GR field. The Select Destination Directory dialog is opened.
  6. Select the destination directory, i.e. where you want the converted document to be saved.
  7. Click the OK button.
  8. Click the Convert button in the Convert to GR dialog.

    9. The file is converted and is stored in a file with a generated file name in the given directory. The generated file name is the MP file name with the extension .itex. The name of the generated file is shown in the Organizer log. (You will have to open the log window to see it.)

Now perform the following:

  1. Select the TTCN Test Specification chapter in the Organizer.
  2. Select Add Existing in the Edit menu in the Organizer. The Add Existing dialog is opened.
  3. Select the file that you just converted, that is Example_suite.itex.

    4. Either type the filename and the path or click the folder button to select the file. (In that dialog, you may have to change the filter to *.itex. When you have selected the file, click OK.)
  4. Make sure that the Show in editor option is selected.
  5. Click the Add button.

    6. The test suite is now added in the TTCN Test Specification chapter and it is opened in the Browser.
  6. In the Browser, rename this test suite as Example_B.
  7. Expand the entire test suite.
  8. Analyze the entire test suite.
  9. Do not close Example_B, you will need it in the following exercise.

Replacing, Comparing and Merging

In this exercise you are going to merge the two test suites, the Example_A and the Example_B that you have just created. First you should change some names in one test suite though, -- to make it different -- and then compare it with the other.

What You Will Learn

Replacing a Text String

The first thing you should do is to change some names in Example_B. The reason for this is that there would be no use comparing the documents -- which you are soon going to do -- if they both are the same.

The Replace tool is available from both the Browser and the Table Editor. In this exercise you will only apply it from the Browser. However, note that in the Browser, Replace works on selected items in the test suite but in the Table Editor it only works within the table that is opened.

  1. Select the entire test suite Example_B.
  2. Select Replace from the Browser Edit menu.

    3. The Replace dialog is opened:

Figure 55  : The Replace dialog

Extracted pic [13]

  1. Type 1 in the Search pattern field.
  2. Type 2 in the Replace string field.

    3. These settings will change all occurrences of 1 to 2. For example TEST_CASE_1 will become TEST_CASE_2.
  3. Click the Replace button.

    4. In the ITEX log window you should see that 12 replacements were made.

    Note that this replacement also changes text within the tables. For example, the behaviour line+TEST_STEP_1becomes+TEST_STEP_2.

Comparing Two Documents

If you have used Replace as described above, you may now apply the Compare tool to see if any similarities exist:

  1. Ensure that the test suites Example_A and Example_B are opened.
  2. Select the entire test suite Example_B
  3. Select Compare from the Browser Tools menu.

    4. The Compare Documents dialog is opened:

Figure 56  : The Compare dialog

Extracted pic [21]

  1. Make the dialog settings as depicted in Figure 56.

    2. This will compare the test suite Example_A with the selection that you made in Example_B, in this case the entire test suite.

    Also make sure that Example_A is selected in the Documents field in the dialog.
  2. Click the Compare button.

    3. The comparison will deselect all items in the Browser for Example_B that do not match with items in Example_A. What remains are the items that are the same in both test suites, namely the lower PCO L and the PDUs SEND and RECEIVE. These tables will also be presented in the ITEX log.
  3. Delete the selected items from Example_B.

    4. The only items left now are the ones that differ between the two test suites. You are now ready to try a merge.

Merging Two Documents

The Merge tool is used for merging one TTCN document (complete or partial) into another. This only works on condition that the documents do not conflict, that is, if an item in one document has the same name as another item in the other document. This will not be a problem now, as you have already compared the documents and deleted the similarities.

The final exercise in this tutorial is that you should merge what is left of Example_B into Example_A:

  1. Select the entire suite Example_B.
  2. Select Merge from the Browser Tools menu.

    3. The Merge Documents dialog is opened:

Figure 57 : The Merge Documents dialog

Extracted pic [11]

  1. Select Example_A in the Documents chapter. That is the suite that you are going to merge Example_B into
  2. Click the Merge button.

    3. If you look at the Example_A Browser, you should see that the suites have been merged into one. This is also depicted in Figure 58.

Figure 58  : The Example_B has been merged into Example_A

Extracted pic [10]

So Far ...

You should now have learned how to create a test suite and what the test suite looks like in the Browser. You have also learned to create and edit tables and how to work with the Table Editor. Other things you should have learned is how to analyze the test suite and how to find errors.

Some other ITEX functionality that you have used are selecting, generating the overview, printing, making reports, converting to MP and back to GR, replacing, comparing and merging.

By practicing this tutorial you have probably not achieved any knowledge about TTCN. If you want to know more about the basics of TTCN you may read the ITEX Methodology Guidelines. That volume is, however, not a hands-on tutorial on TTCN.

The following tutorial is Tutorial: The ITEX Simulator on UNIX. Before you start practising that, you should know how to use the SDT Simulator. A tutorial on that can be found in Tutorial: The SDT Simulator.

[Previous] [Next] [Contents] [Index]