TestComposer™ ScriptGen Tcl Reference
Release 7.00 EA Part No. 913-1603 Rev A December 2012 Copyright © 2012 Ixia. All rights reserved. This publication may not be copied, in whole or in part, without Ixia’s consent. RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the U.S. Government is subject to the restrictions set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and FAR 52.227- 19. Ixia, the Ixia logo, and all Ixia brand names and product names in this document are either trademarks or registered trademarks of Ixia in the United States and/or other countries. All other trademarks belong to their respective owners. The information herein is furnished for informational use only, is subject to change by Ixia without notice, and should not be con- strued as a commitment by Ixia. Ixia assumes no responsibility or liability for any errors or inaccuracies contained in this publica- tion.
Corporate Ixia Worldwide Headquarters Web site: www.ixiacom.com Headquarters 26601 W. Agoura Rd. General: [email protected] Calabasas, CA 91302 Investor Relations: [email protected] USA Training: [email protected] +1 877 FOR IXIA (877 367 4942) Support: [email protected] +1 818 871 1800 (International) +1 818 595 2599 (FAX) +1 818 871 1805 For the online support form, go to: [email protected] http://www.ixiacom.com/support/inquiry/
EMEA Ixia Technologies Europe Limited Support: [email protected] Part 2nd floor, +40 21 3015699 Clarion House, Norreys Drive For the online support form, go to: Maidenhead, UK SL6 4FL http://www.ixiacom.com/support/inquiry/ +44 (1628) 408750 ?location=emea FAX +44 (1628) 639916 [email protected]
Asia Pacific Ixia Pte Ltd Support: [email protected] 210 Middle Road +65 6332125 #08-01 IOI Plaza For the online support form, go to: Singapore 188994 http://www.ixiacom.com/support/inquiry/
Japan Ixia Communications KK Support: [email protected] Nishi-Shinjuku Mitsui Bldg 11F +81 3 5326 1948 6-24-1, Nishi-Shinjuku, Shinjuku-ku For the online support form, go to: Tokyo 160-0023 http://www.ixiacom.com/support/inquiry/ Japan
India IXIA Technologies Pvt. Ltd. Support: [email protected] Tower 1, 7th Floor, UMIYA Business Bay +91 80 49396400 Cessna Business Park For the online support form, go to: Survey No. 10/1A, 10/2, 11 & 13/2 http://www.ixiacom.com/support/inquiry/ Outer Ring Road, Varthur Hobli ?location=india Kadubeesanahalli Village Bangalore East Taluk Bangalore-560 037, Karnataka, India +91 80 42862600
Part No. 913-1603 Rev A December 2012 For viewing the FAQs related to the product, go to Ixia Technical Support Online: https://ebsoprod.ixiacom.com/OA_HTML/jtflogin.jsp
ii TestComposer ScriptGen Tcl Reference, Release 7.00 Contents
Chapter 1 About This Guide
Purpose ...... 1-1 Manual Content ...... 1-1 Technical Support ...... 1-3
What’s New in this Release...... 1-3
Related Documentation...... 1-3
Chapter 2 Introduction to IxNetwork TestComposer
TestComposer Overview ...... 2-1
On IxNetwork Configurations and TestComposer Scripts . . 2-2
The TestComposer GUI...... 2-3 Edit Mode GUI ...... 2-3 Debug Mode GUI...... 2-5
The Structure of a TestComposer Script ...... 2-5
TestComposer: A Tcl-Enabled Plug-in...... 2-6
TestComposer ScriptGen Tcl Reference, Release 7.00 iii Table of Contents
A Sample IxNetwork TestComposer Workflow ...... 2-7
Chapter 3 Creating and Editing a TestComposer Script
Using the TestComposer Edit Mode ...... 3-1 Creating a Main Procedure Script...... 3-3 Creating Additional Procedure Scripts ...... 3-3 Defining Script Properties ...... 3-4 Configuring a Test Script...... 3-5 The Edit Mode GUI ...... 3-5 The Edit Mode Commands Toolbar...... 3-7 The Edit Mode Tabs ...... 3-9 Validation Messages ...... 3-9 Execution Messages...... 3-9 Find/Replace...... 3-9 Variables ...... 3-10 Breakpoints ...... 3-11 Command Response ...... 3-12 Tcl Packages...... 3-12 Events ...... 3-13 Adding Scrips Steps ...... 3-14 Using the Step Configuration Wizard ...... 3-14 By Capturing Commands on Established Sessions ...... 3-15 The Session Consoles Pane...... 3-15 By Inserting a Procedure ...... 3-17 Editing Script Steps In-Place...... 3-17 Defining Input Parameters ...... 3-18 Using Attached Script Files...... 3-20 Defining User Events ...... 3-22 Retrieving Step Results using Response Templates ...... 3-24 Specifying Exported Statistics ...... 3-24 Specifying a Script Pass/Fail Result ...... 3-26 Validating a Script ...... 3-26 Saving a Script into an IxNetwork Test Configuration ...... 3-27 Executing Selected Steps ...... 3-27
Chapter 4 Additional Editing Options
Additional Editing Options ...... 4-1
iv TestComposer ScriptGen Tcl Reference, Release 7.00 Table of Contents
Using Copy / Paste Operations ...... 4-1 Using Drag and Drop Operations ...... 4-1 Including and Excluding Steps from Execution ...... 4-2 Marking Steps For Parallel Execution ...... 4-2 Re-arranging the Steps Sequence ...... 4-3 Surrounding Steps with Control Blocks ...... 4-3 Using Find / Replace Operations...... 4-4 Using the Undo / Redo Functionality ...... 4-4 Customizing the Script Steps Table Layout ...... 4-5
Chapter 5 Using the Capture Functionality
Capture Functionality Overview ...... 5-1 The TestComposer GUI with Capture Functionality Enabled . . . . . 5-2
Creating, Configuring, and Using Device Sessions...... 5-4 Creating a New Device Session ...... 5-4 Creating a Device Session Based on an Existing Resource ...... 5-4 Configuring Session Parameters...... 5-5 Variables as Session Id ...... 5-5 Defining Connection Settings ...... 5-7 Telnet Connection Settings...... 5-8 CmdTool Connection Settings ...... 5-8 SSH1/SSH2/SSHAuto Connection Settings...... 5-9 Raw Interface Connection Settings ...... 5-9 TclSh Connection Settings ...... 5-10 COM Connection Settings ...... 5-10 TL1 Connection Settings ...... 5-10 SNMP Connection Settings ...... 5-11 Syslog Connection Settings ...... 5-12 CSVAnalyzer Connection Settings ...... 5-13 Reporter Connection Settings ...... 5-14 PacketDecoder Connection Settings ...... 5-14 Defining Terminal Settings ...... 5-14 Defining Device Prompts...... 5-18 Defining Capture Mode Exceptions...... 5-21 Specifying a Response Templates Folder ...... 5-22 Saving Device Sessions ...... 5-23 Connecting to a Device and Capturing Commands ...... 5-24 Using Multiple Device Sessions ...... 5-27
TestComposer ScriptGen Tcl Reference, Release 7.00 v Table of Contents
Chapter 6 Script Steps Reference Information
Control Statement Steps ...... 6-1 Comment Statement Step ...... 6-2 Comment Step in Step Configuration Wizard...... 6-2 Comment Step In-Place Editing ...... 6-2 Assign Statement Step...... 6-3 Assign Statement Step in Step Configuration Wizard ...... 6-3 Assign Step In-Place Editing ...... 6-5 ReadWriteGlobal Statement Step ...... 6-6 ReadWriteGlobal Statement Step in Step Configuration WIzard ...... 6-6 ReadWriteGlobal Step In-Place Editing...... 6-8 For Statement Step ...... 6-8 For Statement Step in Step Configuration Wizard ...... 6-9 For Step In-Place Editing...... 6-11 While Statement Step...... 6-12 While Statement Step in Step Configuration Wizard ...... 6-12 While Step In-Place Editing ...... 6-14 Do...While Statement Step ...... 6-14 Do...While Statement in Configuration Wizard ...... 6-14 Do...While Step In-Place Editing ...... 6-16 StepSearch Statement Step...... 6-17 StepSearch Statement Step in Step Configuration Wizard ...... 6-17 StepSearch Step In-Place Editing ...... 6-19 BinarySearch Statement Step ...... 6-20 BinarySearch Statement Step in Step Configuration Wizard ...... 6-20 BinarySearch Step In-Place Editing ...... 6-24 Break Statement Step ...... 6-25 Break Statement Step in Step Configuration Wizard ...... 6-25 Break Step In-Place Editing ...... 6-27 Return Statement Step...... 6-27 Return Statement Step in Step Configuration Wizard ...... 6-27 Return Step In-Place Editing ...... 6-28 Exit Statement Step ...... 6-29 Exit Statement Step in Step Configuration Wizard ...... 6-29 Exit Step In-Place Editing ...... 6-30 If Statement Step ...... 6-30 If Statement Step in Step Configuration Wizard ...... 6-30 If Step In-Place Editing ...... 6-31 Else Statement Step ...... 6-31 Else Statement Step in Step Configuration Wizard ...... 6-31 Else Step In-Place Editing ...... 6-33 vi TestComposer ScriptGen Tcl Reference, Release 7.00 Table of Contents
Join Statement Step ...... 6-33 Join Statement Step in Step Configuration Wizard ...... 6-33 Join Step In-Place Editing ...... 6-35 RunProcedure Step ...... 6-35 RunProcedure Step in Step Configuration Wizard...... 6-35 RunProcedure Step In-Place Editing ...... 6-37 RunProcess Step ...... 6-38 RunProcess Step in Configuration Wizard ...... 6-38 RunProcess Step In-Place Editing...... 6-40 Sleep Step ...... 6-41 Sleep Step in Step Configuration Wizard...... 6-41 Sleep Step In-Place Editing ...... 6-42
Command Steps ...... 6-43 StartSession ...... 6-44 StartSession Command Step in Configuration Wizard ...... 6-44 Editing In-Place a StartSession Step ...... 6-46 Execute ...... 6-46 Execute Command in Step Configuration Wizard...... 6-47 Editing In-Place an Execute Step ...... 6-52 StopSession...... 6-53 StopSession Command Step in Step Configuration WIzard ...... 6-53 StopSession Step In-Place Editing ...... 6-54 Get Time ...... 6-55 GetTime Step in Step Configuration Wizard ...... 6-55 GetTime Step In-Place Editing...... 6-58 TclEval Step...... 6-60 TclEval Command Step in Step Configuration Wizard ...... 6-60 TclEval Step In-Place Editing ...... 6-61 Watch...... 6-62 Watch Command Step in Step Configuration Wizard ...... 6-62 Trace ...... 6-66 Trace Command Step in Step Configuration Wizard ...... 6-66 Trace Step In-Place Editing ...... 6-68 ShowMessage ...... 6-68 ShowMessage Step in Step Configuration Wizard ...... 6-68 ShowMessage Step In-Place Editing ...... 6-70 ReadFile ...... 6-71 ReadFile Command Step in Step Configuration Wizard...... 6-71 ReadFile Command Step In-Place Editing ...... 6-73 WriteCSV...... 6-73 WriteCSV Command Step in Step Configuration WIzard ...... 6-73
TestComposer ScriptGen Tcl Reference, Release 7.00 vii Table of Contents
WriteCSV Step In-Place Editing ...... 6-76 GetValue ...... 6-76 GetValue Command Step in Step Configuration Wizard...... 6-77 GetValue Step In-Place Editing ...... 6-79 Config Get...... 6-80 Config Get Command Step in Step Wizard ...... 6-80 Config Get Step in-Place Editing ...... 6-83 Config Set ...... 6-85 Config Set Command Step in Step Wizard ...... 6-85 Config Set Command Step In-Place Editing ...... 6-87 Config Add ...... 6-89 Config Add Command Step in Step Wizard ...... 6-89 Config Add Step in-Place Editing ...... 6-91 Config Remove ...... 6-93 Config Remove Command Step in Step Wizard ...... 6-93 Config Remove Step in-Place Editing ...... 6-95 Config Action...... 6-97 Config Action Command Step in Step Wizard...... 6-97 Config Action Step in-Place Editing...... 6-99 Group ...... 6-101 Group Step in Step Wizard ...... 6-101 Group Step in-Place Editing ...... 6-101
Procedure Step ...... 6-101 New Procedure Step ...... 6-101
QuickTest Structure Steps ...... 6-103 ApplyConfig...... 6-103 Trial ...... 6-103 FrameSize...... 6-103 Iteration ...... 6-104 Iteration ...... 6-106 StartTraffic...... 6-106 StartProtocols ...... 6-106 TestUnderSize...... 6-107 Framesize Undersize ...... 6-107 TestOverSize...... 6-107 Framesize Oversize ...... 6-107 TestBadCRC ...... 6-107
viii TestComposer ScriptGen Tcl Reference, Release 7.00 Table of Contents
Framesize BadCRC ...... 6-108 TestFragment...... 6-108 Framesize Fragment ...... 6-108
Chapter 7 Using the Composer Expression Builder
About Variables ...... 7-1 Variable Scope ...... 7-1 Variable Types ...... 7-2 Variables Creation Statements ...... 7-2
Creating Expressions in the Expression Builder ...... 7-3 Expression Builder - Basic Mode...... 7-3 Expression Builder - Advanced Mode ...... 7-5 The Expression Builder Panes ...... 7-5 The Tcl Commands Pane ...... 7-6 The Test Variables Pane...... 7-7 The Operators Pane ...... 7-10 The Expression Pane ...... 7-10 Building An Expression ...... 7-10
Chapter 8 Executing a TestComposer Script
Execution from the TestComposer GUI...... 8-1 Executing Script Steps in Edit Mode ...... 8-1 Executing a Script in Debug Mode ...... 8-1 The Debug Mode GUI...... 8-2 The Debug Mode Toolbar ...... 8-3 Using the Autoscroll Functionality in Debug Mode ...... 8-4 The Debug Window Tabs ...... 8-4 Execution Messages ...... 8-5 Expressions ...... 8-5 Threads ...... 8-6 Global Output ...... 8-7 Call Stack ...... 8-7 Variables...... 8-8 Sessions Output ...... 8-9 Breakpoints...... 8-10
TestComposer ScriptGen Tcl Reference, Release 7.00 ix Table of Contents
Using Breakpoints ...... 8-11 Running a TestComposer Script without Procedures ...... 8-12 Running a TestComposer Script with Procedures...... 8-13 Running a TestComposer Script with Parallel Steps...... 8-14 Test Status Indicator ...... 8-15
Execution from the IxNetwork GUI...... 8-17 Execution From the IxNetwork QuickTests Page ...... 8-17 Execution As a Custom Test ...... 8-17
Chapter 9 Working with Multiple Test Scripts in TestComposer
Working with Multiple Scripts ...... 9-1 Opening Multiple Scripts with MDI ...... 9-2 Debugging nested scripts ...... 9-3 Using Copy / Paste Operations...... 9-3 Capturing Steps with MDI ...... 9-3 Executing Steps with MDI ...... 9-3 Saving to Resources...... 9-4
Chapter 10 Viewing Script Execution Files in IxNetwork
Script Execution Results Integration in Data Miner ...... 10-1
Chapter 11 Persisting TestComposer Scripts
Saving a Script into an IxNetwork Configuration ...... 11-1
Exporting a Script as a Procedure Resource...... 11-1
Exporting as a Script To Test Conductor ...... 11-2
Chapter 12 Exporting TestComposer Scripts to Tcl Code
Exporting as a Tcl Script ...... 12-1
x TestComposer ScriptGen Tcl Reference, Release 7.00 Table of Contents
Chapter 13 Managing IxNetwork TestComposer Resources
What Is an IxNetwork TestComposer Resource? ...... 13-1
Creating Device Sessions ...... 13-3
Creating Procedure Resources...... 13-5
Creating Response Templates ...... 13-7 The Response Template Editor ...... 13-8 About Regions, Targets, and Markers ...... 13-10 Free-Form Response Templates ...... 13-13 RepeatingBlock Response Templates...... 13-19 Table-Form Response Templates ...... 13-22 Defining a Response Template - Command Association ...... 13-27
Creating CSV Template Resources...... 13-28
Handling MIB Resources...... 13-31
The Resource Manager...... 13-32 Resource Manager Common Operations ...... 13-33
Chapter 14 Capturing IxNetwork Actions with Macro Recorder
Macro Recorder Overview...... 14-1 What Actions are Recorded?...... 14-1
Capturing Actions to TestComposer Steps ...... 14-3
Chapter 15 TestComposer Menu Commands Reference
Script Ribbon...... 15-1 Play ...... 15-1 Play all...... 15-1 Play all with user delay ...... 15-1 Play selected only ...... 15-1
TestComposer ScriptGen Tcl Reference, Release 7.00 xi Table of Contents
Pause ...... 15-2 Stop ...... 15-2 Toggle Breakpoint ...... 15-2 Edit ...... 15-2 Debug ...... 15-2 New ...... 15-2 New Script ...... 15-2 New Procedure ...... 15-3 New Device Resource ...... 15-3 Create New CSV Template ...... 15-3 Create New Response Template ...... 15-3 Append Last Step ...... 15-3 Add Control Step ...... 15-3 Add Command...... 15-4 Append Last Step ...... 15-4 New Step ...... 15-4 Insert above...... 15-5 Insert below ...... 15-5 Place Inside ...... 15-5 Delete ...... 15-5 Clear Script ...... 15-5 Edit ...... 15-6 Move Up / Down ...... 15-6 Cut ...... 15-6 Copy ...... 15-6 Paste ...... 15-6 Include / Exclude ...... 15-6 Expand/Collapse ...... 15-6 Select all ...... 15-6 Undo ...... 15-7 Redo ...... 15-7 Validate ...... 15-7 Find/Replace ...... 15-7 Go to ...... 15-7 Go to step ...... 15-7 Go to procedure...... 15-7 Debug Views ...... 15-7 Events ...... 15-8 Tcl Packages ...... 15-8 Validation Messages ...... 15-8
xii TestComposer ScriptGen Tcl Reference, Release 7.00 Table of Contents
Execution Messages...... 15-8 Command Response ...... 15-8 Find/Replace...... 15-8 Global Output ...... 15-8 Sessions Output ...... 15-8 Call Stack ...... 15-8 Breakpoints ...... 15-9 Console ...... 15-9 Reset Layout ...... 15-9
Test Ribbon ...... 15-9 Test Parameters ...... 15-9 Import Procedure ...... 15-9 Export Procedure ...... 15-9 Manage Resources ...... 15-9 Exported Stats ...... 15-11 User Events ...... 15-11 Files Catalog ...... 15-11 Options ...... 15-11 Appearance...... 15-11 Debugging...... 15-12 Reset Tcl Interpreter ...... 15-14 Reset Built-In Event Session ...... 15-14 Refresh Protocols Configuration Tree ...... 15-14 Show Summary, Show Detailed ...... 15-14 Text Wrap ...... 15-14
Automation Ribbon ...... 15-15 Export Script ...... 15-15 Tcl ScriptGen ...... 15-15
Appendix A Creating a Sample TestComposer Script
Test Overview ...... A-1
Creating the Composer Test ...... A-2
TestComposer ScriptGen Tcl Reference, Release 7.00 xiii Table of Contents
Appendix B Response Templates Creation Samples
Creating a Text-Format Response Template ...... B-1
Creating a RepeatingBlock Response Template ...... B-2
Creating a Table Format Response Template ...... B-4
Appendix C Executing IxNetwork QuickTests from TestComposer
Executing IxNetwork QuickTests ...... C-1
Adding Input Parameters to QuickTests in IxNetwork Test Composer ...... C-2
Appendix D IxNetwork Events
IxNetwork Events ...... D-1
Appendix E Predefined Commands for Miscellaneous Other Session Types
SNMP Session Commands ...... E-1 SNMP Get...... E-1 SNMP Set ...... E-2 SNMP GetTable ...... E-3 SNMP Walk...... E-4 SNMP Listen ...... E-5 SNMP WaitForTraps ...... E-6 Custom Commands ...... E-7
Syslog Session Commands ...... E-8 WaitForMessage...... E-8 Pause ...... E-9 Resume...... E-9
xiv TestComposer ScriptGen Tcl Reference, Release 7.00 Table of Contents
ShowMessages ...... E-9
CSVAnalyzer Session Commands ...... E-9 StatQuery...... E-9 Clear ...... E-11 WriteBlock ...... E-11 WriteLines ...... E-12
Reporter Session Commands ...... E-13 AddTextToReport...... E-13 AddHTMLToReport ...... E-14 AddImageToReport ...... E-14 AddTableToReport...... E-14 AddSectionTo Report ...... E-15 GenerateXYPlot...... E-15 GenerateBarChart ...... E-16 GenerateReport...... E-17
Packet Decoder Session Commands ...... E-18 Load Capture...... E-18 Filter...... E-18 Get Data ...... E-19 Show Data ...... E-20
Appendix F IxiaTestComposer Tcl Commands
Supported Additional Tcl Commands ...... F-1 SetBaseline ...... F-1 GetBaseline ...... F-1 GetValue ...... F-2
Appendix G Configuring the IxNetwork StatQuery Command
IxNetwork StatQuery Command Configuration ...... G-1
TestComposer ScriptGen Tcl Reference, Release 7.00 xv Table of Contents
Appendix H TestComposer Licensing Information
Supported Licensing Schemes ...... H-1 Basic ...... H-2 Device Configuration...... H-2 Advanced License...... H-2
Appendix I The MIB Browser
Using the MIB Browser ...... I-1
Appendix J Parallel Steps Configuration Hints
Parallel Steps Execution Examples ...... J-1 Example 1 ...... J-1 Example 2 ...... J-2 Example 3 ...... J-3
Appendix K TestComposer Menu Shortcuts
Command Shortcuts ...... K-1
xvi TestComposer ScriptGen Tcl Reference, Release 7.00 Chapter 1: About This Guide 1
The information in this section is provided to help you navigate this manual and make better use of its content.
Purpose This manual contains information about the structure of a Tcl test script gener- ated using the TestComposer ScriptGen command and provides deployment details required for running such a script remotely from Tcl-enabled network hosts.
Manual Content This manual contains the following sections:
Section Description
Chapter 1, About This Guide Provides information on this manual, including its purpose, content, and related documentation. Also explains how to contact technical support.
Chapter 2, Automation Deployment Provides information on the ScriptGen-based export operation and Scenario the automation topology required for running Tcl test scripts remotely.
Chapter 3, Ix_tc Package Commands Describes the commands implemented by the ix_tc test automation package that is provided with the TestComposer application. Map- ping of TestComposer commands into Tcl native code is also described.
Chapter 4, Configuring Event Processing Describes the Tcl support for TestComposer event processing. In Tcl
Chapter 5, Accessing Resources/ Provides information on accessing the configured TestComposer Execution Files resources and application files from the Tcl code.
Chapter 6, Accessing Client Machine Provides information on accessing execution logs on the Client Logs host.
Chapter 7, Sample Script Describes a sample script so as to illustrate its functionality.
TestComposer ScriptGen Tcl Reference, Release 7.00 1-1 1 About This Guide
Technical Support You can obtain technical support for any Ixia product by contacting Ixia Techni- cal Support by any of the methods mentioned on the inside cover of this manual. Technical support from Ixia’s corporate headquarters is available Monday through Friday from 6 a.m. to 6 p.m., Pacific Standard Time (excluding Ameri- can holidays). Technical support from Ixia’s EMEA and India locations is avail- able Monday through Friday, 8 a.m. to 5 p.m. local time (excluding local holidays).
1-2 TestComposer ScriptGen Tcl Reference, Release 7.00 Chapter 2: Automation 2 Deployment Scenario
This chapter provides general information on the Tcl export operation and the topology required for running a generated Tcl script. Tcl Export Overview
Using the ScriptGen command of TestComposer, any test script that is opened in TestComposer can be converted to a Tcl script in order to be run from any net- work host that has a Tcl interpreter installed.
Exporting a TestComposer test to Tcl using the ScriptGen command results in the following files being created on the TestComposer host: • A Tcl file that contains the code corresponding to the Main_Procedure por- tion of the TestComposer script. The Tcl file contains a main procedure grouping the Tcl code that corresponds to steps from the main procedure, and additional procedure definitions result- ing from the translation of local and external procedures contained in the ini- tial TestComposer script. In the generated Tcl script, TestComposer steps of the control type, such as For, While, and TclEval, are converted to native Tcl calls, while any other step, such as StartSession or Execute, are mapped to Tcl commands from the special ix_tc package that is supplied with TestComposer. Any of these commands take a number of arguments, usually those defined in the Test Steps table of the TestComposer GUI. • A binary file (.tcp) that corresponds to the underlying TestComposer script.
TestComposer ScriptGen Tcl Reference, Release 7.00 2-1 Automation Deployment Scenario 2 Test Automation Topology
Test Automation Topology
Using the ScriptGen command, you can create Tcl scripts that can be run from any automation client host – Unix/Linux or Windows – that has a Tcl interpreter installed.
In order to be able to run an exported Tcl script, a configuration is required as shown in Figure 2-1:
Figure 2-1. Automation Deployment Topology
The execution of a generated Tcl script requires the following deployment con- figuration: • A Windows machine that hosts the Composer Runtime Environment (CRE) component, which is responsible for executing the ix_tc::* commands con- tained in the Tcl code files. • Client Tcl machines: The generated Tcl script that corresponds to the TestComposer test is transferred to and then run from any Client host running the Linux / Unix OS and a Tcl console application.
When running a Tcl script, the Client host opens a communication channel with the remote CRE host and runs the ix_tc:: commands remotely, while the rest of the Tcl code is executed locally. Additionally, for the TestComposer functionality subset that is not supported by the ScriptGen translation and which is as such not available in Tcl, such as processing of command output using Response Tem- plates and the handling of User Events, the Client host also relies on the CRE to execute the corresponding code.
Following the script execution, associated test execution files created at runtime on the CRE host, such as global and per-session logs and exported statistic files, are passed back to the Client host and result in a number of files being stored in the Results folder.
Important: When executing the Tcl script file, the working directory on the Client host must be the directory where the Tcl and the .tcp files are stored.
2-2 TestComposer ScriptGen Tcl Reference, Release 7.00 Automation Deployment Scenario Generated Tcl Script Structure
Important: When exporting a TestComposer test script using ScriptGen, steps of the IxTC Test type (Test Conductor tests) are not translated to Tcl code.
Generated Tcl Script Structure
All generated Tcl script files contain a similar structure with the following logi- cal sections: • Definition of global test variables • An instruction to source the generated binary file • A special section for declaring script input arguments • A special section for declaring system events that are to be processed locally by the Tcl script • The actual Tcl code corresponding to the underlying TestComposer test. This contains a main procedure definition that corresponds to the main test body, and additional procedure definitions for the local or external procedures defined or referenced within the initial test.
• An ix_tc code portion for connecting to the CRE component, and a final portion for the disconnect code.
• An ix_tc code portion containing commands for starting the generated Tcl script. This is generally followed by a call to the main procedure, which pos- sibly calls any additional procedures contained in the Tcl script. • A final section that contains code for stopping the Tcl script execution, dis- connecting from the CRE, and returning a script return value.
Figure 2-2 below illustrates these logical sections that make up the structure of a generated Tcl script:
TestComposer ScriptGen Tcl Reference, Release 7.00 2-3 Automation Deployment Scenario 2 Generated Tcl Script Structure
Defines global variables, including one that references the binary test file (.tcp)
Invokes the ix_tc package
Defines the main procedure that establishes a Telnet session to a Cisco router and calls a ConfigureDutInterfaces procedure for configuring its interfaces
The ConfigureDutInterface procedure definition
The ConfigureDutInterfaces procedure definition which calls the ConfigureDutInterface repeatedly
Connects to the CRE WIndows host
Starts the test execution by referencing the test binary file Calls the main procedure
‘Stops the test execution
Disconnects from the Windows CRE host
Figure 2-2. Sample Tcl Script Structure
2-4 TestComposer ScriptGen Tcl Reference, Release 7.00 Chapter 3: Ix_tc Package 3 Commands
This section provides information on the ix_tc package commands, as well as information on the TestComposer commands that translate into native Tcl code. The ix_tc Package
Using the ScriptGen menu command, any TestComposer script that is open in the GUI can be converted to a Tcl script in order to be run from multiple hosts in an automated mode.
During the conversion process, control steps such as While, For, TclEval, are converted into native Tcl code constructs, while the rest of the TestComposer steps, such as StartSession, StopSession, and Execute are mapped to Tcl com- mands from the ix_tc package.
Additionally, the ix_tc package also contains commands for connecting to and disconnecting from the CRE Windows host that is required by the automation topology (see Test Automation Topology on page 2-2), and for launching the Tcl code execution.
Tcl Conversion When a TestComposer script is exported to Tcl code, the following conversion Rules Overview rules apply: • Commands for connecting to the CRE host and disconnecting from it are automatically added to the generated Tcl code file. • Commands for starting the generated script is automatically added to the gen- erated Tcl code file.
• For non-control step types, such as StartSession and Execute, steps are mapped to ix_tc commands, whose first argument is always the id of the initial script step; for example, a StartSessionStep (StepNo:11) step becomes the following code instruction: ix_tc::startSession -id "11" The id property is very important in that it ensures that the Tcl code is exe- cuted with the settings previously configured in the TestComposer GUI.
TestComposer ScriptGen Tcl Reference, Release 7.00 3-1 Ix_tc Package Commands 3 The ix_tc Package
• The list of arguments passed to an ix_tc::* command is the same as that from the default columns exposed by the Test Steps table of the TestCom- poser GUI. • Steps that have a response template associated for retrieving portions of the step output have the -returnVar
• If the id argument is missing for an ix_tc:: command call, a new step from that category is created. The newly created step has default value for all prop- erties (generally the properties are those exposed as columns in the Test Steps table), but any Tcl-specified properties override the default ones.
Important: Once a Tcl code file was generated, you can add to it additional instructions that were not present in the initial TestComposer script and which, as such, do not need to reference any steps of the initial test script. For these steps that do not have an id argument, a new step from that category is created with default parameters. For example, the following command opens a telnet session named "session1". ix_tc::startSession -session "session1" -command "Telnet, 10.10.10.10, 23"
3-2 TestComposer ScriptGen Tcl Reference, Release 7.00 Ix_tc Package Commands TestComposer Test Step Mappings
TestComposer Test Step Mappings
The following sections provide a mapping of TestComposer steps – command steps and control steps – into ix_tc commands and native Tcl constructs respec- tively. ix_tc:: Command TestComposer command steps, such as StartSession, StopSession, and Execute, Mappings are mapped to Tcl commands from the ix_tc package.
Additionally, the ix_tc package contains a number of commands which do not have an underlying TestComposer command, such as for example commands for connecting/disconnecting to/from the CRE, or launching into execution a gener- ated Tcl script file.
The following commands are provided by the ix_tc package:
ix_tc::connect
Connects to the CRE on a specified machine and using the port 11001.
Syntax:
ix_tc::connect
Description:
Connects to the host specified by the host parameter on port 11001. Please note that, since initially the command connects to the localhost, you have to replace this reference with a reference to the actual host that is running the CRE in your test topology.
Examples: Considering, for example, the following code: if { [catch {ix_tc::connect localhost 11001} err] } {puts "Cannot establish the Composer Runtime Environment connection.\n$err" return } this contains the ix_tc::connect function enclosed in error handling code.
ix_tc::startTest
Starts a test specified by a file.
Syntax:
TestComposer ScriptGen Tcl Reference, Release 7.00 3-3 Ix_tc Package Commands 3 TestComposer Test Step Mappings
ix_tc::startTest $filename
Description
Starts a test specified by the $testfile variable.
Examples: Considering, for example, the following code:
ix_tc::startTest $testfile
this starts the script contained in the file referenced by $testfile.
ix_tc::disconnect
Disconnects from the CRE component.
Syntax:
ix_tc::disconnect
Description
Disconnects from the CRE component.
Examples: Considering, for example, the following code:
ix_tc::disconnect
this disconnects from the CRE.
ix_tc::startSession
This command starts a protocol or test application session to a configured test device or to an Ixia chassis.
Syntax
ix_tc::startSession [-id “
Description
This command results as a translation of a StartSession step of the protocol ses- sion (Telnet. CmdTool, ssh, etc.) or a test application session (IxExplorer, IxLoad, IxChariot, IxNetwork, IxNetwork-FT, IxAutomate, IxANVL).
This command has the following parameters:
3-4 TestComposer ScriptGen Tcl Reference, Release 7.00 Ix_tc Package Commands TestComposer Test Step Mappings
•
•
•
•
•
•
Examples: 1. Considering, for example, the following code:
ix_tc::startSession -id "3" -session "Telnet-1" -host "10.205.11.34" -port "23"
this starts the Telnet-1 session defined in step 3 of the original TestComposer test to a host having IP address 10.205.11.34. 2. Considering, for example, the following code:
ix_tc::startSession -id "11" -session "IxiaChassis" - command "IxExplorer, Session Start chassis=optixiaxm12 ports=4.* ownershipmode=force loginname=john ixospath=\"C:/Program Files/Ixia/IxOS/5.20-GA-Patch2\""
this starts an IxExplorer session named IxiaChassis and executes an IxExplorer Start Session command.
ix_tc::execute
This command executes a command over an established session.
Syntax
ix_tc::execute [-id “
Parameters
•
•
As an alternative, the encrypted value can be used, in which case the com- mand value is hidden at runtime.
TestComposer ScriptGen Tcl Reference, Release 7.00 3-5 Ix_tc Package Commands 3 TestComposer Test Step Mappings
•
•
Note: If a return variable is specified (using the resultVar parameter), but no targets are defined, then the return variable contains the entire command output.
•
Example: Considering, for example, the following code:
ix_tc::startSession -id "3" -session "Telnet-01" -host "10.205.11.34" -port "23" ix_tc::execute -id "4" -session "Telnet-01" -command encrypted ix_tc::execute -id "5" -session "Telnet-01" -command "ena"
this starts a Telnet session named Telnet-01 to a router with IP address 10.205.11.34 on port 23, then sends an encrypted command (the password) and eventually sends an ena command over the established session.
ix_tc::stopSession
This command terminates an active session.
Syntax
ix_tc::stopSession [-id “
Description:
Terminates an active session. This command has the following parameters:
•
3-6 TestComposer ScriptGen Tcl Reference, Release 7.00 Ix_tc Package Commands TestComposer Test Step Mappings
•
Example: Considering, for example, the following code: ix_tc::stopSession -id "10" -session "Telnet-01" this terminates the Telnet-01 session from step 10 of the underlying TestComposer test.
ix_tc::setGlobalVar
This command defines and sets a global variable value.
Syntax
ix_tc::setGlobalVar
Description:
Both this and the ix_tc::getGlobalVar functions result from the translation of the TestComposer ReadWriteGlobal step. This command has the following parame- ters:
•
Example: Considering, for example, the following code:
ix_tc::setGlobalVar var1 10
this sets the value of var1 to 10.
Note: Global variables are mainly used for passing variable values between the main script body and procedures executing in parallel. In such cases, you would normally use the setter function in the parallel function to initialize a variable, then, after the procedure completed, you could retrieve the variable value in the main procedure using the getter function.
ix_tc::getGlobalVar
This function returns the value of a global variable.
Syntax
ix_tc::getGlobalVar
Description:
TestComposer ScriptGen Tcl Reference, Release 7.00 3-7 Ix_tc Package Commands 3 TestComposer Test Step Mappings
Both this and the ix_tc::setGlobalVar functions result from the translation of the TestComposer ReadWriteGlobal step. This command has the following parame- ters:
•
Example: Considering, for example, the following code:
set local [ix_tc::getGlobalVar var1]
this retrieves the value of the var1 variable and assign it to the local variable.
Note: Global variables are mainly used for passing variable values between the main script body and procedures executing in parallel. In such cases, you would normally use the setter function in the parallel function to initialize a variable, then, after the procedure completed, you could retrieve the variable value in the main procedure using the getter function.
ix_tc::getValue
This function retrieves the value of a field from a composite variable, possibly filtering by the values of other fields. Additionally, if the filtering operation yields multiple values, an aggregation operator can be applied to the values list.
Syntax
ix_tc::getValue -aggregatefunction “
Description:
This function results from the translation of the TestComposer GetValue step. The function has the following parameters:
•
3-8 TestComposer ScriptGen Tcl Reference, Release 7.00 Ix_tc Package Commands TestComposer Test Step Mappings
Example: Considering, for example, the following code:
ix_tc::execute -id "15" -session "IxNetwork1" -command "Get Statistics …” -resultVar X
ix_tc::getValue -aggregatefunction "Sum" -expression "Sum X OSPF_Number_Of_Session_Configured" –resultVar Full_Nbrs
ix_tc::getValue -aggregatefunction "Sum" -expression "Sum X OSPF_Number_Of_Full_Neighbors" –resultVar Sess_Configured
this retrieves the result of a Get Statistics call into the X composite variable, and then queries X using an ix_tc::getValue function. Both the Full_Nbrs and Sess_Configured variables are computed using the Sum aggregation function.
ix_tc::runProcess
This function runs an external command, such as an .exe command file or a Tcl script.
Syntax
ix_tc::runProcess [-id “
Description:
This function results from the translation of the TestComposer RunProcess step. The function has the following parameters:
•
Example: Considering, for example, the following code:
ix_tc::runProcess -id "10" -command "\"C:\\Program Files\\Ixia\\IxNetwork\\5.40EA\\tcl8.4\\bin\\wish84.exe \" init.tcl"
this executes an wish84.exe command specified using a full path.
ix_tc::setFileVariables
Defines a Files Catalog variable that is used for referencing an input or output file.
Syntax
TestComposer ScriptGen Tcl Reference, Release 7.00 3-9 Ix_tc Package Commands 3 TestComposer Test Step Mappings
ix_tc::setFileVariables
Description:
This function has no direct correspondent in terms of TestComposer steps, but results from a variable definition in the TestComposer Files Catalog. The func- tion has the following parameters:
•
Example: Considering, for example, the following code: #### FileCatalog variables ix_tc::setFileVariables csvFileCatalogVar set a "foo1" set b "foo2" ix_tc::writeCsv -id "5" -filename "$csvFileCatalogVar" -variable "$a $b" -header "column1 this defines the csvFileCatalogVar and writes into it the values of the $a and $b variables using the WriteCSV function.
ix_tc::readFile
This function reads an ASCII formatted input file and retrieves parts from it into a structured variable. The file portions to be retrieved are specified by a TestCom- poser Response Template.
Syntax
ix_tc::readFile [-id “
Description:
This function results from the translation of the TestComposer ReadFile step. The function has the following parameters: •
•
Note: The file argument is necessarily a file that is defined in the Files Catalog and resides on the CRE host.
•
3-10 TestComposer ScriptGen Tcl Reference, Release 7.00 Ix_tc Package Commands TestComposer Test Step Mappings
Example: Considering, for example, the following code: #### FileCatalog variables ix_tc::setFileVariables UserResultsDirectory file1 ix_tc::readFile -id "1" -filePath "$file1" -resultVar r puts "Variable ${r.Target_1}" this declares the predefined file1 and UserResultsDirectory variables and reads the file referenced by the file1 variable. If the file has any target(s) defined by an associated Response Template, these are retrieved into the variable r.
ix_tc::writeCSV
This function writes one or more TestComposer variables to an attached output file using a CSV format.
The resulting CSV file is stored in the Results directory on the Client host.
Syntax
ix_tc::writeCSV -id “
Description:
This function results from the translation of the WriteCSV TestComposer step. The function has the following parameters:
•
•
•
TestComposer ScriptGen Tcl Reference, Release 7.00 3-11 Ix_tc Package Commands 3 TestComposer Test Step Mappings
Example: Considering, for example, the following code: ix_tc::setFileVariables UserResultsDirectory csvFileCatalogVar set a "foo1" set b "foo2" set outFile "$UserResultsDirectory\\test.csv" ix_tc::writeCsv -id "4" -filename "$outFile" -variable "$a $b" -header "column1 column2" ix_tc::writeCsv -id "5" -filename "$csvFileCatalogVar" -variable "$a $b" -header "column1 column2" this writes the variables $a and $b into the outFile and csvFileCatalogVar files defined in the TestComposer Files Catalog using variables.
Note: If the header columns are defined using variables, you need to use the built-in ix_tc::formatColumn command, which ensures that the headers does not contain any whitespace (it is replaced by “_”). Example:
ix_tc::writeCsv -id "17" -filename "c:/test.csv" -variable "\{${ret.Target_1}\} \{${ret.Target_2}\} \{${ret.Target_3}\} " -header "col1 [ix_tc::formatColumn $h1] [ix_tc::formatColumn $h2]"
ix_tc::watch
This function monitors a specified session for an event.
Syntax
ix_tc::watch -id “
Description:
This function results from the translation of the TestComposer Watch step. The function has the following parameters:
•
•
•
3-12 TestComposer ScriptGen Tcl Reference, Release 7.00 Ix_tc Package Commands TestComposer Test Step Mappings
Example: Considering, for example, the following code:
ix_tc::startSession -id "1" -session "CmdTool-1" - command "CmdTool"
ix_tc::spawn -parallelName "Parallel 1" -exec "ix_tc::watch -id \"2\" -session \"CmdTool-1\" -watchForever \"True\" "
this starts a CmdTool session and monitors it using a watch function that is executing in parallel.
ix_tc::spawn
This function generates a new thread for executing in parallel a command or a procedure.
Syntax
ix_tc::spawn -parallelName “
Description:
This function result from the translation of a TestComposer Execute or Run- Procedure step that was defined as executing in parallel.
The function has the following parameters:
•
•
Example: Considering, for example, the following code:
ix_tc::spawn -parallelName “prl1” -exec “proc1 11 13”
this executes a procedure as a parallel step.
TestComposer ScriptGen Tcl Reference, Release 7.00 3-13 Ix_tc Package Commands 3 TestComposer Test Step Mappings
Important: For an ix_tc::execute command call that is configured for parallel execution, if the step command has multiple targets defined, all targets must be declared in the -returnVar parameter, such as for example in the code sample below, which has two targets defined.
ix_tc::spawn -parallelName “prl2” -exec “ix_tc::execute
ix_tc::join
This function waits for one or more processes executing in parallel to finish, or terminates them forcefully.
Syntax
ix_tc::join “
Description:
This function result from the translation of the Join TestComposer step. The function has the following parameters:
•
Example: Considering, for example, the following code:
ix_tc::spawn -parallelName “parall1” -exec proc1 11 13”
ix_tc::spawn -parallelName “parall2” -exec proc1 14 16”
...
ix_tc::join “parall1” “parall2”
this generates two procedure instances that execute in parallel and then waits for them to complete.
ix_tc::generatePassFailStats
This function waits for one or more processes executing in parallel to finish, or terminates them forcefully.
Syntax
ix_tc::generatePassFailStats
Description:
3-14 TestComposer ScriptGen Tcl Reference, Release 7.00 Ix_tc Package Commands TestComposer Test Step Mappings
This function generates a file in CSV format that contains the values of statistics exported by the initial TestComposer test script. The resulting PassFailStats.csv file is stored in the script execution folder underneath the Result directory on the Client host. The function has no parameters:
Example: Considering, for example, the following code:
ix_tc::generatePassFailStats
this generates the CSV file containing the exported statistics.
ix_tc::systemEvent
This function configures system events processing.
Note: Refer to Chapter 4, Configuring Event Processing In Tcl for an overview of TestComposer events.
Syntax
ix_tc::systemEvent -scope "
Description
This function is used for configuring system event processing. The function has the following parameters:
•
•
•
Example: Considering, for example, the following code snippet:
ix_tc::systemEvent -scope "test" -type "Step TimeOut" - action "Continue" -procedure "timeout_handler"
this defines a test-level system event of the Timeout type which has an associated timeout_handler procedure and which does not cause the test to terminate when a timeout occurs on any step.
Control Step TestComposer control steps such as Assign, For, If, While, Do...While, Binary- Mappings Search, and StepSearch are translated into native Tcl code constructs.
TestComposer ScriptGen Tcl Reference, Release 7.00 3-15 Ix_tc Package Commands 3 TestComposer Test Step Mappings
The following is a description of the generated Tcl code for TestComposer con- trol steps.
StepSearch
A TestComposer StepSearch step is translated into a complex construct that implements a linear search algorithm using predefined functions such as linearSearchComputeBestIteration and linearSearchCompute NextIteration.
Example:
BinarySearch
A TestComposer BinarySearch step is translated into a complex construct that implements a binary search algorithm using predefined functions such as binarySearchComputeNextValue and binarySearchReachEnd.
3-16 TestComposer ScriptGen Tcl Reference, Release 7.00 Ix_tc Package Commands TestComposer Test Step Mappings
Example:
If
A TestComposer If step is translated into a conditional construct that uses an if / else instruction.
Example: Considering, for example, the following code:
set succes [check_key $key]
if { $succes == 0 } {
puts "$dut does not support $key key size"
} else {
puts "created $key bits ssh key size on $dut"
}
this tests the value of the success variable.
Note: Since the underlying TestComposer If step can have two working modes - Simple and Advanced - you are likely to see different translation results for each mode.
TestComposer ScriptGen Tcl Reference, Release 7.00 3-17 Ix_tc Package Commands 3 TestComposer Test Step Mappings
For
A TestComposer For step is translated into a looping construct that uses a for instruction.
Example: Considering, for example, the following code:
set keys "360"
for { set index1 361 } { $index1 <= 2048 } { incr index1 1 } {
set keys "$keys $index1"
}
this loops over values of the index1 variable.
While
A TestComposer While step is translated into a looping construct that uses a while instruction.
Example: Considering, for example, the following code:
set keys "360"
while { [expr { [lindex $keys [expr [llength $keys]-1]] < 2048}] } {
lappend keys [expr [lindex $keys [expr \ [llength $keys]-1]] +1]
}
this loops as long as the condition is true.
Do...while
A TestComposer Do...while step is translated into a looping construct that uses a while instruction.
3-18 TestComposer ScriptGen Tcl Reference, Release 7.00 Ix_tc Package Commands TestComposer Test Step Mappings
Example: Considering, for example, the following code:
while {1} {
lappend keys [expr [lindex $keys [expr \ [llength $keys]-1]] +1]
if {![expr { [lindex $keys [expr [llength \ $keys]-1]] < 2048}]} {
break;
}
this loops until the condition associated with the if statement is true.
ShowMessage
A TestComposer ShowMessage step is translated into a variable declaration that is being initialized to the step’s default response message.
Example: Considering, for example, a ShowMessage step that has a var1 return variable assigned and that is configured using two response messages, Response 1 and Response 2 (default), the generated Tcl code is the following:
set var1 “Response 2”
Please note that this behavior is different from that of the underlying TestComposer ShowMessage step and that the generated Tcl code has limited functionality, in that it does not allow for user interaction at runtime, referring instead to the configured default response.
Procedure
A TestComposer Procedure step is translated into a procedure definition.
TestComposer ScriptGen Tcl Reference, Release 7.00 3-19 Ix_tc Package Commands 3 TestComposer Test Step Mappings
Example: Considering, for example, the following code: #### procedure global events proc login { } { ix_tc::execute -id "48" -session "Telnet-1" -command "ixia" ix_tc::execute -id "49" -session "Telnet-1" -command encrypted ix_tc::execute -id "50" -session "Telnet-1" -command "ena" ix_tc::execute -id "51" -session "Telnet-1" -command encrypted ix_tc::execute -id "52" -session "Telnet-1" -command "conf t" ix_tc::execute -id "53" -session "Telnet-1" -command "do show run" -resultVar runnning_config puts "${runnning_config.hostname}.${runnning_config.domain- name}" if { ${runnning_config.domain-name}=="" } { ix_tc::execute -id "56" -session "Telnet-1" -command "ip domain-name ixiacom.com" } set ret "${runnning_config.hostname}.${runnning_config.domain- name}" return $ret } this defines the login procedure that establishes a Telnet session to a router device.
RunProcedure
A TestComposer RunProcedure step is translated into a procedure call.
Example: Considering, for example, the following code: set name [login ] this calls the login procedure that was shown in the previous Procedure step example.
3-20 TestComposer ScriptGen Tcl Reference, Release 7.00 Ix_tc Package Commands TestComposer Test Step Mappings
Config Get, Config Set, Config Add, Config Remove, Config Action
A TestComposer step from the Config category is translated into an ix_tc::execute call that executes a configuration command on the default Built-In Event session.
The command call has the following parameters:
•
• Configuration Set • Configuration Add • Configuration Remove • Configuration Action
Example: Considering, for example, the following code: ix_tc::execute -id "36" -session "Built-In Event" - command "Configuration Get select=\"/traffic/ trafficItem\[1\] \" get=\"biDirectional\"" this executes a Configuration Get command on traffic item with index 1 and returns the state of the bidirectional attribute. As another example, the following code: ix_tc::execute -id "41" -session "Built-In Event" - command "Configuration Set select=\"/traffic/ trafficItem[1]/endpointSet[1] \" set=\"name TEST10\"" configures the name attribute of an endpoint set to TEST10.
TestComposer ScriptGen Tcl Reference, Release 7.00 3-21 Ix_tc Package Commands 3 TestComposer Test Step Mappings
3-22 TestComposer ScriptGen Tcl Reference, Release 7.00 Chapter 4: Configuring Event 4 Processing In Tcl
This section provides information on how TestComposer script events translate into the Tcl code generated using the ScriptGen feature. Overview
TestComposer can monitor a test or individual test steps for events, and to respond to the occurrence of such an event by executing a specified procedure and taking an action.
TestComposer supported events fall into the following categories: • System events: Two predefined system events, Timeout and Error, can be associated with a procedure to execute and an action. System events can be configured at test, procedure, or step level. When a system event is config- ured both at test level and for an individual step, the step-level definition is prioritary. • User events: Such events are created by users using the User Events Catalog and are associated with a procedure to execute and an action to perform. A user event can only be configured to define conditional processing at step level for Execute-type commands. At run-time a command output can be monitored for a user-specified pattern, and, if that pattern is matched, an associated event is considered to have occurred. This triggers the associated procedure and the associated action is performed.
Events Representation in Tcl
Depending on the TestComposer event type – system or user-defined – the repre- sentation and the processing of events in the generated Tcl code is different.
System Events When a TestComposer script is translated using ScriptGen, configured system events are translated into the Tcl code using the ix_tc::systemEvent func- tion, one function instance for each event.
TestComposer ScriptGen Tcl Reference, Release 7.00 4-1 Configuring Event Processing In Tcl 4 Events Representation in Tcl
As previously described in ix_tc::systemEvent on page 3-15, each function call configures an event type, a scope, an executed procedure, and an action.
Given the Tcl representation of system events, such events can be edited and modified in the generated Tcl script.
At script runtime system event processing is done on the Client host.
User Events Opposed to system events, the user events configuration is not translated to Tcl code, and, as such, cannot be edited from the generated Tcl code.
Consequently, when a test is run that has user events associated with steps, the Client host relies on the CRE to resolve the user events; the occurrence of user events is triggered on the CRE and a notification is sent back to the Client host.
4-2 TestComposer ScriptGen Tcl Reference, Release 7.00 Chapter 5: Accessing Resources/ 5 Execution Files
This section provides information on accessing TestComposer resources and exe- cution files from a Tcl script generated using ScriptGen. Overview
TestComposer defines resources – Procedures, Response Templates, Device Ses- sions, CSV files, MIBs – as re-usable entities that facilitate the creation of tests and contain procedures definitions, session parameters, MIBs, etc.
Resources As a general rule, TestComposer resources referenced by a Tcl script are manipu- lated on the CRE host and need to be present on the CRE at script run time, their invocation being transparent to the user running the script.
For example, assuming we have a TestComposer WriteCSV command call trans- lating into a writeCsv Tcl function that creates a CSV file resource such as the following: ix_tc::writeCsv -id "6" -filename "d:\\result.csv" - variable "$a $b" -header "column1 column2"
the result.csv file is generated at the specified location on the CRE host.
Attached Test Files The TestComposer Files Catalog is used for defining attached test files using variables.
When running a generated Tcl script, files that are referenced via file catalog variables also need to exist on the CRE.
For example, assuming we had following code: #### FileCatalog variables ix_tc::setFileVariables UserResultsDirectory file1 ix_tc::readFile -id "1" -filePath "$file1" -resultVar r
TestComposer ScriptGen Tcl Reference, Release 7.00 5-1 Accessing Resources/Execution Files 5 Overview
For instance, if the $file1 variable points to a“d:\file1.txt” file, at runtime that file should exist on CRE.
Retrieving In TestComposer, execution files are stored in a folder referenced by the pre- Execution Files on defined UserResultsDirectory variable that is defined in the Files Catalog. the Client In the generated script, this variable definition is translated as follows: #### FileCatalog variables ix_tc::setFileVariables UserResultsDirectory
At the end of a TestComposer test execution, all files from the folder specified by the UserResultsDirectory variable are compressed and archived into User ResultsDirectory.zip, which is then transferred to the Tcl Client host under the Results sub-folder.
As such, in order for the execution files to be retrieved, the files must be gener- ated under the UserResultsDirectory path.
5-2 TestComposer ScriptGen Tcl Reference, Release 7.00 Chapter 6: Accessing Client 6 Machine Logs
This section provides information on the logger functions available in the ix_tc package and the logs generated on the Client host following the execution of a Tcl test script. Logger Functions
The logger functions from the ix_tc package are used for writing log information of different levels into the tcl_client_log.txt file that is generated for every Tcl script execution. This file, conjointly with other log files are stored in the Results folder on the Client machine.
Note: Please note that in order to have custom information logged to the tcl_client_log.txt file, logger function from the ix_tc package must be used. Native Tcl commands, such as puts, is not suitable for logging, neither from the main thread nor from parallel procedures.
The following logger functions are available: ix_tc::initLogger This function starts the logger.
Syntax
ix_tc::initLogger
Description:
This logger function is present in the Tcl script and has no corresponding TestComposer step. The function has no parameters. ix_tc::logInfo This function logs the specified string with the info level.
Syntax
ix_tc::logInfo “
TestComposer ScriptGen Tcl Reference, Release 7.00 6-1 Accessing Client Machine Logs 6 Logger Functions
Description:
This logger function is present in the Tcl script and has no corresponding TestComposer step. The function has the following parameters:
•
Example: Considering, for example, the following code:
ix_tc::initLogger
ix_tc::logInfo “Binary Search execution finished after $iteration iteration(s).”
this logs a string that also contains a variable.
ix_tc::logWarning This function logs the specified string with the warning level.
Syntax
ix_tc::logWarning “
Description:
This logger function is present in the Tcl script and has no corresponding TestComposer step. The function has the following parameters:
•
Example: Considering, for example, the following code:
ix_tc::initLogger
ix_tc::logWarning “Binary Search execution finished after $iterationNumber iteration(s).”
this logs a string that also contains a variable.
ix_tc::logError This function logs the specified string with the error level.
Syntax
ix_tc::logError “
Description:
6-2 TestComposer ScriptGen Tcl Reference, Release 7.00 Accessing Client Machine Logs The Results Folder Content
This logger function is present in the Tcl script and has no corresponding TestComposer step. The function has the following parameters:
•
Example: Considering, for example, the following code:
ix_tc::initLogger
ix_tc::logError “Binary Search execution finished after $iterationNumber iteration(s).”
this logs a string that also contains a variable. ix_tc::closeLogger This function closes the logger.
Syntax
ix_tc::closeLogger
Description:
This function, which has no corresponding TestComposer step, has no parame- ters. The Results Folder Content
Following a Tcl script execution, a new folder is created on the Client host with a name following the year_month_date_hour_min_sec_
TestComposer ScriptGen Tcl Reference, Release 7.00 6-3 Accessing Client Machine Logs 6 The Results Folder Content
• PassFailStats.csv: This file contains the TestComposer-exported stats in CSV format. The file is only generated if the ix_tc::generatePassFailStats function is called in the Tcl script.
In addition to the execution log listed above, the generated Tcl script file and the binary test (.tcp) file are also found in the script execution folder on the Client host.
6-4 TestComposer ScriptGen Tcl Reference, Release 7.00 Chapter 7: Sample Script 7
This section provides a sample Tcl script to illustrate the Tcl script functionality. Using Script Samples
A number of samples are provided, illustrating different functionalities.
Sample Tcl Script A sample script that was generated using the ScriptGen command is given in Figure 7-1:
TestComposer ScriptGen Tcl Reference, Release 7.00 7-1 Sample Script 7 Using Script Samples
Defines global variables
Invokes the ix_tc package
Defines the main procedure that establishes a Telnet session to a Cisco router and calls a ConfigureDutInterfaces procedure for configuring its interfaces
The ConfigureDutInterface procedure definition
The ConfigureDutInterfaces procedure definition which calls the ConfigureDutInterface repeatedly
Connects to the CRE WIndows host
Starts the test execution
Calls the main procedure
‘Stops the test execution
Disconnects from the Windows CRE host
Figure 7-1. Example Tcl Script
7-2 TestComposer ScriptGen Tcl Reference, Release 7.00 Sample Script Using Script Samples
This script contains three procedure definitions: main, ConfigureDUTInterface and ConfigureDUTInterfaces.
The main procedure calls starts a Telnet session to the configured router device. After logging in (following the sending of user and password information over the established session), the ConfigureDUTInterfaces procedure is called with a list of all device interfaces as parameters. Eventually the main function closes the session to the configured devices.
The ConfigureDUTInterface procedure performs the configuration of a single device interface.
The ConfigureDUTInterfaces performs configuration of all device interfaces by calling the ConfigureDUTInterface procedure repeatedly.
The last portion of the Tcl script connects to the CRE host, starts the test execu- tion and then calls the main procedure. Eventually the return value of the main procedure is displayed, the test execution is stopped and the script disconnects from the CRE host.
TestComposer ScriptGen Tcl Reference, Release 7.00 7-3 Sample Script 7 Using Script Samples
7-4 TestComposer ScriptGen Tcl Reference, Release 7.00