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

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

C Example

In Example 1, web_reg_find searches for the text string "Welcome". If the string is not found, it fails and the script execution stops.

In Example 2, based on example 1, shows error handling in the script.

In Example 3, web_reg_find searches for the text string "Error." If the string is found, it fails and the script execution stops.

In Example 4, web_reg_find searches for the text string "ABC". The path of script execution depends on whether the string is found.

In Example 5, an ID argument "XYZ" associates the call to web_reg_find with a line in the log file.

Example 1

In the following example, web_reg_find searches for the text string "Welcome". If the string is not found, it fails and the script execution stops.

    // Run the Web Tours sample 
    web_url("WebTours",
        "URL=http://localhost/WebTours/",
        "Resource=0",
        "RecContentType=text/html",
        "Referer=",
        "Snapshot=t1.inf",
        "Mode=HTML",
        LAST );

// Set up check for successful login by looking for "Welcome"

    web_reg_find("Text=Welcome",
        LAST );
// Now log in
    web_submit_form("login.pl",
        "Snapshot=t2.inf",
        ITEMDATA,
        "Name=username", "Value=jojo", ENDITEM,
        "Name=password", "Value=bean", ENDITEM,
        "Name=login.x", "Value=35", ENDITEM,
        "Name=login.y", "Value=14", ENDITEM,
        LAST );

Example 2

Example 2 is the same as example 1, but because Save Count is used, the script execution is not halted on failure. Instead, the error is handled in the code.

    // Run the Web Tours sample 

    web_url("WebTours",
        "URL=http://localhost/WebTours/",
        "Resource=0",
        "RecContentType=text/html",
        "Referer=",
        "Snapshot=t1.inf",
        "Mode=HTML",
        LAST );

// Set up check for successful login by looking for "Welcome"

    web_reg_find("Text=Welcome",
        "SaveCount=Welcome_Count",
        LAST );

// Now log in

    web_submit_form("login.pl",
        "Snapshot=t2.inf",
        ITEMDATA,
        "Name=username", "Value=jojo", ENDITEM,
        "Name=password", "Value=bean", ENDITEM,
        "Name=login.x", "Value=35", ENDITEM,
        "Name=login.y", "Value=14", ENDITEM,
        LAST );

// Check result

    if (atoi(lr_eval_string("{Welcome_Count}")) > 0){
        lr_output_message("Log on successful.");
        }
     else{
          lr_error_message("Log on failed");
          return(0);
     }

Example 3

In the following example, web_reg_find searches for the text string "Error." If the string is found, it fails and the script execution stops.

web_reg_find("Text/IC=Error", "Fail=Found", LAST );
web_url("Step", "URL=...", LAST );

Example 4

In the following example, web_reg_find searches for the text string "ABC". If the string is not found, the script executes Action A. If the string is found one or more times, it executes Action B.

web_reg_find("Text=ABC", "SaveCount=abc_count", LAST );
web_url("Step", "URL=...", LAST );
if (atoi(lr_eval_string("{abc_count}")) == 0)  {
	// ACTION A
	lr_output_message("Found Ct is zero");	
} else {
	// ACTION B
	lr_output_message("Found Ct is  %s", lr_eval_string("{abc_count}"));
}

Example 5

In the following example, an ID argument "XYZ" associates the call to web_reg_find with a line in the log file. When looking for the entry in the log file that logged the call to web_reg_find, searching for the string "XYZ" will make it much easier.

web_reg_find("Text=mitcham", "ID=XYZ", LAST );
web_url("web_url", "URL=http://lazarus/", "TargetFrame=", 
    "Resource=0", "Referer=", LAST );

The entries in the log file will be one of the following, depending on whether the web_reg_find succeeded in finding the text "mitcham" was found:

Action1.c(12): Matched web_reg_find with "Fail=NotFound" ("XYZ"). Text "mitcham" (count=78)

Action1.c(10): Error: No match for web_reg_find with "Fail=NotFound" ("XYZ"). Text "mitcham"

Java Example

In Example 1, reg_find searches for the text string "Welcome". If the string is not found, it fails and the script execution stops.

In Example 2, reg_find searches for the text string "Error." If the string is found, it fails and the script execution stops.

In Example 3, reg_find searches for the text string "ABC". The execution path of the script changes depending on whether the string is found.

Example 1

In this example, web.reg_find checks for the login name. Commented out, is an alternative example of how to use the function to look for leading and trailing strings.

{
    // Run the Web Tours sample program
    web.url("WebTours",
        "URL=http://localhost/WebTours/",
        new String[]{
            "Resource=0",
            "RecContentType=text/html",
            "Referer=",
            "Mode=HTML",
            web.LAST
        });

    /* In a real script, you will probably use parameterization
    for LoginName. For this example, we simply create one parameter.
    */

        lr.save_string("jojo" , "LoginName" ); 

    // Set up check for successful login by looking for the login name

    web.reg_find("Text=<LoginName>",
        new String[]{
            "SaveCount=WelcomeCount",
            web.LAST
        });

/*      ******** Alternative ************
An alternative check which does not require knowing the login name, is to look for the strings that precede and follow the login name when the login is successful.

    web.reg_find("Text=",
        new String[]{
            "TextPfx=Welcome,",
            "TextSfx=, to Web Tours",
            "SaveCount=WelcomeCount",
            web.LAST
        });

*************************************/

// Now log in
    web.submit_form("login.pl",
        new String[]{},
        new String[]{
            "Name=username", "Value=<LoginName>", web.ENDITEM,
            "Name=password", "Value=bean", web.ENDITEM,
            "Name=login.x", "Value=35", web.ENDITEM,
            "Name=login.y", "Value=14", web.ENDITEM,
            web.LAST
        });

    /* Check the Welcome Count and take whatever actions are
        appropriate for your script */

    if (lr.eval_int("<WelcomeCount>") == 0 )
        lr.message("Login " + lr.eval_string("<LoginName>") + " unsuccessful");
    else
        lr.message("Login " + lr.eval_string("<LoginName>") + " successful");
}
catch (Exception e){}

Example 2

In the following example, reg_find searches for the text string "Error." If the string is found, it fails and the script execution stops.

web.reg_find("Text/IC=Welcome", 
    new String []{Fail=Found", "LAST"});
web.url("test1.html",
    "URL=http://localhost/test1.html",
     new String []{"LAST"});

Example 3

In the following example, reg_find searches for the text string "ABC". If the string is not found, the script executes Action A. If the string is found one or more times, it executes Action B.

web.reg_find("Text/IC=ABC", 
    new String []{"SaveCount=abc_count", "LAST"});

web.url("test1.html",
    "URL=http://localhost/test1.html",
     new String []{"LAST"});

lr.message("Value of abc_count is " + lr.eval_string("<abc_count>"));

if (lr.eval_int("<abc_count>") == 0)
      lr.message("Not Found");
else
      lr.message("Found");