UserScenarios.md

# User guides 

TDL and TOP can be used in different ways. Depending on the specific goals, different parts of TDL and TOP may be relevant for a given usage scenario. 
For different starting points and end goals, the following common use cases may come into question:

 - [Selected TOP user scenarios](UserScenarios.md#selected-top-user-scenarios)
 
    - [User control of the analysis level](UserScenarios.md#sec-user-control-of-the-analysislevel)
    - [Textual modelling](UserScenarios.md#sec-textual-modelling)
    - [TDL Wizards and Perspective](UserScenarios.md#sec-tdl-wizards-and-perspective)
    - [Graphical modelling](UserScenarios.md#sec-graphical-modelling)
    - [Importing protocol specifications](UserScenarios.md#sec-importing-protocol-specifications)
        - [Using TDL with OpenAPI™ Specifications](UserScenarios.md#sec-using-tdl-with-openapi-specifications)
        - [Using TDL with ASN.1 Specifications](UserScenarios.md#sec-using-tdl-with-asn-specifications)
        - [Using TDL with YANG Specifications](UserScenarios.md#sec-using-tdl-with-yang-specifications)>
    - [Creating test objectives based on TDL meta-model](UserScenarios.md#sec-creating-test-objectives-based-on-tdl-meta-model)
        - [Unified Definition of Test Puposes and Test Descriptions](UserScenarios.md#unified-definition-of-test-purposes-and-test-descriptions)
    - [Generate TD from TO](UserScenarios.md#sec-generate-td-from-to)
    - [Export to Word](UserScenarios.md#sec-export-to-word)
    - [Conversion to TTCN-3](UserScenarios.md#sec-conversion-to-tttn3)
 - [Defining Structured Test Objectives](UserScenarios.md#sec-defining-structured-test-objectives)
 - [Transforming Structured Test Objectives into Test Descriptions](UserScenarios.md#sec-transforming-structured-test-objectives-into-test-descriptions)
 - [Defining Test Descriptions](UserScenarios.md#sec-defining-test-descriptions)
 - [Transforming Test Descriptions into TTCN-3 Test Cases](UserScenarios.md#sec-transforming-test-descriptions-into-ttcn-3-test-cases)
 

  



## Selected TOP user scenarios <a name="selected-top-user-scenarios"></a>


### Overview

This section describes a set of user scenarios that illustrate how the features of the TOP tools can be used for specific testing tasks.


### User control of the analysis level <a name="sec-user-control-of-the-analysislevel"></a>

<a name="uc1-openclose"></a>
1. **Usage scenario:** The user saves and re-opens an incomplete TDL specification. The incomplete specification and associated analysis results are maintained.

2. **Usage scenario:** Incompatible assignment of types, e.g. assignment of a boolean value to integer type or exceeding the limit of a restricted list type (collection).  

3. **Usage scenario:** The user may set the level of analysis performed by TOP tool when developing the TDL test model. 

From the TDL toolbar shown in [Figure TDL toolbar](#figure-TDL-toolbar) the analysis level of the specification can be set.

<figure style="margin-left:auto; margin-right:auto; width:20%"><a id="figure-TDL-toolbar"></a>
  <img src="images/TdlToolbar.png" alt="TDL toolbar">
  <figcaption style="text-align:center; font-weight:bold">Figure 1: TDL toolbar</figcaption>
</figure>


The left "V" button sets the constraint validation to be automatically performed when editing the model. The selection mode is shown by marking the button with a darker 
shade when constraint validation is active. The rightmost "V" button causes the model to be analysed for syntactical errors. Errors are shown in the editor and in the problem view. 
Alternatively these settings can be controlled from the TDL menu shown in [Figure 2](#figure-tdl-menu-items).


<figure style="margin-left:auto; margin-right:auto; width:20%"><a id="figure-tdl-menu-items" ></a>
  <img src="images/TdlMenuList.png" alt="TDL Menu items">
  <figcaption style="text-align:center; font-weight:bold">Figure 2: TDL Menu items</figcaption>
</figure>


### Textual modelling <a name="sec-textual-modelling"></a>


1.	**Usage scenario:** Refactoring and renaming  

Reuse of existing TDL specification for which a slight modification is needed to use it in a context. E.g. a package containing TDL type definitions or configuration declarations may be re-used in a specific test specification context. To increase the readability the TDL TOP tool refactoring features may be used.
To use the rename feature, select an instance of an element and from the options when right-click on the mouse select option "Rename Element" (alternatively use key shortcut Alt + Shift + R). Type in the new element name in the dialog box.


<figure style="margin-left:auto; margin-right:auto; width:30%">
<img src="images/RenameDialog.png" alt="Rename dialog">
<figcaption style="text-align:center; font-weight:bold">Figure 3: Rename dialog box</figcaption>   
</figure>


In case the selected element is local to a single file the rename feature is executed inline without the Rename Element dialog.

<ol start=2>
<li> <b>Usage scenario:</b> Code formatting and syntax highlighting</li>
</ol>

The syntax coloring can be set from the "Syntax Coloring" dialog box: Open the "Window" menu and select "Preferences". Select the TDL tool used, ("TDLan2", "TDLtx", or "TDLtxi"), expand the subitems and select "Syntax Coloring".


<figure style="margin-left:auto; margin-right:auto; width:70%"><a id="figure-code-formatting-settings-dialog-box" ></a>
<img src="images/SyntaxColoring.png" alt="Code formatting settings">
<figcaption style="text-align:center; font-weight:bold">Figure 4: Code formatting settings dialog box</figcaption>   
</figure>


In the code formatting dialog box the preferences for different syntax elements can be set, see <a href=#figure-code-formatting-settings-dialog-box>Figure 4</a>.

<ol start=3>
  <li>  <b>Usage scenario:</b> Syntax auto complete</li>
</ol>

To use the syntax auto complete feature type in an initial part of a keyword or model element, press "Ctrl + Space", and the syntax auto complete options available in the context are displayed.


<figure style="margin-left:auto; margin-right:auto; width:70%">
<img src="images/SyntaxAutoCompletion.png" alt="Syntax auto complete">
<figcaption style="text-align:center; font-weight:bold">Figure 5: Syntax auto complete example</figcaption>   
</figure>


Press "Enter" and the selected text is inserted.

<ol start=4>
  <li> <b>Usage scenario:</b> Validation results presentation </li>
</ol>

The TOP tools support syntax check for the textual and graphical notations defined in the TDL standard. Syntax errors are indicated in the Problems view as well as in the editor 
as shown in <a href=#figure-syntax-error-presentation>Figure 6</a>.


<figure style="margin-left:auto; margin-right:auto; width:70%"><a id="figure-syntax-error-presentation" ></a>
<img src="images/syntaxerror.png" alt="Syntax error presentation">
<figcaption style="text-align:center; font-weight:bold">Figure 6: Syntax error presentation</figcaption>   
</figure>


The TOP tool offers semantic constraints check of a TDL specification. When this check is to be performed can be controlled from the TDL tool bar or the TDL menu item list. 
Either the check is performed when the "Validate TDL model" is selected or the check is performed automatically when the TDL model is updated, if the "Automatically validate 
TDL model" is selected. In <a href=#figure-constraint-error-presentation>Figure 7</a> an example of a semantics check is illustrated.


<figure style="margin-left:auto; margin-right:auto; width:70%"><a id="figure-constraint-error-presentation" ></a>
<img src="images/ValidationView.png" alt="Constraint error presentation">
<figcaption style="text-align:center; font-weight:bold">Figure 7: Constraint error presentation</figcaption>   
</figure>


<ol start=5><a id="us-templates-usage-and-definition"></a>
  <li> <b>Usage scenario:</b> Templates - usage and definition </li>
</ol>  
  
For each of the notations supported by the TOP tools the specific editor provides templates available in the context of the cursor position. The templates available at a given 
cursor position are shown when "Ctrl + Space" are pressed. When a template is selected pressing "Enter" inserts the template and allows for parameters to be modified.
An example of templates available in the context of a configuration specification is shown in <a href=#figure-templates-available-in-a-configuration-specification-context>Figure 8</a>.


<figure style="margin-left:auto; margin-right:auto; width:70%"><a id="figure-templates-available-in-a-configuration-specification-context" ></a>
<img src="images/TemplatesInContext.png" alt="Templates available in a configuration specification context">
<figcaption style="text-align:center; font-weight:bold">Figure 8: Templates available in a configuration specification context</figcaption>   
</figure>


The user may define additional templates for the different editors available in the TOP tool. The template editor is accessed via the "Window" menu item, option "Preferences". 
From the Preferences dialog box the specific TOP editor can be selected and user-defined templates be created. <a href=#figure-template-dialog-box>Figure 9</a> illustrates a list of templates defined for the 
TDLtx editor.


<figure style="margin-left:auto; margin-right:auto; width:70%"><a id="figure-template-dialog-box"></a>
<img src="images/TDLtxTemplates.png" alt="Template dialog box">
<figcaption style="text-align:center; font-weight:bold">Figure 9: Template dialog box</figcaption>   
</figure>


### TDL Wizards and Perspective  <a name="sec-tdl-wizards-and-perspective"></a>

Wizards provide support to create functional TDL project either with textual or graphical models according to user choice:
1.	**User scenario:** Create new TDL project
2.	**User scenario:** Reference to predefined model elements
3.	**User scenario:** Using predefined skeletons
4.	**User scenario:** Importing interface specifications

In order to create a new TDL specification:- Select from File menu item New and in the submenu select "Project". In the dialog box "Select a wizard", select the wanted 
TDL project, e.g. TDLtx for a textual TDL specification.


<figure style="margin-left:auto; margin-right:auto; width:50%"><a id="figure-wizard-selection-dialog-box"></a>
<img src="images/NewProjectSelectWizard_TextualProject.png" alt="Wizard selection dialog box">
<figcaption style="text-align:center; font-weight:bold">Figure 10: Wizard selection dialog box</figcaption>   
</figure>


Press "Next" and in the dialog box specify a name of the project to be create. If the default location is not to be used, uncheck the "Use default location" and specify 
the location of the project.


<figure style="margin-left:auto; margin-right:auto; width:50%"><a id="figure-creating-a-new-template-tdl-project"></a>
<img src="images/NewProjectTextualProjectName.png" alt="Creating a new template TDL project">
<figcaption style="text-align:center; font-weight:bold">Figure 11: Creating a new template TDL project</figcaption>   
</figure>


Select "Next" to open the dialog box for select among parameterized TDL textual project templates.


<figure style="margin-left:auto; margin-right:auto; width:50%"><a id="figure-create-new-tdl-project-with-support-for-openapi"></a>
<img src="images/NewProjectSelectTemplate.png" alt="Create new TDL project with support for OpenAPI">
<figcaption style="text-align:center; font-weight:bold">Figure 12: Create new TDL project with support for OpenAPI</figcaption>   
</figure>