web_reg_find

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

C Language

int web_reg_find( const char *attribute_list, LAST );

Java Language

int object.reg_find( String text, String[] argumentList );

Return Values

This function returns LR_PASS (0) on success, and LR_FAIL (1) on failure.

Parameterization

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

General Information

The web_reg_find 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.

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_reg_find 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_global_verification. The web_global_verification 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_get_int_property.

Attribute List

The attributes are passed in Name=Value pairs, for example: "Text=string". Either Text, or TextPfxandTextSfx is required. The rest of the attributes are optional.

Text: The text string to search for. Text is a non–empty, null–terminated character string. You can further customize your search by using Text Flags.

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 must specify the following two attributes if you do not specify Text. You can further customize your search by using Text Flags with these attributes.

TextPfx: The left boundary for the search. This is the text immediately preceding the text string for which you are searching.

TextSfx: The right boundary for the search. This is the text immediately following the text string for which you are searching.

Search: 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: 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 run–time setting Continue on error is selected.

The value assigned to the parameter is retained between iterations until the first action function following the web_reg_find of the next iteration. Once the script perfoms the first action function following the web_reg_find of the next iteration, the count is updated. Alternatively, you can use the lr_save_string function to change the value of the parameter at the end of the current iteration—for example, with lr_save_string("0", "Count").

Fail: 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: An identifying string that associates the entry in the log file with the call to web_reg_find. See the Example: web_reg_find.

RelFrameId: The relative frame ID, for example: 1.2
Note: RelFrameID is not supported in GUI level scripts.