This topic explains how to prompt SOAtest to scan a web application. Static analysis can then be performed on the accessed pages as described in Performing Static Analysis.
Sections include:

Configuring the Scanning

A Scanning Test is a test that crawls the specified web UI when the test case is executed To configure SOAtest to scan your web UI, you add a Scanning Test as follows:

1. Do one of the following:
   • To add a "Scanning Test" to a new .tst file: Right-click the project node where you want the new .tst file added and choose New Test ( .tst) file. Enter a name for the new .tst file, click Next, then choose Web > Scan web application.
   • To add a "Scanning Test" to an existing project: Select the test suite node where you want the new test added and click Add Test or Output on the tool bar.
     
     In the Add Test wizard that opens, choose Standard Test on the left and Scanning Tool on the right, then click Finish.
2. Specify whether you want to scan from an HTTP, FTP, or local source.

   • If you choose FTP or Local, complete the available fields, then your configuration is completed. You can skip the following steps.

     FTP Options

     When specifying an FTP source, you have the following options:

     • Case Insensitive Server: Indicates that your server is case insensitive.
     • Follow Symbolic Links: If selected, this option tells SOAtest to scan symbolic links as though they were actual files or folders on the ftp site. If the links point to a folder, SOAtest will scan the contents of that folder
   • If you choose HTTP, continue specifying settings as detailed in the following steps.
3. Click the Required Basic Settings tab of the HTTP Tool Settings and complete the following:
   • Start URL: Specify a single URL or .urls file in the field.

     • If the username and password of a URL are entered as '*', SOAtest will first try using the same credential used for the closest URL that precedes this URL and belongs to the same domain. If this credential does not apply to this URL, SOAtest will open a realm password dialog, asking you to input the correct credential.

       Using .urls Files

       Use a .urls file if you plan to have SOAtest add positive restrictions to the project and start loading all the appropriate sites starting at the URLs specified in the file to one default depth specified in the Project Creation panel. If usernames and passwords are specified for protected URLs, the credentials will be automatically added to the project.

       The format of a .urls file is: URLs are specified on separate lines; if a credential is specified for a URL, it must be put on the same line as the url in the order: url, username, password. The url, username, and password are separated by commas. If any item of the three has commas, the item must be put inside a pair of double quotes. If any item contains double quotes, each of the double quote must be escaped with another double quote, and the whole item must be put in double quotes. For example,
       http://url1.com/
       http://url2.com/, username, password
       http://url3.com/, "user,name", ",password,"
       http://url4.com/, "username", "pass""word"

   • Limit loading depth: If you do not want SOAtest to try to load the entire site, use this control to limit the loading depth. The depth settings determines the number of clicks (links) deep to load the site. A loading depth of 0 means to load only the initial page. This option is particularly useful if you want to test only selected paths through the site or if you want SOAtest to automatically construct the site structure and paths based on the traffic recorded in log file entries.
   • Restrict scanning to deepest subdirectory of start URL: If you want SOAtest to load only the subdirectories from the initial start URL, select this option. See Restricting Scanning to the Deepest Subdirectory of the Start URL for more details.
   • Follow redirects not specified as restrictions in the table: If you want SOAtest to follow redirects to sites that are not specified as allowed URLs, select this option. For more information about redirect handling, see Understanding and Configuring Redirect Handling.
   • Allowable/Restricted URLs: If accessing certain pages (for example, log out pages) might prevent SOAtest from loading the site correctly and/or completely, prompt SOAtest to avoid these pages by marking them as restricted URLs in this table; see Preparing SOAtest to Load Sites that Use JavaScript for instructions.
   • Form Options: The following options are available:
     • Scan Forms With Default Input: Off by default.
     • Fill Active Inputs Manually: On by default.
4. If you want to enter connection passwords, select the Realm Passwords tab and click Add to specify passwords.
5. If you want to specify advanced scanning options, select the Advanced Settings tab and complete the following:
   • Default Pages: * (this is the default setting)
   • Obey Robot Restrictions: Off (provided that the site’s Webmaster has granted you permission to ignore robot restrictions)
   • Pass Cookies: On
   • Invoke CGI For All Arguments: On
   • Case Insensitive Server: Depends on your server
   • Aliases: Depends on your site. If your site uses aliases, enter them here by clicking Add. An alias is a domain that you want SOAtest to consider equivalent to the domain of one of the sites in your project. For example, http://www.parasoft.com might have the aliases parasoft.com and www.parasoft.com.
6. Click Save.

You can now run any available Test Configuration on the test suite or the individual Scanning tool. When the test executes, SOAtest spiders through static and dynamic pages and loads at least one instance of each page it encounters.

If you chose the recommended HTTP Configuration options and your site contains forms, SOAtest allows you to populate forms using form input dialog boxes. If SOAtest opens form input dialog boxes as it loads your site, complete them as described in Populating Forms.

Handling Special Loading Issues

This section explains how to handle the following special loading issues:

• Preparing SOAtest to Restrict and/or Allow URLs During Scanning
• Preparing SOAtest to Load Sites that Use JavaScript
• Populating Forms
• Managing Authentication During Loading

Preparing SOAtest to Restrict and/or Allow URLs During Scanning 

You can control what site URLs SOAtest loads and ignores by adding restrictions and/or allowances in the Allowed/Restricted URL table.

If a URL is marked as restricted, SOAtest will not load that URL if it’s encountered during scanning. If you do not want SOAtest to access certain directories or files, you can mark them as restricted URLs. For example, if you have a logout page, you might want to mark it as restricted so that it does not prevent the loading of other pages or cause other pages to become invalid. SOAtest avoids restricted URLs when creating paths, exercising the site with virtual users, and so on. If your site has a Web server source, you can specify restricted URLs before you load the site (as described in this section).

If a URL is marked as allowed, SOAtest will load that URL if it’s encountered during scanning. The deepest directory URL pattern for the URL specified in the Start URL field is automatically added as allowed URL; this URL is called the Allowed Subdirectories URL. http(s)://... is used here so that both the HTTP and HTTPS versions of the specified URLs will be allowed or restricted. For more information, see URL Restriction Examples.

You can also specify additional allowed URLs. This is particularly useful for configuring SOAtest to load related sites. A related site is any site that is linked to one of your project’s sites, but does not have the same host name as any of the project’s sites. For example, if your primary project source is http://www.parasoft.com and that site links to http://forums.parasoft.com and http://www2.parasoft.com, those two sites are related sites for the current project. If you want SOAtest to automatically load a related site when it encounters it in the context of the current project, you need to indicate that they are Allowed URLs.

Restrictions and allowances are both specified in the Scanning Tool’s Allowed/Restricted URL table. In the table, allowances are marked with a + sign and restrictions are marked with a - sign. Allowances/restrictions are case sensitive.

Restrictions and allowances can be combined to create a sophisticated scanning scheme. Allowances/restrictions are processed in order, starting with the entry at the top of the table and ending with the entry at the bottom of the table.

To add an entry to the Allowed/Restricted URL table:

1. Click Add. A new row will be added to the Allowed/Restricted URL table.
2. In the text field of the newly-added row, enter the URL you want to restrict or allow.
   • The wildcard asterisk (*) can be used anywhere in the URL to match 0 or more characters. "*" means any combination of characters. It can be used in any combination of ways to construct an Allowed/Restricted URL table entry. See Wildcard Examples for samples.
   • If there is a slash '/' at the end of the URL, then the slash will be removed before the comparison.
3. If needed, toggle the +/- sign to indicate whether the specified URL should be allowed or restricted.
   • The + sign is used to mark allowed URLs.
   • The - sign is used to mark restricted URLs.

To change the position of an Allowed/Restricted URL table entry, select the entry that you want to move and click the upward and downward arrow buttons next to the Allowed/Restricted URL table until the entry is in the desired position.

To remove an Allowed/Restricted URL table entry, select the entry you want to move and click Remove.

URL Restriction Examples

The following examples explain specifics about the http(s)://... restriction:

• The default http(s)://... restriction allows URLs to match either http:// or https://. For example, with the default restriction:
  http(s)://www.google.com/*
  would match both
  http://www.google.com/amazing_page.html and https://www.google.com/amazing_page.html
• The string "http(s)://" does not have meaning in a URL restriction other than at the very start. For example, you could NOT have the restriction:
  http(s)://www.google.com/* and have it match http://www.google.com/amazing_page.html
  The string "http(s)://" is case-sensitive. So, you could NOT have: HTTP(S)://www.google.com/* and have it match http://www.google.com/amazing_page.html
• The special string is "http(s)://" and not any part of the string. For example, you could NOT have the restriction:
  http://www.para(s)oft.com/* and have it match http://www.parasoft.com/* or http://www.paraoft.com/*

Wildcard Examples

The following table shows how wildcards can be used to achieve various goals:

*.parasoft.com would match www.parasoft.com and articles.parasoft.com.

*parasoft*  would match www.parasoft.com, www.parasoft.net, parasoft.com, etc.

direc*ry/*  would match directory/dir2, direcHELLOry/dir2/dir3, and direc12345fry/images.

Understanding the SOAtest Scanning Heuristic

During project scanning and refreshing, each potential URL is matched against the Allowed/Restricted URLs table to determine if the URL should be visited. The process for determining whether the URL should be visited is as follows:

1. Find the last matching URL in the Allowed/Restricted URLs table.
2. If the sign of the last matching URL is positive, the URL is allowed. If the sign is negative, the URL is restricted.

The Allowed/Restricted URL table (described above in Preparing SOAtest to Restrict and/or Allow URLs During Scanning) allows you to control what portions of a site are scanned. For example, it can allow certain URLs to be specified as "off-limits" within a portion of a site that is otherwise allowed to be scanned. Or, it can allow the scanning of specific URLs that are within an area of the site that otherwise should not be scanned.

Example 1

The URL http://www.dev.parasoft.com/products/dir/page.html will match the following URLs from the table above:

+ http(s)://www.dev.parasoft.com/*
- http(s)://www.dev.parasoft.com/products/*
+ http(s)://www.*.com/products/dir/*

The last matching URL is http(s)://www.*.com/products/dir/*. Because this URL has a positive sign (indicating that it is an allowed URL), the URL http://www.dev.parasoft.com/products/dir/page.html will be allowed.

The URL http://www.dev.parasoft.com/products/soap.html will match the following URLs from the table above:

+ http(s)://www.dev.parasoft.com/*
- http(s)://www.dev.parasoft.com/products/*

The last matching URL is http(s)://www.dev.parasoft.com/products/*. Because this URL has a negative sign (indicating that it is a restricted URL), the URL http://www.dev.parasoft.com/products/soap.html will be restricted.

Example 2

Your  site http://www.dev.parasoft.com has information regarding several thousand types of hardware. You want to limit scanning of the site to two types of hardware: routers and disks. You also want to process all other parts of the site—except for the old part of the site.

To start scanning at the URL http://www.dev.parasoft.com/index.html, enter this URL in the Start URL field.

This allowed URL will automatically be added to the Allowed/Restricted URLs table:

+  http(s)://www.dev.parasoft.com/*

To scan only the two folder Routers and Disks in the hardware directory, you will need to add the following entries to the table in the following order:

-  http(s)://www.dev.parasoft.com/newdir/hardware/*
+  http(s)://www.dev.parasoft.com/newdir/hardware/Routers/*
+  http(s)://www.dev.parasoft.com/newdir/hardware/Disks/*

 To restrict the scanning of your old directory, you will need to add the following entry.

-  http(s)://www.dev.parasoft.com/olddir/*

This is how the table will look like after you are done.

Restricting Scanning to the Deepest Subdirectory of the Start URL

When the Restrict scanning to deepest subdirectory of Start URL Http Scanning option is selected, SOAtest will automatically take the Start URL, create an allowed URL for the deepest subdirectories, and add it to the first row of the Allowed/Restricted URL table. If you clear this option, SOAtest will automatically add the default Allowed Subdirectories URL to the first row of the Allowed/Restricted URL table. SOAtest also behaves this way when the first redirect is to a URL with the same fully-qualified domain name.

For example:

Understanding and Configuring Redirect Handling

If the specified Start URL is a redirect, SOAtest will load that redirect and any continuous subsequent redirects. In addition, SOAtest will automatically add an Allowed Subdirectories URL for each of those redirects. All the added entries for the redirects will be added to the top of the Allowed/Restricted URL table.

If you want SOAtest to follow redirects that are not added as allowed URLs, enable the Follow redirects not specified as restrictions in the table option. When this option is enabled, if SOAtest encounters a redirect during scanning and this redirect is not specified in the Allowed/Restricted URLs table, it will be loaded. SOAtest will add an Allowed Subdirectories URL for the redirect to the Allowed/Restricted URLs table.

Preparing SOAtest to Load Sites that Use JavaScript

Before you load a site that contains JavaScript, verify that the Load JavaScript option is enabled. (This option is enabled by default.) When this option is enabled, SOAtest will execute JavaScript and load any related links.

To verify that this option is enabled:

1. Go to Parasoft > Preferences.
2. Choose Parasoft > Scanning.
   

Customizing JavaScript Event Simulation

If you want to customize how SOAtest simulates JavaScript events (such as opening and closing additional windows, running timers, and so on), you can do so by modifying the JavaScript options in this tab. Use the following table to determine what options to choose.

Working with Alert, Confirm, and Prompt Messages

Each time SOAtest encounters JavaScript Alert, Confirm, Prompt messages as it scans your site, it will print a message to the results area (in the right GUI panel) and take the default action. By default, SOAtest will print the following messages and performs the following actions:

If you want SOAtest to handle these messages differently, you can define custom behavior using scripting. See Customizing Scanning with Scripting Hooks for details.

Populating Forms

If you selected the Fill Active Inputs Manually HTTP configuration panel check box (enabled by default), SOAtest opens a Form Input dialog box each time it detects a form that requires user input. If you want SOAtest to analyze the pages that are returned after forms are submitted, you need to tell SOAtest how to populate the forms’ various input elements (text fields, select boxes, check boxes, radio buttons, and so on). You can do this by specifying fixed inputs in these dialog boxes during the loading process.

You do not need to add test inputs for every form. We recommend that you add only the inputs required to access all major areas of your site; you can skip dialog boxes as needed. Moreover, you do not need to enter any form inputs during the loading process if SOAtest can reach all of your site areas without submitting specific form inputs.

To indicate that you do not want to enter inputs for any forms, click Skip All in the first dialog box.

To enter inputs for some or all forms, use the following table to determine what action to take for each dialog box that opens.

Understanding Form Inputs Purpose and Options

If your site uses forms and you want SOAtest to load and test the pages that are returned after those forms are submitted, you need to tell SOAtest how to populate the forms’ various input elements (text fields, select boxes, check boxes, radio buttons, and so on). The more different page instances you want to test, the more different inputs you need to use to populate the forms.

There are several ways to populate a form:

• By entering fixed values that will be used every time SOAtest encounters the related form. (We will refer to these as fixed inputs).
• By configuring SOAtest to use the default input (as specified in the code). (We will refer to these as default inputs).
• By configuring SOAtest to extract the value from the page on which the form appears—for instance, if the correct form value is set dynamically by JavaScript. (We will refer to these as extracted inputs).
• By disabling the input completely.
• By configuring SOAtest to use the returned value of a custom method. (We will refer to these as script inputs).

Completing Form Input Panels

To add or change fixed inputs in a Form Input panel that SOAtest has opened:

1. (Optional) Modify the input label name in the Form Test Name field.
2. (Optional) Modify the form action in the Form Action field.
   • If you want to use the default form action (as specified in the code), enable Default. Note that if the default value changes, SOAtest will update the form action automatically; you will not need to manually update the form test.
   • If you want to specify a fixed value, enable Fixed, then specify the desired form action in the text field.
3. Use the Form Inputs controls to add or modify inputs for each form input element.
   • If you want to use the default input (as specified in the code), enable Default. Note that if the default value changes, SOAtest will update the form test value automatically; you will not need to manually update the form test.
   • If you want to specify a fixed value, enable Fixed, then specify the desired value using the available controls.
     • Check boxes, radio buttons, and select inputs have a User-Defined option, which allows you to specify a simple string that will be sent as the value for this input.
     • Radio buttons and select inputs also have an Index option which allows you to specify the index of a radio button or of select option(s). If an index is selected, then the value of that radio button or option will be sent, regardless of how the option changes. This index is 0-based. For instance, if you want to always select the 2nd option, then you can choose the Index option and choose the index “1”. For radio buttons, the current value of the radio button at that index is shown for each index. For select inputs, the current display value of the option is shown along with each index.
     • Select inputs store the display values for the select rather than the values that would be sent to the server. Consequently, when the submit values change, you do not need to modify the test.
   • If you want SOAtest to extract the form input value from the page on which the form appears—for instance, if the correct form value is set dynamically by JavaScript—select Extracted, fill the Left-hand text field with the text string that always appears to the left of the value you want extracted, then fill the Right-hand text field with the text string that always appears to the right of the value you want extracted. For example, to extract the value 123 from the text pre123post, you would enter pre in the Left-hand text field and post in the Right-hand text field.
   • If you want to disable an enabled input, enable Disable. If you want to enable a disabled input, enable Enable.
   • If you want to use the return value of a custom method, enable Script. Click Edit to create or edit the method(s) and choose the desired method for use from the Method dropdown menu in the popup dialog. If there are two or more methods, you can also select a different method for use from the dropdown menu in the form panel.
4. (If a form has an OnSubmit handler) Enable or disable Process OnSubmit Handler When Submitting Form depending on whether you want that handler used during the test.
   • If the form has an OnSubmit handler, this option by default is set to true by default, unless the form test was created while recording paths with the browser. In this case, it is set to false because when SOAtest records a path from the browser, SOAtest sets up the form test in such a way that the OnSubmit does not need to be processed (and, in fact, processing this handler in this case could cause problems during path execution).
5. (Optional) Change the default form submission method.
   • If you want to mimic a simple JavaScript submission or a situation where the user submits the form by pressing the Enter key, enable Implied Submit.
   • If you want to mimic the user submitting the form by clicking a submit button, either choose the option representing that submit button (for example, Image: "Anonymous") or click a specific area of the submit image (if available in the Form Input panel).

Managing Authentication During Loading

If SOAtest reaches a page that requires authentication, it will open a password dialog box in which you can enter a valid username and password.

Enter a valid username and password in the appropriate fields, specify whether you want SOAtest to save the password in its project file, then click OK.

Loading/Site Scanning FAQ

Customizing Scanning with Scripting Hooks

You can customize SOAtest’s scanning behavior by having it execute custom scripts when the events associated with "hooks" occur within the SOAtest program.

Understanding the Concept of Hooks

Customized hooks can be used to record or modify the values passed at specific points in the Scan tool’s execution (for example, when alert dialog boxes are opened, users are prompted for responses, users are prompted for passwords, and so on).

For example, one of SOAtest’s hooks is the "Alert" hook. This hook is called whenever SOAtest’s Scan tool encounters a JavaScript alert. If you want SOAtest to record this alert information and report it in a SOAtest Message window, you can do so by creating a script that defines this hook, then describes how you want SOAtest to behave when it encounters this hook. After this script is invoked, SOAtest will access it and perform the specified action (recording and reporting alert information) each time it encounters a JavaScript alert.

Hooks are defined and customized in scripts using custom methods. The same file can define multiple hooks. If you add more than one method to a hook, all methods defined for that hook will be executed when the hook is called.

You can create, apply, and invoke scripts that define hooks in the same way that you create, apply, and invoke any other script in SOAtest: upon startup (only for JavaScript and Jython scripts), by creating and applying an Extension tool, and by adding scripts to a specific path node. You can invoke hooks at different times to elicit the desired functionality. For example, if you want to use a script’s hook functionality for all SOAtest projects and sites, you could add the JavaScript or Jython script that defines and uses that hook to the <INSTALL>/plugins/com.parasoft.ptest.libs.web_<VERSION>/root/startup directory. Any time the program calls the hook, the associated user-defined methods will be executed. The methods will be executed until you call clear () on the hook.

For a complete description of general hook options, see the SOAtest Extensibility API, go to Parasoft > Help or Help > Help Contents (depending on your installation) and look for the book titled "Parasoft SOAtest Extensibility API".

Understanding Available Hooks

SOAtest allows you to define and manipulate the following specific hooks in your scripts:

• Alert
• Confirm and Prompt
• Realm Password
• URL Logging

Alert

When SOAtest encounters a JavaScript alert() method, its default behavior is to click the OK button and print JavaScript Alert: "message" to the SOAtest Console view. You can modify this behavior using the Alert hook.

By default, the Alert hook is called whenever SOAtest encounters a JavaScript alert. By adding methods to this hook, you determine how SOAtest behaves when it encounters a JavaScript alert. When the Alert hook is invoked, SOAtest will print the message JavaScript Alert: "message" to the location specified in the script, or to the SOAtest Console view (if no alternate location is specified).

This hook is commonly used to print the results of alert messages to a special SOAtest Message window. For example, if you wanted SOAtest to report all alert messages in a SOAtest Message window named "Alert Messages," you could create the following Jython script and add it to your <INSTALL>/plugins/com.parasoft.ptest.libs.web_<VERSION>/root/startup directory:

from com.parasoft.api import Application
def myAlertHook(msg):
   # Print the alert message to SOAtest Messages
   Application.showMessage("    JavaScript Alert: %s" % str(msg))    
   # Add the contents of the alert message to a Result Window named
   # "Alert Messages".  This ResultWindow can later be used
   # as part of a test suite in a regression test, to make sure the 
   # contents of the window, which contains the alert message,
   # are what you expect them to be.
   Application.report("Alert Messages", str(msg))
# Add your method to the Alert Hook Application.getHook("Alert").set(myAlertHook)

The argument passed into the method myAlertHook will be the alert message. It is a string that is the message the alert contains.

You could also use the Alert hook to verify that when a user (or SOAtest) submits certain invalid form values, the application opens an alert box warning that invalid data was entered. To implement this test, you would first create and invoke a script (like the one above) that records alert messages into a SOAtest Message window. Then, you would implement a test suite that checks the contents of the Message window using the following test cases:

1. An Extension tool that clears the Message window.
2. A Test Path tool that executes the click path that should cause the alert message.
3. An Extension tool with a script (like the one shown below) that returns the text of the Message window, with an attached regression control that verifies that the correct alert message appears in the Message window.

#Script to return text of result window named "Alert Messages" from soaptest.api import *
def return(): 
    return SOAPUtil.getResultWindowText("Alert Messages")
#Script to clear text of result window named "Alert Messages" from soaptest.api import *
def clear(): 
    SOAPUtil.clearResultWindow("Alert Messages")

Confirm and Prompt

When SOAtest encounters a JavaScript confirm() method, its default behavior is to click the Cancel button, return false, and print JavaScript Confirm: "message" to the SOAtest Console view. When SOAtest encounters a JavaScript prompt() method, its default behavior is to click the Cancel button, return null, and print JavaScript Prompt: "message" to the Console view. You can modify these behaviors by using scripting to define and customize a Confirm hook or Prompt hook (the hook used depends upon the JavaScript method whose return value you want to modify).

Confirm

By customizing the Confirm hook, you determine how SOAtest behaves when it encounters the confirm() method.

For example, one way to prompt SOAtest to return a customized (non-default) response whenever it encounters the confirm() method is to perform the following steps:

First, create a Jython file (named startup.py) that defines a method which takes a single argument. This argument will have the same value that gets passed to the confirm() method in your JavaScript to this argument. Based on whatever logic you need, determine whether you want confirm() to return "true" or "false", and then return that value from the method you defined. To have SOAtest use the method you just defined, add it to the Confirm hook in the following way, where the argument you pass to set is the name of the method that you defined. In the example, the method defined is named myConfirmHook.

from com.parasoft.api import Application
# msg will have the same value that gets passed to confirm() def myConfirmHook(msg):
    if msg == "Yes or no?":
        return 1
    return 0
Application.getHook("Confirm").set(myConfirmHook)

Next, add this file to the <INSTALL>/plugins/com.parasoft.ptest.libs.web_<VERSION>/root/startup directory. The next time you start SOAtest, it will execute the above script whenever it encounters a confirm() method.

When the Confirm hook is invoked, SOAtest will print one of the following messages (depending on the confirmation action) to the location specified in the script, or to the Console view (if no alternate location is specified):

• Based on the script, SOAtest clicked the "OK" button
• Based on the script, SOAtest clicked the "CANCEL" button

Prompt

By customizing the Prompt hook, you determine how SOAtest behaves when it encounters the prompt() method.

The Prompt hook works very much like the Confirm hook does. One difference between these hooks is that Prompt takes two arguments and passes them to the prompt() JavaScript method. The other difference is that the method you define for Confirm returns a boolean, but the method you define for Prompt must return either a string, or "null" ("None" in Jython).

You can define logic that determines return values based on the arguments that are passed to the prompt() method. Returning "null" is equivalent to clicking Cancel in the prompt box that the browser opens when the prompt() method is called. You add the method to the appropriate hook in the same way that you added a custom method for confirm(), but now the hook is named "Prompt". An example script that returns "http://www.parasoft.com" as the value for prompt() follows:

from com.parasoft.api import Application
def myPromptHook(msg, defaultMsg):
    return "http://www.parasoft.com"
Application.getHook("Prompt").set(myPromptHook)

When the Prompt hook is invoked, SOAtest will print one of the following messages (depending on the prompt response) to the location specified in the script, or to the Console view (if no alternate location is specified):

• Based on the script, SOAtest entered "[message- string that the script returns]"
• Based on the script, SOAtest clicked the "CANCEL" button

Returning Different Values in Different Situations

You can have SOAtest return different confirm() or prompt() values in different situations by adding the appropriate logic to the method you define for the Confirm or Prompt hook. You determine what value is returned using the text of the first argument to the method you're adding to the Confirm or Prompt hook. For example, you might want SOAtest to return http://www.parasoft.com for the prompt "Enter a URL", but return John for the prompt "Enter your name". This functionality could be implemented as follows:

def myPromptHook(msg, defaultMsg):
  if msg == "Enter a URL":
    return "http://www.parasoft.com"
elif msg == "Enter your name":
  return "John"
else:
  return None

Realm Password

The Realm Password hook is called when all of the following conditions are satisfied:

• SOAtest makes a request of a server.
• The server responds with a challenge, asking for either a realm password or an NTLM password (both of which SOAtest handles in the same way).
• You have not yet entered a realm or NTLM password.

If you have defined a custom Realm Password hook before the above conditions are satisfied, SOAtest will execute the custom hook method before prompting you to manually enter a password. If that method adds a password (either to a site in the project, or to a load test virtual user), SOAtest will use that password, and will not prompt you for a password. If you or another SOAtest user previously entered a password, this hook will not get executed. If you want to ensure that SOAtest uses the password you defined for the hook, you should clear the site passwords before you want SOAtest to add new passwords from the hook.

This hook is particularly useful in cases where you want to vary usernames/passwords depending on the particular context you are in (for example, based on the particular path you are using, or you would like to use different usernames/passwords in the context of a virtual user load test).

The following sample Java file is a very basic sample implementation of the Realm Password hook. This script adds the same password regardless of the context.

import com.parasoft.api.*;
import java.lang.reflect.*;
import java.net.*;
import soaptest.api.*;
public class RealmPasswordHook {
    static public void returnPassword(String realm, String url, boolean ntlm, Context context)
throws MalformedURLException {
         SOAPUtil.addSitePassword(realm, "user1", "password1", url, ntlm);
    }
    public void setHook() throws UserMethodException, NoSuchMethodException
{
        Hook hook = Application.getHook("RealmPassword");
        Method userMethod = getClass().getMethod("returnPassword", new Class[] {String.class,
String.class, boolean.class, Context.class});
        hook.set(userMethod);
    }
}

The following Jython sample file is similar to the previous Java file, except that it clears all existing passwords when the Realm Password hook is accessed.

from com.parasoft.api import *
from soaptest.api import *
def returnPassword(realm, url, ntlm, context):
  SOAPUtil.addSitePassword(realm, "user1", "password1", url, ntlm)
def setHook():
  hook = Application.getHook("RealmPassword")
  hook.set(returnPassword)
  // Remove all previous passwords to the new one being added above is the one that gets used.
  SOAPUtil.removeSitePasswords()

The following sample JavaScript file removes existing realm passwords when the hook is accessed, then—when a virtual user load test is executed—submits passwords that depend upon the URL currently being accessed.

// This method uses a different password based on the URL.
var Application = Packages.com.parasoft.api.Application
function returnPassword(realm, url, ntlm, context) {
  Packages.soaptest.api.SOAPUtil.removeSitePasswords()
  // Adds password to a virtual user in load test
   if (url.indexOf("http://toad.parasoft.com:90" == 0) {
     Packages.soaptest.api.SOAPUtil.addSessionPassword(realm, "user1", "password1", url, ntlm, context)
  } else {
     Packages.soaptest.api.SOAPUtil.addSessionPassword(realm, "user2", "password2", url, ntlm, context)
  }
}
function setHook() {
  var hook = Application.getHook("RealmPassword")
  hook.set(returnPassword)
  Packages.soaptest.api.SOAPUtil.removeSitePasswords()
}

URL Logging

The URL Logging hook is called every time SOAtest visits a URL. It can be used to prompt SOAtest to print each URL visited.

The methods you attach to this hook need to have either three or four arguments. The first argument should be a string specifying the URL visited. The second argument should be any POST data submitted with the URL (this mat be NULL). The third argument is a java.util.Hashtable containing other HTTP properties sent with the request, (for example, referer). The optional fourth argument, if added to the method signature, is a com.parasoft.api.Context.

In addition, you need to set SiteUtil.enableLogging to true and pass UrlLogging to Application.getHook()

For example, if you wanted SOAtest to print each URL visited to the Console view, you could create the following Jython script and add it to your <INSTALL>/plugins/com.parasoft.ptest.libs.web_<VERSION>/root/startup directory:

from com.parasoft.api import *
from webtool.site import SiteUtil

count = 1

def setHook():
    SiteUtil.enableLogging = 1
    hook = Application.getHook("UrlLogging")
    hook.set(loggingHook)
def loggingHook(url, post, props):
    global count
    if post:
        Application.showMessage(str(count) + ". " + url + " [POST=" + post + "]")
    else:
        Application.showMessage(str(count) + ". " + url)
   count = count + 1
setHook()