3 Creating and Modifying Scripts

This chapter explains the procedures for creating and modifying basic scripts in OpenScript. The module chapters provide additional information about creating scripts using the features and capabilities provided within specific modules.

3.1 Creating Repositories and Workspaces

Repositories and workspaces store project related script files and results log files. You can use repositories and workspaces to organize your various testing projects. OpenScript lets you create multiple workspaces.You can create repositories to organize the storage of your script projects.

Note:

Any scripts you plan to run, along with any associated assets, in the Oracle Load Testing application must be stored in a repository/workspace.

A repository is the directory location where you store workspaces. Workspaces are user-specified subdirectories of the repository. As of version 9.10, OpenScript no longer uses an exclamation point at the end of the directory name to identify the directory as a Workspace directory. Any folder (directory) below the specified repository can be a workspace folder.

When you record and save scripts, or play back a script and save the log file, OpenScript stores the script or log file in the specified Workspace.

OpenScript does not create any new repository if you have at least 1 repository kept from a previous installation. If there was no Open Script installed on this machine by the current User, then OpenScript will create a repository named "Default" in the location <installDir>/OFT. You can create your own repositories and workspaces using OpenScript.

Repositories specify the location to use to store scripts and related asset files. Repositories also provide a way to share files between OpenScript and Oracle Load Testing. Oracle Load Testing requires that all assets live inside of a named Repository. Oracle Load Testing will not be able to find an asset located in the local file system outside of a repository. Any shared directory can be used as a repository. However, all repositories shared between Oracle Load Testing, Oracle Test Manager, OpenScript, and team members must share the same repository name. For example, if one member of a team calls a shared repository SharedRepo1, but another member of a team calls the same shared repository Shared_Repository_1, it is possible that some script assets may not be found when the team members share scripts.

To reduce the chance of local repository name conflicts, it is recommended that you create a new local repository named something unique to the user, such as <machineName>.<windowsUserName>.MyRepository. Store in this folder all scripts that are not intended to be shared among team members.

Best Practices:

  • Always store scripts and assets (i.e. databanks, .jar files, etc.) inside named repositories.

  • Avoid selecting the Save path relative to current script option in OpenScript when saving scripts.

  • Establish a consistent repository naming scheme across all Oracle Load Testing, Oracle Test Manger, and OpenScript installations.

  • Avoid using the repository named "Default" for storing local scripts. Use "machineName.Default" instead.

  • Do not use the file system (i.e. Windows Explorer) to copy/move script folders or files. Scripts are Eclipse bundles (with unique IDs) and have file dependencies within script folders. If you need to move scripts, use Save As on the OpenScript File menu. Use the Manage options on the Tools menu to rename scripts and manage folders and repositories.

3.1.1 Creating a Repository

To create a repository:

  1. Select OpenScript Preferences from the View menu.

  2. Expand the OpenScript node.

  3. Expand the General node.

  4. Select the Repository node.

  5. Click Add.

    This dialog box lets you specify the name and location of the repository to use to store script files.

  6. Enter a repository name. The name is required.

    Name: Enter any name to identify the repository.

    Note:

    If you plan to use OpenScript scripts with Oracle Load Testing, the repository names you specify should match the repository name specified in Oracle Load Testing (including case).
  7. Enter the drive and directory location or click Browse to select the location to use for the repository.

    Location: Enter the drive and directory path to the repository or use the Browse button to select a location. The location must be a valid drive and directory path.

  8. Click OK to add the new repository to the list of repositories.

  9. Click OK to close the preferences.

When you create new a script project, you can select the repository to use to store the project.

3.1.2 Managing Repositories

To add, edit, or delete repositories:

  1. Select Manage Repositories from the Tools menu.

  2. Select the repository where you want to create the workspace.

  3. Click the Add, Edit or Delete buttons to manage repositories.

  4. Click Close when finished.

3.1.3 Managing Folders (Workspaces)

When starting a new testing project, you should create a project-specific workspace folder to store related files.

To create, rename, or delete workspace folders:

  1. Select Manage Folders from the Tools menu. OpenScript opens a dialog box for managing workspace folders in repositories.

  2. Expand the tree and select the workspace folder to manage.

  3. Click New, Rename, or Delete buttons to manage workspace folders.

  4. Click Close when finished.

3.1.4 Managing Scripts

To rename or delete scripts:

  1. Select Manage Scripts from the Tools menu.

  2. Select the script.

  3. Click the Rename or Delete buttons to manage script files.

  4. Click Close when finished.

3.2 Creating a Script Project

You must create a script project to generate the basic structure that you can then customize.

To create a script project:

  1. Select New from the File menu.

  2. Expand a group node and select the type of asset or script to create:

    Functional Testing (Browser/GUI Automation): The Functional Testing group contains the following script types:

    • Adobe Flex: This option lets you create a new script for automated functional testing of web applications that use the Adobe Flex Automation Framework at the browser/gui level. The resulting script will contain the Initialize, Run, and Finish nodes. The Run node will contain recorded Web navigations based upon the defined Web Functional test Step Group preferences and the Web navigations and Flex actions performed during recording. You can edit the script tree or Java code to customize the script.

    • Oracle EBS/Forms: This option lets you create a new script for automated functional testing of Oracle E-Business Suite and other applications that utilize Web and Oracle Forms components at the browser/gui level. The resulting script will contain the Initialize, Run, and Finish nodes. The Run node will contain recorded Web navigations based upon the defined Step Group preferences and the Web navigations and Forms actions performed during recording. You can edit the script tree or Java code to customize the script.

    • Oracle Fusion/ADF: This option lets you create a new script for automated functional testing of Oracle Application Development Framework (ADF)-based applications and other applications that utilize Web and ADF components at the browser/gui level. The resulting script will contain the Initialize, Run, and Finish nodes. The Run node will contain recorded Web navigations based upon the defined Step Group preferences and the Web navigations and ADF actions performed during recording. You can edit the script tree or Java code to customize the script.

    • Siebel: This option lets you create a new script for automated functional testing of Siebel applications that utilize Siebel High Interactivity and Standard Interactivity/Web controls at the browser/gui level. The resulting script will contain the Initialize, Run, and Finish nodes. The Run node will contain recorded Web navigations based upon the defined Step Group preferences and the Web navigations performed during recording. You can edit the script tree or Java code to customize the script.

    • Web: This option lets you create a new script for automated functional testing of Web applications at the browser/gui level. The resulting script will contain the Initialize, Run, and Finish nodes. The Run node will contain recorded Web navigations based upon the defined Step Group preferences and the Web navigations performed during recording. You can edit the script tree or Java code to customize the script.

    General: The General group contains the following script types:

    • Database: This option lets you create the basic structure of a Database script for automated testing of SQL statements to test a database and run them in the Oracle Load Testing application. A basic script structure contains only the Initialize, Run, and Finish nodes. You can use the Import Database Capture File option on the Tools menu to import an Oracle Database Replay capture workload file, plain SQL and PL/SQL statement .SQL script file, or SQL statements captured and stored in an SQL Tuning Set (STS) into a script.

    • Java Code Script: This option lets you create a new automated test script using your own custom Java code through the OpenScript Eclipse IDE. A basic script structure contains only the Initialize, Run, and Finish nodes. You can edit the script tree or Java code to develop your own custom script. Java Code scripts are typically used for function libraries.

    • Script from Template: This option lets you create a new script from a script that has previously been saved as a template script. When you select this option, you select from a list of previously saved template scripts before specifying the name for the new script. The resulting script will contain the Initialize, Run, and Finish nodes and include any custom code that was added to the template script. You can edit the script tree or Java code to customize the script.

    • Web Services: This option lets you create the basic structure of a Web Services script for automated testing of Web Services at the SOAP/HTTP protocol level. A Web Services script structure contains only the Initialize, Run, and Finish nodes. You can use the WSDL Manager to add WSDL files and edit the script tree or Java code to customize the script. If you have a Web Services client application written already that communicates over HTTP and which communicates through a proxy, you can record the traffic using the OpenScript HTTP recorder.

    Load Testing (Protocol Automation): The Load Testing group contains the following script types:

    • Adobe Flex (AMF): This option lets you create a new script for load testing of Web applications that utilize HTTP and the Adobe Flex Action Message Format (AMF) protocols at the protocol level. The resulting script will contain the Initialize, Run, and Finish nodes. The Run node will contain recorded Flex AMF and HTTP protocol navigations based upon the defined Step Group preferences and the navigations protocol for actions performed during recording. You can edit the script tree or Java code to customize the script.

    • Oracle EBS/Forms: This option lets you create a new script for load testing of Oracle E-Business Suite and other applications that utilize HTTP and Oracle Forms (NCA) protocols at the protocol level. The resulting script will contain the Initialize, Run, and Finish nodes. The Run node will contain recorded HTTP protocol navigations based upon the defined Step Group preferences and the navigations and Forms protocol for actions performed during recording. You can edit the script tree or Java code to customize the script.

    • Oracle Fusion/ADF: This option lets you create a new script for load testing of Oracle Application Development Framework (ADF)-based applications and other applications that utilize HTTP and ADF protocols at the protocol level. The resulting script will contain the Initialize, Run, and Finish nodes. The Run node will contain recorded HTTP protocol navigations based upon the defined Step Group preferences and the navigations and ADF protocol for actions performed during recording. You can edit the script tree or Java code to customize the script.

    • Oracle JD Edwards EnterpriseOne: This option lets you create a new script for load testing of Oracle JD Edwards EnterpriseOne-based applications at the HTTP protocol level. The resulting script will contain the Initialize, Run, and Finish nodes. The Run node will contain recorded HTTP protocol navigations based upon the defined HTTP Step Group preferences and the JD Edwards Load Test Module correlation library. You can edit the script tree or Java code to customize the script.

    • Siebel This option lets you create a Siebel script structure of a new OpenScript script project. A Siebel script lets you record Siebel Web navigations using a browser for load testing Siebel applications. The resulting script will contain the Initialize, Run, and Finish nodes. The Run node will contain recorded HTTP protocol navigations based upon the defined Step Group preferences and the Web and Siebel navigations performed during recording. You can edit the script tree or Java code to customize the script.

    • Web/HTTP This option lets you create a new script for load testing of Web Applications at the HTTP protocol level. The resulting script will contain the Initialize, Run, and Finish nodes. The Run node will contain recorded Web navigations based upon the defined Step Group preferences and the Web navigations performed during recording. You can edit the script tree or Java code to customize the script. This script type has two recording modes: Web and HTTP. The recording mode is specified in the HTTP module Recording preferences, which you should set before recording new scripts. See Section 2.5.2, "HTTP Preferences" for additional information about setting the recording mode.

    Script Asset: The Script Asset group contains the following script asset types:

    • Databank: This option lets you create a new databank or open an existing databank file. The new asset wizard lets you navigate to the databank file location of an existing databank file or enter the name of a new databank file. When you click Finish in the wizard, the existing or new databank file opens in a text editor view.

    • Object Library: This option lets you create a new Object Library or open an existing Object Library. The new asset wizard lets you navigate to the Object Library file location of an existing Object Library file or enter the name of a new Object Library file. When you click Finish in the wizard, the existing or new Object Library file opens in the Object Library editor view.

  3. Click Next.

  4. Select the location where you want to store the script project. Scripts can be stored in repositories and workspaces. Load test scripts developed for use with Oracle Load Testing must be stored in a repository/workspace.

    • Path: Shows the file path of the selected repository/workspace.

    • My Repositories: Specifies the repository where the script project will be saved. Select a repository and workspace from the tree. Repositories can be managed using Manage Repositories on the Tools menu.

    • [file list]: List the names of the existing files or scripts in the selected repository/workspace.

    • Script: Specify a name for the script project. The script name is required and must be unique.

  5. Enter a script name.

  6. Click Finish to create a script or select Create as Function Library script and click Next to create a function library.

    For Java Code Scripts, a basic script tree will be created in the script view. You can edit the Java code in the code view. For module scripts, a script tree will be created in the script view. After you record the script, the tree view will contain the navigations and actions depending upon the type script.

    For existing scripts, the file concurrency control prevents multiple users from editing the same script. If you try to open a script that is in use by another user, the script copy wizard opens and you will be asked if you want to make a copy of the script and additional files.

  7. If you are creating a function library, enter a unique Package Name and Class Name to identify the library. The Package Name and Class Name must be unique among all function libraries used by a team. The Package Name and Class Name name should conform to the syntax of a Java class name, and must not contain Double-Byte Character Sets (DBCS). The suggested format for the Package name is "lib.orgName.groupName.subgroupName", for example: "lib.oracle.oats.dev.TestLibrary". The Class Name should be:

    • meaningful and provide context as to the purpose of the library,

    • clear and concise so it is easy to read and type in scripts,

    • something unique so it is not confused with other function libraries.

  8. Click Finish to create the function library. If an existing script is converted to a function library, the initialize, run, and finish sections will appear in the function library, but they only can be called as any other method in the library from caller script.

    When creating function libraries, you can use the menu options to add functions to the library file. Select the Script menu and then select Other from the Add sub menu. The procedure is similar to adding custom functions to a script. See Section 3.3.6, "Using a Script as a Dedicated Function Library" for additional information about creating a function library.

3.2.1 Recording Scripts

OpenScript includes Record capabilities for recording user actions within the application-under-test. After creating a script project, you can use the Record toolbar button or Record menu option on the Script menu to start the recorder for the type of script project. You can specify which section of the script (Initialize, Run, Finish) in which to record using the Set Record Section menu option on the Script menu.

When you start recording, OpenScript launches a browser instance along with the OpenScript Browser Helper Object (BHO) for the type of script being recorded. You can then start the application-under-test and begin recording user actions. Recorded actions will appear in the script tree and in the Java code view. A floating toolbar appears with toolbar buttons for common script recording actions such as adding tests, pause and resume, and stop recording.

Some basic script recording tips include:

  • Non-Administrator users running OpenScript on Vista, Windows 7, Windows 2008, Windows 2008r2 with Internet Explorer browsers may encounter recording and playback problems due to account privileges.

    Users in the Administrators Group, but not the exact Administrator, can use "Run As Administrator" if any recording and playback problems are encountered.

    Users belonging to Non-Administrators Group may have more problems because of access privileges to the registry or file system. These users can try the following to work around recording and playback issues:

    • add "about:blank" and the applications/web sites under testing into Trusted sites.

    • turn off the "Protected Mode" settings of the related zone (Internet, Local intranet, Trusted sites, Restricted sites). In Internet Explorer, select Internet Options from the Tools menu, then select the Security tab and clear the Enable Protected Mode option.

    If these workarounds do not resolve recording and playback issues for Non-Administrator users, the users will need to get administrator privilege to "Run As Administrator" (Administrator password needed).

  • The browser instance launched by OpenScript is index 0. Additional tabs or browser windows are indexed incrementally as they are opened. The index value is one of the identifier values used in the script Java code for object identification.

  • If you need to access another application while recording is paused or stopped, you should open a new browser window rather than use a new tab in the browser used for recording.

  • Make sure the browser zoom setting is set to 100%. Record and playback of functional test scripts at other zoom settings is not supported and may not work correctly.

3.2.2 Opening Existing Scripts

The introduction of Script Assets (in Script Properties) requires pre-version 9.10 scripts to be migrated to the current version of 9.10 or higher. This section provides information about backwards compatibility of OpenScript scripts and upgrading OpenScript scripts.

Scripts created in older versions of OpenScript will always run in new versions of the product without modification from the command-line, Oracle Load Testing, and Oracle Test Manager.

Older OpenScript scripts may not be opened or played back in the newer version of the OpenScript User Interface without upgrading them first.

Previously published script API functions are supported in the latest release. Some published API may be marked as deprecated, but will still work in the new release in order to maintain backwards compatibility.

3.2.2.1 Opening Older Scripts in OpenScript

OpenScript requires that scripts be upgraded to the latest release in order to open them in the OpenScript User Interface. You are not required to upgrade a script to the new version unless you want to open the script in the OpenScript User Interface. Older versions of OpenScript scripts can be run without modification from the command-line, Oracle Load Testing, and Oracle Test Manager. However, for version 9.0x scripts, you must maintain the Repository/Workspace structure as repositoryLocation/workspace!/script. It is not possible to copy 9.0x scripts directly to a Version 9.1+ repository.

Caution:

Version 9.10 and higher scripts cannot be played back in earlier versions of OpenScript, Oracle Load Testing, and Oracle Test Manager. If you want to maintain pre-version 9.10 scripts, you should make a back up copy of your scripts before opening and saving them in version 9.10 or higher. OpenScript automatically migrates any pre-version 9.10 scripts when the script is opened and saved in OpenScript version 9.10 or higher.

OpenScript automatically prompts you to upgrade older version scripts to the current version whenever the script is opened in the OpenScript User Interface. When opening an older script, you can choose not to open the script and the script will not be upgraded.

When prompted to upgrade a script, if the script depends on any child scripts or function libraries, OpenScript provides an option to upgrade the child scripts or function libraries to the new version also.

Once a script is upgraded to a new release, the script cannot be opened or run using older versions of Oracle Application Testing Suite (OpenScript, Oracle Load Testing, or Oracle Test Manager).

3.2.2.2 Migrating Older Scripts in OpenScript

If you wish to upgrade scripts without opening them individually in OpenScript, you can use the Migrate Scripts upgrade option on the Tools menu. The Migrate Scripts tool lets you migrate pre-version 9.10 scripts to the current version without having to open scripts individually.

The Migrate Scripts tool provides options for migrating top-level scripts and locating all dependent child scripts. The Migrate Scripts tool lets you select which scripts to migrate to the current version and find any child scripts that also need to be migrated.

Since version 9.10, scripts that will be run in Oracle Load Testing may not specify absolute paths for their repositories or script assets. However, if your pre-9.10 scripts use absolute paths, you may continue to run the same scripts, unmodified, in the current version of Oracle Load Testing. As soon as you upgrade the pre-9.10 scripts to the current version using either the OpenScript User Interface or the Migrate Script tool, the script will not playback in Oracle Load Testing until the absolute paths are changed to relative paths. The Migrate Scripts tool does not migrate absolute paths to relative paths or to repository paths. The absolute paths must be changed in the scripts manually.

3.2.2.3 Running Mixed Versions of Scripts

You are advised not to run mixed versions of "job" scripts where a parent script calls child scripts or function libraries. This may happen in cases where you may have 9.1x "parent" scripts that run 9.0x "child" scripts or function libraries. Although this configuration has been tested and is supported, the combination of mixed versions scripts may lead to unpredictable results and some confusion as to which scripts are the latest version. In addition, mixed version job scripts may not be able to take advantage of certain new version 9.10 improvements, such as:

  • Version 9.10 provides an option to visually inspect and add child script functions into a parent script. If child scripts are not upgraded to 9.10, OpenScript will not display their available functions in the user interface options.

  • Version 9.10 scripts no longer require that parent scripts add all child script databanks as their own databanks. If child scripts are not upgraded to 9.10, then parent scripts still must have child script databanks added as their own databanks.

3.2.2.4 Multiple Users Opening Scripts

For existing scripts, the file concurrency control prevents multiple users from editing the same script. If you try to open a script that is in use by another user, The script copy wizard opens and you will be asked if you want to make a copy of the script and additional files.

3.2.3 Migrating Scripts

To migrate scripts to the current version:

  1. Select Migrate Scripts from the Tools menu.

    This dialog box lets you migrate pre-version 9.10 OpenScript scripts to the current version. The Prompt on the top of the dialog box shows if the selected script is current or should be migrated and prompts for the appropriate action. The Script Migration Manager has the following options:

    • Path: Shows the file path of the selected repository/workspace.

    • My Repositories: Specifies the repository for selecting scripts to migrate or search. Select a repository and workspace from the tree.

    • [file list]: List the names of the existing files or scripts in the selected repository/workspace.

    • Script: Specify a name of a script to migrate or search.

    • Migrate: When enabled, the selected script is a pre-version 9.10 script and can be migrated to the current version. When disabled, the script is already a version 9.10 or higher script and doe not require migration.

    • Find child scripts: When enabled, the selected script is a pre-version 9.10 script and can be migrated to the current version. When disabled, the script is already a version 9.10 or higher script and does not require migration.

  2. Expand the My Repositories tree to navigate to a workspace folder containing the script files.

  3. Select the script.

    If Migrate is enabled, the script is a pre-version 9.10 and can be migrated. If Migrate is disabled, the script is already a version 9.10 or higher script and does not require migration.

    If Find child scripts is enabled, the script is already a version 9.10 or higher script and you can use the Find child scripts feature to locate any child scripts that may be assets for the currently selected script. If child scripts are located, you can use the Migrate Child Scripts options to migrate child scripts or search for additional child scripts. If Find child scripts is disabled, the script is a pre-version 9.10 script and must be migrated to the current version.

  4. Click Migrate or Find child scripts as required for the selected script file.

  5. Click Close when finished.

3.2.4 Creating New Scripts from Templates

You can create a new script from any other previously saved script. The resulting script will contain the Initialize, Run, and Finish nodes and include any custom code that was added to the saved script.

To create a new script from a saved script:

  1. Select New from the File menu or click the toolbar button.

  2. Expand the General section and select Script from Template.

  3. Click Next.

    Note:

    If you have previously saved an existing script as a template script using an earlier version of OpenScript, you can also create a new script from a template script.
  4. Select the script to use to create the new script and click Next.

  5. Enter a script name for the new script and click Finish. If you are creating a new dedicated function library script from a saved dedicated function library script, you will also need to specify a new library class name for the new function library so there will not be duplicated function library classes.

3.2.5 Setting Script Properties

Script properties specify the property settings for a specific script. You can set script properties at any time when a script is open. Script properties include the following:

  • Script assets including Databanks, Object Libraries, Generic Jar files, and other scripts to run as child scripts.

  • Correlation properties for Load Testing (protocol automation)-type scripts.

  • Module properties specifying which module services to include with a script.

  • Step Group properties specifying how step groups are created during recording.

To set Script Properties:

  1. Open or a create a script project.

  2. Select Script Properties from the Script menu.

  3. Select the property type in the left pane.

  4. Use the options in the right pane to set specific properties.

  5. Click OK when finished.

The script property panes are described in the following sections.

3.2.5.1 About

This dialog box shows the current script's location and history.

3.2.5.2 Correlation and Validation

This dialog box lets you specify correlation properties for Load Testing (protocol automation)-type scripts. The Correlation pane has the following options:

  • Module: Specifies the module type the script will use for the correlation rules.

  • Selected Module's Settings: Shows the current script's Correlation library and rules settings. Expand the tree view to view the selected libraries and rules.

    • Edit: Opens the correlation properties window for the specified module type.

3.2.5.3 Modules

This dialog box lets you specify which module services to include with a script. The Modules pane has the following options:

  • Modules: Shows which module services are included with the current script. The Basic and Utilities modules are common to all script types. The Shared Data module can also be used with all script types. The HTTP module is common to all load testing (protocol automation)-type scripts. The Functional Test and Web Functional Test modules are common to functional test-type scripts. Other modules are specific to a script type.

3.2.5.4 Script Assets

This dialog box lets you specify assets to a script. The Script Assets pane has the following options:

  • Asset: Lists the Assets added to a script by type in a tree view. Script Assets can be Databanks, Object Libraries, Generic Jar files, and other scripts.

  • File: Shows the files added as Assets to the current script. Expand the tree view in the Assets column to view the files.

  • Add: Opens a file selection dialog box for selecting the file to add as an asset. Expand the My Repositories tree to navigate to a workspace folder containing the file.

    Note:

    Any scripts you plan to run, along with any associated assets, in the Oracle Load Testing application must be stored in a repository/workspace that can be accessed by the Oracle Load Testing Controller. If you create new repositories in OpenScript, you should also add the new repositories in Oracle Load Testing.
  • Edit: Opens a file selection dialog box for changing which file is added as an asset.

  • Open: Opens the selected asset file in the appropriate editor.

  • Remove: Removes the selected asset file from the Assets tree. The file still exists in repository/workspace.

3.2.5.5 Step Groups

This dialog box lets you specify Step Group properties for the current script. The Step Group pane has the following options:

  • Module: Specifies the module type the script will use for the step group rules.

  • Selected Module's Settings: Shows the current script's Step Group settings. The settings are specific to the script type.

    • Edit: Opens the Step Group properties window for the specified module type.

3.2.6 Importing Database Capture Files

You can import a Database Replay capture file, plain SQL and PL/SQL statements .SQL script file, or SQL statements captured and stored in an SQL Tuning Set (STS) to generate an OpenScript load testing script that connects to a database and executes the SQL statements.

To set the Database preferences:

  1. Select OpenScript Preferences from the View menu.

  2. Expand the OpenScript node.

  3. Select the General node.

  4. Select the Date Format. See Chapter 2, "General Preferences" for additional information.

  5. Click OK.

To create a script from Database Capture file:

  1. Select New from the File menu.

  2. Expand the General group and select the Database script type.

  3. Click Next.

  4. Select the repository and workspace where you want to store the script.

  5. Enter a script name and click Finish. A new basic script project is created in the Script tree.

  6. Select Import Database Capture File from the Tools menu. The Import Database Capture File Wizard opens for specifying the file format type, source file, and SQL statement parameterization for imported database capture files or SQL statement files.

  7. Select the Database file format to import:

    • Database Replay Capture File: When selected, an Oracle DBReplay capture workload file can be imported.

    • SQL and PL/SQL Statement Script: When selected, a plain SQL and PL/SQL statements .SQL script file can be imported.

    • STS in Oracle Database: When selected, SQL statements captured and stored in an SQL Tuning Set (STS) can be imported.

  8. Specify the maximum number of items to import.

  9. Click Next.

  10. Enter the file path and name of the Database Replay capture file (.rec file extension), SQL and PL/SQL statement script file (.sql file extension), or SQL Tuning Set (STS), or click Browse to select the file.

  11. Click Next.

  12. Select the alias name of the database connection to use or click New to specify a new connection. If you select New, enter the Database Driver, URL, username, password, and alias information. The alias is the name used in the script to reference the database connection. Click Test to verify the connection and click OK to use the new connection.

  13. Select or clear individual SQL statements to include in the script and set the parameterization for the SQL statements.

    • Edit: Opens a dialog box for editing a specific SQL query. You can edit the SQL query or use the edit options to Parameterize specific values of the query.

    • Parameterize: Creates SQL bindings for all literal parameters of the selected SQL query. This is used to make the database parse the SQL statements more efficiently. For example, an application that makes the following three database queries:

      BEGIN DBMS_OUTPUT.GET_LINES(1, 100); END;
      BEGIN DBMS_OUTPUT.GET_LINES(5, 100); END;
      BEGIN DBMS_OUTPUT.GET_LINES(7, 100); END;
      

      The above statements require the database to parse the entire query 3 times, even though the structure of the query does not change. It is more efficient for database parsing to pass parameter arguments to the queries. For example:

      BEGIN DBMS_OUTPUT.GET_LINES(?, ?); END;
      BEGIN DBMS_OUTPUT.GET_LINES(?, ?); END;
      BEGIN DBMS_OUTPUT.GET_LINES(?, ?); END;
      

      When executing the above SQL statements, the application would separately specify the literal parameter values to input to the database (that is: 1, 100, 5, 100, 7, 100).

      If you insert a new SQL query manually using Edit, the Parameterize button parameterizes all literals and named parameters. For example, the following statement:

      BEGIN DBMS_OUTPUT.GET_LINES(5, :NUMLINES); END;
      

      will be parameterized as:

      BEGIN DBMS_OUTPUT.GET_LINES(?, ?); END;
      

      In certain cases, using the Parameterize button may produce unwanted parameterization of a literal. For example, in the following statement:

      SELECT 1 FROM EMPLOYEES
      

      will be parameterized as:

      SELECT ? FROM EMPLOYEES
      

      In the above example, if the you did not intend for the "1" to be parameterized, you would have to manually adjust the parameterization using Revert.

      When importing a DBReplay file, or .SQL file, OpenScript will only parameterize things that are already parameterized in the file itself.

    • Revert: Reverts the selected parameterized SQL query back to the original imported statement.

    • Check All: Selects all imported SQL statements.

    • Uncheck All: Clears the check marks from all imported SQL statements.

    • Automatically Add Row Count Tests: When selected, a row count test is automatically inserted for each SQL statement added to the script.

    • Parameterize Checked: Creates SQL bindings for all literal parameters in all checked statements.

    • Revert Checked: Reverts to the original imported SQL statement for all checked statements.

  14. Click Finish.

The Database capture or SQL file import recorder parses the file and generates an OpenScript script using the specified Parameterize settings. The script creation time can vary depending upon the size of the capture file.

The resulting script contains the Java code required to connect to the database and execute the SQL queries selected in the import wizard. The script uses the OpenScript utilities.getSQLService() methods to execute the SQL statements.

3.2.7 Importing Oracle Real User Experience Insight (RUEI) Session Logs

You can import a RUEI captured user session log file to generate an HTTP-based OpenScript load testing script. The RUEI User Session log must be generated using RUEI version 6 or higher.

To create a script from RUEI user session log:

  1. Select New from the File menu.

  2. Expand the Load Testing (Protocol Automation) group and select the Web/HTTP script type.

  3. Click Next.

  4. Select the repository and workspace where you want to store the script.

  5. Enter a script name and click Finish. A new HTTP protocol script project is created in the Script tree.

  6. Select Import Oracle Real User Experience Insight (RUEI) Session Log from the Tools menu.

  7. Enter the file path and name of the RUEI User Session log (.tab file extension) or click Browse to select the file.

  8. Set the Correlate script and Create step groups options.

  9. Click OK.

The RUEI Session log import recorder parses the log file and generates an HTTP-based OpenScript script using the specified Correlate script and Create step groups settings. The script creation time can vary depending upon the size of the log file and if the Correlate script and Create step groups settings are set or not. Generally, when Correlate script and Create step groups are set, the script creation time increases.

The RUEI User Session Log consists of the following files and folder:

  • data.tab file: This file contains the url, host and port, method, postdata, etc.

  • version.txt: This files contains the export version number which determines the version of the OpenScript RUEI User Session Log importer to use.

  • content folder: This folder contains text content that corresponds to the entries in the data.tab file.

To get the necessary files to be exported from RUEI, URL prefix masking should be set to "Complete logging". Complete logging is not turned on by default in RUEI. In addition, the session exported from RUEI should not be older than the Full Session Replay (FSR) setting specified in the Collector data retention policy settings. Otherwise, no (or only partial) data will be available. See the Oracle Real User Experience Insight User's Guide for details about URL prefix masking and the Collector data retention policy settings.

3.2.8 Exporting Script Playback Settings

You can export the script playback settings to a properties file. The playback setting properties file lists all of the options and settings that were specified for the script. You can use the properties file for Command Line execution of the script using the -propertiesPath setting. See Appendix A, "Script Command Line Reference" for additional information about using the -propertiesPath setting.

To export script playback settings:

  1. Open the script in OpenScript.

  2. Select Export Playback Settings from the Tools menu.

  3. Select the directory location and specify a file name.

  4. Click Save. The file name is filename.properties.

3.3 Modifying Scripts

Once you have created a script project, you can customize the script for your specific testing purposes using the available menu options or editing your own code in the Java Code view.

3.3.1 Adding Step Groups to a Script

Step groups provide a way to group multiple procedures into a single reporting step.

To add a manual step group to a script:

  1. Open or create a script project.

  2. Select the script node where you want to add the step group.

  3. Select the Script menu and then select Step Group from the Add sub menu.

    This dialog box lets you specify or modify a step group node in a script tree.

  4. Enter a name for the Step Group.

    Title: Specify the title text of the step group. The title text will appear in the script tree.

  5. Enter any think time delay to add to the Step Group.

    Think time: Specify the amount of time in milliseconds to use as a think time delay for the step group or select no delay.

    • No delay: When selected, no additional think time delay is added to the beginning of the step group.

    • Delay [ ] sec: When selected, the specified amount of think time delay is factored with the VU Pacing (think time) playback setting to specify the amount of delay to add to the beginning of the step group.

  6. Click OK. The Step Group is added to the script tree.

To add a step groups to a script based upon preferences:

  1. Open or create a script project.

  2. Select OpenScript Preferences from the View menu.

  3. Expand the OpenScript node.

  4. Expand the Record node.

  5. Select the Step Groups node.

  6. Specify the Step Group preferences and click OK.

  7. Select Create Step Groups from the Script menu. The Step Groups will be automatically added to the script tree.

  8. In the Java Code view, the step group consists of the code executed between beginStep and endStep:

    beginStep("Step Group 1", 10);
    {
            /**
             * Add code to be executed for the step group.
             */
           info("Step Group 1");
    }
    endStep();
    

3.3.2 Adding a Delay to a Script

To add a delay to a script:

  1. Open or create a script project.

  2. Select the script node where you want to add the delay.

  3. Select the Script menu and then select Other from the Add sub menu.

  4. Expand the General node and select Think Time.

    This dialog box lets you specify or modify a delay time in seconds.

  5. Enter a valid integer to use as the think time in seconds.

  6. Click OK. The Think node is added to the script tree.

  7. In the Java Code view, the think(time;) (the time is in seconds) statement will be added to the script code:

    think(10.0);
    

3.3.3 Adding a Log Message to a Script

To add a log message to a script:

  1. Open or create a script project.

  2. Select the script node where you want to add the log message.

  3. Select the Script menu and then select Message from the Add sub menu.

    This dialog box lets you specify or modify a log message in a script tree.

  4. Enter the message text.

    Message: Specify the text of the log message. The text will appear in the Console view on script playback.

  5. Click OK. The log message node is added to the script tree.

  6. In the Java Code view, the type("log message") method will be added to the script code:

    info("Message");
    warn("Message");
    fail("Message");
    

The log message text appears in the Console View when the script is played back.

3.3.4 Adding a For Statement to a Script

To add a For statement to a script:

  1. Open or create a script project.

  2. Select the script node where you want to add the For statement.

  3. Select the Script menu and then select Other from the Add sub menu.

  4. Expand the Control Statements node and select For.

    This dialog box lets you specify or modify the For statement loop count.

  5. Enter a valid integer to use as the loop count.

    Loop Count: Specify the number of times to loop though the For statement.

  6. Click OK. The For node is added to the script tree.

  7. In the Java Code view, the for (int i=0; i < loop count; i++) statement will be added to the script code:

    for (int i=0; i < 10; i++)
    

3.3.5 Adding a Function to a Script

You can add your own custom functions to your script and specify the arguments to pass to the function. Custom functions can be in the current script or in another script or function library script that has been added to the current script's Scripts Assets Properties. See Section 3.3.6, "Using a Script as a Dedicated Function Library" for additional information about creating a dedicated function library script.

To add a function to a script:

  1. Create a script project.

  2. Record a complete script.

  3. Select the Run node in the script tree.

  4. Select the Script menu and then select Other from the Add sub menu.

  5. Expand the General node and select New Function.

    This dialog box lets you specify a custom function name with multiple arguments.

    Name: Specifies the name of the custom function. Click Add to define the names and data type of an argument.

    Description: Specifies a user-defined description for the custom function.

    Argument: Lists the defined function arguments for the custom function.

    Type: Lists the data type for the defined argument for the custom function.

    Description: Lists the user-defined description for the argument defined for the custom function.

    Add: Opens a dialog box for defining a new argument for the custom function.

    Edit: Opens a dialog box for editing the selected argument.

    Delete: Removes the selected argument from the list.

    Up: Moves the selected argument up one place in the list.

    Down: Moves the selected argument down one place in the list.

  6. Enter the function name.

  7. Enter a description for the function.

  8. Click Add.

    This dialog box lets you specify a custom function argument to use to pass data to the function.

    Name: Specify a name of the custom function argument.

    Type: Select the data type: String, Integer, Double, Long, Boolean, Select List, List<String>, or Map<String, String>.

    Description: Specify a description for the argument (you may want to include the data type in the description so that it is indicated in the Substitute Variable list).

  9. Enter an argument name.

  10. Select the data type for the argument.

  11. Click OK.

  12. Click Add and add more arguments or click OK to add the function to the script. The function name node is added to the script tree.

  13. In the Java Code view, the public void function name statement will be added to the script code followed by the arguments with the data types:

    /**
     * My custom Function
     * @param argString Description of argString
     * @param argInt Description of argInt
     * @param argDouble Description of argDouble
     * @param argLong Description of argLong
     * @param argBool Description of argBool
    */
    public void MyFunction(@Arg("argString") String argString,
          @Arg("argInt") int argInt,
          @Arg("argDouble") double argDouble,
          @Arg("argLong") long argLong,
          @Arg("argBool") boolean argBool)
       throws Exception {
    
  14. Add items into the Function. You can use the Tree View drag/drop or cut/paste features to move Tree View items to the function. You can use the Script Add option to add variable items to the function. You can also use the Code View to add custom code to the function.

To pass arguments into a function:

Define the variables to use to pass values to the custom function arguments somewhere in the script before where the Call Function statement will be placed in the script:

  1. Select the script node where you want to add variables.

  2. Select the Script menu and then select Other from the Add sub menu.

  3. Expand the Variables node and select Set Variable.

    This dialog box lets you define a variable in a script.

  4. Enter the variable name and value.

    • Name: Specify the name of the variable.

    • Value: Specify the value to assign to the variable.

  5. Enter a value or click the Substitute Variable icon to select a variable value to assign to the variable.

  6. Click OK.

  7. In the Java Code view, the getVariables().set() statement will be added to the script code followed by the variable name and value for each variable:

    getVariables().set("MyString", "String");
    getVariables().set("MyInt", "1");
    getVariables().set("MyDouble", "12.34");
    getVariables().set("MyLong", "1234560");
    getVariables().set("MyBool", "True");
    

    The following is an example of a variable set to a Databank value:

    getVariables().set("MyString", "{{db.customer.FirstName,String}}");
    
  8. Select the Function node (your custom function name) in the script.

  9. Select the Script menu and then select Other from the Add sub menu.

  10. Expand the tree and select the item to add. For example Message under the General node or Set Variable under the Variables node.

  11. Click the Substitute Variable icon to select a custom variable or function argument. The Select Variable tree lists the custom function with all of is defined arguments.

  12. Select an argument for the custom function.

  13. Click OK.

  14. In the Java Code view, the message statement (info, warn or fail) or getVariables().set() statement will be added to the script code followed by the variable name and value for each variable:

    public void MyFunction(@Arg("argString") String argString,
          @Arg("argInt") int argInt,
          @Arg("argDouble") double argDouble,
          @Arg("argLong") long argLong,
          @Arg("argBool") boolean argBool)
       throws Exception {
          info("{{arg.argString}}");
          getVariables().set("MyArgString", "{{arg.argString}}");
          getVariables().set("MyArgInt", "{{arg.argInt}}");
          getVariables().set("MyArgDouble", "{{arg.argDouble}}");
          getVariables().set("MyArgLong", "{{arg.argLong}}");
          getVariables().set("MyArgBool", "{{arg.argBool}}");
    }
    

To call a custom function in a script:

  1. Select the node in the script tree here you want to call the function.

  2. Select the Script menu and then select Other from the Add sub menu.

  3. Expand the Script Function node and the sub node where the custom function is located. Custom functions can be in the local (currently open) script or in another script added to the Script Assets Properties (select Script Properties from the Script menu to add other scripts to the Script Assets Properties).

  4. Select the function to call and click OK.

    This dialog box lets you specify a custom function to call and specify the argument values.

  5. Enter the argument data to pass to the custom function or click the Substitute Variable icon to select a custom variable or databank variable.

    • Function: Select the name of the custom function. The names of custom functions that were added to the script will appear in this list.

    • Arguments: A field for each custom function argument will appear for the selected function. Enter the argument value or click the Substitute Variable icon to select a custom variable or databank variable.

  6. Click OK.

  7. In the Java Code view, the callFunction, getScript("ScriptAlias").callFunction(), or className.function()statement will be added to the script code followed by the function name and arguments. If the function is in the same script, the callFunction statement is added:

    callFunction("MyFunction", "MyStringArg");
    

    To pass data types other than String, enclose a defined variable name in double curly braces as follows, "{{VarName}}".

    callFunction("MyFunction", "{{MyString}}", "{{MyInt}}", "{{MyDouble}}", "{{MyLong}}", "{{MyBool}}");
    

    If the function is in a another script (a script containing functions that has been added to the current script as a script asset), the getScript("MyScriptAlias").callFunction("MyCustomFunction", "args"); statement is used to call the function similar to the following example:

    getScript("MyScriptAlias").callFunction("MyCustomFunction",
      "MyString", "true", "2", "10.5", "100", "list1",
      toList("ListString1", "ListSting2"), toMap("key1=value1"));
    

    If the function is in a dedicated function library script (a script specifically created as a function library that has been added to the current script as a script asset), the className.function("args"); statement is used to call the function similar to the following example:

    myFunctionLibrary.MyLibraryFunction("MyString", true, 2, 10.5, 100,
      "list1", toList("ListString1", "ListString2"),
      toMap("key1=value1"));
    

    See Section 3.3.6, "Using a Script as a Dedicated Function Library" for addition information about dedicated function libraries.

3.3.5.1 Adding Functions that Use Lists

The Type options of the Argument dialog box used when adding a function to a script includes a List<String> type that can be used to create a function that accepts a list of values as a parameter.

Follow steps 1-9 in Section 3.3.5, "Adding a Function to a Script" to add a new function to a script. Select List<String> as the argument type.

Enter the list of values into the Arguments Values field and click OK.

The following example code shows a function that uses List<String> for one of the parameter values:

/**
 * a function that uses List<String> parameter.
 * @param user a String specifying the user name.
 * @param password a String specifying the password.
 * @param urls a List<String> specifying the urls.
 */
public void myListFunction(@Arg("user") String user, 
      @Arg("password") String password, 
      @Arg("urls") java.util.List<String> urls)
   throws Exception{
   }

When the user calls the function using the Script menu options, the Call Function dialog box will include a multi-line text box that allows a list of values to be entered. In the Java Code view, the callFunction() code will include a toList parameter similar to the following example:

callFunction("myListFunction", "testuser", "testpwd", toList(
    "http://mysite.com/url1.html",
    "http://mysite.com/url2.html",
    "http://mysite.com/url3.html"));

If the function is in a function library script (a function library script added as a script asset), the ClassName.function() statement is used to call the function similar to the following example:

MyClassNameAlias.myListFunction("testuser", "testpwd", toList(
    "http://mysite.com/url1.html",
    "http://mysite.com/url2.html",
    "http://mysite.com/url3.html"));

3.3.5.2 Adding Functions that Use Maps

The Type options of the Argument dialog box used when adding a function to a script includes a Map<String, String> type that can be used to create a function that accepts key/value pair maps as a parameter.

Follow steps 1-9 in Section 3.3.5, "Adding a Function to a Script" to add a new function to a script. Select Map<String, String> as the argument type.

Enter the key=value pairs into the Arguments Values field and click OK.

The following example code shows a function that uses Map<String, String> for the parameter values:

/**
 * a function that uses Map<String, String> parameter.
 * @param keyandvalue a Map<String, String> specifying key/value pair maps.
 */
public void myMapFunction(
      @Arg("keyandvalue") java.util.Map<String, String> keyandvalue) 
   throws Exception {
   }

When the user calls the function using the Script menu options, the Call Function dialog box will include a multi-line text box that allows a key/value pair maps to be entered. In the Java Code view, the callFunction() code will include a toMap parameter similar to the following example:

callFunction("myMapFunction", toMap(
    "key1=value1",
    "key2=value2",
    "key3=value3"));

If the function is in a function library script (a function library script added as a script asset), the ClassName.function() statement is used to call the function similar to the following example:

MyClassNameAlias.myMapFunction(toMap(
    "key1=value1",
    "key2=value2",
    "key3=value3"));

3.3.5.3 Adding Functions that use Enumerated Lists

The Type options of the Argument dialog box used when adding a function to a script includes a Select List type that can be used to create a function that accepts a value from a known list of values as parameters.

Follow steps 1-9 in Section 3.3.5, "Adding a Function to a Script" to add a new function to a script. Select Select List as the argument type.

Enter the values into the Arguments Values field and click OK.

The following example code shows a function that uses Select List for the parameter values:

/**
 * a function that uses Select List parameter.
 * @param color a Select List specifying enumerated list of color values.
 */
public void mySelectListFunction(
      @Arg("color") @Values( { "red", "blue", "green" }) String color) 
   throws Exception {
   }

When the user calls the function using the Script menu options, the Call Function dialog box will include a select list box that allows a single value from a list of values to be selected. In the Java Code view, the callFunction() code will include the function name and selected parameter similar to the following example:

callFunction("mySelectListFunction", "blue")

If the function is in a function library script (a function library script added as a script asset), the ClassName.function() statement is used to call the function similar to the following example:

MyClassNameAlias.mySelectListFunction("blue");

3.3.5.4 Inputting Values from a File

The list and map functions can also specify one or more files as an alternate method for inputting list or map data to function arguments using the @dataFile variable. The @dataFile variable specifies the optional repository name, data file path, and optional file encoding using the following format:

{{@dataFile('repository','relativeFilePath')}} 
{{@dataFile('repository','relativeFilePath','encoding')}} 

Create data files containing the appropriate function argument data.

For list functions that use toList(), the data file might appear similar to the following example:

    "http://mysite.com/url1.html"
    "http://mysite.com/url2.html"
    "http://mysite.com/url3.html"

For map functions that use toMap(), the data file might appear similar to the following example:

    "key1=value1"
    "key2=value2"
    "key3=value3"

The toList() and toMap() methods also parse all arguments for any newline delimiters. Any newline delimiters embedded in a value or file will be converted into new list entries. For example,

"value1\r\nvalue2\r\nvalue3"

is equivalent to:

"value1"
"value2"
"value3"

When the user calls a function that uses lists or maps as argument values using the Script menu options, the Call Function dialog box will include the Substitute Variable icon next to the Arguments values field.

Click the Substitute Variables icon next to the Arguments values field.

Expand the @Functions tree, select @dataFile, and click Finish.

The argument value field will contain the {{@dataFile('repository', 'relativeFilePath')}} transform variable. Edit the repository and relativeFilePath values to specify the repository name and relative path to the data file containing the data to pass to the function.

  • repository - specifies the name of the repository where the data file is located. The repository argument can be left blank (using two single quotation marks '') if a relative path is specified for the data file.

  • relativeFilePath - specifies the path and file name of the data file. The file path is relative to the script directory. If the repository is not specified (''), then relativeFilePath should begin with ../.

  • encoding - specifies the file encoding to use. Although not automatically added the in the @dataFile() default value, the file encoding can be added as a third String value in the @dataFile() variable. For example, UTF-8, cp1252 (ANSI), SHIFT-JIS, cp1250 (Central Europe), cp1251 (Eastern Europe).

When you click OK, the function will be added to the tree view similar to the following:

myMapFunction(toMap({{@dataFile('myRepo','files/datafile.txt','cp1252')}}))

In the Java Code view, the callFunction() code will include the function name and @dataFile() variable similar to the following example:

callFunction("myMapFunction", toMap(
  "{{@dataFile('myRepo','files/datafile.txt','cp1252')}}"));

If the function is in a function library script (a function library script added as a script asset), the ClassName.function() statement is used to call the function similar to the following examples:

MyClassNameAlias.myMapFunction(toMap("{{@datafile('','../files/datafile.txt'}}"));

MyClassNameAlias.myListFunction("user", "pwd", 
   toList("{{@datafile('','../files/datafile.txt'}}"));

3.3.6 Using a Script as a Dedicated Function Library

You can create a script that can be used as a dedicated function library that can be used by other scripts as a script asset. The dedicated function library script can contain custom functions that can be called from other scripts. A dedicated function library provides a way for having code assistance in scripts calling functions from the library. When creating dedicated function library scripts you should make the library either a generic Java code script or the same type as the scripts (that is, Web, HTTP, Siebel, etc.) that will be calling functions from the library.

3.3.6.1 About Function Libraries

This section provides basic information and Frequently Asked Questions (FAQs) about function libraries.

What is a function library?

A function library is a means to make your code more reusable and modular. Any script can be used as a function library by creating a library of custom functions within the script code. The function library script can then be added to other scripts as a script asset. The other scripts can then call custom functions from the function library script.

What is the difference between a function library and a regular script?

In general, there is only a minor difference between a function library script and regular script. A function library is a script which you can record into and play back but also includes a unique package and class name. However, function library scripts are generally not intended to be played back. You use a function library script as an asset for other scripts that can call the custom functions contained in the library. Function library scripts include the Initialize, Run, and Finish methods the same as a regular script. The Initialize, Run, and Finish methods in a dedicated function library script are not intended to be called from other scripts. The Initialize, Run, and Finish methods are provided for debugging function library scripts before publishing them.

How do I create a function library?

Before OpenScript version 12.1.0.1, regular scripts were used as function libraries. Users simply added custom functions to a script which was designated as a function library. See Section 3.3.5, "Adding a Function to a Script" for additional information about adding functions to a script. OpenScript version 12.1.0.1 introduces dedicated function library scripts. See Section 3.3.6.2, "Creating a Dedicated Function Library Script" for additional information about creating a dedicated function library script.

What are the advantages of using a dedicated function library?

There are three main advantages to using dedicated function libraries compared with using a script containing functions:

  • The primary advantage is provided for teams that widely use the Java Code view with custom code. The style of calling functions from a dedicated function library script is much more straight forward and clear. For example, with the dedicated function library you call a function a function foo in the library with alias myLib as follows:

    myLib.foo("myArg"); 
    

    With custom functions in a regular script, you call a function using the Reflection style, as follows:

    getScript("myLib").callFunction("foo", "MyArg")
    
  • A second advantage of a dedicated function library is that the direct style of calls provides code assistance in the Java Code view for calling functions stored in a dedicated function library script. There is no code assistance in the Java Code view for calling functions stored in a regular script and called using the callFunction method.

  • A third advantage of a dedicated function library is the ability to use custom classes in the library.

What are the disadvantages of using a dedicated function library, versus using a script with functions in it?

There are some advantages to using dedicated function libraries compared with using a script containing functions:

  • A dedicated function library not only has a unique script location, but also a unique library class name. The library class name is rendered when creating the dedicated function library and cannot be changed. If for some reason you need or want to change function library class name (for example, a duplicated function library name was found or something else), you will need to create a new script by selecting Save As from the File menu or by creating a script from an existing script. You will need to enter a new name for the function library class and a new script will be created. The new script will have all of the functions declared in the old function library.

  • Another minor disadvantage of using a dedicated function library is that it needs to be assigned as an asset to each script that uses it. In contrast, using getScript("funcLib").callFunction(), you only need to assign a function library as an asset with the alias "funcLib" to the top level script. Any child scripts will find the function library by its alias during runtime. However, this usage is blind as users have no Tree View or dialog support for inserting such code. By not assigning the dedicated function library directly to a script as an asset, you can only call its functions by typing code directly into the Java code view using the Reflection style syntax. Also, code assistance is not provided for Reflection style syntax.

How can I use a common function library in all scripts I create?

Particularly when creating many test scripts, it can be time consuming to attach commonly used function libraries to each one individually. There are two approaches to solve this problem.

  1. Create Scripts from an Existing Script

    You can create an empty script and attach to it all the common function libraries you want your scripts to use. Each time you create a new script, select New from the File menu, select Script from Template in the General section, then select the script with your common functions to create the new script. Each new script will have the common function libraries attached to it.

    The one downside to attaching a function library to every script. If you physically move a function library to a different location on disk, then all existing scripts referencing it from the old location will break.

  2. Attach Function Libraries to a Parent "Master" Script

    If you have a test setup where one parent "master" script calls several "child" scripts, you can attach the common function libraries only to the parent script and not attach it to any child scripts. Child scripts will be able to directly call the function libraries from Java Code using the reflexive code syntax. For example

    getScript("myLib").callFunction("foo", "MyArg");
    

    The benefit to attaching the function library to the parent script, and not to the child scripts, is that if the function library is moved to a different location, you only need to update the parent script with the new function library location. All child scripts will continue to work. However, using this approach, child scripts cannot use the explicit code syntax when calling functions. For example:

    myLib.foo("MyArg");
    

    Child scripts will not be able to use any custom classes exposed by the function libraries or leverage any Java Code assistance features. The child scripts' Tree view will also not provide any UI for adding available functions. This approach is only recommended for teams not relying on the Tree view UI for adding function calls.

Will my existing pre-12.1 function libraries continue to work in new releases?

Yes. See Section 3.2.2, "Opening Existing Scripts" for additional information about backwards compatibility of scripts. Existing scripts and function libraries will continue to work, unmodified, in newer releases.

If you want to take advantage of new features such as code assistance, custom classes, and the explicit function calling syntax, then you would need to create a dedicated function library. However, it is optional if you want to convert your existing script-based function libraries into dedicated function libraries or leave them as regular scripts.

What happens if two different dedicated function library scripts used in a test suite have the same library class name?

Using two function libraries with the same library class name will cause your script to behave unpredictably. Most likely, the OpenScript script editor will display an error when it compiles the script, indicating that some particular method or class cannot be found. This is why, when you are creating a name for library class, it is better to use a long package path to differentiate your library class from other libraries. For example, lib.TestLib is a poor choice. A much better choice would similar to: lib.myCompany.myTeam.framework2.UtilLib.

Can I use custom classes as arguments and return values for functions in function libraries?

You can only use custom classes as arguments and return values for functions in dedicated function libraries. In order for custom classes to be visible to calling scripts they should reside in package "lib" that is automatically created for each dedicated function library. If the author of the function library needs some internal custom classes, then their place is in a sub-package of "lib" package. This way they will be hidden from other scripts. It is better not to put any additional classes in the package where library class itself resides.

Be cautious and do not overuse custom classes. The user of the function library will not get help from UI or code assistance for them. Almost any task can be achieved with the set of data types provided in the OpenScript UI for providing assistance, which includes all primitive types, Enum(selection), List<String>, and Map<String, String>.

I have a function in a function library that returns a custom type. How do I to save it for later use?

You will need to know what type is returned and save it in a script or java variable. Note that OpenScript does not support declaring custom functions (in regular scripts or dedicated function library scripts) that expect the varargs argument feature. That is, arg type, Something...). For example, Foo(String name, String... args);.

Also, having an argument type of List is always preferable to argument of type Array. Thus List<String> is better than Array[]. The reason is creating functions with argument that has an Array type requires the users of the function resolve any ambiguity of casting Array[] vararg type, as it could be cast to Object or Object[].

My function library needs to use third-party JAR files. How I can I do it?

A function library is a script. Assign the JAR file to the script as a generic JAR script asset. You will then have access to all public methods from the Java Code view. Code assistance will help you add the required import statements and call methods in the code view.

Note:

Generic JAR files should not contain any code that uses OpenScript API or Eclipse API.

I would like to expose some methods in third-party JAR files to test scripts to be able to call them. What I should do?

You can assign this JAR file to each script that is going to use it as a script asset. However, it is a blind way for users to call functions in JAR file. A better way is to assign this JAR file to a function library script and wrap the methods in the JAR file that will be called by scripts within functions in the function library. You will be able to control access to the JAR file and, more importantly, add extensive comments on when and how to use these methods. This will benefit the other members in your group by making the use of the functions easier.

What help should I provide to users of my function library?

Function library developers should provide meticulous and extensive Javadoc comments for each function in the function library. The Javadoc comments are what the user sees about each function in the Tree View and as code assistance in the Java Code view.

3.3.6.2 Creating a Dedicated Function Library Script

To create a dedicated function library script:

  1. Select New from the File menu.

  2. Select the project type (typically Java Code Script) and click Next.

  3. Enter a script name for the function library (for example, myScriptLib).

  4. Select Create script as a Function Library.

  5. Click Next. The script wizard opens the Create Function Library options:

    Package: Specifies a unique Package name for the function library. Package must be a valid Java Package name that matches A-Z, a-z, 0-9, _. It must not contain spaces or Double-Byte Character Sets (DBCS). The initial default value is myCompany.myTeam. Subsequently, the default value will be set to the last value specified.

    Class: Specifies a unique alias to use as the name (typically the Class name) for the function library script. Class must be a valid Java Class name that matches A-Z, a-z, 0-9, _. It must not contain spaces or Double-Byte Character Sets (DBCS). The Class Name should be:

    • meaningful and provide context as to the purpose of the library,

    • clear and concise so it is easy to read and type in scripts,

    • something unique so it is not confused with other function libraries.

  6. Enter a unique Package name for the function library in the form:

    orgName.groupName.subgroupName
    

    For example:

    oracle.oats.dev
    
  7. Enter a unique alias to use as the Class name for the function library to identify the library. For example:

    WebFunctLib
    
  8. Click Finish.

  9. Select the script section (Initialize, Run, or Finish) where you want to add custom functions.

  10. Select the Script menu and then select Other from the Add sub menu.

  11. Expand the Script Functions and Local Script nodes.

  12. Select [New Function] and click OK.

  13. Enter a function name and description.

  14. Click Add to add any arguments to the function.

    • Enter a name, specify the data type, and enter a description for the argument.

    • Click OK to add the argument.

  15. Repeat step 14 for each argument to add to the function.

  16. Click OK to add the function to the script.

  17. Add your custom code to the function.

    • Use the script recorder to record steps.

    • Switch to the Java Code view and edit the code in the function.

  18. Repeat steps 10 through 17 to add additional functions to the library script. See also Section 3.3.5, "Adding a Function to a Script" for additional information about adding functions to a script.

  19. Save the library script.

3.3.6.3 Calling Functions from a Function Library Script

To call functions from the library script:

  1. Create a new script project (for example, masterScript).

  2. Select the Script menu and then select Properties.

  3. Select the Script Assets type and then select Scripts.

  4. Click Add.

  5. Select your custom functions library script and click OK.

  6. Click OK to close the Script Properties.

  7. Select the Script menu and then select Other from the Add sub menu.

  8. Expand the Script Functions and Script: scriptLibraryName nodes.

  9. Select the function name from the library script and click OK.

  10. If the Call Function dialog box appears, enter the function arguments and click OK.

    The function name appears in the script tree as scriptLibraryname.functionName(args, [...])

    In the Java Code view, the @FunctionLibrary assignment will be added to the script code followed by the library Package Name and function library alias entered when the function library was created, as follows:

    @FunctionLibrary lib.package alias;
    

    For example

    @FunctionLibrary lib.oracle.oats.dev webFunctLib;
    

    Functions called from the function library appear in the Java Code view using the function library alias and called function name and arguments, as follows:

    alias.functionName("args", "[...]")
    

    For example:

    WebFunctLib.selectColor("red");
    

    When you type the function library alias followed by a period in the code view, the code assistance view opens listing the functions available in the function library with the required arguments.

    In the Java Code view, the getScript().callFunction() statement can also be used with the script code followed by the function name and arguments, as follows:

    getScript("scriptLibraryName").callFunction("functionName", "args", "[...]")
    

    However, code assistance is not available for functions called using the getScript().callFunction() statement.

  11. Save the master script and play it back to execute the custom functions. See Section 3.3.5, "Adding a Function to a Script" for additional information about passing arguments to functions.

Note:

In the master script, be sure to add a “Launch Browser” command to the Initialize section if it is not in the first function called from the master script.

3.3.7 Converting a Script to a Dedicated Function Library

You can convert existing scripts to a dedicated function library script.

To convert an existing script to a dedicated function library script:

  1. Open the script to convert to a dedicated function library script.

  2. Select Convert to Function Library from the Tools menu.

  3. Specify a unique package name for the function library script.

  4. Specify a unique alias as the Class name for the function library script. See Section 3.3.6, "Using a Script as a Dedicated Function Library" for additional information about package and class names.

  5. Click OK. The converted script is saved and reopened.

3.3.8 Adding Script Assets

You can add assets to a script such as, databanks, generic Jar files, object libraries, or other scripts containing recorded steps or custom functions. The asset must exist before it can be added. Select New from the File menu to record scripts or create databanks and object libraries. You also use the Add option in the Script Properties to create databanks and object libraries.

To add assets to a script:

  1. Open or create a script project.

  2. Select a script node and select Script Properties from the Script menu.

  3. Select Assets in the property type list. The Assets pane has the following options:

    • Asset: Lists the Assets added to a script by type in a tree view. Assets can be databanks, object libraries, generic Jar files, and other scripts.

    • File: Shows the files added as Assets to the current script. Expand the tree view in the Assets column to view the files.

    • Add: Opens a file selection dialog box for selecting the file to add as an asset. Expand the My Repositories tree to navigate to a folder containing the file.

      Note:

      Any scripts you plan to run, along with any associated assets, in the Oracle Load Testing application must be stored in a repository/workspace that can be accessed by the Oracle Load Testing Controller. If you create new repositories in OpenScript, you should also add the new repositories in Oracle Load Testing.
    • Edit: Opens a file selection dialog box for changing which files is added as an asset.

    • Open: Opens the selected asset file in the appropriate editor.

    • Remove: Removes the selected asset file from the Assets tree. The file still exists in the repository/workspace.

  4. Select the type of asset to add and click Add.

  5. Select the asset to add from a repository.

  6. Set the Relative to option. The Relative to current script and Relative to a repository options specify how the current script will locate the specified script asset. The Relative to a repository option locates the script asset by a repository path such as, [Repository: Default] Default!/WebTutor, if the asset is selected from a repository. The Relative to current script option locates the script asset by a relative path such as ../WebTutor. Selecting the The Relative to current script option is not recommended as script-relative paths are more brittle than repository-relative paths if scripts are moved or shared.

    The following are guidelines when using script assets in a team or distributed environment:

    • Do not use Absolute Paths when referring to assets or saving assets. Oracle Load Testing does not support absolute paths.

    • OpenScript, Oracle Test Manager, Oracle Load Testing, and all command-line agents should all use the same shared repository names and paths.

    • Do not refer to an asset in another repository by a relative path.

  7. Click OK to add the asset to the script properties.

  8. Click OK when finished adding script assets to close the script properties.

Script asset information is stored in the assets.xml file located in the script project directory.

3.3.9 Adding a Script to Run from a Script

To add a script to run to a script:

  1. Open or create a script project.

  2. Select the script node where you want to add the script to run.

  3. Select the Script menu and then select Other from the Add sub menu.

  4. Expand the General node and select Run Script.

  5. Click OK.

    This dialog box lets you specify the script to run from within another script.

    Script: Specifies the OpenScript script to run.

    New: Opens the script properties for selecting the script asset to run.

    Sections of script to run: Specifies which script sections to run during playback.

    • Initialize Section: When selected, the code in the Initialize section of the selected script to run is executed during playback. When cleared, the code in the Initialize section is skipped.

    • Run Section: When selected, the code in the Run section of the selected script to run is executed during playback. When cleared, the code in the Run section is skipped.

    • Finish Section: When selected, the code in the Finish section of the selected script to run is executed during playback. When cleared, the code in the Finish section is skipped.

    Iterations: Specify the number of script iterations to run.

  6. Select the script using New next to the Script field.

  7. Select the next script to run from the available script assets in the Script properties. Use the Add button to add scripts to the script assets properties.

  8. Select or clear the Sections of script to run option.

  9. Set the iteration count.

  10. Click OK. The script name node is added to the script tree.

  11. In the Java Code view, the getScript().run(); statement will be added to the script code, as follows:

    getScript(alias=String).run(interation count = int, initialize = true|false, run = true|false, finish = true|false);
    

    Example

    getScript("Web1").run(1, true, true, true);
    

3.3.10 Adding a Synchronization Point to a Script

A sync point allows multiple scripts being run as virtual users in Oracle Load Testing to synchronize their actions and interactions with the application under test. Sync points provide the ability to create realistic multi-user situations that may expose resource conflicts such as deadlocks. When you specify a sync point, multiple virtual users executing the script will reach this sync point at various times depending on a number of factors (for example, the speed of the machine).

Sync points cause each virtual user to wait until all virtual users have reached that sync point. Each of the virtual users notifies the master upon reaching the sync point. The master waits for all of the virtual users to notify it and then issues the go-ahead for all the virtual users to continue past that sync point.

Sync points are added to individual scripts (parent or child scripts) when they are created in OpenScript. The execution parameters for sync points are defined in the Oracle Load Testing application.

To add a sync point to an OpenScript script:

  1. Create or open a script in OpenScript.

  2. Select the script node where you want to add the sync point.

  3. Select Add from the Script menu then select Other.

  4. Select the Synchronization Point node and click OK.

    This dialog box lets you specify the name to use for the sync point.

    Name: Specifies the name used to reference the sync point in the Oracle Load Testing application.

  5. Enter a name for the synchronization point and click OK.

  6. In the Java Code view, the syncPointWait("name"); method will be added to the script code, as follows:

    syncPointWait("MySyncPoint");
    
  7. Save the script in OpenScript.

  8. Load the script into the Oracle Load Testing application and specify the execution parameters for the sync point(s) in the load test scenario. See the Oracle Load Testing User's Guide for additional information about specifying the sync point execution parameters.

3.3.11 Adding a Set Variable to a Script

To add a Set Variable to a script:

  1. Open or create a script project.

  2. Select the script node where you want to add the set variable.

  3. Select the Script menu and then select Other from the Add sub menu.

  4. Expand the Variable node and select Set Variable.

    This dialog box lets you set a variable value in a script.

  5. Enter the variable name and value.

    • Name: Specify the name of the variable.

    • Value: Specify the value to assign to the variable.

  6. Click OK. The Set variable = value node is added to the script tree.

  7. In the Java Code view, the getVariables().set("variable name", "value"); method will be added to the script code:

    getVariables().set("sVar_MyVar", "My_Value");
    

    If you want to set the variable with a value from an OpenScript transform variable (i.e. a variable value contained in {{}} syntax), use the Transforms.transform method with the getVariables().set, as follows (requires HTTP module):

    http.solve("varTitle", "<TITLE>(.+)</TITLE>", "Page Title Error", false, Source.Html, 0);
    
    getVariables().set("sVar_MyVar", Transforms.transform("{{varTitle}}", getVariables()));
    

3.3.11.1 Variables with Scope

You can use the variables method in the Java code to get or set variable with scope. For example:

variables.set(String name, String Value, Variables.Scope.scope)
variables.get(String name, Variables.Scope.scope)

Script variables are global for all scripts and functions for a single Oracle Load Testing Virtual User.

  • Each Virtual User keeps its own map of script variables.

  • One Virtual User cannot read/write another Virtual User's script variables. The exception is that a Child Virtual User (i.e. a Virtual User as a child script) has access to all variables in its parent Virtual User.

  • All scripts and functions that a Virtual User runs will have read/write access to all the Virtual User's variables.

  • In Functional Testing, a script typically represents only one Virtual User. In Functional Testing, script variables are generally global variables.

There are three scopes:

  • Local - all variables that the current script explicitly defines as local variables.

  • Parent - all variables that the parent (calling) script defines as its own local variables.

  • Global - all other variables not defined in an explicit scope. This is the default scope when no scope is specified. The Global scope is the parent scope of top-level VUser (top-level script). So a top-level script will have two scopes (Global and Parent) that coincide.

    Scope can be used to avoid confusion. If an author of a child script wants to change variables in global or parent scope, the script author should do it explicitly. If the author of a child script wants to change local script-level variables, then Scope Local should be used.

    Child scripts inherit its entire parent script variables. It is not a copy of the variables, it is a reference to the same variables, i.e. getParentVUSer().variables.

The following examples show uses of the Variable Scope:

//local variable
variables.set("user", "rich", Variables.Scope.Local);

//global variable (same as set("myData", "globalData", Variables.Scope.Global);) 
variables.set("myData", "globalData"); 

//parent variable
variables.set("anotherData", "parentData", Variable.Scope.Parent);

getScript("Script2").run();

// "globalData" as parent and global scope for top-level script coincide.
variables.get("myData", Variables.Scope.Parent)

3.3.12 Removing Unchanging Variables

You can select and remove script variables that it is known will never change. Removing unchanging variables can improve script playback performance because unchanging variables will not need to be evaluated during script playback. The script will use the value captured during recording as a fixed value rather than a variable.

To remove unchanging variable from a script:

  1. Record a script.

  2. Play back the script at least once to compare the recorded values to the playback values to determine which variables are unchanged.

  3. Select Remove Unchanging Variables from the Tools menu.

    This dialog box lets you specify the variables to remove from the script:

    Variable Name - shows the name of the script variable.

    Recorded Value - shows the variable value set during recording.

    Playback Value - shows the variable value set during playback.

    Check All - selects all of the variables in the table.

    Check Unchanged - selects only the unchanged variables in the table.

    Uncheck All - unselects all of the variables in the table.

  4. Select the variables to remove using the Check/Uncheck buttons.

  5. Click OK when finished.

3.3.13 Parameterizing URLs

You can create variables to use for URLs in a script. In cases where you need to change the base URL of a script, paramterizing the URLs provides a quick way to re-baseline a script to use a new URL. The URL will only need to be changed in one place.

To parameterize URLs:

  1. Record a script.

  2. Select Parameterize URLs from the Tools menu.

    This wizard lets you create variable names to use for URLs contained in the script. The Enter URL panel lets you specify the URL and variable name to parameterize:

    URL - specifies the URL to parameterize. Use the dropdown selector to select from URLs that have been recorded to the current script.

    Variable Name - specifies the name to use as the script variable.

  3. Select the URL to parameterize.

  4. Enter a variable name to use for the URL.

  5. Click Next.

    The Verify Changes panel lets you verify and select the which instances of the URL in the script will be changed:

    Tree view - shows the script nodes with the URL instances.

    Check All - selects all of the URL nodes in the tree.

    Uncheck All - unselects all of the URL nodes in the tree.

    Original URL - shows the original value of the URL before parameterizing as a script variable.

    New URL - shows the value of the URL after parameterizing as a script variable. For example, if you parameterize the URL http://myServer.com as the variable name myServerVar, the new URL will be the parameterized script variable {{myServerVar,http://myServer.com}}.

  6. Select which instances of the URL in the script will be changed by selecting or clearing the check boxes in the Tree view or using the Check/Uncheck buttons.

  7. Click Finish.

  8. In the Java Code view, the getVariables().set("variable name", "value",scope); method will be added to the script code in the initialize() section:

    getVariables().set("myServerVar", "http://myServer.com", 
       Variables.Scope.GLOBAL);
    
  9. Repeat steps 2-7 to parameterize other URLs in the script.

3.3.14 Adding Comments to Script Results

To add comments to script results:

  1. Open or create a script.

  2. Click the Code view tab.

  3. Add comments or warnings using one of the following code examples:

  • Using a step group:

  • beginStep("Any comment string", 0);
    {
    //The comment string appears in the Name column of the Results view.
    }
    endStep();
    
  • Using the getStepResult().addComment method:

  • //The comment string appears in the Summary column of the Results view
    getStepResult().addComment("Any comment string");
    
  • Using the getStepResult().addWarning method:

  • //The warning string appears in the Summary column of the Results view. 
    //addWarning overides addcomment.
    getStepResult().addWarning("Any warning string");
    

3.3.15 Adding Error Recovery to a Script

To add error recovery to a script:

  1. Open or create a script project.

  2. Select the script node where you want to add the log message.

  3. Select the Script menu and then select Other from the Add sub menu.

  4. Expand the General node and select Error Recovery Action.

    Exception: Select the type of exception error. The list will vary depending upon the script type.

    Action: Select the error recovery action: Fail, Warn, Ignore, Report , or P:ause as follows:

    • Fail: Report the error as failure and stop script execution.

    • Warn: Report the error as a warning and continue script execution.

    • Ignore: Ignore the error and continue script execution.

    • ReportErrorAndContinue: Report the error to the results log and continue script execution.

    • Pause: Pause playback and wait for user's decision to continue or abort script execution.

  5. Click OK. The log message node is added to the script tree.

  6. In the Java Code view, the setErrorRecovery(scriptType.constant, ErrorRecoveryAction.action); method will be added to the script code:

    setErrorRecovery(BasicErrorRecovery.ERR_VARIABLE_NOT_FOUND, ErrorRecoveryAction.Fail);
    

3.3.15.1 Script Types

The following are the possible values for scriptType in the Java code statements:

BasicErrorRecovery (Basic module)

FormsErrorRecovery (EBS/Forms Functional module)

FTErrorRecovery (Generic Functional module)

HttpErrorRecovery (HTTP module)

NcaErrorRecovery (EBS/Forms Load module)

UtilitiesErrorRecovery (Generic Utilities)

WebErrorRecovery (Web Functional module)

3.3.15.2 Constants

The following are the possible values for constant in the Java code statements:

BasicErrorRecovery (Basic module)

ERR_VARIABLE_NOT_FOUND
ERR_CREATE_VARIABLE_ERRORCODE
ERR_FILE_NOT_FOUND
ERR_SEGMENT_PARSER_ERROR
ERR_BINARY_DECODE
ERR_ENCRYPTION_SERVICE_NOT_INITIALIZED
ERR_GENERIC_ERROR_CODE

FormsErrorRecovery (EBS/Forms Functional module)

ERR_FORMS_FT_ERROR
STATUSBAR_TEST_ERROR

FTErrorRecovery (Generic Functional Module)

ERR_FT_MATCH_ERROR
ERR_OBJECT_TEST_ERROR
ERR_TABLE_TEST_ERROR

HttpErrorRecovery (HTTP Module)

ERR_ZERO_LENGTH_DOWNLOAD
ERR_MATCH_ERROR
ERR_RESPONSE_TIME_ERROR
ERR_SOLVE_ERROR
ERR_HTML_PARSING_ERROR
ERR_INTERNET_INVALID_URL
ERR_INVALID_HTTP_RESPONSE_CODE
ERR_KEYSTORE_LOAD_ERROR

NcaErrorRecovery (EBS/Forms Load Module)

CONNECT_ERROR
MESSAGE_IO_ERROR
CONTROL_INITIALIZE_ERROR

UtilitiesErrorRecovery (Generic Utilities)

ERR_SQL_EXECUTE_ERROR
ERR_XML_PARSING_ERROR
ERR_CSV_LOADING_ERROR

WebErrorRecovery (Web Functional module)

ERR_RESPONSE_TIME_ERROR
ERR_WEBDOM_SOLVE_ERROR
ERR_WAIT_FOR_PAGE_TIMEOUT_ERROR

3.3.15.3 Actions

The following are the possible values for action in the Java code statements:

Fail
Ignore
Warn
ReportErrorAndContinue
Pause

3.3.16 Verifying Script Actions

You can verify script actions to check the result of a script action and adjust the behavior of the script based on the result of the action.

The basic process to use verify script actions is as follows:

  1. Add an Error Recovery Action before the script node where you want to verify the result code. You can add the Error Recovery Action from the script Add sub menu or in the Java Code view. Set the error recovery action to Warn or Ignore to ensure that the Has Error block gets executed. This allows script execution to continue past the code where an exception occurred to the next statement in the script code.

  2. Add a 'Has Error' Control Statement after the script node where you want to verify the result code. You can add the Has Error Control Statement from the script Add sub menu or in the Java Code view. The if(hasLastError()) block is added to the script code directly after the script node where you want to verify the result code.

  3. Add your custom code into the if(hasLastError()) block in the Java Code view.

  4. Add Results Object messages to return the result values. The Result Code Verification features provide access to a Results object. The Result Object provides Result Code, Summary, Error Message, and Duration information.

The following sections explain the steps in more detail.

3.3.16.1 Adding an Error Recovery Action

To add an Error Recovery Action:

  1. Select the script node before the script node where you want to verify the result code.

  2. Select the Script menu and then select Other from the Add sub menu.

  3. Expand the General node.

  4. Select Error Recovery Action and click OK.

  5. Select the Exception type. See Section 3.3.15, "Adding Error Recovery to a Script" for additional information.

  6. Select the Action type and click OK.

  7. Add the Has Error condition to the script. See Section 3.3.16.2, "Adding a Has Error Control Statement" for additional information.

3.3.16.2 Adding a Has Error Control Statement

The Has Error Control Statement can be added to the script using the Tree view. However, the conditional behavior must be specified in the Java Code view.

To add a Has Error condition:

  1. Select the script node after the script node where you want to verify the result code.

  2. Select the Script menu and then select Other from the Add sub menu.

  3. Expand the Control Statements node.

  4. Select Has Error? and click OK. The if (hasLastError()) node is added to the script tree.

  5. Add a Result Object or add your custom code in the if (hasLastError()) block in the Java Code view. See Section 3.3.16.3, "Adding a Result Object Message" for additional information.

3.3.16.3 Adding a Result Object Message

The Result Object can be used to return result values.

To add a Result Object message:

  1. Select the if (hasLastError()) node in the script tree.

  2. Right-click the if (hasLastError()) node and then select Other from the Add sub menu.

  3. Expand the General node.

  4. Select Message and click OK.

  5. Select Info or Warn as the Message Type.

  6. Click Substitute Variable.

  7. Expand Last Result.

  8. Expand All Actions or assertions and Verifications.

  9. Select the Result to add to the message and click Finish.

  10. Click OK to add the message to the script.

    In the Java Code view, the message code with the result type is added to the if (hasLastError()) block:

    info("{{result.summary}}");
    

    You can customize the message string in the Java Code view. For example:

    info("Summary of last action: {{result.summary}}");
    
  11. If necessary drag the message node into the if (hasLastError()) node so the message is a child node of the if (hasLastError()) block. For example:

    if (hasLastError()) {
        info("Summary of last action: {{result.summary}}");
    }
    

3.3.16.4 Actions That Can Be Verified

Only specific OpenScript actions provide the ability to verify their results. In general, all actions that are available for adding from the tree view UI, including all verifications and assertions, support verification.

The following types of actions typically do not support verification:

  • Java methods that are only available from code and not from the UI

  • Deprecated methods

  • "Get" methods

  • Methods that interact with OpenScript internal code such as Logger, VUDisplay, Settings, Counters

  • Methods that don't throw any exceptions, such as http.removeCookie

3.3.17 Chaining Multiple Scripts

You can run multiple scripts from within a single script to chain playback of scripts together.

The procedure involves the following major steps:

  • Setting the browser preferences

  • Recording scripts

  • Creating a shell script

3.3.17.1 Setting the Browser Preferences

The browser preferences specify if a new browser will launch when recording a different script. Because the navigation sequence between multiple scripts is important, the same instance of the browser should run all scripts if the scripts are a continuation of each other. If each script is self-contained and there is no navigation between scripts, each script can launch its own browser and you can skip the Browser Preferences steps.

  1. Select Preferences from the View menu.

  2. Expand the General category and select Browsers.

  3. Clear the Always launch a new browser when recording a different script option.

  4. Click OK.

3.3.17.2 Recording Scripts

When recording scripts for chained playback, it is important to plan the start and stop points between scripts. This is especially true if session state needs to be maintained between scripts. All of the scripts must be of the same type.

  1. Create and record the first script, for example a Web Functional test log in script.

  2. Stop the recording but do not close the browser.

  3. Save the script.

  4. Create and record the next script. The navigation in this script should start from the point in the browser where the first script stopped.

  5. Stop the recording and save the script.

  6. Create and record any additional scripts to chain. The navigation in these script should start from the point in the browser where the previous script stopped.

3.3.17.3 Creating a Shell Script

The shell script is used to run the previously recorded scripts in sequence.

  1. Create a new script to use as the shell script.

  2. Select the script node where you want to add the first script. This could be either the Initialize or Run nodes.

  3. Select the Script menu and then select Other from the Add sub menu.

  4. Expand the General node and select Run Script.

  5. Click OK.

  6. Click New.

  7. Select the script to run from the available script assets in the Script properties. Use the Add button to add scripts to the script assets properties.

  8. Click OK.

  9. Select or clear the script sections to run and the iteration count.

  10. Click OK.

  11. Select the script node where you want to add the next script. This could be either the Initialize, Run, or Finish nodes.

  12. Select the Script menu and then select Other from the Add sub menu.

  13. Expand the General node and select Run Script.

  14. Click OK.

  15. Click New.

  16. Select the next script to run from the available script assets in the Script properties. Use the Add button to add scripts to the script assets properties.

  17. Click OK.

  18. Select or clear the script sections to run and the iteration count.

  19. Click OK.

  20. Repeat the Add script steps for each additional script to run.

  21. Save and playback the shell script to verify the script navigations work together correctly.

  22. In the Java Code view, the getScript().run() methods will be added to the script code:

    getScript("Web1").run(1, true, true, true);
    getScript("Web2").run(1, true, true, true);
    

3.3.18 Moving Nodes in a Script

You can click and drag a node in the script tree view to move the node to another location in the script tree. For example, you move a step group node from the Run section to the Initialize section or move a navigation node.

To move script nodes in the script tree:

  1. Open or create a script project.

  2. Select the script node to move in the Tree View tab of the Script View.

  3. Click and drag the mouse to move the node in the script tree. The script tree shows an indicator line that points to the location in the script tree where the node will be moved.

  4. Release the mouse button when the indicator line is at the location where you want to move the script node.

When moving Step Groups between script sections (i.e. between Run and Initialize, etc.) you may need to move the node to the section node.

You can also switch to the code view and move lines of code manually.

3.3.19 Aborting and Resuming a Script Programmatically

The Application Programming Interface (API) includes methods for aborting and resuming a script programmatically.

The abort() method immediately aborts the Virtual User as soon as possible. The remaining actions in the iteration, including any parent scripts and functions, will not complete. The Finish section will not be run. The currently running script will return a failed result indicating that the Virtual User was aborted.

If a Virtual User is aborted, it is possible to resume the script by catching the abort user exception and calling resume().

The resume() method allows the caller to reset a previously fired abort() request so that script execution can successfully continue from that point on. The caller must first catch the StopScriptRuntimeException that gets thrown by the abort() request and then call resume().

The resume() method works together with the abort() method. Calling resume() will only recover from a previously called abort().

The following examples show how to use the abort() and resume() methods.

//Example Use Case 1 - Abort a script at any point
info("Running a script...");
abort();
info("This line will not be run.");

//Example Use Case 2 - Abort a script and resume
try {
  info("Perform any steps inside a try-catch block...");
  abort();
  info("This line will not be run.");
}
catch (StopScriptRuntimeException e) {
   // optionally take any corrective action and optionally resume script
  resume();
}

//Example Use Case 3 - Abort Script after 5 Minutes and Execute the Finish Section
public void initialize() throws Exception {
  abortAfter(5*60); // Abort after 5 minutes
  try {
     // Insert script Initialize section here
     info("initializing resources");
  }
  catch (StopScriptRuntimeException e) {
     // ignore this and continue to run()
  }
}

public void run() throws Exception {
  try {
     // Insert script Run section here
     http.get(null, "http://myServer/longrunningtask?length=10min");
  }
  catch (StopScriptRuntimeException e) {
     // ignore the exception; OpenScript will run the finish()
  }
}

public void finish() throws Exception {
  resume();
  info("cleanup resources");
  // Insert real customer script Finish section here
}

//Example Use Case 4 - abort() after waiting for the specified amount of time
// Usage Example:
//abortAfter(5); to abort after 5 seconds
//abortAfter(5*60); to abort after 5 minutes
private void abortAfter(int seconds) {
  new Timer().schedule(new TimerTask() {
     public void run() {
       try {
          abort();
       }
       catch (StopScriptRuntimeException e) { /* ignore exception thrown */ }
     }
  }, seconds*1000);
}

3.4 Changing Text File Encoding

Before recording sites with international characters on an English OS, users should change the default character set encoding to a character set that supports the desired character set.

To change the text file encoding:

  1. Start OpenScript and select Developer Perspective from the View menu.

  2. Select Preferences from the Windows menu.

  3. Expand the General node.

  4. Select the Workspace node.

  5. Select the Other option under Text file encoding.

  6. Select desired text file encoding (i.e. UTF-8 for Japanese language Web sites, etc.).

  7. Click Close when finished.

3.5 Debugging Scripts

You can use features of the Eclipse IDE to debug scripts. For debugging purposes, it is not always necessary to switch to the Debug Perspective to debug a script. You can add views to the Tester Perspective, such as Breakpoints, Debug, and Expressions views. In most cases, you do not need to use the Outline, Variables, and Tasks views. This section provides tips for basic script debugging techniques.

3.5.1 Adding Views to the Tester Perspective

In some cases, you may want to add additional views to the Tester Perspective for debugging purposes. You select the view to open using the shortcut keys to get to the Show View window.

To open the Show View window:

  1. Press and hold the Shift and Alt keys, then press the Q key (Shift+Alt+Q).

  2. Press the Q key again. The Show View window opens.

  3. If necessary, expand the Debug tree.

  4. Select the View(s) you want to open:

    • Press and hold the Shift key and click to select multiple contiguous view names.

    • Press and hold the Ctrl key and click to select multiple non-contiguous view names.

  5. Click OK.

The selected views open in the Tester Perspective.

Note:

If you are in the Developer Perspective, you can add a view by selecting Show View from the Window menu and then selecting Other.

3.5.2 Adding Breakpoints to a Script

You can add breakpoints to the script tree view or in the Java Code to halt script execution at a specific line of code in the script.

To add a breakpoint to the script tree view:

  1. Create a script project.

  2. Record the script.

  3. In the Script view, click the Tree View tab.

  4. Expand the script tree and select the node where you want to add a breakpoint.

  5. Click the right mouse button and select Add Breakpoint from the shortcut menu. The "[Breakpoint]" indicator appears at the end of the script node text.

  6. Play back the script.

    When you play back the script, code execution will stop at the breakpoint. The Confirm Perspective Switch message appears the when the code execution arrives at a breakpoint. Select the Remember my decision option if you do not want the message to appear again during future script playback.

  7. Click No to stay in the Tester perspective or Yes to switch to the Debug Perspective. You can use the following Script menu options to debug scripts:

    • Step - runs the currently selected node and moves the execution pointer to the next sibling node. If the selected node has a child node, the execution pointer is moved to the first child node. This option is only active during script playback and script execution is suspended while stepping through the script code.

    • Step Into - steps into the function or sub procedure. This option is only active during script playback and script execution is suspended while stepping through the script code. The execution pointer is moved into the beginning of the function.

    • Pause/Resume - pauses and resumes script playback. These options are only active during script playback.

  8. You can use the following right-click shortcut menu options to debug scripts

    • Skip/Unskip - set the code to skip or unskip.

    • Playback to Here - starts playback from the beginning of the script and halts playback at selected node in the script tree.

    • Playback from Here - starts playback from the selected node in the script tree and plays to the end or the next breakpoint.

    • Add Breakpoint/Remove Breakpoint - adds or removes a breakpoint in the script tree view. Script tree nodes with a breakpoint set show the "[Breakpoint]" indicator at the end of the script node text.

    • Execute - executes the code for the selected node in the script tree. This option is only active during script playback and the script is paused. Execute compiles the highlighted code in the editor or tree view and runs it in the currently paused thread. However, the original running program code isn't changed and the current execution pointer does not move when using Execute. You can use Execute to test changes to a script while debugging. For changes to be permanent, you must save the script which recompiles the code and returns the execution pointer back to the beginning of the run() section.

    • Step - runs the currently selected node and moves the execution pointer to the next sibling node. If the selected node has a child node, the execution pointer is moved to the first child node. This option is only active during script playback and script execution is suspended while stepping through the script code.

    • Step Into - steps into the function or sub procedure. This option is only active during script playback and script execution is suspended while stepping through the script code. The execution pointer is moved into the beginning of the function.

To add a breakpoint to the script code:

  1. Create a script project.

  2. Record the script.

  3. In the Script view, click the Java Code tab.

  4. Double-click in the right-most column of the code view frame next to the code line where you want to add a breakpoint. The breakpoint indicator appears as a round dot in the frame. You can add as many breakpoints as needed.

  5. Play back the script.

    When you play back the script, code execution will stop at the breakpoint. The Confirm Perspective Switch message appears the when the code execution arrives at a breakpoint. Select the Remember my decision option if you do not want the message to appear again during future script playback.

  6. Click No to stay in the Tester perspective or Yes to switch to the Debug Perspective. You can use the following keyboard debug features to execute code while in debugging mode:

    • Single-step (F6) - executes the next line of code.

    • Step-into (F5) - opens the method/function class file.

      Note:

      Source code for the JRE or for the Eclipse IDE is not included with the product. When stepping into code, an editor may appear that does not contain source code. In this case, close the editor and resume script playback. You can use the Step-into feature to step into your own custom functions that you have added to a script.
    • Resume (F8) - resumes code execution to the script end or to the next breakpoint.

3.5.3 Adding a Java Exception Breakpoint

You can pause a script when any error occurs by adding a "Java Exception Breakpoint" to the Breakpoints list.

To add a Java Exception Breakpoint:

  1. Create a script project.

  2. Record the script.

  3. Open the Breakpoints view.

  4. Click the Add Java Exception Breakpoint icon on the Breakpoints View toolbar.

  5. Type "AbstractScriptException" and click OK to add this exception to the breakpoint list.

  6. Right-click on the breakpoint in the Breakpoints view and select Breakpoint Properties.

  7. Select the Suspend on Subclasses of this Exception option in the breakpoint properties and click OK.

During script playback, if an exception occurs, you can correct the problem and then continue script playback.

3.5.4 Pausing and Resuming Script Playback in Debug Mode

You can pause and resume script playback using the Tree view or the Debug view.

To pause and resume play back in the Tree view:

  1. Create a script project.

  2. Record the script.

  3. Play back the script.

  4. Click the Pause toolbar button to pause playback.

  5. Click the Resume toolbar button to resume playback of a paused script.

To pause and resume play back in Debug mode:

  1. Create a script project.

  2. Record the script.

  3. In the Script view, click the Java code tab.

  4. If necessary, add a Debug view to the Tester Perspective. If the Developer Perspective is open the Debug view should already be open.

  5. Play back the script.

  6. In the Debug view tree, select the Thread [Iterating Agent 1] thread and click the Pause toolbar button. The Thread [Iterating Agent 1] thread is the Virtual User's thread. You can ignore the others.

  7. In the Debug view tree, select script.run() and click the Resume toolbar button to resume playback.

    If you want to resume from a specific point in a script, comment out all lines before the current one, save the script, and then resume.

You can also execute portions of the script without having to comment out lines and restart the playback.

  1. Insert a breakpoint at the first line of the run() section.

  2. Playback the script. You can execute or inspect any line when playback halts a the breakpoint.

  3. Select the specific line(s) of code you want to playback, right-click and select Execute. You can modify the code and re-execute without having to save the script.

  4. Repeat the select code, right-click, Execute process until the script works the way you want it to work.

  5. Stop playback, or select the Resume button on the Debug view to replay from the breakpoint.

3.5.5 Inspecting and Changing Script Variable Values

You can inspect or watch script variable values to debug scripts. The script must be running or stopped at a breakpoint.

There is a difference between Java local variables and script variables. Java local variables are declared using standard Java syntax, such as String x or int i. Script variables are set using the OpenScript API methods, such as getVariables().set("someVariable", "123" or http.solve().

To inspect the value of a script variable:

  1. Create a script project.

  2. Record the script.

  3. Add a breakpoint to the script.

  4. Play back the script.

  5. At the breakpoint highlight the script code containing the variable or type the following code and highlight the code:

    getVariables().get("someVariable")
    
  6. Right-click and select Inspect or Watch.

    • Inspect opens a pane that shows the variable (Shift-Alt-I adds the variable to the Expressions view).

    • Watch copies the variable to the Expressions view.

  7. To change the value of a script variable, type the following code:

    getVariables().set("someVariable", "newValue")
    
  8. Highlight the code.

  9. Right-click and select Execute.

    Note:

    You can also test individual web actions by pausing the script, selecting the code for the action to test, then right-clicking and selecting Execute (or pressing Ctrl+U).

3.6 Enabling Debug Logging

OpenScript provides debug logging capability using Jakarta Log4j.

To enable debug logging:

  1. Close OpenScript.

  2. Open the file log4j.xml located in C:\OracleATS\OpenScript.

  3. Locate the following section at the end of the file:

  4. <!-- ======================= -->
      <!-- Setup the Root category -->
      <!-- ======================= -->
    
            <!-- For production  -->
      <root>
       <priority value="WARN"/>
       <appender-ref ref="AGENTFILE" />
      </root>
    
            <!-- For debugging
      <root>
       <priority value="DEBUG"/>
       <appender-ref ref="AGENTFILE" />
       <appender-ref ref="CONSOLE" />
      </root>
            -->
    
  5. Move the ending comment brackets from:

  6. <!-- For production  -->
      <root>
       <priority value="WARN"/>
       <appender-ref ref="AGENTFILE" />
      </root>
    
            <!-- For debugging
      <root>
       <priority value="DEBUG"/>
       <appender-ref ref="AGENTFILE" />
       <appender-ref ref="CONSOLE" />
      </root>
            -->
    

    to:

    <!-- For production
      <root>
       <priority value="WARN"/>
       <appender-ref ref="AGENTFILE" />
      </root>
            -->
    
            <!-- For debugging -->
      <root>
       <priority value="DEBUG"/>
       <appender-ref ref="AGENTFILE" />
       <appender-ref ref="CONSOLE" />
      </root>
    
  7. Save the file log4j.xml and restart OpenScript.

  8. Run scripts.

The debug messages are stored in the file OpenScript.log located in <installdir>\OpenScript.

To turn off debugging, move the ending comment braces back to the original locations.