Modified: jmeter/trunk/docs/usermanual/component_reference.html URL: http://svn.apache.org/viewvc/jmeter/trunk/docs/usermanual/component_reference.html?rev=1822450&r1=1822449&r2=1822450&view=diff ============================================================================== --- jmeter/trunk/docs/usermanual/component_reference.html (original) +++ jmeter/trunk/docs/usermanual/component_reference.html Sun Jan 28 08:38:53 2018 @@ -483,6 +483,9 @@ <li> <a href="#SMIME_Assertion">SMIME Assertion</a> </li> +<li> +<a href="#JSON_Assertion">JSON Assertion</a> +</li> </ul> </li> <li> @@ -501,6 +504,9 @@ <a href="#Constant_Throughput_Timer">Constant Throughput Timer</a> </li> <li> +<a href="#Precise_Throughput_Timer">Precise Throughput Timer</a> +</li> +<li> <a href="#Synchronizing_Timer">Synchronizing Timer</a> </li> <li> @@ -579,6 +585,9 @@ <li> <a href="#JSON_Extractor">JSON Extractor</a> </li> +<li> +<a href="#Boundary_Extractor">Boundary Extractor</a> +</li> </ul> </li> <li> @@ -1418,17 +1427,8 @@ However the <span class="code">Java</spa <p> <b>Response size calculation</b> <br> -Optional properties to allow change the method to get response size:<br> -</p> -<ul> -<li>Gets the real network size in bytes for the body response -<pre class="source">sampleresult.getbytes.body_real_size=true</pre> -</li> -<li>Add HTTP headers to full response size -<pre class="source">sampleresult.getbytes.headers_size=true</pre> -</li> -</ul> + <div class="clear"></div> <div class="note"> The <span class="code">Java</span> implementation does not include transport overhead such as @@ -1437,23 +1437,32 @@ The <span class="code">HttpClient4</span so the value may be greater than the number of bytes in the response content. </div> <div class="clear"></div> -<div class="clear"></div> -<div class="note">When those two properties are set <span class="code">false</span>, JMeter returns only data response size (uncompressed if request uses gzip/deflate mode).</div> -<div class="clear"></div> + +</p> <p> <b>Retry handling</b> <br> -For HttpClient4 the retry count has been set to <span class="code">0</span>, meaning not retry is attempted. -Note that the Java implementation appears to retry 1 time. -The retry count can be overridden by setting the relevant JMeter property, for example: -</p> +By default retry has been set to 0 for both HttpClient4 and Java implementations, meaning no retry is attempted.<br> +For HttpClient4, the retry count can be overridden by setting the relevant JMeter property, for example: + <pre class="source"> httpclient4.retrycount=3 </pre> + +<div class="clear"></div> +<div class="note"> +With HC4 Implementation, retry will be done on Idempotent Http Methods by default. +If you want to retry for all methods, then set property <pre class="source"> httpclient4.request_sent_retry_enabled=true </pre> +</div> +<div class="clear"></div> + +Note that the Java implementation does not retry neither by default, you can change this by setting <pre class="source">http.java.sampler.retries=3</pre> + +</p> <p> <b>Note: Certificates does not conform to algorithm constraints</b> @@ -1580,7 +1589,7 @@ the additional variables for rows four, </div> <div class="property"> -<div class="name req-true">Variable Name</div> +<div class="name req-true">Variable Name of Pool declared in JDBC Connection Configuration</div> <div class="description req-true"> Name of the JMeter variable that the connection pool is bound to. This must agree with the '<span class="code">Variable Name</span>' field of a <a href="../usermanual/component_reference.html#JDBC_Connection_Configuration">JDBC Connection Configuration</a>. @@ -3215,7 +3224,15 @@ Currently the only way to change these i <div class="description"> <p> -The JSR223 Sampler allows JSR223 script code to be used to perform a sample. +The JSR223 Sampler allows JSR223 script code to be used to perform a sample or some computation required to create/update variables. +<div class="clear"></div> +<div class="note"> +If you don't want to generate a <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a> when this sampler is run, call the following method: +<pre class="source">SampleResult.setIgnore();</pre> + +</div> +<div class="clear"></div> + </p> <p> @@ -3975,7 +3992,7 @@ The following table shows some values wh <div class="description"> <p> - JMS Publisher will subscribe to messages in a given destination (topic or queue). For those not + JMS Subscriber will subscribe to messages in a given destination (topic or queue). For those not familiar with JMS, it is the J2EE specification for messaging. There are numerous JMS servers on the market and several open source options. </p> @@ -4061,7 +4078,7 @@ The following table shows some values wh <div class="property"> <div class="name req-true">Setup</div> -<div class="description req-true">The destination setup type. With <span class="code">At startup</span>, the destination name is static (i.e. always same name during the test), with <span class="code">Each sample</span>, the destination name is dynamic and is evaluate at each sample (i.e. the destination name may be a variable)</div> +<div class="description req-true">The destination setup type. With <span class="code">At startup</span>, the destination name is static (i.e. always same name during the test), with <span class="code">Each sample</span>, the destination name is dynamic and is evaluated at each sample (i.e. the destination name may be a variable)</div> <div class="required req-true">Yes</div> </div> @@ -4179,9 +4196,15 @@ The following table shows some values wh <p> -<span class="code">Request Only</span> will typically be used to put load on a JMS System.<br> +<span class="code">request_only</span> will typically be used to put load on a JMS System.<br> + +<span class="code">request_reply</span> will be used when you want to test response time of a JMS service that processes messages sent to the Request Queue as this mode will wait for the response on the Reply queue sent by this service.<br> + +<span class="code">browse</span> returns the current queue depth, i.e. the number of messages on the queue.<br> -<span class="code">Request Response</span> will be used when you want to test response time of a JMS service that processes messages sent to the Request Queue as this mode will wait for the response on the Reply queue sent by this service.<br> +<span class="code">read</span> reads a message from the queue (if any).<br> + +<span class="code">clear</span> clears the queue, i.e. remove all messages from the queue.<br> </p> @@ -4248,6 +4271,12 @@ The following table shows some values wh </div> <div class="property"> +<div class="name req-true">Number of samples to aggregate</div> +<div class="description req-true">Number of samples to aggregate. Only applicable for Communication style Read.</div> +<div class="required req-true">Yes</div> +</div> + +<div class="property"> <div class="name req-false">JMS Selector</div> <div class="description req-false"> Message Selector as defined by JMS specification to extract only @@ -4259,7 +4288,8 @@ The following table shows some values wh <div class="property"> <div class="name req-true">Communication style</div> <div class="description req-true"> - The Communication style can be <span class="code">Request Only</span> (also known as Fire and Forget) or <span class="code">Request Response</span>: + The Communication style can be <span class="code">Request Only</span> (also known as Fire and Forget), <span class="code">Request Response</span>, + <span class="code">Read</span>, <span class="code">Browse</span>, <span class="code">Clear</span>: <dl> <dt> @@ -4278,6 +4308,23 @@ The following table shows some values wh With <span class="code">Request Response</span> mode, you need to have a Server that listens to messages sent to Request Queue and sends replies to queue referenced by <span class="code">message.getJMSReplyTo()</span>.</dd> +<dt> +<span class="code">Read</span> +</dt> +<dd> will read a message from an outgoing queue which has no listeners attached. This can be convenient for testing purposes. + This method can be used if you need to handle queues without a binding file (in case the jmeter-jms-skip-jndi library is used), + which only works with the JMS Point-to-Point sampler. In case binding files are used, one can also use the JMS Subscriber Sampler for reading from a queue.</dd> + +<dt> +<span class="code">Browse</span> +</dt> +<dd> will determine the current queue depth without removing messages from the queue, returning the number of messages on the queue.</dd> + +<dt> +<span class="code">Clear</span> +</dt> +<dd> will clear the queue, i.e. remove all messages from the queue.</dd> + </dl> </div> @@ -4338,7 +4385,7 @@ The following table shows some values wh <div class="description req-true"> The timeout in milliseconds for the reply-messages. If a reply has not been received within the specified time, the specific testcase fails and the specific reply message received after the timeout is discarded. - Default value is <span class="code">2000</span> ms. + Default value is <span class="code">2000</span> ms. <span class="code">0</span> means no timeout. </div> <div class="required req-true">Yes</div> </div> @@ -4871,7 +4918,7 @@ In non-GUI mode, JMeter will exit if som <div class="property"> <div class="name req-true">Target</div> <div class="description req-true"> -<span class="code">Current Thread</span> / <span class="code">All Threads</span> (ignored for Pause)</div> +<span class="code">Current Thread</span> / <span class="code">All Threads</span> (ignored for <span class="code">Pause</span> and <span class="code">Go to next loop iteration</span>)</div> <div class="required req-true">Yes</div> </div> @@ -5470,6 +5517,12 @@ loop through them a certain number of ti specified for the Thread Group. For example, if you add one HTTP Request to a Loop Controller with a loop count of two, and configure the Thread Group loop count to three, JMeter will send a total of <span class="code">2 * 3 = 6</span> HTTP Requests. +<div class="clear"></div> +<div class="note">JMeter will expose the looping index as a variable named <span class="code">__jm__<Name of your element>__idx</span>. So for +example, if your Loop Controller is named LC, then you can access the looping index through <span class="code">${__jm__LC__idx}</span>. +Index starts at 0</div> +<div class="clear"></div> + </p> </div> <div class="screenshot"> @@ -5624,10 +5677,6 @@ Bug Page, Bug Page.</p> </div> -<div class="clear"></div> -<div class="note">The behaviour of the Once Only controller under anything other than the -Thread Group or a Loop Controller is not currently defined. Odd things may happen.</div> -<div class="clear"></div> <div class="go-top"> <a href="#">^</a> </div> @@ -5985,7 +6034,8 @@ Please refer to the <a href="../usermanu </h2> <div class="description"> -<p>The Runtime Controller controls how long its children are allowed to run. +<p>The Runtime Controller controls how long its children how long its children will run. + Controller will run its children until configured <span class="code">Runtime(s)</span> is exceeded. </p> </div> @@ -6014,7 +6064,7 @@ Please refer to the <a href="../usermanu <div class="property"> <div class="name req-true">Runtime (seconds)</div> -<div class="description req-true">Desired runtime in seconds</div> +<div class="description req-true">Desired runtime in seconds. 0 means no run.</div> <div class="required req-true">Yes</div> </div> @@ -6037,26 +6087,48 @@ Please refer to the <a href="../usermanu </p> <p> - The script can be processed as a variable expression, rather than requiring JavaScript. - It was always possible to use functions and variables in the JavaScript condition, so long as they evaluated to "<span class="code">true</span>" or "<span class="code">false</span>"; - now this can be done without the overhead of using JavaScript as well. For example, previously one could use the condition: + If Controller will internally use javascript to evaluate the condition but this can have a performance penalty. + <figure> +<a href="../images/screenshots/if_controller_javascript.png"><img src="../images/screenshots/if_controller_javascript.png" width="819" height="265" alt="If Controller using javascript"></a> +<figcaption>If Controller using javascript</figcaption> +</figure> + A better option (default one) is to check <span class="code">Interpret Condition as Variable Expression?</span>, then in the condition field you have 2 options: + <ul> + +<li>Option 1 : Use a variable that contains <span class="code">true</span> or <span class="code">false</span> + +<div class="clear"></div> +<div class="note">If you want to test if last sample was successful, you can use <span class="code">${JMeterThread.last_sample_ok}</span> + +<figure> +<a href="../images/screenshots/if_controller_variable.png"><img src="../images/screenshots/if_controller_variable.png" width="815" height="260" alt="If Controller using Variable"></a> +<figcaption>If Controller using Variable</figcaption> +</figure> + +</div> +<div class="clear"></div> + +</li> + +<li>Option 2 : Use a function (<span class="code">${__jexl3()}</span> is advised) to evaluate an expression that must return <span class="code">true</span> or <span class="code">false</span> + +<figure> +<a href="../images/screenshots/if_controller_expression.png"><img src="../images/screenshots/if_controller_expression.png" width="815" height="260" alt="If Controller using expression"></a> +<figcaption>If Controller using expression</figcaption> +</figure> + +</li> + +</ul> + + For example, previously one could use the condition: <span class="code">${__jexl3(${VAR} == 23)}</span> and this would be evaluated as <span class="code">true</span>/<span class="code">false</span>, the result would then be passed to JavaScript which would then return <span class="code">true</span>/<span class="code">false</span>. If the Variable Expression option is selected, then the expression is evaluated and compared with "<span class="code">true</span>", without needing to use JavaScript. - Also, variable expressions can return any value, whereas the - JavaScript condition must return "<span class="code">true</span>"/"<span class="code">false</span>" or an error is logged. </p> <div class="clear"></div> <div class="note"> - No variables are made available to the script when the condition is interpreted as JavaScript. - If you need access to such variables, then select "<span class="code">Interpret Condition as Variable Expression?</span>" and use - a <span class="code"><a href="../usermanual/functions.html#__jexl3">__jexl3</a></span>, <span class="code"><a href="../usermanual/functions.html#__groovy">__groovy</a></span> or <span class="code"><a href="../usermanual/functions.html#__javaScript">__javaScript()</a></span> (discouraged for performance) function call. You can then use the objects "<span class="code">vars</span>", "<span class="code">log</span>", "<span class="code">ctx</span>" etc. in the script. - </div> -<div class="clear"></div> - -<div class="clear"></div> -<div class="note"> To test if a variable is undefined (or null) do the following, suppose var is named <span class="code">myVar</span>, expression will be: <pre class="source">"${myVar}" == "\${myVar}"</pre> Or use: @@ -6068,7 +6140,7 @@ Please refer to the <a href="../usermanu </div> <div class="screenshot"> <figure> -<a href="../images/screenshots/ifcontroller.png"><img src="../images/screenshots/ifcontroller.png" width="497" height="131" alt="Screenshot for Control-Panel of If Controller"></a> +<a href="../images/screenshots/if_controller_expression.png"><img src="../images/screenshots/if_controller_expression.png" width="814" height="262" alt="Screenshot for Control-Panel of If Controller"></a> <figcaption>Screenshot of Control-Panel of If Controller</figcaption> </figure> </div> @@ -6136,7 +6208,8 @@ Please refer to the <a href="../usermanu </ul> If there is an error interpreting the code, the condition is assumed to be <span class="code">false</span>, and a message is logged in <span class="code">jmeter.log</span>. <div class="clear"></div> -<div class="note">Note it is advised to avoid using JavaScript mode for performances</div> +<div class="note">Note it is advised to avoid using JavaScript mode for performance.<br> +<br>When using <span class="code"><a href="../usermanual/functions.html#__groovy">__groovy</a></span> take care to not use variable replacement in the string, otherwise if using a variable that changes the script cannot be cached. Instead get the variable using: <span class="code">vars.get("myVar").</span> See the Groovy examples below.</div> <div class="clear"></div> </div> @@ -6147,6 +6220,15 @@ Please refer to the <a href="../usermanu <ul> <li> +<span class="code">${__groovy(vars.get("myVar") != "Invalid" )}</span> (Groovy check myVar is not equal to Invalid)</li> + +<li> +<span class="code">${__groovy(vars.get("myInt").toInteger() <=4 )}</span> (Groovy check myInt is less then or equal to 4)</li> + +<li> +<span class="code">${__groovy(vars.get("myMissing") != null )}</span> (Groovy check if the myMissing variable is not set)</li> + +<li> <span class="code">${__jexl3(${COUNT} < 10)}</span> </li> @@ -6200,7 +6282,7 @@ If the last sample just before the loop <div class="clear"></div> <div class="note"> The condition can be any variable or function that eventually evaluates to the string "<span class="code">false</span>". -This allows the use of JavaScript, BeanShell, properties or variables as needed. +This allows the use of <span class="code">__jexl3</span>, <span class="code">__groovy</span> function, properties or variables as needed. </div> <div class="clear"></div> @@ -6221,11 +6303,11 @@ For example: <span class="code">${VAR}</span> - where <span class="code">VAR</span> is set to false by some other test element</li> <li> -<span class="code">${__javaScript(${C}==10)}</span> +<span class="code">${__jexl3(${C}==10)}</span> </li> <li> -<span class="code">${__javaScript("${VAR2}"=="abcd")}</span> +<span class="code">${__jexl3("${VAR2}"=="abcd")}</span> </li> <li> @@ -6252,15 +6334,15 @@ For example: </div> <div class="property"> -<div class="name req-true">Name</div> -<div class="description req-true">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</div> -<div class="required req-true">Yes</div> +<div class="name req-false">Name</div> +<div class="description req-false">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</div> +<div class="required req-false">No</div> </div> <div class="property"> -<div class="name req-true">Condition</div> -<div class="description req-true">blank, <span class="code">LAST</span>, or variable/function</div> -<div class="required req-true">Yes</div> +<div class="name req-false">Condition</div> +<div class="description req-false">blank, <span class="code">LAST</span>, or variable/function</div> +<div class="required req-false">No</div> </div> </div> @@ -6317,15 +6399,15 @@ If there is no default, then no element </div> <div class="property"> -<div class="name req-true">Name</div> -<div class="description req-true">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</div> -<div class="required req-true">Yes</div> +<div class="name req-false">Name</div> +<div class="description req-false">Descriptive name for this controller that is shown in the tree.</div> +<div class="required req-false">No</div> </div> <div class="property"> -<div class="name req-true">Switch Value</div> -<div class="description req-true">The number (or name) of the subordinate element to be invoked. Elements are numbered from 0.</div> -<div class="required req-true">Yes</div> +<div class="name req-false">Switch Value</div> +<div class="description req-false">The number (or name) of the subordinate element to be invoked. Elements are numbered from 0. Defaults to 0</div> +<div class="required req-false">No</div> </div> </div> @@ -6374,6 +6456,14 @@ with the return variable having the resp </p> <p> +<div class="clear"></div> +<div class="note">JMeter will expose the looping index as a variable named <span class="code">__jm__<Name of your element>__idx</span>. So for +example, if your Loop Controller is named FEC, then you can access the looping index through <span class="code">${__jm__FEC__idx}</span>. +Index starts at 0</div> +<div class="clear"></div> +</p> + +<p> It is especially suited for running with the regular expression post-processor. This can "create" the necessary input variables out of the result data of a previous request. By omitting the "<span class="code">_</span>" separator, the ForEach Controller can be used to loop through the groups by using @@ -6520,7 +6610,7 @@ The Module Controller provides a mechani <p> A test plan fragment consists of a Controller and all the test elements (samplers etc.) contained in it. -The fragment can be located in any Thread Group, or on the <a href="../usermanual/component_reference.html#WorkBench">WorkBench</a>. +The fragment can be located in any Thread Group. If the fragment is located in a Thread Group, then its Controller can be disabled to prevent the fragment being run except by the Module Controller. Or you can store the fragments in a dummy Thread Group, and disable the entire Thread Group. @@ -6556,9 +6646,6 @@ otherwise a duplicate may be accidentall <figcaption>Screenshot of Control-Panel of Module Controller</figcaption> </figure> </div> -<div class="clear"></div> -<div class="note">The Module Controller should not be used with remote testing or non-gui testing in conjunction with Workbench components since the Workbench test elements are not part of test plan <span class="code">.jmx</span> files. Any such test will fail.</div> -<div class="clear"></div> <div class="properties"> <h3 id="Module_Controller_parms1"> Parameters @@ -7201,8 +7288,8 @@ are part of the test plan.</p> <div class="clear"></div> <div class="note"> -View Results Tree MUST NOT BE USED during load test as it consumes a lot of resources (memory and CPU). Use it only for either functional testing or -during Test Plan debugging and Validation. +View Results Tree MUST NOT BE USED during load test as it consumes a lot of resources (memory and CPU). +Use it only for either functional testing or during Test Plan debugging and Validation. </div> <div class="clear"></div> The View Results Tree shows a tree of all sample responses, allowing you to view the @@ -7353,8 +7440,9 @@ video/ <tr> <td><span class="code">XML</span></td> -<td>The <i>XML view</i> will show response in tree style. +<td>The <i>XML view</i> will show response in tree style. Any DTD nodes or Prolog nodes will not show up in tree; however, response may contain those nodes. +You can right-click on any node and expand or collapse all nodes below it. <br> </td> </tr> @@ -7368,6 +7456,15 @@ will be displayed in the lower panel.<br </td> </tr> +<tr> +<td><span class="code">Boundary Extractor Tester </span></td> +<td>The <i>Boundary Extractor Tester</i> only works for text responses. It shows the plain text in the upper panel. +The "<span class="code">Test</span>" button allows the user to apply the Boundary Extractor query to the upper panel and the results +will be displayed in the lower panel.<br> + +</td> +</tr> + </table> <p> @@ -8868,7 +8965,7 @@ By default, a Graphite implementation is <a href="../images/screenshots/grafana_dashboard.png"><img src="../images/screenshots/grafana_dashboard.png" width="1265" height="581" alt="Grafana dashboard"></a> <figcaption>Grafana dashboard</figcaption> </figure> -<p>Since JMeter 3.2, a new implementation (in Beta state) has been added that allows writing directly in InfluxDB with a custom schema, it is called <span class="code">InfluxdbBackendListenerClient</span> +<p>Since JMeter 3.2, a new implementation has been added that allows writing directly in InfluxDB with a custom schema, it is called <span class="code">InfluxdbBackendListenerClient</span> The following parameters apply to the <a href="../api/org/apache/jmeter/visualizers/backend/influxdb/InfluxdbBackendListenerClient.html">InfluxdbBackendListenerClient</a> implementation:</p> <div class="properties"> <h3 id="Backend_Listener_parms3"> @@ -8897,7 +8994,7 @@ By default, a Graphite implementation is <div class="property"> <div class="name req-true">application</div> -<div class="description req-true">Name of tested application. This value is stored in the 'events' measurement as a tag named 'application' </div> +<div class="description req-true">Name of tested application. This value is stored in the 'events' measurement too as a tag named 'application' </div> <div class="required req-true">Yes</div> </div> @@ -8927,7 +9024,7 @@ By default, a Graphite implementation is <div class="property"> <div class="name req-false">eventTags</div> -<div class="description req-false">List of tags. This value is stored in the 'events' measurement as a tag named 'tags'.</div> +<div class="description req-false">Grafana allow to display tag for each annotation. You can fill them here. This value is stored in the 'events' measurement as a tag named 'tags'.</div> <div class="required req-false">No</div> </div> @@ -8939,6 +9036,12 @@ By default, a Graphite implementation is List must be semicolon separated. Generally 3 or 4 values should be sufficient.</div> <div class="required req-true">Yes</div> </div> + +<div class="property"> +<div class="name req-false">TAG_WhatEverYouWant</div> +<div class="description req-false">You can add as many custom tags as you want. For each of them, just create a new line and prefix its name by "<span class="code">TAG_</span>"</div> +<div class="required req-false">No</div> +</div> </div> <p>See also <a href="realtime-results.html">Real-time results</a> and <a href="http://docs.grafana.org/reference/annotations/#influxdb-annotations";>Influxdb annotations in Grafana</a> for more details.</p> @@ -9104,7 +9207,7 @@ By default, a Graphite implementation is </div> <div class="property"> -<div class="name req-false">Ignore first line (only used if Variable Names is not empty)</div> +<div class="name req-false">Use first line as Variable Names</div> <div class="description req-false"> Ignore first line of CSV file, it will only be used used if Variable Names is not empty, if Variable Names is empty the first line must contain the headers. @@ -10141,7 +10244,7 @@ instead. (see figures 12 and 13).</p> </div> <div class="property"> -<div class="name req-true">Variable Name</div> +<div class="name req-true">Variable Name for created pool</div> <div class="description req-true">The name of the variable the connection is tied to. Multiple connections can be used, each tied to a different variable, allowing JDBC Samplers to select the appropriate connection. @@ -11536,16 +11639,16 @@ These can be used anywhere within the ex <ul> <li> -<span class="code">Main sample only</span> - assertion only applies to the main sample</li> +<span class="code">Main sample only</span> - only applies to the main sample</li> <li> -<span class="code">Sub-samples only</span> - assertion only applies to the sub-samples</li> +<span class="code">Sub-samples only</span> - only applies to the sub-samples</li> <li> -<span class="code">Main sample and sub-samples</span> - assertion applies to both.</li> +<span class="code">Main sample and sub-samples</span> - applies to both.</li> <li> -<span class="code">JMeter Variable</span> - assertion is to be applied to the contents of the named variable</li> +<span class="code">JMeter Variable Name to use</span> - assertion is to be applied to the contents of the named variable</li> </ul> @@ -11788,7 +11891,7 @@ the size be equal to, greater than, less <span class="code">Main sample and sub-samples</span> - assertion applies to both.</li> <li> -<span class="code">JMeter Variable</span> - assertion is to be applied to the contents of the named variable</li> +<span class="code">JMeter Variable Name to use</span> - assertion is to be applied to the contents of the named variable</li> </ul> @@ -12184,10 +12287,10 @@ Some sample expressions: <ul> <li> -<span class="code">//title[text()='Text to match']</span> - matches <span class="code"><text>Text to match</text></span> anywhere in the response</li> +<span class="code">//title[text()='Text to match']</span> - matches <span class="code"><title>Text to match</title></span> anywhere in the response</li> <li> -<span class="code">/title[text()='Text to match']</span> - matches <span class="code"><text>Text to match</text></span> at root level in the response</li> +<span class="code">/title[text()='Text to match']</span> - matches <span class="code"><title>Text to match</title></span> at root level in the response</li> </ul> @@ -12769,6 +12872,77 @@ please ensure that you select "<span cla </div> </div> +<div class="component"> +<h2 id="JSON_Assertion">JSON Assertion<a class="sectionlink" href="#JSON_Assertion" title="Link to here">¶</a> +</h2> +<div class="description"> + +<p> + This component allows you to perform validations of JSON documents. + First, it will parse the JSON and fail if the data is not JSON. + Second, it will search for specified path, using syntax from <a href="https://github.com/jayway/JsonPath";> Jayway JsonPath 1.2.0</a>. If the path is not found, it will fail. + Third, if JSON path was found in the document, and validation against expected value was requested, it will perform validation. For the <span class="code">null</span> value there is special checkbox in the GUI. + Note that if the path will return array object, it will be iterated and if expected value is found, the assertion will succeed. To validate empty array use <span class="code">[]</span> string. Also, if patch will return dictionary object, it will be converted to string before comparison. + </p> + +</div> +<div class="properties"> +<h3 id="JSON_Assertion_parms1"> + Parameters + <a class="sectionlink" href="#JSON_Assertion_parms1" title="Link to here">¶</a> +</h3> +<div class="property title"> +<div class="name title">Attribute</div> +<div class="description title">Description</div> +<div class="required title">Required</div> +</div> + +<div class="property"> +<div class="name req-true">Assert JSON Path exists</div> +<div class="description req-true">Path to JSON element for assert.</div> +<div class="required req-true">Yes</div> +</div> + +<div class="property"> +<div class="name req-false">Additionally assert value</div> +<div class="description req-false">Select checkbox if you want make assert with some value</div> +<div class="required req-false">No</div> +</div> + +<div class="property"> +<div class="name req-false">Match as regular expression</div> +<div class="description req-false">Select checkbox if you want use regular expression</div> +<div class="required req-false">No</div> +</div> + +<div class="property"> +<div class="name req-false">Expected Value</div> +<div class="description req-false">Value for assert or regular expression for match</div> +<div class="required req-false">No</div> +</div> + +<div class="property"> +<div class="name req-false">Expect null</div> +<div class="description req-false">Select checkbox if you expect null</div> +<div class="required req-false">No</div> +</div> + +<div class="property"> +<div class="name req-false">Invert assertion (will fail if above conditions met)</div> +<div class="description req-false">Invert assertion (will fail if above conditions met)</div> +<div class="required req-false">No</div> +</div> + +</div> +<figure> +<a href="../images/screenshots/json_path_assertion.png"><img src="../images/screenshots/json_path_assertion.png" width="1140" height="356" alt="JSON Assertion"></a> +<figcaption>JSON Assertion</figcaption> +</figure> +<div class="go-top"> +<a href="#">^</a> +</div> +</div> + <a href="#">^</a> @@ -12989,7 +13163,7 @@ The value can be changed in various ways <li>using a counter variable</li> -<li>using a JavaScript or BeanShell function to provide a changing value</li> +<li>using a <span class="code">__jexl3</span>, <span class="code">__groovy</span> function to provide a changing value</li> <li>using the remote BeanShell server to change a JMeter property</li> @@ -13077,97 +13251,336 @@ Note that the throughput value should no <div class="component"> -<h2 id="Synchronizing_Timer">Synchronizing Timer<a class="sectionlink" href="#Synchronizing_Timer" title="Link to here">¶</a> +<h2 id="Precise_Throughput_Timer">Precise Throughput Timer<a class="sectionlink" href="#Precise_Throughput_Timer" title="Link to here">¶</a> </h2> <div class="description"> +<p>This timer introduces variable pauses, calculated to keep the total throughput (e.g. in terms of samples per minute) as close as possible to a give figure. Of course the throughput will be lower if the server is not capable of handling it, or if other timers, or if there's not enough threads, or time-consuming test elements prevent it.</p> -<p> -The purpose of the SyncTimer is to block threads until X number of threads have been blocked, and -then they are all released at once. A SyncTimer can thus create large instant loads at various -points of the test plan. -</p> +<p>Although the Timer is called Precise Throughput Timer, it does not aim to produce precisely the same number of samples over one-second intervals during the test.</p> -</div> -<div class="screenshot"> -<figure> -<a href="../images/screenshots/timers/sync_timer.png"><img src="../images/screenshots/timers/sync_timer.png" width="410" height="145" alt="Screenshot for Control-Panel of Synchronizing Timer"></a> -<figcaption>Screenshot of Control-Panel of Synchronizing Timer</figcaption> -</figure> -</div> -<div class="properties"> -<h3 id="Synchronizing_Timer_parms1"> - Parameters - <a class="sectionlink" href="#Synchronizing_Timer_parms1" title="Link to here">¶</a> -</h3> -<div class="property title"> -<div class="name title">Attribute</div> -<div class="description title">Description</div> -<div class="required title">Required</div> -</div> - -<div class="property"> -<div class="name req-false">Name</div> -<div class="description req-false">Descriptive name for this timer that is shown in the tree. </div> -<div class="required req-false">No</div> -</div> - -<div class="property"> -<div class="name req-true">Number of Simultaneous Users to Group by</div> -<div class="description req-true">Number of threads to release at once. Setting it to <span class="code">0</span> is equivalent to setting it to Number of threads in Thread Group.</div> -<div class="required req-true">Yes</div> -</div> - -<div class="property"> -<div class="name req-false">Timeout in milliseconds</div> -<div class="description req-false">If set to <span class="code">0</span>, Timer will wait for the number of threads to reach the value in "<span class="code">Number of Simultaneous Users to Group</span>". If superior to <span class="code">0</span>, then timer will wait at max "<span class="code">Timeout in milliseconds</span>" for the number of Threads. If after the timeout interval the number of users waiting is not reached, timer will stop waiting. Defaults to <span class="code">0</span> -</div> -<div class="required req-false">No</div> -</div> +<p>The timer works best for rates under 36000 requests/hour, however your milage might vary (see monitoring section below if your goals are + vastly different).</p> -</div> -<div class="clear"></div> -<div class="note"> -If timeout in milliseconds is set to <span class="code">0</span> and number of threads never reaches "<span class="code">Number of Simultaneous Users to Group by</span>" then Test will pause infinitely. -Only a forced stop will stop it. Setting Timeout in milliseconds is an option to consider in this case. -</div> -<div class="clear"></div> -<div class="clear"></div> -<div class="note"> -Synchronizing timer blocks only within one JVM, so if using Distributed testing ensure you never set "<span class="code">Number of Simultaneous Users to Group by</span>" to a value superior to the number of users -of its containing Thread group considering 1 injector only. -</div> -<div class="clear"></div> -<div class="go-top"> -<a href="#">^</a> -</div> -</div> +<h4>Best location of a Precise Throughput Timer in a Test Plan</h4> + +<p>As you might know, the timers are inherited by all the siblings and their child elements. That is why one of the best places for + <span class="code">Precise Throughput Timer</span> is under the first element in a test loop. For instance, you might add a dummy sampler at the beginnig, + and place the timer under that dummy sampler</p> -<div class="component"> -<h2 id="BeanShell_Timer">BeanShell Timer<a class="sectionlink" href="#BeanShell_Timer" title="Link to here">¶</a> -</h2> -<div class="description"> + +<h4>Produced schedule</h4> <p> -The BeanShell Timer can be used to generate a delay. -</p> +<span class="code">Precise Throughput Timer</span> models <a href="https://en.wikipedia.org/wiki/Poisson_point_process";>Poisson arrivals</a> schedule. That schedule often happens in a real-life, so it makes sense to use that for load testing. + For instance, it naturally might generate samples that are close together thus it might reveal concurrency issues. Even if you manage to generate Poisson arrivals + with <a href="../usermanual/component_reference.html#Poisson_Random_Timer">Poisson Random Timer</a>, it would be suseptible to the issues listed below. For instance, true Poisson arrivals might have indefinitely long + pause, and that is not practical for load testing. For instance, "regular" Poisson arrivals with 1 per second rate might end up with 50 samples over 60 second long test.</p> <p> +<a href="../usermanual/component_reference.html#Constant_Throughput_Timer">Constant Throughput Timer</a> converges to the specified rate, however it tends to produce samples at even intervals.</p> -<b>For full details on using BeanShell, please see the <a href="http://www.beanshell.org/";>BeanShell website.</a></b> -</p> +<h4>Ramp-up and startup spike</h4> + +<p>You might used "ramp-up" or similar approaches to avoid a spike at the test start. For instance, if you configure <a href="../usermanual/component_reference.html#Thread_Group">Thread Group</a> to have + 100 threads, and set <span class="code">Ramp-up Period</span> to 0 (or to a small number), then all the threads would start at the same time, and it would produce an unwanted spike of the load. On top of that, if you set <span class="code">Ramp-up Period</span> too high, it might result in "too few" threads being available at the very beginning to achieve +the required load.</p> <p> -The test element supports the <span class="code">ThreadListener</span> and <span class="code">TestListener</span> methods. -These should be defined in the initialisation file. -See the file <span class="code">BeanShellListeners.bshrc</span> for example definitions. -</p> +<span class="code">Precise Throughput Timer</span> schedules executions in a random way, so it can be used to generate constant load, and it is recommended to set both + <span class="code">Ramp-up Period</span> and <span class="code">Delay</span> to <span class="code">0</span>.</p> -</div> -<div class="screenshot"> -<figure> -<a href="../images/screenshots/timers/beanshell_timer.png"><img src="../images/screenshots/timers/beanshell_timer.png" width="846" height="636" alt="Screenshot for Control-Panel of BeanShell Timer"></a> + +<h4>Multiple thread groups starting at the same time</h4> + +<p>A variation of <span class="code">Ramp-up</span> issue might appear when <a href="../usermanual/component_reference.html#Test_Plan">Test Plan</a> includes multiple <a href="../usermanual/component_reference.html#Thead_Group">Thead Group</a>s. To mitigate that issue + one typically adds "random" delay to each <a href="../usermanual/component_reference.html#Thead_Group">Thead Group</a> so threads start at different times.</p> + +<p> +<span class="code">Precise Throughput Timer</span> avoids that issue since it schedules executions in a random way. You do not need to add extra random delays to mitigate startup spike</p> + + +<h4>Number of iterations per hour</h4> + +<p>One of the basic requirements is to issue N samples per M minutes. Let it be 60 iterations per hour. Business customers would not understand if you report load test + results with 57 executions "just because the random was random". In order to generate 60 iterations per hour, you need to configure as follows (other parameters + could be left with their default values)</p> + +<ul> + +<li> +<span class="code">Target throughput (samples)</span>: 60</li> + +<li> +<span class="code">Throughput period (seconds)</span>: 3600</li> + +<li> +<span class="code">Test duration (seconds)</span>: 3600</li> + +</ul> + +<p>The first two options set the throughput. Even though 60/3600, 30/1800, and 120/7200 represent exactly the same load level, pick the one that represents + business requirements better. For instance, if the requirement is to test for "60 sample per hour", then set 60/3600. If the requirement is to test "1 sample per minute", + then set 1/60.</p> + +<p> +<span class="code">Test duration (seconds)</span> is there so the timer ensures exact number of samples for a given test duration. <span class="code">Precise Throughput Timer</span> creates + a schedule for the samples at the test startup. For instance, if you + wish to perform 5 minutes test with 60 per hour throughput, you would set <span class="code">Test duration (seconds)</span> to 300. This enables to configure throughput + in a business-friendly way. Note: <span class="code">Test duration (seconds)</span> does <b>not</b> limit test duration. It is just a hint for the timer.</p> + + +<h4>Number of threads and think times</h4> + +<p>One of the common pitfalls is to adjust number of threads and think times in order to end up with the desired throughput. Even though it might work, that approach + results in lots of time spent on the test runs. It might require to adjust threads and delays again when new application version arrives.</p> + +<p> +<span class="code">Precise Throughput Timer</span> enables to set throughput goal and go for it no matter how well application performs. In order to do that, <span class="code">Precise Throughput Timer</span> + creates a schedule at the test startup, then it uses that schedule to release threads. The main driver for the think times and number of threads should be business + requirements, not the desire to match troughput somehow.</p> + +<p>For instance, if you application is used by support engineers in a call center. Suppose there are 2 engineers in the call center, and the target throughput is 1 per minute. + Suppose it takes 4 minutes for the engineer to read and review the web page. For that case you should set 2 threads in the group, use 4 minutes + for think time delays, and specify 1 per minute in <span class="code">Precise Throughput Timer</span>. Of course it would result in something around 2samples/4minutes=0.5 per minute + and the result of such a test means "you need more support engineers in a call center" or "you need to reduce the time it takes an engineer to fulfill a task".</p> + + +<h4>Testing low rates and repeatable tests</h4> + +<p>Testing at low rates (e.g. 60 per hour) requires to know the desired test profile. For instance, if you need to inject load at even intervals (e.g. 60 seconds in between) + then you'd better use <a href="../usermanual/component_reference.html#Constant_Throughput_Timer">Constant Throughput Timer</a>. However, if you need to have randomized schedule (e.g. to model real users that execute reports), + then <span class="code">Precise Throughput Timer</span> is your friend.</p> + +<p>When comparing outcomes of multiple load tests, it is useful to be able to repeat exactly the same test profile. For instance, if action X (e.g. "Profit Report") + is invoked after 5 minutes of the test start, then it would be nice to replicate that pattern for subsequent test executions. Replicating the same load pattern + simplifies analysis of the test results (e.g. CPU% chart).</p> + +<p> +<span class="code">Random seed (change from 0 to random)</span> enables to control the seed value that is used by <span class="code">Precise Throughput Timer</span>. By default it is + initialized with <span class="code">0</span> and that means random seed is used for each test execution. If you need to have repeatable load pattern, then change + <span class="code">Random seed</span> so some random value. The general advice is to use non-zero seed, and "0 by default" is an implementation limit.</p> + +<p>Note: when using multiple thread groups with same throughput rates and same non-zero seed it might result in unwanted firing the samples at the same time.</p> + + +<h4>Testing high rates and/or long test durations</h4> + +<p>When the number of samples is high (e.g. it exceeds 10'000), schedule generation might take noticeable time (e.g. seconds) as <span class="code">Precise Throughput Timer</span> tries + to produce the exact number of samples. There's memory consumption as well, however it should not matter much as every item in the schedule consumes 8 bytes. + In order to reduce schedule generation overhead, <span class="code">Precise Throughput Timer</span> allows some slack when generating long schedules. It is controlled by + <span class="code">Accuracy of generated delays</span> properties. By default, inexact schedules are allowed when number of samples exceeds 10'000.</p> + +<p>If you want to perform 2-week long test with 5'000 per hour rate, you do not need to create a schedule for that 2 weeks. + You can set <span class="code">Test duration (seconds)</span> property of the timer to 1 hour. The timer would create a schedule of 5'000 samples for an hour, and when the schedule is exhausted, the timer would generate + a schedule for the next hour.</p> + + +<h4>Bursty load</h4> + +<p>There might be a case when all the samples should come in pairs, triples, etc. Certain cases might be solved via <a href="../usermanual/component_reference.html#Synchronizing_Timer">Synchronizing Timer</a>, however + <span class="code">Precise Throughput Timer</span> has native way to issue requests in packs. This behavior is disabled by default, and it is controlled with "Batched departures" + settings</p> + +<ul> + +<li> +<span class="code">Number of threads in the batch (threads)</span>. Specifies the number of samples in a batch. Note the overall number of samples will still be in line with <span class="code">Target Throughput</span> +</li> + +<li> +<span class="code">Delay between threads in the batch (ms)</span>. For instance, if set to 42, and the batch size is 3, then threads will depart at x, x+42ms, x+84ms</li> + +</ul> + + +<h4>Variable load rate</h4> + +<p>Even though property values (e.g. throughput) can be defined via expressions, it is recommended to keep the value more or less the same through the test, as it takes time to recompute the new schedule to adapt new values.</p> + + +<h4>Monitoring</h4> + +<p>As next schedule is generated, <span class="code">Precise Throughput Timer</span> logs a message to <span class="code">jmeter.log</span>: + <span class="code">2018-01-04 17:34:03,635 INFO o.a.j.t.ConstantPoissonProcessGenerator: Generated 21 timings (... 20 required, rate 1.0, duration 20, exact lim 20000, + i21) in 0 ms, restart was issued 3 times. First 15 events will be fired at: 1.1869653574244292 (+1.1869653574244292), 1.4691340403043207 (+0.2821686828798915), + 3.638151706179226 (+2.169017665874905), 3.836357090410566 (+0.19820538423134026), 4.709330071408575 (+0.8729729809980085), 5.61330076999953 (+0.903970698590955), + ...</span> +This shows that schedule generation took 0ms, and it shows absolute timestamps in seconds. In the case above, the rate was set to be 1 per second, and the actual timestamps + became 1.2 sec, 1.5 sec, 3.6 sec, 3.8 sec, 4.7 sec, and so on.</p> + +</div> +<div class="screenshot"> +<figure> +<a href="../images/screenshots/timers/precise_throughput_timer.png"><img src="../images/screenshots/timers/precise_throughput_timer.png" width="523" height="318" alt="Screenshot for Control-Panel of Precise Throughput Timer"></a> +<figcaption>Screenshot of Control-Panel of Precise Throughput Timer</figcaption> +</figure> +</div> +<div class="properties"> +<h3 id="Precise_Throughput_Timer_parms1"> + Parameters + <a class="sectionlink" href="#Precise_Throughput_Timer_parms1" title="Link to here">¶</a> +</h3> +<div class="property title"> +<div class="name title">Attribute</div> +<div class="description title">Description</div> +<div class="required title">Required</div> +</div> + +<div class="property"> +<div class="name req-false">Name</div> +<div class="description req-false">Descriptive name for this timer that is shown in the tree</div> +<div class="required req-false">No</div> +</div> + +<div class="property"> +<div class="name req-true">Target throughput (in samples per 'throughput period')</div> +<div class="description req-true">Maximum number of samples you want to obtain per "throughput period", including all threads in group, from all affected samplers.</div> +<div class="required req-true">Yes</div> +</div> + +<div class="property"> +<div class="name req-true">Throughput period (seconds)</div> +<div class="description req-true">Throughput period. For example, if "throughput" is set to 42 and "throughput period" to 21 sec, then you'll get 2 samples per second.</div> +<div class="required req-true">Yes</div> +</div> + +<div class="property"> +<div class="name req-true">Test duration (seconds)</div> +<div class="description req-true">This is used to ensure you'll get throughput*duration samples during "test duration" timeframe.</div> +<div class="required req-true">Yes</div> +</div> + +<div class="property"> +<div class="name req-true">Number of threads in the batch (threads)</div> +<div class="description req-true">If the value exceeds 1, then multiple threads depart from the timer simultaneously. Average throughput still meets "throughput" value.</div> +<div class="required req-true">Yes</div> +</div> + +<div class="property"> +<div class="name req-true">Delay between threads in the batch (ms)</div> +<div class="description req-true">For instance, if set to 42, and the batch size is 3, then threads will depart at x, x+42ms, x+84ms.</div> +<div class="required req-true">Yes</div> +</div> + +<div class="property"> +<div class="name req-true">Use approximate throughput when sequence length exceeds (samples)</div> +<div class="description req-true">When the required number of samples is less than this limit, timer will generate exact number of samples.</div> +<div class="required req-true">Yes</div> +</div> + +<div class="property"> +<div class="name req-true">Allowed throughput surplus (percents)</div> +<div class="description req-true">When more than "max exact samples" samples is required, timer might generate slightly more events than specified by throughput.</div> +<div class="required req-true">Yes</div> +</div> + +<div class="property"> +<div class="name req-true">Random seed (change from 0 to random)</div> +<div class="description req-true">Note: different timers should better have different seed values. Constant seed ensures timer generates the same delays each test start. The value of "0" means the timer is truly random (non-repeatable from one execution to another)..</div> +<div class="required req-true">Yes</div> +</div> + +</div> +<div class="go-top"> +<a href="#">^</a> +</div> +</div> + + +<div class="component"> +<h2 id="Synchronizing_Timer">Synchronizing Timer<a class="sectionlink" href="#Synchronizing_Timer" title="Link to here">¶</a> +</h2> +<div class="description"> + +<p> +The purpose of the SyncTimer is to block threads until X number of threads have been blocked, and +then they are all released at once. A SyncTimer can thus create large instant loads at various +points of the test plan. +</p> + +</div> +<div class="screenshot"> +<figure> +<a href="../images/screenshots/timers/sync_timer.png"><img src="../images/screenshots/timers/sync_timer.png" width="410" height="145" alt="Screenshot for Control-Panel of Synchronizing Timer"></a> +<figcaption>Screenshot of Control-Panel of Synchronizing Timer</figcaption> +</figure> +</div> +<div class="properties"> +<h3 id="Synchronizing_Timer_parms1"> + Parameters + <a class="sectionlink" href="#Synchronizing_Timer_parms1" title="Link to here">¶</a> +</h3> +<div class="property title"> +<div class="name title">Attribute</div> +<div class="description title">Description</div> +<div class="required title">Required</div> +</div> + +<div class="property"> +<div class="name req-false">Name</div> +<div class="description req-false">Descriptive name for this timer that is shown in the tree. </div> +<div class="required req-false">No</div> +</div> + +<div class="property"> +<div class="name req-true">Number of Simultaneous Users to Group by</div> +<div class="description req-true">Number of threads to release at once. Setting it to <span class="code">0</span> is equivalent to setting it to Number of threads in Thread Group.</div> +<div class="required req-true">Yes</div> +</div> + +<div class="property"> +<div class="name req-false">Timeout in milliseconds</div> +<div class="description req-false">If set to <span class="code">0</span>, Timer will wait for the number of threads to reach the value in "<span class="code">Number of Simultaneous Users to Group</span>". If superior to <span class="code">0</span>, then timer will wait at max "<span class="code">Timeout in milliseconds</span>" for the number of Threads. If after the timeout interval the number of users waiting is not reached, timer will stop waiting. Defaults to <span class="code">0</span> +</div> +<div class="required req-false">No</div> +</div> + +</div> +<div class="clear"></div> +<div class="note"> +If timeout in milliseconds is set to <span class="code">0</span> and number of threads never reaches "<span class="code">Number of Simultaneous Users to Group by</span>" then Test will pause infinitely. +Only a forced stop will stop it. Setting Timeout in milliseconds is an option to consider in this case. +</div> +<div class="clear"></div> +<div class="clear"></div> +<div class="note"> +Synchronizing timer blocks only within one JVM, so if using Distributed testing ensure you never set "<span class="code">Number of Simultaneous Users to Group by</span>" to a value superior to the number of users +of its containing Thread group considering 1 injector only. +</div> +<div class="clear"></div> +<div class="go-top"> +<a href="#">^</a> +</div> +</div> + + +<div class="component"> +<h2 id="BeanShell_Timer">BeanShell Timer<a class="sectionlink" href="#BeanShell_Timer" title="Link to here">¶</a> +</h2> +<div class="description"> + +<p> +The BeanShell Timer can be used to generate a delay. +</p> + +<p> + +<b>For full details on using BeanShell, please see the <a href="http://www.beanshell.org/";>BeanShell website.</a></b> + +</p> + +<p> +The test element supports the <span class="code">ThreadListener</span> and <span class="code">TestListener</span> methods. +These should be defined in the initialisation file. +See the file <span class="code">BeanShellListeners.bshrc</span> for example definitions. +</p> + +</div> +<div class="screenshot"> +<figure> +<a href="../images/screenshots/timers/beanshell_timer.png"><img src="../images/screenshots/timers/beanshell_timer.png" width="846" height="636" alt="Screenshot for Control-Panel of BeanShell Timer"></a> <figcaption>Screenshot of Control-Panel of BeanShell Timer</figcaption> </figure> </div> @@ -13516,6 +13929,9 @@ vars.putObject("OBJ1",new Object());</pr <p>This timer pauses each thread request for a random amount of time, with most of the time intervals occurring near a particular value. The total delay is the sum of the Poisson distributed value, and the offset value.</p> + +<p>Note: if you want to model Poisson arrivals, consider using <a href="../usermanual/component_reference.html#Precise_Throughput_Timer">Precise Throughput Timer</a> instead.</p> + </div> <div class="screenshot"> <figure> @@ -14495,7 +14911,7 @@ generate the template string, and store <span class="code">Main sample and sub-samples</span> - applies to both.</li> <li> -<span class="code">JMeter Variable</span> - assertion is to be applied to the contents of the named variable</li> +<span class="code">JMeter Variable Name to use</span> - extraction is to be applied to the contents of the named variable</li> </ul> Matching is applied to all qualifying samples in turn. @@ -14561,7 +14977,7 @@ generate the template string, and store </div> <div class="property"> -<div class="name req-true">Reference Name</div> +<div class="name req-true">Name of created variable</div> <div class="description req-true">The name of the JMeter variable in which to store the result. Also note that each group is stored as <span class="code">[refname]_g#</span>, where <span class="code">[refname]</span> is the string you entered as the reference name, and <span class="code">#</span> is the group number, where group <span class="code">0</span> is the entire match, group <span class="code">1</span> is the match from the first set of parentheses, etc.</div> <div class="required req-true">Yes</div> </div> @@ -14747,7 +15163,7 @@ extracting the node as text or attribute <span class="code">Main sample and sub-samples</span> - applies to both.</li> <li> -<span class="code">JMeter Variable</span> - assertion is to be applied to the contents of the named variable</li> +<span class="code">JMeter Variable Name to use</span> - extraction is to be applied to the contents of the named variable</li> </ul> Matching is applied to all qualifying samples in turn. @@ -14782,7 +15198,7 @@ extracting the node as text or attribute </div> <div class="property"> -<div class="name req-true">Reference Name</div> +<div class="name req-true">Name of created variable</div> <div class="description req-true">The name of the JMeter variable in which to store the result.</div> <div class="required req-true">Yes</div> </div> @@ -14978,7 +15394,7 @@ extracting the node as text or attribute <span class="code">Main sample and sub-samples</span> - applies to both.</li> <li> -<span class="code">JMeter Variable</span> - assertion is to be applied to the contents of the named variable</li> +<span class="code">JMeter Variable Name to use</span> - extraction is to be applied to the contents of the named variable</li> </ul> XPath matching is applied to all qualifying samples in turn, and all the matching results will be returned. @@ -14997,6 +15413,10 @@ extracting the node as text or attribute </ul> +<div class="clear"></div> +<div class="note">For HTML, CSS/JQuery Extractor is the correct and performing solution. Don't use XPath for HTML extractions.</div> +<div class="clear"></div> + </div> <div class="required req-true">Yes</div> </div> @@ -15024,14 +15444,7 @@ extracting the node as text or attribute <div class="description req-false"> If checked, then the XML parser will use namespace resolution.(see note below on NAMESPACES) Note that currently only namespaces declared on the root element will be recognised. - A later version of JMeter may support user-definition of additional workspace names. - Meanwhile, a work-round is to replace: - <pre class="source">//mynamespace:tagname</pre> - by - <pre class="source">//*[local-name()='tagname' and namespace-uri()='uri-for-namespace']</pre> - where "<span class="code">uri-for-namespace</span>" is the uri for the "<span class="code">mynamespace</span>" namespace. - (not applicable if Tidy is selected) - + See below for user-definition of additional workspace names. </div> <div class="required req-false">If Tidy is not selected</div> </div> @@ -15065,7 +15478,7 @@ extracting the node as text or attribute </div> <div class="property"> -<div class="name req-true">Reference Name</div> +<div class="name req-true">Name of created variable</div> <div class="description req-true">The name of the JMeter variable in which to store the result.</div> <div class="required req-true">Yes</div> </div> @@ -15185,6 +15598,10 @@ You reference this file in <span class=" </div> <div class="clear"></div> +<p></p> +<pre class="source">//mynamespace:tagname</pre> +<pre class="source">//*[local-name()='tagname' and namespace-uri()='uri-for-namespace']</pre> +<span class="code">uri-for-namespace</span><span class="code">mynamespace</span> <div class="go-top"> <a href="#">^</a> </div> @@ -15696,7 +16113,7 @@ It will allow you to extract in a very e </div> <div class="property"> -<div class="name req-true">Variable Names</div> +<div class="name req-true">Names of created variables</div> <div class="description req-true">Semi-colon separated names of variables that will contain the results of JSON-PATH expressions (must match number of JSON-PATH expressions)</div> <div class="required req-true">Yes</div> </div> @@ -15751,6 +16168,214 @@ It will allow you to extract in a very e </div> +<div class="component"> +<h2 id="Boundary_Extractor">Boundary Extractor<a class="sectionlink" href="#Boundary_Extractor" title="Link to here">¶</a> +</h2> +<div class="description"> +<p>Allows the user to extract values from a server response using left and right boundaries. As a post-processor, +this element will execute after each Sample request in its scope, testing the boundaries, extracting the requested values, +generate the template string, and store the result into the given variable name.</p> +</div> +<div class="screenshot"> +<figure> +<a href="../images/screenshots/boundary_extractor.png"><img src="../images/screenshots/boundary_extractor.png" width="1127" height="277" alt="Screenshot for Control-Panel of Boundary Extractor"></a> +<figcaption>Screenshot of Control-Panel of Boundary Extractor</figcaption> +</figure> +</div> +<div class="properties"> +<h3 id="Boundary_Extractor_parms1"> + Parameters + <a class="sectionlink" href="#Boundary_Extractor_parms1" title="Link to here">¶</a> +</h3> +<div class="property title"> +<div class="name title">Attribute</div> +<div class="description title">Description</div> +<div class="required title">Required</div> +</div> + +<div class="property"> +<div class="name req-true">Name</div> +<div class="description req-true">Descriptive name for this element that is shown in the tree.</div> +<div class="required req-true"></div> +</div> + +<div class="property"> +<div class="name req-true">Apply to:</div> +<div class="description req-true"> + This is for use with samplers that can generate sub-samples, + e.g. HTTP Sampler with embedded resources, Mail Reader or samples generated by the Transaction Controller. + <ul> + +<li> +<span class="code">Main sample only</span> - only applies to the main sample</li> + +<li> +<span class="code">Sub-samples only</span> - only applies to the sub-samples</li> + +<li> +<span class="code">Main sample and sub-samples</span> - applies to both.</li> + +<li> +<span class="code">JMeter Variable Name to use</span> - assertion is to be applied to the contents of the named variable</li> + +</ul> + Matching is applied to all qualifying samples in turn. + For example if there is a main sample and 3 sub-samples, each of which contains a single match test, + (i.e. 4 matches in total). + For match number = <span class="code">3</span>, Sub-samples only, the extractor will match the 3<sup>rd</sup> sub-sample. + For match number = <span class="code">3</span>, Main sample and sub-samples, the extractor will match the 2<sup>nd</sup> sub-sample (1<sup>st</sup> match is main sample). + For match number = <span class="code">0</span> or negative, all qualifying samples will be processed. + For match number > <span class="code">0</span>, matching will stop as soon as enough matches have been found. + </div> +<div class="required req-true">Yes</div> +</div> + +<div class="property"> +<div class="name req-true">Field to check</div> +<div class="description req-true"> + The following fields can be checked: + <ul> + +<li> +<span class="code">Body</span> - the body of the response, e.g. the content of a web-page (excluding headers)</li> + +<li> +<span class="code">Body (unescaped)</span> - the body of the response, with all Html escape codes replaced. + Note that Html escapes are processed without regard to context, so some incorrect substitutions + may be made. + <div class="clear"></div> +<div class="note">Note that this option highly impacts performances, so use it only when absolutely necessary and be aware of its impacts</div> +<div class="clear"></div> + +</li> + +<li> +<span class="code">Body as a Document</span> - the extract text from various type of documents via Apache Tika (see <a href="../usermanual/component_reference.html#View_Results_Tree">View Results Tree</a> Document view section). + <div class="clear"></div> +<div class="note">Note that the Body as a Document option can impact performances, so ensure it is OK for your test</div> +<div class="clear"></div> + +</li> + +<li> +<span class="code">Request Headers</span> - may not be present for non-HTTP samples</li> + +<li> +<span class="code">Response Headers</span> - may not be present for non-HTTP samples</li> + +<li> +<span class="code">URL</span> +</li> + +<li> +<span class="code">Response Code</span> - e.g. <span class="code">200</span> +</li> + +<li> +<span class="code">Response Message</span> - e.g. <span class="code">OK</span> +</li> + +</ul> + Headers can be useful for HTTP samples; it may not be present for other sample types. + </div> +<div class="required req-true">Yes</div> +</div> + +<div class="property"> +<div class="name req-true">Name of created variable</div> +<div class="description req-true">The name of the JMeter variable in which to store the result. Also note that each group is stored as <span class="code">[refname]_g#</span>, where <span class="code">[refname]</span> is the string you entered as the reference name, and <span class="code">#</span> is the group number, where group <span class="code">0</span> is the entire match, group <span class="code">1</span> is the match from the first set of parentheses, etc.</div> +<div class="required req-true">Yes</div> +</div> + +<div class="property"> +<div class="name req-true">Left Boundary</div> +<div class="description req-true">Left boundary of value to find</div> +<div class="required req-true">Yes</div> +</div> + +<div class="property"> +<div class="name req-true">Right Boundary</div> +<div class="description req-true">Left boundary of value to find</div> +<div class="required req-true">Yes</div> +</div> + +<div class="property"> +<div class="name req-true">Match No. (0 for Random)</div> +<div class="description req-true">Indicates which match to use. The boundaries may match multiple times. + <ul> + +<li>Use a value of zero to indicate JMeter should choose a match at random.</li> + +<li>A positive number N means to select the n<sup>th</sup> match.</li> + +<li> Negative numbers are used in conjunction with the <a href="../usermanual/component_reference.html#ForEach_Controller">ForEach Controller</a> - see below.</li> + +</ul> + +</div> +<div class="required req-true">Yes</div> +</div> + +<div class="property"> +<div class="name req-false">Default Value</div> +<div class="description req-false"> + If the boundaries do not match, then the reference variable will be set to the default value. + This is particularly useful for debugging tests. If no default is provided, then it is difficult to tell + whether the boundaries did not match, or maybe the wrong variable + is being used. + <p> + However, if you have several test elements that set the same variable, + you may wish to leave the variable unchanged if the expression does not match. + In this case, remove the default value once debugging is complete. + </p> + +</div> +<div class="required req-false">No, but recommended</div> +</div> + +</div> +<p> + If the match number is set to a non-negative number, and a match occurs, the variables are set as follows: +</p> +<ul> + +<li> +<span class="code">refName</span> - the value of the extraction</li> + +</ul> +<p> + If no match occurs, then the <span class="code">refName</span> variable is set to the default (unless this is absent). +</p> +<p> + If the match number is set to a negative number, then all the possible matches in the sampler data are processed. + The variables are set as follows: +</p> +<ul> + +<li> +<span class="code">refName_matchNr</span> - the number of matches found; could be <span class="code">0</span> +</li> + +<li> +<span class="code">refName_<em>n</em></span>, where <span class="code">n</span> = <span class="code">1</span>, <span class="code">2</span>, <span class="code">3</span> etc. - the strings as generated by the template</li> + +<li> +<span class="code">refName_<em>n</em>_g<em>m</em></span>, where <span class="code">m</span>=<span class="code">0</span>, <span class="code">1</span>, <span class="code">2</span> - the groups for match <span class="code">n</span> +</li> + +<li> +<span class="code">refName</span> - always set to the default value</li> + +</ul> +<p> + Note that the <span class="code">refName</span> variable is always set to the default value in this case, + and the associated group variables are not set. +</p> +<div class="go-top"> +<a href="#">^</a> +</div> +</div> + </div> <div class="section"> <h1 id="Miscellaneous_Features">18.9 Miscellaneous Features<a class="sectionlink" href="#Miscellaneous_Features" title="Link to here">¶</a> @@ -15936,7 +16561,7 @@ Behaviour can be modified with some prop <span class="code">Continue</span> - ignore the error and continue with the test</li> <li> -<span class="code">Start Next Loop</span> - ignore the error, start next loop and continue with the test</li> +<span class="code">Start Next Thread Loop</span> - ignore the error, start next loop and continue with the test</li> <li> <span class="code">Stop Thread</span> - current thread exits</li> @@ -15993,26 +16618,10 @@ Behaviour can be modified with some prop </div> <div class="property"> -<div class="name req-false">Start Time</div> -<div class="description req-false">If the scheduler checkbox is selected, one can choose an absolute start time. When you start your test, JMeter will wait until the specified start time to begin testing. - Note: the <span class="code">Startup Delay</span> field over-rides this - see below. - </div> -<div class="required req-false">No</div> -</div> - -<div class="property"> -<div class="name req-false">End Time</div> -<div class="description req-false">If the scheduler checkbox is selected, one can choose an absolute end time. When you start your test, JMeter will wait until the specified start time to begin testing, and it will stop at the specified end time. - Note: the <span class="code">Duration</span> field over-rides this - see below. - </div> -<div class="required req-false">No</div> -</div> - -<div class="property"> <div class="name req-false">Duration (seconds)</div> <div class="description req-false"> If the scheduler checkbox is selected, one can choose a relative end time. - JMeter will use this to calculate the End Time, and ignore the <span class="code">End Time</span> value. + JMeter will use this to calculate the End Time. </div> <div class="required req-false">No</div> </div> @@ -16021,7 +16630,7 @@ Behaviour can be modified with some prop <div class="name req-false">Startup delay (seconds)</div> <div class="description req-false"> If the scheduler checkbox is selected, one can choose a relative startup delay. - JMeter will use this to calculate the Start Time, and ignore the <span class="code">Start Time</span> value. + JMeter will use this to calculate the Start Time. </div> <div class="required req-false">No</div> </div> @@ -16036,57 +16645,6 @@ Behaviour can be modified with some prop <div class="component"> <h2 id="WorkBench">WorkBench<a class="sectionlink" href="#WorkBench" title="Link to here">¶</a> </h2> -<div class="description"> - -<p>The WorkBench simply provides a place to temporarily store test elements while not in use, for copy/paste purposes, or any other purpose you desire. -When you save your test plan, WorkBench items are not saved with it by default unless you check "<span class="code">Save Workbench</span>" option. -Your WorkBench can be saved independently, if you like (right-click on <span class="code">WorkBench</span> and choose <span class="code">Save</span>).</p> - -<p>Certain test elements are only available on the WorkBench:</p> - -<ul> - -<li> -<a href="../usermanual/component_reference.html#HTTP(S)_Test_Script_Recorder">HTTP(S) Test Script Recorder</a> -</li> - -<li> -<a href="../usermanual/component_reference.html#HTTP_Mirror_Server">HTTP Mirror Server</a> -</li> - -<li> -<a href="../usermanual/component_reference.html#Property_Display">Property Display</a> -</li> - -</ul> - -<div class="properties"> -<h3> - Parameters - </h3> -<div class="property title"> -<div class="name title">Attribute</div> -<div class="description title">Description</div> -<div class="required title">Required</div> -</div> - -<div class="property"> -<div class="name req-false">Save WorkBench</div> -<div class="description req-false"> - Allow to save the WorkBench's elements into the JMX file. - </div> -<div class="required req-false">No</div> -</div> - -</div> - -</div> -<div class="screenshot"> -<figure> -<a href="../images/screenshots/workbench.png"><img src="../images/screenshots/workbench.png" width="384" height="103" alt="Screenshot for Control-Panel of WorkBench"></a> -<figcaption>Screenshot of Control-Panel of WorkBench</figcaption> -</figure> -</div> <div class="go-top"> <a href="#">^</a> </div> @@ -16161,11 +16719,11 @@ Ensure you read this <a href="https://wi </p> -<p>To use the recorder, <i>add</i> the HTTP(S) Test Script Recorder element to the workbench. -Select the WorkBench element in the tree, and right-click on this element to get the -Add menu +<p>To use the recorder, <i>add</i> the HTTP(S) Test Script Recorder element. +Right-click on the Test Plan element to get the Add menu: (<span class="menuchoice"><span class="guimenuitem">Add</span> → <span class="guimenuitem">Non-Test Elements</span> → <span class="guimenuitem">HTTP(S) Test Script Recorder</span></span> -).</p> +). +</p> <p> The recorder is implemented as an HTTP(S) proxy server. @@ -16496,7 +17054,6 @@ Both Chrome and Internet Explorer use th <div class="required req-true">Yes</div> </div> - <div class="property"> <div class="name req-true">Capture HTTP Headers</div> <div class="description req-true">Should headers be added to the plan? @@ -16524,6 +17081,20 @@ Both Chrome and Internet Explorer use th </div> <div class="property"> +<div class="name req-false">Prefix/Transaction name</div> +<div class="description req-false">Add a prefix to sampler name during recording (Prefix mode). Or replace sampler name by user choosen name (Transaction name)</div> +<div class="required req-false">No</div> +</div> + +<div class="property"> +<div class="name req-true">Create new transaction after request (ms)</div> +<div class="description req-true">Inactivity time between two requests needed to consider them in two separate groups.</div> +<div class="required req-true"> + No + </div> +</div> + +<div class="property"> <div class="name req-true">Type</div> <div class="description req-true">Which type of sampler to generate (the HTTPClient default or Java)</div> <div class="required req-true">Yes</div> @@ -16977,7 +17548,6 @@ You can also use the following query par <p> The Property Display shows the values of System or JMeter properties. Values can be changed by entering new text in the Value column. -It is available only on the WorkBench. </p> </div> @@ -17281,7 +17851,7 @@ If Test Plan is stopped, tearDown will n <div class="copyright"> Copyright © 1999 – - 2017 + 2018 , Apache Software Foundation </div> <div class="trademarks">Apache, Apache JMeter, JMeter, the Apache
