web.regFind

Registers a search for a text string on an HTML page.

Syntax

            
            web.regFind( {object} );

JavaScript Object

{
    text: "<string>"|{value: "<string>", flag: "<string>"},
    textPfx: "<string>"|{value: "<string>", flag: "<string>"},
    textSfx: "<string>"|{value: "<string>", flag: "<string>"},
    search: "<string>",
    saveCount: "<string>",
    fail: "<string>",
    id: "<string>",
    relFrameId: "<string>"
}

Property Name	Description
text	The text string to search for. text is a non–empty, null–terminated character string. If text is passed, do not pass textPfx and textSfx.
textPfx	The left boundary for the search. This is the text immediately preceding the text string for which you are searching. Required if text not passed.
textSfx	The right boundary for the search. This is the text immediately following the text string for which you are searching. Required if text not passed.
search	Optional. The scope of the search—where to search for the string. The possible values are Headers (search only the headers), Body (search only the body data), Noresource (search only the HTML body, excluding headers and resources), or All (search body , headers, and resources). The default value is Body.
saveCount	Optional. The number of matches that were found, stored in a parameter. The saveCount attribute assigns the number of matches that were found to a parameter. To use this attribute, specify "saveCount=param". When the check is performed, param is assigned a null–terminated string representing a numerical value. When the saveCount argument is used, and the fail argument is not used, the check does not fail whether the text is found or not. To check whether the text has been found, examine the value of the saveCount parameter. If it is "0", the string was not found. If both saveCount and fail are used, the fail handling option specified works together with the saveCount. Thus, if saveCount is used with "fail=NotFound" and the text is found, the saveCount parameter is assigned the number of occurrences and the check succeeds. If the text is not found, the saveCount parameter is assigned "0" and the check fails. Of course, if the text is not found and "fail=NotFound" has been specified, the value "0" of the parameter is only useful if the runtime setting Continue on error is selected. The value assigned to the parameter is retained between iterations until the first action function following the web.regFind of the next iteration. Once the script perfoms the first action function following the web.regFind of the next iteration, the count is updated. Alternatively, you can use the lr.saveString function to change the value of the parameter at the end of the current iteration—for example, with `lr.saveString("0", "Count").`
fail	Optional. The handling method that sets the condition under which the check fails. fail can be either "Found" or "NotFound". The default is NotFound. "fail=NotFound" indicates that an error occurs when the text is not found. You use NotFound when searching for the text you expect to find if the web request succeeds. "fail=Found" indicates that the check fails when the text is found. You might use Found, for example, searching for the word "Error". If you find "Error", the web request did not succeed, and you want the check to fail. When "fail = Found" is specified with textPfx and textSfx and the left and right boundaries are found more than once, each match is issued as an error up to the maximum number of errors configured in the Runtime Settings > Preferences > Advanced Options. Subsequent matches are logged as informational messages. For information about using fail with saveCount, see saveCount.
id	Optional. An identifying string that associates the entry in the log file with the call to web.regFind. See the Example
relframeId	Optional. The relative frame id, for example: 1.2 Note: relframeid is not supported in GUI level scripts.

Return Values

Not applicable

Parameterization

You can use standard parameterization for the text for which you are searching.

General Information

The web.regFind function registers a request to search for a text string on a web page retrieved by the next action function. The search does not apply to values returned as a result of calls to asynchronous or cross-step functions.

This function helps you verify whether or not the page you received is the desired page by searching for an expected text string. For example, you can search for the text "Welcome" to check if your home page opened properly. You can check for the word "Error" to check if the browser encountered an error. You can also use this function to register a request to count the number of times the text appeared.

Either text, or textPfx and textSfx is required. The rest of the attributes are optional. text searches for a known string. textPfx and textSfx are used when the string is not known in advance, but you know what strings will precede and follow it. For example, when a user is issued a user name, the server may return "Your new user name is <user name>". The user name changes, but to confirm that a name was issued it is sufficient to confirm that there is some string preceded by "Your new user name is " and followed by a ".".

You can use one of the following flags to modify text, or textPfx and textSfx:

IC to ignore the case.
BIN to specify Using binary code.

For example, {value: "Mansfield park", flag: "IC"} or {value: "\\x24\\x81", flag: "BIN"}.

If the check fails, the error is reported after the next action function executes. This function only registers requests, but does not perform them. Thus, the return value of web.regFind indicates only if the registration succeeded, and not if the check succeeded.

You can search for either the text or the strings surrounding the text. Do not specify both text, and a prefix–suffix pair.

This function can be used for both HTML–based and url–based scripts (see Recording Options > Recording tab). It registers the search request before the buffers arrive, so the buffers are scanned as they come. This results in a more efficient script with better performance.

To globally search all subsequent action functions (not only the following one), use web.globalVerification. The web.globalVerification function is useful in detecting application level errors that are not represented by HTTP status codes. To locate errors that are represented by HTTP status codes, use the web.getIntProperty.

Example

web.regFind({text:'Useful Pages'});