Skip to content

Building & Maintaining the Test Instructions within a Test Script

← Building Test Scripts & Managing Script Library
Quick Links:

Click on the links below to jump to the relevant section of interest to you:

    Purpose of the Test Instructions Grid within a Test Script:

    The main purpose of the test instructions grid is to hold all the test instructions within your test script. All the information that is outside the test instructions grid is meta-data if you will about the script or the configuration of the test script.

    The test instructions grid is the heart of your test script. That's where the logic within your test script is contained.

    If you used QaSCRIBE to develop your test scripts, the instructions created there go directly into the test instructions grid within the view or edit test screen within the Worksoft SaaS application.

    In Worksoft SaaS a test script cannot exist without at least one test instruction in the test instructions grid. You cannot save a test script if there are no test instructions inside it.

    Understanding the 'Instructions Grid' and the various features that the grid's 'Header' offers:    

    The header of the test instruction grid has several handy little powerful features. You should spend some time to become aware of these features:

                         

    The 'Actions' column:

    It contains several icons that will allow you to perform key actions like:

    • adding, editing, deleting a test instruction
    • commenting in/out a test instruction so that it does not execute when the automated test executes
    • adding verbose descriptions above a grouping of test instructions to describe what that group of instructions do

    Turning 'ON'/'OFF' the Tooltips on the Actions column icons:  

    In the header of the 'Actions' column, there is a little blue annotation icon that you can use to shut off the tooltips that show on each of the actions icons within in each of the test instructions rows in the grid. This icon acts like a toggle. If you click it once, the tooltips are enabled (turned on). If you click it again, the tooltips are disabled (turned off). o

    Some users find the tooltips on every row of the test instructions grid annoying and as a productivity issue. This feature allows you to turn off the tooltips


    Test Instruction # column:  

    This column contains a unique identifier that is Worksoft SaaS system generated that shows the sequence number of test instruction within the test script. The last number in this column tells you how many instructions the script contains.

    You cannot edit the value of the instruction sequence number because it is system generated and informational purposes only.

    When you execute tests that contain a script and failures occur within specific instructions, you will be able to easily trace back to the specific test instructions in a script by using this #.

    The 'Command' column:

    The 'Command' column contains the specific commands that are used within the script to implement the logic of your manual test case. The commands within the test script are chosen from the command repository that Worksoft SaaS supports. Refer to Worksoft SaaS Command Reference for a complete list of categories of commands and the list of commands within each category.

    The 'Target' and 'Value' columns:

    The 'Target' column typically contains the target on which the command works and the 'Value' column typically contains the values fed into the command as input. 

    The 'Target' will contain the locators to identify that the user interface elements on the web page or the native/hybrid app for commands that interact with your AUT. For other commands that don't interact with the app, you can generally treat the contents you pass into the 'target' and 'value' fields as inputs to the command. Sometimes, the output of the command will be written into a variable or a dataset you pass into the 'value' field of the command.

    Hiding/Unhiding bindings and encryption indicator icons in the 'Target' & 'Value' columns:

    Worksoft SaaS allows you to encrypt sensitive content (like passwords, social security numbers, etc) within the target and value fields of the test instructions of the test script. When you mark a target or value as 'encrypted', by default, the test instruction grid shows a visual indicator (a lock) within the 'Target' and 'Value' columns if there is at least one instruction within the test script that has its target and/or value encrypted.

    In addition, Worksoft SaaS also allows you to bind the 'target' and/or 'value' fields of test instructions within a script to 'attributes' of a data-definition, to user-defined variable(s), to system variables. In the 'Target' and 'Value' columns of the test instruction grid three visual indicators exist, all of which look like a clip with a alphabet as superscript. The superscript of 'A' stands for 'Attribute', 'U' for User-defined Variable, 'S' for 'System Variable', and 'F' for 'Files' (for browser upload to your AUT from within your automated tests). 

    The color of the clip in these icons will either appear gray or blue. If it is grey, it means that the target or value is not bound to 'A' , 'U', 'S' OR 'F'. If it is blue it means the target or value is bound.

    While the appearance of the four graphical icons is useful for you, when your focus is not the significance or cues from these icons but the content of the target or value of test instructions, it will make sense for you to temporarily get the graphical icons to not appear on the screen. There is a little black right-facing arrow in the border between the 'command' and 'target' columns, and between the 'target' and 'value' columns. When you click on this icon, Worksoft SaaS will temporarily hide the bindings indicator icons and the encrypted content indicator icon within all rows of the test instruction grid so that you can see more of the content of the target and values. 

    If you click on the left-facing arrow indicator, all the indicators will reappear. By default, the indicators are shown in both target and value columns.  


    Viewing encrypted data in clear text temporarily for 'Target' and 'Value' of Test Instructions:

    Worksoft SaaS allows you to encrypt sensitive content (like passwords, social security numbers, etc) within the target and value fields of the test instructions of the test script. When you mark a target or value as 'encrypted', by default, the test instruction grid only shows encrypted (and not clear text) content. 

    If you want to temporarily view the contents of the encrypted data in clear text format, you don't have to open each instruction that has the target and/or the value fields encrypted and turn off the encryption. Instead, you can very simply click on the little blue icon that has an inclined line going through that appears to the right of the 'target' column and/or the 'value' column header.  That will show the encrypted content in all those instructions that have encrypted targets and/or values. That action of yours will make the inclined blue line within the eye to go away. If you click on that icon, the encrypted values will show again within the test instructions grid. Please note that after enabling the display of clear text values for encrypted content in the target and/or value columns, if you move out of the test script screen and come back into the same script, the default view will display the encrypted content again.

     

    Resizing the width of the Command and Target columns:

    The little blue marker icon that appears right above the column separation between the 'Command' header and the 'Target' can be used to reduce the width of the command column so that more width is temporarily allocated to the 'Target' column in the grid. 

    This feature, when used, will allow you to see more content in the 'target' column within the grid. (Note: In the near future, we will also support the same feature to adjust the width of the 'Value' column and 'Target' columns.)   

       

    Understanding the difference between the 'Basic Test Instruction Editor' and the 'Premium Test Instruction Editor'   

    As you aware by now, a test script is essentially a collection of test instructions. The core logic of your automated tests resides within the test instructions.

    To allow you to easily create and edit test instruction, Worksoft SaaS offers two editors, each with its own advantages:

    • A 'Basic Editor' allows you to enter content for the target and value fields of your test instruction into text input fields or special purpose drop-downs within the test instruction pane that appears inline within the test instructions grid. When the length of the content is not too high, you may like the basic editor view 
    • A 'Premium Editor' allows you to enter the content of target or value fields using large text areas which is easier to the eye when the length of the content is high. There are other advantages as well. At a high level, this editor allows you to configure less number of fields that make up a test instruction (all of which are configurable within the basic instruction editor).

    You can very easily switch back and forth between the basic and the premium test instruction editors (or viewers if your test script in the 'view' mode).

    The Basic Test Instruction Editor:

    When you are in the the edit mode (or the view mode) of a test script, you can open the basic test instruction editor (or viewer), by double clicking anywhere in the test instruction that you are interested in editing. 
    When you add a new test instruction in the edit mode of the test script, you can configure the test instruction using the basic test instruction editor, by default. 

    When you are in the edit mode of a test script, you can also click on the 'Edit' icon in the 'Actions' column to open the test instruction in the 'basic test instruction editor' as well. This additional options does not exist when you are in the 'view' mode of the test script, however.

    The 'basic test instruction editor' allows you to:
    • Specify a 'command' for your test instruction by choosing from one of the many commands that are supported within Worksoft SaaS. Refer to Worksoft SaaS Command Reference for a complete list of categories of commands and the list of commands within each category.
    • Enter into the 'Target' field the list of locators to identify the user interface elements within your AUT for commands that interact with your AUT. For other commands that don't interact with your AUT, you will be entering a single input.
    • 'Element' field shows up for commands that interact with AUT. This is user editable field so if you want to make any modifications, you will be able to do so. The icon shown in the field has two flavours: grey & blue. You see grey icon when this field is not used in execution results page and when you do a mouseover on the icon, text can be seen stating the same. 



      You would need to toggle the setting in 'User Settings' to have this value showing up in execution results instead of the locator value from the target field.

      The screenshot below illustrates how the UI Element Name will display on the Test Execution Results screen (both for local & cloud executions)

       
      QaSCRIBE captures this information for commands that fall under any of the following categories: UI Automation - Manipulation, UI Automation - Interrogation, UI Automation - Navigation & UI Automation - Synchronization excluding small set of commands (captureEntirePageScreenshot, captureEntirePageScreenshotAndWait, capturePageScreenshot, pause, setTimeout.) This will significantly help you correlate the locators that are captured to the UI element when you are trying to debug issues, if any, associated with the execution of your automated tests.

      When recording new test instructions within a new or an existing test script, you don't have to do anything additional for this information to be captured by QaSCRIBE and for that information to be saved as part of your Test Script. If you editing an older test script that has no AUT Labels captured, you can use one of the below features to record AUT Labels.

      • Select element to capture its locators



      • Verify validity of locators and follow that up with using magic wand



      QaSCRIBE captures this information from the AUT based on below criteria (in the order of precedence given below):

      • Label - labels are tags used in HTML to explain the use of an element
      • Display name of the AUT element - like text on buttons, reference text for anchor tag or place holder for input types
      • ARIA tags (title < aria-label < aria-labelledby < alt) - Text used by various text readers and most of the applications these days are using these tags to comply with American Disabilities Accessibility (ADA) Web Accessibility Standards & Requirements
      • As a last resort, text within the element if none of the above are available



    • Enter into the 'Value' field a single input that is expected from the command.
    • You can also optional add your own note on what the test instruction is doing in the context of your manual test case OR why you configured the test instruction as you did or anything of importance for you.
    • In addition to the above-mentioned core fields, you can also parameterize the target or value fields by binding the target or value to attributes of a data definition, to user-defined variables, system variables, data definition names, or files.
    • By clicking on the set-of-books icon that appears to the right of the 'command' drop-down, you can launch/access the Worksoft SaaS Knowledge Base that will open in a new browser tab.
    • You can mark the 'target' and/or 'value' fields for encryption by clicking on the blue lock icon that appears to the right of the those two input fields. 
    • If you marked the 'target' and/or 'value' fields for encryption, and you want to temporarily see in clear text the encrypted content of those fields, you can click on the blue eye icon that has a inclined line inside. To see the encrypted content again, you can click on the blue eye icon.
    • When the command is one that interacts with your AUT and if the target has more than one locator to identify the user interface elements, you can expand the drop-down for the 'target' field, and within that control add new locators, edit existing locators, delete locators, or even drag-n-drop the locators to adjust the sequence of execution of those locators. You can also copy to clipboard the locator, one at a time, and paste the copied values to create additional locators for the same instruction or other instructions.
    • Within both the 'target' and 'value' text input fields, if you want to, launch the 'Premium Test Instruction Editor' (or viewer if you are in the view mode of the test script).


     
    The Premium Test Instruction Editor:

    The 'Premium Test Instructions Editor' (or viewer if you are in the 'view' mode of the test script) can be used to more conveniently view/edit the contents of the target or the value fields of a test instruction. 
    The Premium Editor will highlight the keywords within the contents of the target or value fields based on the type of content to improve the content's readability and help you maintain the test instructions more easily and with higher levels of productivity. For example, if there is JavaScript content in a target, the standard keywords within JavaScript will be automatically highlighted. If the content of a target field is SQL, then the standard keywords from that language are auto-highlighted,, and so and so forth.

    The Premium Editor will also allow you to do some of the same functions that the basic editor supports like:
    • If you marked the 'target' and/or 'value' fields for encryption, and you want to temporarily see in clear text the encrypted content of those fields, you can click on the blue eye icon that has a inclined line inside. To see the encrypted content again, you can click on the blue eye icon.
    • When the command is one that interacts with your AUT and if the target has more than one locator to identify the user interface elements, you can use the left and right navigator arrows to easily navigate between all the locators of the target.
    • You will be able to delete the locators one at a time. 
    • You can also copy to clipboard the locator, one at a time, and paste the copied value to create additional locators for the same instruction or other instructions.
    • You can also embed or insert into the target or value fields dynamic variables that involve user-defined variable(s), system variable(s), data definition name.
                     


    Key actions that you can perform within the test instructions grid


    There are numerous actions that are available for you to use to easily build and maintain test instructions within a test script.

    Adding a Test Instruction


    To add a new test instruction just click on the green plus icon in the 'Actions' column of the test instruction row below you which you want the new instruction to be added.

                

    Then you fill out the necessary details (command, target, values, etc) in the new instruction and once you are done click 'Save'. Remember that you can always switch to the Premium Test Instruction Editor to more easily configure your target and value fields, if you want to.

    Editing a Test Instruction


    To edit a test instruction just click on the edit icon in the 'Actions' column of the test instruction row that you want to edit.

            

    Then you fill out the necessary details (command, target, values, etc) in the new instruction and once you are done click 'Save'. Remember that you can always switch to the Premium Test Instruction Editor to more easily configure your target and value fields, if you want to.  

    Deleting a Instruction

      
    To delete a test instruction just click on the red minus icon in the 'Actions' column of the test instruction row that you want to delete. Then you have to save the test script.  

                                                                                   

    Commenting out a test instruction so that it does not execute when an automated test runs

    If you don't want a test instruction to be executed but want to retain it within the test script because you want to come back to edit mode and use that instruction (because your debugging and you want to skip some instructions from execution and see what happens), you can very easily Comment OUT the test instruction within a test script by clicking on the grey # icon.
                                                                                                       
    To 'Uncomment' the commented instruction within the test script, just click on the blue # icon within the 'Actions' column of the test instruction that you are interested in. Then you have to save the test script.

    Adding verbose comments above/below a group of test instruction to capture key info about what the group of instructions do

    Worksoft SaaS allows you to added verbose comments above or below a group of test instructions for you to record within the test script what that group of test instructions do. These verbose comments are similar to the ones you typically add to a programming source code file as best practice. Such comments usually serve like a reminder for you and your peers to understand the logic built into the test scripts easily oiver time. Without adding verbose comments around the main instructions, it becomes very difficult for you or your peers to understand the logic behind the test instructions and this will impact the ease of maintenance of your test scripts. 

    To add a verbose comment, just click on the speech bubble like icon in the 'Actions' column for the test instruction right above where you want to add a verbose comment.

                                                     

    Changing the order of Test Instructions using Drag-and-Drop

    You can rearrange/change the sequence of the test instructions very easily by dragging and dropping test instructions from one place to another within the same script.

                     

    Copy/Pasting Test Instructions within the Script using keyboard shortcuts

    You can very easily copy contiguous or non-contiguous test instructions in a test script. 

    If you wish to copy multiple instructions then select the instructions that you wish to copy and paste in the requested position/sequence in the test script. The instructions will get copied in the same sequence/order that you selected.

             

    Expanding and Collapsing of a 'Grouping' of loop constructs (like while, foreach, etc.,) within the test script

    Conditional and Looping construct commands like "If", "for", "while", "foreach" can be expanded/collapsed by clicking on the + icon or - icon that appear on the the tree line within the 'Command' column of the test instructions grid.

                                         

    Expanding and Collapsing of a 'Grouping' of block commands (like dbBlock, if, else, wsBlock, etc.,)


    All the commands that should be executed within a block such as commands related to Database, Web Services, and Team Notifications are represented using the grouping icon. This icon allows you to expand/collapse the block.

    You can click on the + icon within the tree line to expand the block of instructions. To collapse it, just click on the - icon with the tree line within the 'Command' column of the test instructions grid.

             

    Adding & Maintaining Locators/Content in the Target field:


    To add one or more locators that identify or interact with a specific user interface element within your AUT, just open the 'Basic Test Instruction Editor', expand the 'Target' drop-down control, and within that add as many locators that you have that can identify the UI element of interest to you.
                   

    Encrypting/Decrypting contents of the 'Target' & 'Value' fields of a Test Instruction:


    To encrypt the contents of the 'target' or the 'value' fields of a test instruction, click on the unlocked lock icon that appears to the right of the 'target' or 'value' fields.
           

    To decrypt the contents, just click on the locked lock icon.

    Viewing the contents of the 'Target' or 'Value' in clear text temporarily:


    To temporarily view the encrypted content within the 'target' or 'value' fields of a test instruction, just click on the blue eye icon.


         

    Entering User Notes for a Test Instruction

    User Notes is like the description to the instruction. This section allows you to write notes for further references in case there are any changes to the command/Target/Value or any reference text that would would want to input.


                

    Parameterizing (Binding) the 'Target' field to an Attribute of the Data Definition for data-driven testing:

    If you want to parameterize the 'target' of a test instruction with the 'attribute' of a data definition so that when an automated test that contains the test script gets executed, the test gets data feed for this target from a 'Data File' ( CSV File) in your project, then you can assign the name of the 'attribute' from the data definition that is chosen at the test script level.

            

    Parameterizing (Binding) the 'Value' field to an Attribute of the Data Definition for data-driven testing: 
    If you want to parameterize the 'value' of a test instruction with the 'attribute' of a data definition so that when an automated test that contains the test script gets executed, the test gets data feed for this 'value' field from a 'Data File' ( CSV File) in your project, then you can assign the name of the 'attribute' from the data definition that is chosen at the test script level.  

                

    Parameterizing the Value for 'File' binding:


    If you want your automated test perform browser upload of files into your AUT at runtime, you have to paramterize the 'value' field by assining it a file placeholder name first . Then within each Test Scenario and Run Definition that you assemble this test script into, you will have to 'bind' the actual file from the 'Files' module of your project that you want to dynamically feed into your automated test at run-time. To know more about the feature in Worksoft SaaS click here.

               

    Inserting (embedding) User-defined Variable(s) into the 'Target' or 'Value' fields:


    You can bind one or more 'User-Defined Variables' to the Target and/or Value fields of test instruction.
      
            

    When a run definition or a test scenario that contains this test script is executed, at run time, the values for the user-defined variables are retrieved for the specific project environment against which the test was pointed to.   

    Inserting (embedding) System Variable(s) into the 'Target' or 'Value' fields:


    You can bind one or more 'System Variables' to the Target and/or Value fields of test instruction.


    When a run definition or a test scenario that contains this test script is executed, at run time, the values for the system variables are retrieved and used within the test.  
     

    Inserting Data Definition name into the 'Value' field for the command 'ddCreateDataset':  


    You can bind one or more 'data definition' name into the Value field of a test instruction in the context of the command 'ddCreateDataset'.

      


    Searching for (finding) test scripts that contain specific commands, target and value field content on the test scripts' home screen:

    The Test Scripts home screen allows you to search for or filter the test scripts listed within the 'My Favorites' view or the 'Script Library' view based on the test instruction containing specific commands, target or value field content. To learn more, click here. 

    Searching for (finding) instructions that contain specific commands, target and value field content on the test script:

    You can now search within a test script for a particular command/target/value by accessing the icon which is present at the right corner below the recording button:
                                                                                 
    In Create/Edit/View Test Script, you can see the search control and upon accessing that, the test script name gets collapsed and the search grid would display simultaneously as shown below:



    This search control allows you to search the instructions that contain specific command, target, value or locator. By default, you will see 'All' and 'Contains' in the dropdowns. After selecting the search dropdowns, you would see the instructions getting highlighted according to the input given in the text field.



    If the command/target/value is more than the available text area, you can view the whole data in the Premium Editor. Premium Editor allows you to view the XML/JSON data in the formatted fashion.

    When you click back on search or '+' icon available beside the test script name, you would see the search grid getting collapsed and the test script name is shown as is.

    Feedback and Knowledge Base

    (thinking…)