Create a variable extractor

This tutorial describes in detail the various steps involved in creating a Variable Extractor. It explains in which context a Variable Extractor should be used and provides an actual example.

To ensure that this tutorial applies to your case, it is advised to first read and understand the data extraction method, as described in Choose a data extraction method. For an overview of creating a Virtual User, see Design process.

Understand the problem

The contents of HTML pages generated by your application contain dynamic elements. Typical examples of dynamic content are elements such as HTTP request parameters or links with generated URLs. But in some situations these elements are neither parameters nor links, they are plain HTML elements belonging to the page. Nevertheless you might need to extract these dynamic elements to obtain more realistic scenarios and more thorough test results. You can look at the following excerpt from an HTTP response, containing the result of an account registration feature:

<HTML> 
   <BODY> 
      <H2>Create an account</H2> 
      <P> 
         <B>Error registering account:</B> 
         <I>The user name you have chosen is already in use.</I> 
      </P> 
      <P>The following suggestions are available:</P>
      <UL> 
         <LI>Suggestion 1: <I>WBrown</I> 
         <LI>Suggestion 2: <I>WilliamBrown_1</I> 
      </UL> 
      <P>Enter another user name and retry</P> 
      <FORM action="index.jsp" method="post"> 
         <INPUT type="text" name="username" /><BR/> 
         <INPUT type="submit" value="Send"> 
      </FORM> 
   </BODY> 
</HTML>
                                                

The HTML page contains text explaining that account registration has failed because the user name provided by the user already existed. The page then suggests alternative user names that the user could use. It finally provides an HTML form for the user to retry creating an account using a different user name, possibly one of the suggested alternatives. If you wanted to define a scenario where the Virtual User selects one of the suggested alternatives, for example the first one in the list for instance, you need to extract WBrown to re-inject it into the request that submits the form.

In this case, you are going to use a mechanism called the Variable Extractor which extracts arbitrary contents from an HTTP response and assigns the contents to a variable. The variable can then be used anywhere NeoLoad accepts variable values. The extracting mechanism and the way to use the extracted value are the subjects this tutorial mainly addresses.

Extract contents and assign it to a variable

The following screen shot depicts the simple HTML page described in the previous section. You may have recorded pages that enter the account information, including an already existing user name. The example application has then returned the following form and you have recorded the submission using one of the suggested user names. The one you choose during the recording phase has no importance because you will be using the one you decide to extract.

To create a Variable Extractor to extract the first name proposed, follow these steps:

Select the HTTP request containing the content to be extracted:
- Go to Design section.
- Select the Virtual users tab.
- Unfold the appropriate HTML page node.
- Select the HTTP request whose response contains the content to be extracted.
Go to the Variable Extractor settings:
- Click on the Advanced button to open the Advanced settings dialog box.
- Select the Variable extractors tab.
Add and define a variable:
- Add the variable: Click on the + (plus) button to add a new variable. This opens the Variables Extractor dialog box.
 
 This dialog box helps you define how to extract the value that will be assigned to the variable. Extracting the value will be based on regular expressions. Most of the time this task will be greatly eased by the Variables Extractor dialog box. In some situations it might be necessary for you to manually work with regular expressions to extract the contents of the variable. In this case, NeoLoad provides an advanced mode. You can switch to the advanced mode by selecting the Switch to advanced mode button. The advanced mode involves manually manipulating and defining regular expressions. For more information, see Variable extractors and Regular expressions.
- Name the variable: Enter the name of the variable in the Variable Name text box, in the example you call it "SuggestedUsername".
- Enter the Starting with text: Enter the text that will unambiguously identify where the content you want to extract starts. This step is important because the extracting mechanism depends on it to succeed in correctly extracting the value of the variable.
 - Select the picker button associated with the Starting with text box. This opens a Response Text Picker dialog box. The dialog box presents the contents of the HTTP response from which the contents of the variable will be extracted.
 - Select in the response the text that will always be placed before the text you want to extract. This portion of text must unambiguously identify the starting position of the text you are targeting. In the example you select the following sentence <LI>Suggestion 1: . Selecting only  would have been insufficient because in the response, there already is an  preceding the text you want to identify.
 - Select the Pick Selected Text button to confirm the text you have selected.
- Define the matching expression: Define the expression that will match the contents you want to extract. The Followed by panel displays a set of expressions that the text you are targeting should meet. A default expression is provided: it matches Any character that occurs Zero or more times. Any character matches all characters except newline characters.
 - In this case this suits you perfectly, you want to extract any text following the <LI>Suggestion 1:  sentence. There are no particular constraints on the text you are targeting. Another way of seeing the configuration at this stage is to state that you are extracting a value that matches the following regular expression <LI>Suggestion 1: (.*). The (.*) means any number of characters except the newline character. The "Test" panel at the bottom of the Variable Extractor Dialog box displays the text that will be extracted according to the current state of your configuration. This is handy to get an idea of what the result will be while configuring the extraction.
 In this case the dialog box displays WBrown. This is consistent with the fact that the expression "any number of characters except new line" matches all the text including . The Define Ending with step will finalize the configuration so that  is not included in the text you want to extract.
 - Had you wanted to define additional constraints on the text to extract, you could have added other expressions and configured them using the Followed by and Occurs elements.
 - The Starting with text is no longer <LI>Suggestion 1: , but is now reduced to <LI>Suggestion. The first expression you define is a Numeric Character Zero or more times. The second is a literal sentence, : , that occurs only once, the third is Any character Zero or more times.
 - The content to extract has not changed: The extracted value in the Test panel is still WBrown. This configuration is equivalent to matching the following regular expression <LI>Suggestion (\d*)(: )(.*) and extracting the text that only matches the third expression (.*). These expressions are called "value templates". Advanced mode, reserved for users who are at ease working with regular expressions, allows you to view and edit the regular expression generated in standard mode.
 - An important point to understand in this alternative configuration is the Extract column which defines, among the listed expressions, the ones that must actually be extracted and used to assign the variable. The only one of interest to you here is the last one, this is why it is the only one checked in the Extract column.
 - For the rest of the tutorial you will keep to your first and simpler configuration.
- Define Ending with:
 - Define the text that will unambiguously identify where the contents you want to extract ends.
 - You can use the Response text picker as previously detailed for the Starting with item if you want to select the text from the HTTP response. In this case the ending text is quite simple, you know the suggested user name ends with the  HTML element. This is what you enter in the Ending with item.
Test the variable:
- Select the Test tab to test your variable.
- The Test tab provides an easy to use feature to test the variable you have configured in the previous steps. It allows you to test the Variable Extractor on the recorded HTTP response. If required, the HTTP response may be edited.
- The screen shot that follows depicts a situation where you have changed the first suggested value to Will Brown, you want to make sure extraction correctly takes white spaces into account:
Define the behavior when the extracting mechanism fails:
- Select the Error tab to configure NeoLoad behavior when the extracting process fails to find the value for the variable. NeoLoad provides two items to configure its behavior, the value to assign to the variable if the extraction fails, an error value, and the fact that an assertion error is thrown if the extraction fails. For more information about assertions, see Global validation.
- Depending on your application, several strategies are possible. If it makes no sense for your scenario to not find the extracted value then throwing an assertion error is important. On the other hand, if in some situations it is acceptable and consistent not to find the extracted value, an error value can be assigned to the variable. In this case, Virtual User actions such as the if ... then ... else construct can be used to adapt the behavior of the scenario to this situation.
Confirm variable creation:
- Close the Variable Extractor dialog box by selection the OK button: the creation and configuration steps are completed. The Variable extractors tab of the Advanced panel displays all the defined variables. It presents variable names, the associated regular expression and the template expression that will be used to extract the value and assign it to the variable.
- In this case the first template value, $1$, of the <LI>Suggestion 1: (.*) regular expression will be assigned to the SuggestedUsername variable. The $1$ template value corresponds to the (.*) of the regular expression. To quickly and easily spot requests that use Variable Extractors, select any node in the User Paths, right click on this node and select the Flag requests then Variables extractors defined on.
 NeoLoad adds a tick to all the nodes (Virtual Users, HTML pages and HTTP requests) of the User Paths using variable extractors.