diff --git a/Home.md b/Home.md index 1088d35d981c4451a135c43090be368ec8b63a83..e3ec12b00f773215cc8e650cc090809937f31365 100644 --- a/Home.md +++ b/Home.md @@ -26,6 +26,7 @@ The project is an initiative of ETSI TC MTS – the ETSI committee that standard * [[Installation]] * [[Usage]] +* [[UserScenarios]] diff --git a/Installation.md b/Installation.md index a740e60c22cae3bf510b88e28a3b6fc464e0a1c0..76eed402b987de2124e93beff416cfbb88d2fe09 100644 --- a/Installation.md +++ b/Installation.md @@ -21,4 +21,4 @@ To add the new repository to Eclipse, follow these steps: After the installation Eclipse will need to be restarted. -Next step: [Usage of the installed plugins.](Usage) +Next step: [Usage of the installed plugins.](Usage.md) diff --git a/Usage.md b/Usage.md index 69b1915238af4718327c7d1469d74fa370ba02bb..353b995a67dc5954675505538106a4deb0ff2f06 100644 --- a/Usage.md +++ b/Usage.md @@ -38,14 +38,17 @@ After Eclipse restarts, you should be able to see a `W` button in the toolbar be 1. Open a **tplan2** or a **tdltx/tdltxi** document containing structured test objectives and/or test purpose descriptions in Eclipse like this -[![Tdlan example.PNG](https://tdl.etsi.org/wiki/images/8/8a/Tdlan_example.PNG)](https://tdl.etsi.org/wiki/index.php/File:Tdlan_example.PNG) +![Tdlan_example.PNG](images/Tdlan_example.PNG) +[ [![Tdlan example.PNG](https://tdl.etsi.org/wiki/images/8/8a/Tdlan_example.PNG)](https://tdl.etsi.org/wiki/index.php/File:Tdlan_example.PNG) ]: # 2. Click on the `W` button in the toolbar and select the preferred template. It may happen that the Eclipse window is not responsive to clicks during the export execution, it does not mean that it is an error. 3. When the processing is done, the newly created Word document will be in the same folder of the tplan/tdltx/tdltxi file and should appear in the Project Explorer 4. If the file is not shown, select the project, right click and select *Refresh* (or hit F5 on the keyboard) The result will look like: +![Word.PNG](images/Word.PNG) + [![Word.PNG](https://tdl.etsi.org/wiki/images/8/8b/Word.PNG)](https://tdl.etsi.org/wiki/index.php/File:Word.PNG) The result includes relevant parts of the original structured test objective / test purpose description substituted the corresponding placeholders in the templates. Some keywords may be substituted as part of the process (e.g. "entity" keywords, etc.). Textual comments are also included. To exclude certain textual comments from the output, add a "!" prefix in the comment, e.g.: diff --git a/UserScenarios.md b/UserScenarios.md new file mode 100644 index 0000000000000000000000000000000000000000..a84ab313c3d02968a8803f381163a797065ac858 --- /dev/null +++ b/UserScenarios.md @@ -0,0 +1,272 @@ +# 6.1 Usage Scenarios + +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 + +- Defining structured test objectives (or test purposes) with the help of TDL-TO. +- Transforming existing structured test objectives in TDL-TO into TDL test descriptions. +- Defining test descriptions with the help of TDL. +- Transforming existing test descriptions in TDL into TTCN-3 test cases. +- Transforming existing test descriptions in TDL into a target execution language (see clause 9). +- Using existing interface specifications in OpenAPI™ with TDL (see clause 8.2). +- Using existing protocol specifications in ASN.1 with TDL (see clause 8.3). + +## 6.2 Selected TOP user scenarios + +### 6.2.1 Overview + +This clause describes a set of user scenarios that illustrate just how the features of the TOP tools can be used for specific testing tasks. + +### 6.2.2 User control of the analysis level + +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 analysis of the specification the analysis level can be set. + +![TDL Toolbar](images/TdlToolbar.png) + +Figure 6.2.2-1: TDL toolbar + +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. + +![TDL Menu items](images/TdlMenuList.png) + +Figure 6.2.2-2: TDL Menu items + +### 6.2.3 Textual modelling + +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. + +![Rename dialog box](images/RenameDialog.png) + +Figure 6.2.3-1: Rename dialog box + +In case the selected element is local to a single file the rename feature is executed inline without the Rename Element dialog. + +
    +
  1. Usage scenario: Code formatting and syntax highlighting
    2. +
+ +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". + + +![Code formatting settings dialog box](images/SyntaxColoring.png) + +Figure 6.2.3-2: Code formatting settings dialog box + +In the code formatting dialog box the preferences for different syntax elements can be set, see Figure 6.2.3-2. + +
    +
  1. Usage scenario: Syntax auto complete
    2. +
+ +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. + +![Syntax auto complete example](images/SyntaxAutoCompletion.png) + +Figure 6.2.3-3: Syntax auto complete example + +Press "Enter" and the selected text is inserted. + +
    +
  1. Usage scenario: Validation results presentation
    2. +
+ +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 Figure 6.2.3-4. + +![Syntax error presentation](images/syntaxerror.png) + +Figure 6.2.3-4: Syntax error presentation + +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 Figure 6.2.3-5 an example of a semantics check is illustrated. + +![Constraint error presentation](images/ValidationView.png) + +Figure 6.2.3-5: Constraint error presentation + +
    +
  1. Usage scenario: Templates - usage and definition
    2. +
+ +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 Figure 6.2.3-6. + +![Template presentation](images/TemplatesInContext.png) + +Figure 6.2.3-6: Templates available in a configuration specification context + +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. Figure 6.2.3-7 illustrates a list of templates defined for the TDLtx editor. + +![Template dialog box](images/TDLtxTemplates.png) + +Figure 6.2.3-7: Template dialog box + +### 6.2.4 TDL Wizards and Perspective + +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. + +![Wizard selection dialog box](images/NewProjectSelectWizard_TextualProject.png) + +Figure 6.2.4-1: Wizard selection dialog box + +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. + +![Creating a new template TDL project](images/NewProjectTextualProjectName.png) + +Figure 6.2.4-2: Creating a new template TDL project + + +Select "Next" to open the dialog box for select among parameterized TDL textual project templates. + + +![Create new TDL project with support for OpenAPI](images/NewProjectSelectTemplate.png) + +Figure 6.2.4-3: Create new TDL project with support for OpenAPI + + +Select template "TDLtx" and press "Next" to get further options to configure the TDL project. + + +![Create new TDL project with advanced options features](images/NewProjectSelectBasicTDLtxProject.png) + +Figure 6.2.4-4: Create new TDL project using the advanced options features + + +In this dialog box the additional properties of the project may be configured. +If "Advanced" option is set the following options can be selected: + +- The name of path of the project files +- The imported packages +- The name of the project package, default is "Main" + +### 6.2.5 Graphical modelling + +1. **User scenario:** The TOP tool should provide ways to manage diagrams of model elements (create, delete, rename, open). +2. **User scenario:** Visual representation of all model elements should be implemented according to specification. +3. **User scenario:** All model elements and features should be editable either directly on the diagram or via property view. +4. **User scenario:** Negative validation results should be indicated graphically and linked to problem reports. + +To define a TDL model using the graphical editor of the TOP tools, select menu "File" and in the menu select "New "and in the sub-menu list select "TDL project" or use shortcut "Alt-Shift-N". The dialog box shown in Figure 6.2.5-1 appears and a project name can be specified. + + +![Create new TDL graphical project](images/TDLgrNewProj.png) + +Figure 6.2.5-1: Create a new TDL project using the graphical editor + +When the "Finish" button is selected the project is created. In the "Project Explorer " select the project, press the right mouse button, and select option "Create Representation" and the dialog box shown in Figure 6.2.5-2 allow to create a new diagram. + +![Create new TDL graphical diagram](images/TDLgrNewRepresentation.png) + +Figure 6.2.5-2: Create a new diagram + +There are two types of diagrams to create: + +- "Generic TDL" diagram used to specify the package structure, test descriptions, configurations and data; +- "TDL Behaviour" diagram that defines the behaviour of a test description. + +Select the type of diagram to be created, assign a name to the diagram, and press "Finish" to create the diagram. + +NOTE: Initially it is only possible to create a "Generic TDL" diagram as to create a "TDL Behaviour" diagram at least one test description is needed. + +The editors for the two types of diagrams provides access to all graphical elements of the TDL language. The textual parameters can be edited either directly in the graphical element or in the Properties View of a selected element. In Figure 6.2.5-3 the editor for "Generic TDL " diagrams is shown. + +![Generic TDL diagram editor](images/GenericTdlGrEditor.png) + +Figure 6.2.5-3: Generic TDL diagram editor + +Both diagram editors have a pane with all the elements that can be used in the diagram. From the top tool bar a number of general edit functions are available, e.g. select all elements, show and hide elements. Also from the top tool bar the export diagram as an image file is available. The "Properties" view of the editor allows to define the textual parameters of a selected graphical element. + +### 6.2.6 Importing protocol specifications + +The TOP tools support importing external data specifications to TDL data representations with mapping information to the original data specifications. All importers for the external use the "Translate Input to TDL Model" from the "TDL" menu or alternatively the >T> icon on the TDL tool bar. The generated TDL file depends on the type of project the external specification is imported to. The naming convention for the TDL file generated is the original file name extended with "-generated" and with extension according to the importing TDL model type. + +1. **Usage scenario:** Importing OpenAPI specifications according to ETSI EG 203 647 [i.32]. + +For OpenAPI specifications the TOP tools currently supports: +- Importing of data definitions under components/schemas. +- Data mappings to the base OpenAPI definition for traceability. +- Data mappings to the target (Java) data implementation derived from the OpenAPI definitions for executability. + +Further details on how to use OpenAPI specifications with TDL are defined in **clause 8.2 of the present document**. + +
    +
  1. Usage scenario: Importing RESTCONF and YANG specifications.
    2. +
+ +The TOP tools support for importing RESTCONF and YANG data specifications is offered by the conversion of JSON specifications. For YANG data specifications this means that they have to be converted to JSON specifications. + +
    +
  1. Usage scenario: Importing ASN.1 specifications.
    2. +
+ + +ASN.1 data specifications can be converted to a TDL data model. Further details on how to use TDL with ASN.1 data specifications are defined in **clause 8.3 of the present document**. + +### 6.2.7 Creating test objectives based on TDL meta-model + +1. **User scenario:** Use the core TDL syntax for specifying test objectives. + +The TOP tool editors for the standardised textual syntax in ETSI ES 203 119-8 [i.20] support the extended syntax for structured test objectives in ETSI ES 203 119-4 [i.16]. Details on how to use one of the TOP tool textual editors to define structured test objectives are described in **clause 6.7 of the present document**. + +
    +
  1. User scenario: Templates for TO backed by TD, also for constituent parts.
    2. +
+ +The TOP tool textual editors provides context sensitive templates for specification of structured test objectives. Further details on how to use templates are described in **clause 6.2.3. of the present document**. + +
    +
  1. User scenario: Template library for basic configurations and types.
    2. +
+ +The extended syntax for structured test objectives allows for more complete test purpose specification requiring, e.g. configuration specification. For these elements the TOP tool editors provide a template library is available from the template collection of the editors. + +### 6.2.8 Generate TD from TO + +Lossless conversion of TDL test objectives to test descriptions is generally not possible due to conceptual differences between the formalisms. Some of the discrepancies may be overcome by annotating source (and target) models with appropriate information. + +1. **User scenario:** Means to include predefined annotations with TDL models to help guide the conversion process. + +2. **User scenario:** Support for TO to TDL conversion according to element annotations or default (non-functional) mappings for cases where annotations are not provided. + +3. **User scenario:** Generated test descriptions contain references to test objectives from which they originate. + +As the conversion cannot be completely automated the process on how manual steps can support the transformation are defined in **clause 6.4 of the present document**. The TOP tools currently supports: + +- Transforming of inline data descriptions within EventOccurrences into corresponding data types. +- Generation of TestConfigurations based on the EventSequences within the Structured Test Objective. +- Generation of TestDescription skeletons based on the EventSequences within the Structured Test Objective with references to it. +- Importing of the base package and imported packages. + +### 6.2.9 Export to Word + +An essential use case for TDL is its application in producing test specifications, which requires the conversion of models to printable format such as Microsoft Word: + +1. **User scenario:** Export TDL diagrams as images. +2. **User scenario:** Export textual TDL test descriptions to be part of a Word document. +3. **User scenario:** Export test objectives as parts of a Word document. + +The TOP tool graphical editors provide a function to export the current diagram as an image in the format of the users choice. The function is available via the "camera" button shown in Figure 6.2.5-3. +Textual TDL code can be copied from the TDL editors. + +The TOP tools provides a TDL-TO converter for Test Objectives to the Word table format. The TDL-TO converter supports both Structured Test Objectives defined in the example syntax and new the standardised notation. Template files allow to define the layout of the generated Word document. In **clause 5.3.3 in the present document** more information on the TDL-TO converter is defined. + +### 6.2.10 Conversion to TTCN-3 + +1. **User scenario:** Conversion of TDL models to TTCN-3 test suites + +The TOP tools support generation of TTCN-3 according to ES 203 119-6 [i.18]. To use this feature use the T3 button in the TDL tool bar or the TDL Menu item "Transform TDL model to TTCN-3" with the model to be transformed open. In **clause 6.6 of the present document** further information on the translation can be found. + diff --git a/images/GenericTdlGrEditor.png b/images/GenericTdlGrEditor.png new file mode 100644 index 0000000000000000000000000000000000000000..2a349ca28f2c870deea5ebc62645450f8ea8b710 Binary files /dev/null and b/images/GenericTdlGrEditor.png differ diff --git a/images/NewProjectSelectBasicTDLtxProject.png b/images/NewProjectSelectBasicTDLtxProject.png new file mode 100644 index 0000000000000000000000000000000000000000..2819f90d90f9a7c34af6eec8ebd38420abb05ea0 Binary files /dev/null and b/images/NewProjectSelectBasicTDLtxProject.png differ diff --git a/images/NewProjectSelectTemplate.png b/images/NewProjectSelectTemplate.png new file mode 100644 index 0000000000000000000000000000000000000000..239e673061c34bb005edfd6393bc2c3e15be7861 Binary files /dev/null and b/images/NewProjectSelectTemplate.png differ diff --git a/images/NewProjectSelectWizard_TextualProject.png b/images/NewProjectSelectWizard_TextualProject.png new file mode 100644 index 0000000000000000000000000000000000000000..338efa35186b7cdee0542b701bb1cc241e16312b Binary files /dev/null and b/images/NewProjectSelectWizard_TextualProject.png differ diff --git a/images/NewProjectTextualProjectName.png b/images/NewProjectTextualProjectName.png new file mode 100644 index 0000000000000000000000000000000000000000..b41292aeda059687257f79718cf3afe147a92ef6 Binary files /dev/null and b/images/NewProjectTextualProjectName.png differ diff --git a/images/RenameDialog.png b/images/RenameDialog.png new file mode 100644 index 0000000000000000000000000000000000000000..73cdc9ace3c8734be90b0e308103dc4033a64266 Binary files /dev/null and b/images/RenameDialog.png differ diff --git a/images/SyntaxAutoCompletion.png b/images/SyntaxAutoCompletion.png new file mode 100644 index 0000000000000000000000000000000000000000..2803c96e58b93b84bb40eb15419164c05711408b Binary files /dev/null and b/images/SyntaxAutoCompletion.png differ diff --git a/images/SyntaxColoring.png b/images/SyntaxColoring.png new file mode 100644 index 0000000000000000000000000000000000000000..1783637603f6e0c33ddf61bbb38ea414d230e2bb Binary files /dev/null and b/images/SyntaxColoring.png differ diff --git a/images/TDLgrNewProj.png b/images/TDLgrNewProj.png new file mode 100644 index 0000000000000000000000000000000000000000..de40349954755326b03b09565bb2ca19849d7e25 Binary files /dev/null and b/images/TDLgrNewProj.png differ diff --git a/images/TDLgrNewRepresentation.png b/images/TDLgrNewRepresentation.png new file mode 100644 index 0000000000000000000000000000000000000000..7f06e0de8b73bf012ba51c206e125a54de2406d5 Binary files /dev/null and b/images/TDLgrNewRepresentation.png differ diff --git a/images/TDLtxTemplates.png b/images/TDLtxTemplates.png new file mode 100644 index 0000000000000000000000000000000000000000..c422a0728e7137c6c7b45723523337eab1120a8a Binary files /dev/null and b/images/TDLtxTemplates.png differ diff --git a/images/TdlMenuList.png b/images/TdlMenuList.png new file mode 100644 index 0000000000000000000000000000000000000000..5fd030a4d9039c920320a9e336f8ea47d08f4fd2 Binary files /dev/null and b/images/TdlMenuList.png differ diff --git a/images/TdlToolbar.png b/images/TdlToolbar.png new file mode 100644 index 0000000000000000000000000000000000000000..c88cc0ee95d1b23428fff933ca5ec6300c69a60a Binary files /dev/null and b/images/TdlToolbar.png differ diff --git a/images/Tdlan_example.png b/images/Tdlan_example.png new file mode 100644 index 0000000000000000000000000000000000000000..ce28bdbe00e3801b715eb8bb5e9ff3b14d4de49f Binary files /dev/null and b/images/Tdlan_example.png differ diff --git a/images/TemplatesInContext.png b/images/TemplatesInContext.png new file mode 100644 index 0000000000000000000000000000000000000000..3331cacaa6f7fd2db664e576438435be7eeacdce Binary files /dev/null and b/images/TemplatesInContext.png differ diff --git a/images/ValidationView.png b/images/ValidationView.png new file mode 100644 index 0000000000000000000000000000000000000000..1d3bd88ea78fef139321ba73711bb6da23c96214 Binary files /dev/null and b/images/ValidationView.png differ diff --git a/images/Word.png b/images/Word.png new file mode 100644 index 0000000000000000000000000000000000000000..fe3b58e13bde0afed71e967b3931281d491efb59 Binary files /dev/null and b/images/Word.png differ diff --git a/images/syntaxerror.png b/images/syntaxerror.png new file mode 100644 index 0000000000000000000000000000000000000000..e0f01e1cdcc0302ae71485e40fc848f009eb8fb9 Binary files /dev/null and b/images/syntaxerror.png differ