14 Using the Utilities Module

This chapter provides instructions on using the OpenScript Utilities Module, which provides commonly used testing functions.

14.1 About the Utilities Module

The Utilities Module provides commonly used testing functions. The Utilities Module is an extension to the Basic Module. The OpenScript Utilities module includes the following features:

14.1.1 Key Features of the Utilities Module

Text File Processing. Read values from text files including CSV and XML files as well as copy and move files in the file system.
Databases. Read values from various databases such as Oracle as well as other JDBC-ODBC Compliant databases
XML XPath Expressions. Generate XPath expressions from valid XML files.

You can use the Utilities Module API to enhance recorded scripts with additional testing functionality. Commands that are specific to the Utilities Module are part of the "utilities" class.

14.2 Using Text File Processing

You can use the utilities API to read values from text files including CSV and XML. The following sections explain how to use the utilities API.

14.2.1 Reading Lines of Text from a File

The Utilities API includes a method for reading lines of text from a file.

To add code that reads text from a file:

Record a Web Functional Test script.
Open the Java Code view.
Add the readLines() method to specify the file to read. The following example shows how to parse the lines of text in a file and print to the OpenScript console view:
```
String[] lines = utilities.getFileService().readLines("C:/Sample.txt");

for (String line : lines) {

getLogger().info(line);

}
```

14.2.2 Reading Text from a CSV File

The Utilities API includes a method for reading text from a Comma Separated Value text file.

To add code that reads text from a .CSV file:

Record a Web Functional Test script.
Open the Java Code view.
Add the loadCSV method to specify the file to read. For this example the file, "C:\customer.csv" contains this data:
```
FirstName,LastName,MiddleInitial

John,James,R

Mary,Simpson,J
```
The following example shows how to parse a table of text in a .CSV file and print values to the OpenScript console view:
```
Table table = utilities.loadCSV("C:/customer.csv");

Row row = table.getRow(0);

getLogger().info(row.get("LastName"));
```

14.2.3 Reading Text from an XML File

The Utilities API includes a method for reading text from a XML formatted text file.

To add code that reads text from a .XML file:

Record a Web Functional Test script.
Open the Java Code view.

Add the loadXML method to specify the file to read. For this example the file, "C:\oceans.xml" contains this data:

<?xml version="1.0" encoding="utf-8"?>

<Oceans>

   <ocean name="Artic"/>

   <ocean name="Atlantic"/>

   <ocean name="Indian"/>

   <ocean name="Pacific"/>

   <ocean name="Southern"/>

</Oceans>

The following example shows how to parse a table of text in a .XML file and print values to the OpenScript console view:

XML xml = utilities.loadXML("C:/oceans.xml");

XML root = xml.getChildren()[0];

getLogger().info(root.getTagName());

XML[] oceans = root.getChildren();


for (XML ocean : oceans){

getLogger().info(ocean.getAttribute("name"));

}

14.3 Getting Values from a Database

Getting values from a database requires a database definition, a database SQL query or SQL execute and a disconnect from the database.

To get values from a database:

Open or create a Web Functional Test script project.
Select the node where you want to add the database definition.
Select the Script menu and then select Other from the Add sub menu.
Expand the Database node and select Database Definition.
Click OK.
Specify the database definition information.
Click Test to verify a successful connection.
Click OK.
Select the node where you want to add the database connection. The OpenScript database connect method is optional. The database connect is invoked automatically when calling execute or query methods
Select the Script menu and then select Other from the Add sub menu.
Expand the Database node and select Connect.
Select the database alias and click OK.
Select the node where you want to add the database query or execute statement.
Select the Script menu and then select Other from the Add sub menu.
Expand the Database node and select SQL Query or SQL Execute.
Specify the SQL statement to query or execute and click Add.
Specify a data type and define a name for the parameter.
Click OK.
Click OK.
Select the node where you want to add the database disconnect.
Select the Script menu and then select Other from the Add sub menu.
Expand the Database node and select Disconnect.

Select the database alias and click OK.

In the Java Code view, the utilities.getSQLService() methods will be added to the script code for each database script action:

utilities.getSQLService().define("oracledb ",

   "oracle.jdbc.driver.OracleDriver", "00.000.000.000", "myuserID",

   decrypt("ZgEQLMIUx8EVDAhfAenvyg=="));

utilities.getSQLService().connect("oracledb ");

utilities.getSQLService().query("oracledb ",

   "SELECT * FROM Users where username = ?", list("testdb"));

utilities.getSQLService().execute("oracledb ", 

   "SELECT * FROM Users where username = ?", list("sqlexecute1"));

utilities.getSQLService().disconnect("oracledb ");

14.4 Using the XPath Generator

The Utilities Module includes an XPath generator utility that you can use to generate an XPath Expression to a selected element from a valid XML file.

To use the XPath Generator:

Create an XML file that contains the tags and values to use to generate the XPath expression. The following is an example of a simple XML file that can be used with the XPath Generator:

<?xml version="1.0" encoding="utf-8"?>

<Oceans>

   <ocean name="Artic"/>

   <ocean name="Atlantic"/>

   <ocean name="Indian"/>

   <ocean name="Pacific"/>

   <ocean name="Southern"/>

</Oceans>

Create and record a test script. The Tools menu appears on the OpenScript menu bar for functional and load test scripts.
Select Generate XPaths from the Tools menu.
Click Browse and select the XML file to load.
Expand the XML tree under the Tags section of the XML file.
Select the XML tag to use to generate the XPath. The generated XPath appears in the XPath Expression field in a form similar to /Oceans/ocean[1]/@name.
Use the Ctrl+C and Ctrl+V keyboard combinations to copy and paste the generated XPath to a method in the Java Code tab of the script view.

The XPath Expression can be used in the utilities findByXPath API method, as follows:
```
utilities.loadXML("filePath").findByXPath(xpath, xml)
```