| <?xml version="1.0"?> |
| <!-- |
| * Licensed to the Apache Software Foundation (ASF) under one or more |
| * contributor license agreements. See the NOTICE file distributed with |
| * this work for additional information regarding copyright ownership. |
| * The ASF licenses this file to You under the Apache License, Version 2.0 |
| * (the "License"); you may not use this file except in compliance with |
| * the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| * |
| --> |
| <!DOCTYPE document |
| [ |
| <!ENTITY sect-num '20'> |
| <!ENTITY hellip "…" > |
| <!ENTITY le "≤" > |
| <!ENTITY ge "≥" > |
| ]> |
| <document index="yes" index-level-2="yes" index-numbers="no" colbreak="§-num;.4" |
| prev="boss.html" next="properties_reference.html" id="$Id$"> |
| |
| <properties> |
| <title>User's Manual: Component Reference</title> |
| </properties> |
| |
| <body> |
| |
| <!-- |
| Because this is an XML document, all tags must be properly closed, including ones |
| which are passed unchanged into the HTML output, e.g. <br/>, not just <br>. |
| |
| Unfortunately Java does not currently allow for this - it outputs the trailing > - |
| which messes up the Help display. |
| To avoid these artifacts, use the form <br></br>, which Java does seem to handle OK. |
| |
| --> |
| <section name="§-num; Introduction" anchor="introduction"> |
| <description> |
| <p> |
| |
| </p> |
| <note> |
| Several test elements use JMeter properties to control their behaviour. |
| These properties are normally resolved when the class is loaded. |
| This generally occurs before the test plan starts, so it's not possible to change the settings by using the <code>__setProperty()</code> function. |
| </note> |
| <p> |
| </p> |
| </description> |
| </section> |
| |
| <section name="§-num;.1 Samplers" anchor="samplers"> |
| <description> |
| <p> |
| Samplers perform the actual work of JMeter. |
| Each sampler (except <complink name="Test Action" />) generates one or more sample results. |
| The sample results have various attributes (success/fail, elapsed time, data size etc.) and can be viewed in the various listeners. |
| </p> |
| </description> |
| <component name="FTP Request" index="§-num;.1.1" width="911" height="274" screenshot="ftptest/ftp-request.png"> |
| <description> |
| This controller lets you send an FTP "retrieve file" or "upload file" request to an FTP server. |
| If you are going to send multiple requests to the same FTP server, consider |
| using a <complink name="FTP Request Defaults"/> Configuration |
| Element so you do not have to enter the same information for each FTP Request Generative |
| Controller. When downloading a file, it can be stored on disk (Local File) or in the Response Data, or both. |
| <p> |
| Latency is set to the time it takes to login. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| <property name="Server Name or IP" required="Yes">Domain name or IP address of the FTP server.</property> |
| <property name="Port" required="No">Port to use. If this is <code>>0</code>, then this specific port is used, |
| otherwise JMeter uses the default FTP port.</property> |
| <property name="Remote File:" required="Yes">File to retrieve or name of destination file to upload.</property> |
| <property name="Local File:" required="Yes, if uploading (*)">File to upload, or destination for downloads (defaults to remote file name).</property> |
| <property name="Local File Contents:" required="Yes, if uploading (*)">Provides the contents for the upload, overrides the Local File property.</property> |
| <property name="get(RETR) / put(STOR)" required="Yes">Whether to retrieve or upload a file.</property> |
| <property name="Use Binary mode?" required="Yes">Check this to use Binary mode (default ASCII)</property> |
| <property name="Save File in Response?" required="Yes, if downloading"> |
| Whether to store contents of retrieved file in response data. |
| If the mode is ASCII, then the contents will be visible in the <complink name="View Results Tree"/>. |
| </property> |
| <property name="Username" required="Usually">FTP account username.</property> |
| <property name="Password" required="Usually">FTP account password. N.B. This will be visible in the test plan.</property> |
| </properties> |
| <links> |
| <link href="test_plan.html#assertions">Assertions</link> |
| <complink name="FTP Request Defaults"/> |
| <link href="build-ftp-test-plan.html">Building an FTP Test Plan</link> |
| </links> |
| |
| </component> |
| |
| <component name="HTTP Request" index="§-num;.1.2" width="953" height="611" screenshot="http-request.png"> |
| |
| <description> |
| <p>This sampler lets you send an HTTP/HTTPS request to a web server. It |
| also lets you control whether or not JMeter parses HTML files for images and |
| other embedded resources and sends HTTP requests to retrieve them. |
| The following types of embedded resource are retrieved:</p> |
| <ul> |
| <li>images</li> |
| <li>applets</li> |
| <li>stylesheets</li> |
| <li>external scripts</li> |
| <li>frames, iframes</li> |
| <li>background images (body, table, TD, TR)</li> |
| <li>background sound</li> |
| </ul> |
| <p> |
| The default parser is <code>org.apache.jmeter.protocol.http.parser.LagartoBasedHtmlParser</code>. |
| This can be changed by using the property "<code>htmlparser.className</code>" - see <code>jmeter.properties</code> for details. |
| </p> |
| <p>If you are going to send multiple requests to the same web server, consider |
| using an <complink name="HTTP Request Defaults"/> |
| Configuration Element so you do not have to enter the same information for each |
| HTTP Request.</p> |
| |
| <p>Or, instead of manually adding HTTP Requests, you may want to use |
| JMeter's <complink name="HTTP(S) Test Script Recorder"/> to create |
| them. This can save you time if you have a lot of HTTP requests or requests with many |
| parameters.</p> |
| |
| <p><b>There are two different test elements used to define the samplers:</b></p> |
| <dl> |
| <dt>AJP/1.3 Sampler</dt><dd>uses the Tomcat mod_jk protocol (allows testing of Tomcat in AJP mode without needing Apache httpd) |
| The AJP Sampler does not support multiple file upload; only the first file will be used. |
| </dd> |
| <dt>HTTP Request</dt><dd>this has an implementation drop-down box, which selects the HTTP protocol implementation to be used: |
| <dl> |
| <dt><code>Java</code></dt><dd>uses the HTTP implementation provided by the JVM. |
| This has some limitations in comparison with the HttpClient implementations - see below.</dd> |
| <dt><code>HTTPClient3.1</code></dt><dd>(DEPRECATED SINCE 3.0) uses Apache Commons HttpClient 3.1. |
| This is no longer being developed, and support for this will be dropped in a future JMeter release.</dd> |
| <dt><code>HTTPClient4</code></dt><dd>uses Apache HttpComponents HttpClient 4.x.</dd> |
| <dt>Blank Value</dt><dd>does not set implementation on HTTP Samplers, so relies on HTTP Request Defaults if present or on <code>jmeter.httpsampler</code> property defined in <code>jmeter.properties</code></dd> |
| </dl> |
| </dd> |
| </dl> |
| <p>The Java HTTP implementation has some limitations:</p> |
| <ul> |
| <li>There is no control over how connections are re-used. |
| When a connection is released by JMeter, it may or may not be re-used by the same thread.</li> |
| <li>The API is best suited to single-threaded usage - various settings |
| are defined via system properties, and therefore apply to all connections.</li> |
| <li>There is a bug in the handling of HTTPS via a Proxy (the <code>CONNECT</code> is not handled correctly). |
| See Java bugs 6226610 and 6208335. |
| </li> |
| <li>It does not support virtual hosts.</li> |
| <li>It supports only the following methods: <code>GET</code>, <code>POST</code>, <code>HEAD</code>, <code>OPTIONS</code>, <code>PUT</code>, <code>DELETE</code> and <code>TRACE</code></li> |
| <li>It does not support client based certificate testing with Keystore Config.</li> |
| </ul> |
| <note>Note: the <code>FILE</code> protocol is intended for testing purposes only. |
| It is handled by the same code regardless of which HTTP Sampler is used.</note> |
| <p>If the request requires server or proxy login authorization (i.e. where a browser would create a pop-up dialog box), |
| you will also have to add an <complink name="HTTP Authorization Manager"/> Configuration Element. |
| For normal logins (i.e. where the user enters login information in a form), you will need to work out what the form submit button does, |
| and create an HTTP request with the appropriate method (usually <code>POST</code>) |
| and the appropriate parameters from the form definition. |
| If the page uses HTTP, you can use the JMeter Proxy to capture the login sequence. |
| </p> |
| <p> |
| A separate SSL context is used for each thread. |
| If you want to use a single SSL context (not the standard behaviour of browsers), set the JMeter property:</p> |
| <source> |
| https.sessioncontext.shared=true |
| </source> |
| By default, the SSL context is retained for the duration of the test. |
| The SSL session can be optionally reset for each test iteration. |
| To enable this, set the JMeter property: |
| <source> |
| https.use.cached.ssl.context=false |
| </source> |
| <note> |
| Note: this does not apply to the Java HTTP implementation. |
| </note> |
| JMeter defaults to the SSL protocol level TLS. |
| If the server needs a different level, e.g. <code>SSLv3</code>, change the JMeter property, for example: |
| <source> |
| https.default.protocol=SSLv3 |
| </source> |
| <p> |
| JMeter also allows one to enable additional protocols, by changing the property <code>https.socket.protocols</code>. |
| </p> |
| <p>If the request uses cookies, then you will also need an |
| <complink name="HTTP Cookie Manager"/>. You can |
| add either of these elements to the Thread Group or the HTTP Request. If you have |
| more than one HTTP Request that needs authorizations or cookies, then add the |
| elements to the Thread Group. That way, all HTTP Request controllers will share the |
| same Authorization Manager and Cookie Manager elements.</p> |
| |
| <p>If the request uses a technique called "URL Rewriting" to maintain sessions, |
| then see section |
| <a href="build-adv-web-test-plan.html#session_url_rewriting">6.1 Handling User Sessions With URL Rewriting</a> |
| for additional configuration steps.</p> |
| </description> |
| <figure width="951" height="284" image="http-request-advanced-tab.png">HTTP Request Advanced config fields</figure> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| <property name="Server" required="Yes, unless provided by HTTP Request Defaults"> |
| Domain name or IP address of the web server, e.g. <code>www.example.com</code>. [Do not include the <code>http://</code> prefix.] |
| Note: If the "<code>Host</code>" header is defined in a Header Manager, then this will be used |
| as the virtual host name. |
| </property> |
| <property name="Port" required="No">Port the web server is listening to. Default: <code>80</code></property> |
| <property name="Connect Timeout" required="No">Connection Timeout. Number of milliseconds to wait for a connection to open.</property> |
| <property name="Response Timeout" required="No">Response Timeout. Number of milliseconds to wait for a response. |
| Note that this applies to each wait for a response. If the server response is sent in several chunks, the overall |
| elapsed time may be longer than the timeout. |
| <p>A <complink name="Duration Assertion"/> can be used to detect responses that take too long to complete.</p> |
| </property> |
| <property name="Server (proxy)" required="No">Hostname or IP address of a proxy server to perform request. [Do not include the <code>http://</code> prefix.]</property> |
| <property name="Port" required="No, unless proxy hostname is specified">Port the proxy server is listening to.</property> |
| <property name="Username" required="No">(Optional) username for proxy server.</property> |
| <property name="Password" required="No">(Optional) password for proxy server. (N.B. this is stored unencrypted in the test plan)</property> |
| <property name="Implementation" required="No"><code>Java</code>, <code>HttpClient3.1 (DEPRECATED SINCE 3.0)</code>, <code>HttpClient4</code>. |
| If not specified (and not defined by HTTP Request Defaults), the default depends on the value of the JMeter property |
| <code>jmeter.httpsampler</code>, failing that, the HttpClient4 implementation is used.</property> |
| <property name="Protocol" required="No"><code>HTTP</code>, <code>HTTPS</code> or <code>FILE</code>. Default: <code>HTTP</code></property> |
| <property name="Method" required="Yes"><code>GET</code>, <code>POST</code>, <code>HEAD</code>, <code>TRACE</code>, |
| <code>OPTIONS</code>, <code>PUT</code>, <code>DELETE</code>, <code>PATCH</code> (not supported for |
| <code>JAVA</code> implementation). With <code>HttpClient4</code>, the following methods related to WebDav are |
| also allowed: <code>COPY</code>, <code>LOCK</code>, <code>MKCOL</code>, <code>MOVE</code>, |
| <code>PROPFIND</code>, <code>PROPPATCH</code>, <code>UNLOCK</code>, <code>REPORT</code>, <code>MKCALENDAR</code>, |
| <code>SEARCH</code>. |
| <p>More methods can be pre-defined for the HttpClient4 by using the JMeter property |
| <code>httpsampler.user_defined_methods</code>.</p> |
| </property> |
| <property name="Content Encoding" required="No"> |
| Content encoding to be used (for <code>POST</code>, <code>PUT</code>, <code>PATCH</code> and <code>FILE</code>). |
| This is the character encoding to be used, and is not related to the Content-Encoding HTTP header. |
| </property> |
| <property name="Redirect Automatically" required="No"> |
| Sets the underlying http protocol handler to automatically follow redirects, |
| so they are not seen by JMeter, and thus will not appear as samples. |
| Should only be used for <code>GET</code> and <code>HEAD</code> requests. |
| The HttpClient sampler will reject attempts to use it for <code>POST</code> or <code>PUT</code>. |
| <note>Warning: see below for information on cookie and header handling.</note> |
| </property> |
| <property name="Follow Redirects" required="No"> |
| This only has any effect if "<code>Redirect Automatically</code>" is not enabled. |
| If set, the JMeter sampler will check if the response is a redirect and follow it if so. |
| The initial redirect and further responses will appear as additional samples. |
| The URL and data fields of the parent sample will be taken from the final (non-redirected) |
| sample, but the parent byte count and elapsed time include all samples. |
| The latency is taken from the initial response. |
| Note that the HttpClient sampler may log the following message: |
| <source>"Redirect requested but followRedirects is disabled"</source> |
| This can be ignored. |
| <br/> |
| JMeter will collapse paths of the form '<code>/../segment</code>' in |
| both absolute and relative redirect URLs. For example <code>http://host/one/../two</code> will be collapsed into <code>http://host/two</code>. |
| If necessary, this behaviour can be suppressed by setting the JMeter property |
| <code>httpsampler.redirect.removeslashdotdot=false</code> |
| </property> |
| <property name="Use KeepAlive" required="No">JMeter sets the Connection: <code>keep-alive</code> header. This does not work properly with the default HTTP implementation, as connection re-use is not under user-control. |
| It does work with the Apache HttpComponents HttpClient implementations.</property> |
| <property name="Use multipart/form-data for HTTP POST" required="No"> |
| Use a <code>multipart/form-data</code> or <code>application/x-www-form-urlencoded</code> post request |
| </property> |
| <property name="Browser-compatible headers" required="No"> |
| When using <code>multipart/form-data</code>, this suppresses the <code>Content-Type</code> and |
| <code>Content-Transfer-Encoding</code> headers; only the <code>Content-Disposition</code> header is sent. |
| </property> |
| <property name="Path" required="Yes">The path to resource (for example, <code>/servlets/myServlet</code>). If the |
| resource requires query string parameters, add them below in the |
| "Send Parameters With the Request" section. |
| <note> |
| As a special case, if the path starts with "<code>http://</code>" or "<code>https://</code>" then this is used as the full URL. |
| </note> |
| In this case, the server, port and protocol fields are ignored; parameters are also ignored for <code>GET</code> and <code>DELETE</code> methods. |
| Also please note that the path is not encoded - apart from replacing spaces with <code>%20</code> - |
| so unsafe characters may need to be encoded to avoid errors such as <code>URISyntaxException</code>. |
| </property> |
| <property name="Send Parameters With the Request" required="No">The query string will |
| be generated from the list of parameters you provide. Each parameter has a <code>name</code> and |
| <code>value</code>, the options to encode the parameter, and an option to include or exclude an equals sign (some applications |
| don't expect an equals sign when the value is the empty string). The query string will be generated in the correct fashion, depending on |
| the choice of "Method" you made (i.e. if you chose <code>GET</code> or <code>DELETE</code>, the query string will be |
| appended to the URL, if <code>POST</code> or <code>PUT</code>, then it will be sent separately). Also, if you are |
| sending a file using a multipart form, the query string will be created using the |
| multipart form specifications. |
| <b>See below for some further information on parameter handling.</b> |
| <p> |
| Additionally, you can specify whether each parameter should be URL encoded. If you are not sure what this |
| means, it is probably best to select it. If your values contain characters such as the following then encoding is usually required.: |
| </p> |
| <ul> |
| <li>ASCII Control Chars</li> |
| <li>Non-ASCII characters</li> |
| <li>Reserved characters:URLs use some characters for special use in defining their syntax. When these characters are not used in their special role inside a URL, they need to be encoded, example : '<code>$</code>', '<code>&</code>', '<code>+</code>', '<code>,</code>' , '<code>/</code>', '<code>:</code>', '<code>;</code>', '<code>=</code>', '<code>?</code>', '<code>@</code>'</li> |
| <li>Unsafe characters: Some characters present the possibility of being misunderstood within URLs for various reasons. These characters should also always be encoded, example : '<code> </code>', '<code><</code>', '<code>></code>', '<code>#</code>', '<code>%</code>', …</li> |
| </ul> |
| </property> |
| <property name="File Path:" required="No">Name of the file to send. If left blank, JMeter |
| does not send a file, if filled in, JMeter automatically sends the request as |
| a multipart form request. |
| <p> |
| If it is a <code>POST</code> or <code>PUT</code> or <code>PATCH</code> request and there is a single file whose 'Parameter name' attribute (below) is omitted, |
| then the file is sent as the entire body |
| of the request, i.e. no wrappers are added. This allows arbitrary bodies to be sent. This functionality is present for <code>POST</code> requests, |
| and also for <code>PUT</code> requests. |
| <b>See below for some further information on parameter handling.</b> |
| </p> |
| </property> |
| <property name="Parameter name:" required="No">Value of the "<code>name</code>" web request parameter.</property> |
| <property name="MIME Type" required="No">MIME type (for example, <code>text/plain</code>). |
| If it is a <code>POST</code> or <code>PUT</code> or <code>PATCH</code> request and either the '<code>name</code>' attribute (below) are omitted or the request body is |
| constructed from parameter values only, then the value of this field is used as the value of the |
| <code>content-type</code> request header. |
| </property> |
| <property name="Retrieve All Embedded Resources from HTML Files" required="No">Tell JMeter to parse the HTML file |
| and send HTTP/HTTPS requests for all images, Java applets, JavaScript files, CSSs, etc. referenced in the file. |
| See below for more details. |
| </property> |
| <property name="Use as monitor" required="No">For use with the <complink name="Monitor Results"/> listener.</property> |
| <property name="Save response as MD5 hash?" required="No"> |
| If this is selected, then the response is not stored in the sample result. |
| Instead, the 32 character MD5 hash of the data is calculated and stored instead. |
| This is intended for testing large amounts of data. |
| </property> |
| <property name="Embedded URLs must match:" required="No"> |
| If present, this must be a regular expression that is used to match against any embedded URLs found. |
| So if you only want to download embedded resources from <code>http://example.com/</code>, use the expression: |
| <code>http://example\.com/.*</code> |
| </property> |
| <property name="Use concurrent pool" required="No">Use a pool of concurrent connections to get embedded resources.</property> |
| <property name="Size" required="No">Pool size for concurrent connections used to get embedded resources.</property> |
| <property name="Source address type" required="No"> |
| <i>[Only for HTTP Request with HTTPClient implementation]</i> <br></br> |
| To distinguish the source address value, select the type of these: |
| <ul> |
| <li>Select <i>IP/Hostname</i> to use a specific IP address or a (local) hostname</li> |
| <li>Select <i>Device</i> to pick the first available address for that interface which |
| this may be either IPv4 or IPv6</li> |
| <li>Select <i>Device IPv4</i> to select the IPv4 address of the device name (like <code>eth0</code>, <code>lo</code>, <code>em0</code>, etc.)</li> |
| <li>Select <i>Device IPv6</i> to select the IPv6 address of the device name (like <code>eth0</code>, <code>lo</code>, <code>em0</code>, etc.)</li> |
| </ul> |
| </property> |
| <property name="Source address field" required="No"> |
| <i>[Only for HTTP Request with HTTPClient implementation]</i> <br></br> |
| This property is used to enable IP Spoofing. |
| It overrides the default local IP address for this sample. |
| The JMeter host must have multiple IP addresses (i.e. IP aliases, network interfaces, devices). |
| The value can be a host name, IP address, or a network interface device such as "<code>eth0</code>" or "<code>lo</code>" or "<code>wlan0</code>".<br></br> |
| If the property <code>httpclient.localaddress</code> is defined, that is used for all HttpClient requests. |
| </property> |
| </properties> |
| <note> |
| When using Automatic Redirection, cookies are only sent for the initial URL. |
| This can cause unexpected behaviour for web-sites that redirect to a local server. |
| E.g. if <code>www.example.com</code> redirects to <code>www.example.co.uk</code>. |
| In this case the server will probably return cookies for both URLs, but JMeter will only see the cookies for the last |
| host, i.e. <code>www.example.co.uk</code>. If the next request in the test plan uses <code>www.example.com</code>, |
| rather than <code>www.example.co.uk</code>, it will not get the correct cookies. |
| Likewise, Headers are sent for the initial request, and won't be sent for the redirect. |
| This is generally only a problem for manually created test plans, |
| as a test plan created using a recorder would continue from the redirected URL. |
| </note> |
| <p> |
| <b>Parameter Handling:</b><br></br> |
| For the <code>POST</code> and <code>PUT</code> method, if there is no file to send, and the name(s) of the parameter(s) are omitted, |
| then the body is created by concatenating all the value(s) of the parameters. |
| Note that the values are concatenated without adding any end-of-line characters. |
| These can be added by using the <code>__char()</code> function in the value fields. |
| This allows arbitrary bodies to be sent. |
| The values are encoded if the encoding flag is set. |
| See also the MIME Type above how you can control the <code>content-type</code> request header that is sent. |
| <br></br> |
| For other methods, if the name of the parameter is missing, |
| then the parameter is ignored. This allows the use of optional parameters defined by variables. |
| </p> |
| <br/> |
| <p>You have the option to switch to Post Body when a request has only unnamed parameters |
| (or no parameters at all). |
| This option is useful in the following cases (amongst others):</p> |
| <ul> |
| <li>GWT RPC HTTP Request</li> |
| <li>JSON REST HTTP Request</li> |
| <li>XML REST HTTP Request</li> |
| <li>SOAP HTTP Request</li> |
| </ul> |
| <note> |
| Note that once you leave the Tree node, you cannot switch back to the parameter tab unless you clear the Post Body tab of data. |
| </note> |
| <p> |
| In Post Body mode, each line will be sent with <code>CRLF</code> appended, apart from the last line. |
| To send a <code>CRLF</code> after the last line of data, just ensure that there is an empty line following it. |
| (This cannot be seen, except by noting whether the cursor can be placed on the subsequent line.) |
| </p> |
| <figure width="902" height="421" image="http-request-raw-single-parameter.png">Figure 1 - HTTP Request with one unnamed parameter</figure> |
| <figure width="908" height="212" image="http-request-confirm-raw-body.png">Figure 2 - Confirm dialog to switch</figure> |
| <figure width="905" height="423" image="http-request-raw-body.png">Figure 3 - HTTP Request using Body Data</figure> |
| |
| <p> |
| <b>Method Handling:</b><br></br> |
| The <code>POST</code>, <code>PUT</code> and <code>PATCH</code> request methods work similarly, except that the <code>PUT</code> and <code>PATCH</code> methods do not support multipart requests |
| or file upload. |
| The <code>PUT</code> and <code>PATCH</code> method body must be provided as one of the following:</p> |
| <ul> |
| <li>define the body as a file with empty Parameter name field; in which case the MIME Type is used as the Content-Type</li> |
| <li>define the body as parameter value(s) with no name</li> |
| <li>use the Post Body tab</li> |
| </ul> |
| <p> |
| If you define any parameters with a name in either the sampler or HTTP |
| defaults then nothing is sent. |
| <code>PUT</code> and <code>PATCH</code> require a Content-Type. |
| If not using a file, attach a Header Manager to the sampler and define the Content-Type there. |
| The <code>GET</code> and <code>DELETE</code> request methods work similarly to each other. |
| </p> |
| <p>JMeter scan responses from embedded resources. It uses the property <code>HTTPResponse.parsers</code>, which is a list of parser ids, |
| e.g. <code>htmlParser</code> and <code>wmlParser</code>. For each id found, JMeter checks two further properties:</p> |
| <ul> |
| <li><code>id.types</code> - a list of content types</li> |
| <li><code>id.className</code> - the parser to be used to extract the embedded resources</li> |
| </ul> |
| <p>See <code>jmeter.properties</code> file for the details of the settings. |
| If the <code>HTTPResponse.parser</code> property is not set, JMeter reverts to the previous behaviour, |
| i.e. only <code>text/html</code> responses will be scanned</p> |
| <b>Emulating slow connections:</b><br></br> |
| <code>HttpClient31</code>, <code>HttpClient4</code> and <code>Java</code> Sampler support emulation of slow connections; see the following entries in <code>jmeter.properties</code>: |
| <source> |
| # Define characters per second > 0 to emulate slow connections |
| #httpclient.socket.http.cps=0 |
| #httpclient.socket.https.cps=0 |
| </source> |
| <p><b>Response size calculation</b><br></br> |
| Optional properties to allow change the method to get response size:<br></br></p> |
| <ul><li>Gets the real network size in bytes for the body response |
| <source>sampleresult.getbytes.body_real_size=true</source></li> |
| <li>Add HTTP headers to full response size |
| <source>sampleresult.getbytes.headers_size=true</source></li></ul> |
| |
| <note> |
| The <code>Java</code> and <code>HttpClient3</code> implementations do not include transport overhead such as |
| chunk headers in the response body size.<br></br> |
| The <code>HttpClient4</code> implementation does include the overhead in the response body size, |
| so the value may be greater than the number of bytes in the response content. |
| </note> |
| |
| <note>When those two properties are set <code>false</code>, JMeter returns only data response size (uncompressed if request uses gzip/deflate mode).</note> |
| <p> |
| <b>Retry handling</b><br></br> |
| For HttpClient4 and Commons HttpClient 3.1 samplers, the retry count has been set to <code>0</code>, 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> |
| <source> |
| httpclient4.retrycount=3 |
| httpclient3.retrycount=3 |
| </source> |
| <p> |
| <b>Note: Certificates does not conform to algorithm constraints</b><br></br> |
| You may encounter the following error: <code>java.security.cert.CertificateException: Certificates does not conform to algorithm constraints</code> |
| if you run a HTTPS request on a web site with a SSL certificate (itself or one of SSL certificates in its chain of trust) with a signature |
| algorithm using MD2 (like <code>md2WithRSAEncryption</code>) or with a SSL certificate with a size lower than 1024 bits. |
| </p><p> |
| This error is related to increased security in Java 7 version u16 (MD2) and version u40 (Certificate size lower than 1024 bits), and Java 8 too. |
| </p><p> |
| To allow you to perform your HTTPS request, you can downgrade the security of your Java installation by editing |
| the Java <code>jdk.certpath.disabledAlgorithms</code> property. Remove the MD2 value or the constraint on size, depending on your case. |
| </p><p> |
| This property is in this file:</p> |
| <source>JAVA_HOME/jre/lib/security/java.security</source> |
| <p>See <bugzilla>56357</bugzilla> for details. |
| </p> |
| <links> |
| <link href="test_plan.html#assertions">Assertion</link> |
| <link href="build-web-test-plan.html">Building a Web Test Plan</link> |
| <link href="build-adv-web-test-plan.html">Building an Advanced Web Test Plan</link> |
| <complink name="HTTP Authorization Manager"/> |
| <complink name="HTTP Cookie Manager"/> |
| <complink name="HTTP Header Manager"/> |
| <complink name="HTML Link Parser"/> |
| <complink name="HTTP(S) Test Script Recorder"/> |
| <complink name="HTTP Request Defaults"/> |
| <link href="build-adv-web-test-plan.html#session_url_rewriting">HTTP Requests and Session ID's: URL Rewriting</link> |
| </links> |
| |
| </component> |
| |
| <component name="JDBC Request" index="§-num;.1.3" width="710" height="629" screenshot="jdbctest/jdbc-request.png"> |
| |
| <description><p>This sampler lets you send a JDBC Request (an SQL query) to a database.</p> |
| <p>Before using this you need to set up a |
| <complink name="JDBC Connection Configuration"/> Configuration element |
| </p> |
| <p> |
| If the Variable Names list is provided, then for each row returned by a Select statement, the variables are set up |
| with the value of the corresponding column (if a variable name is provided), and the count of rows is also set up. |
| For example, if the Select statement returns 2 rows of 3 columns, and the variable list is <code>A,,C</code>, |
| then the following variables will be set up:</p> |
| <source> |
| A_#=2 (number of rows) |
| A_1=column 1, row 1 |
| A_2=column 1, row 2 |
| C_#=2 (number of rows) |
| C_1=column 3, row 1 |
| C_2=column 3, row 2 |
| </source> |
| <p> |
| If the Select statement returns zero rows, then the <code>A_#</code> and <code>C_#</code> variables would be set to <code>0</code>, and no other variables would be set. |
| </p> |
| <p> |
| Old variables are cleared if necessary - e.g. if the first select retrieves six rows and a second select returns only three rows, |
| the additional variables for rows four, five and six will be removed. |
| </p> |
| <note>The latency time is set from the time it took to acquire a connection.</note> |
| </description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| <property name="Variable Name" required="Yes"> |
| Name of the JMeter variable that the connection pool is bound to. |
| This must agree with the '<code>Variable Name</code>' field of a <complink name="JDBC Connection Configuration"/>. |
| </property> |
| <property name="Query Type" required="Yes">Set this according to the statement type: |
| <ul> |
| <li>Select Statement</li> |
| <li>Update Statement - use this for Inserts and Deletes as well</li> |
| <li>Callable Statement</li> |
| <li>Prepared Select Statement</li> |
| <li>Prepared Update Statement - use this for Inserts and Deletes as well</li> |
| <li>Commit</li> |
| <li>Rollback</li> |
| <li>Autocommit(false)</li> |
| <li>Autocommit(true)</li> |
| <li>Edit - this should be a variable reference that evaluates to one of the above</li> |
| </ul> |
| <note> |
| When "<code>Prepared Select Statement</code>", "<code>Prepared Update Statement</code>" or "<code>Callable Statement</code>" types are selected, a Statement Cache per connection is used by JDBC Request. |
| It stores by default up to 100 PreparedStatements per connection, this can impact your database (Open Cursors). |
| </note> |
| </property> |
| <property name="SQL Query" required="Yes"> |
| SQL query. |
| <note>Do not enter a trailing semi-colon.</note> |
| There is generally no need to use <code>{</code> and <code>}</code> to enclose Callable statements; |
| however they may be used if the database uses a non-standard syntax. |
| [The JDBC driver automatically converts the statement if necessary when it is enclosed in <code>{}</code>]. |
| For example: |
| <ul> |
| <li><code>select * from t_customers where id=23</code></li> |
| <li><code>CALL SYSCS_UTIL.SYSCS_EXPORT_TABLE (null,?, ?, null, null, null)</code> |
| <ul> |
| <li>Parameter values: <code>tablename</code>,<code>filename</code></li> |
| <li>Parameter types: <code>VARCHAR</code>,<code>VARCHAR</code></li> |
| </ul> |
| </li> |
| The second example assumes you are using Apache Derby. |
| </ul> |
| </property> |
| <property name="Parameter values" required="Yes, if a prepared or callable statement has parameters"> |
| Comma-separated list of parameter values. Use <code>]NULL[</code> to indicate a <code>NULL</code> parameter. |
| (If required, the null string can be changed by defining the property "<code>jdbcsampler.nullmarker</code>".) |
| <br></br> |
| The list must be enclosed in double-quotes if any of the values contain a comma or double-quote, |
| and any embedded double-quotes must be doubled-up, for example: |
| <source>"Dbl-Quote: "" and Comma: ,"</source> |
| <note>There must be as many values as there are placeholders in the statement even if your parameters are <code>OUT</code> ones, be sure to set a value even if the value will not be used (for example in a CallableStatement).</note> |
| </property> |
| <property name="Parameter types" required="Yes, if a prepared or callable statement has parameters"> |
| Comma-separated list of SQL parameter types (e.g. <code>INTEGER</code>, <code>DATE</code>, <code>VARCHAR</code>, <code>DOUBLE</code>) or integer values of Constants when for example you use custom database types proposed by driver (<code>-10</code> for <code>OracleTypes.CURSOR</code> for example).<br/> |
| These are defined as fields in the class <code>java.sql.Types</code>, see for example:<br/> |
| <a href="http://docs.oracle.com/javase/7/docs/api/java/sql/Types.html">Javadoc for java.sql.Types</a>.<br/> |
| [Note: JMeter will use whatever types are defined by the runtime JVM, |
| so if you are running on a different JVM, be sure to check the appropriate document]<br/> |
| <b>If the callable statement has <code>INOUT</code> or <code>OUT</code> parameters, then these must be indicated by prefixing the |
| appropriate parameter types, e.g. instead of "<code>INTEGER</code>", use "<code>INOUT INTEGER</code>".</b> <br/> |
| If not specified, "<code>IN</code>" is assumed, i.e. "<code>DATE</code>" is the same as "<code>IN DATE</code>". |
| <br></br> |
| If the type is not one of the fields found in <code>java.sql.Types</code>, JMeter also |
| accepts the corresponding integer number, e.g. since <code>OracleTypes.CURSOR == -10</code>, you can use "<code>INOUT -10</code>". |
| <br></br> |
| There must be as many types as there are placeholders in the statement. |
| </property> |
| <property name="Variable Names" required="No">Comma-separated list of variable names to hold values returned by Select statements, Prepared Select Statements or CallableStatement. |
| Note that when used with CallableStatement, list of variables must be in the same sequence as the <code>OUT</code> parameters returned by the call. |
| If there are less variable names than <code>OUT</code> parameters only as many results shall be stored in the thread-context variables as variable names were supplied. |
| If more variable names than <code>OUT</code> parameters exist, the additional variables will be ignored</property> |
| <property name="Result Variable Name" required="No"> |
| If specified, this will create an Object variable containing a list of row maps. |
| Each map contains the column name as the key and the column data as the value. Usage:<br></br> |
| <source>columnValue = vars.getObject("resultObject").get(0).get("Column Name");</source> |
| </property> |
| <property name="Handle ResultSet" required="No">Defines how ResultSet returned from callable statements be handled: |
| <ul> |
| <li>Store As String (default) - All variables on Variable Names list are stored as strings, will not iterate through a <code>ResultSet</code> when present on the list.</li> |
| <li>Store As Object - Variables of <code>ResultSet</code> type on Variables Names list will be stored as Object and can be accessed in subsequent tests/scripts and iterated, will not iterate through the <code>ResultSet</code> </li> |
| <li>Count Records - Variables of <code>ResultSet</code> types will be iterated through showing the count of records as result. Variables will be stored as Strings.</li> |
| </ul> |
| </property> |
| </properties> |
| |
| <links> |
| <link href="build-db-test-plan.html">Building a Database Test Plan</link> |
| <complink name="JDBC Connection Configuration"/> |
| </links> |
| <note>Versions of JMeter use UTF-8 as the character encoding. Previously the platform default was used.</note> |
| <note>Ensure Variable Name is unique across Test Plan.</note> |
| </component> |
| |
| <component name="Java Request" index="§-num;.1.4" width="628" height="365" screenshot="java_request.png"> |
| |
| <description><p>This sampler lets you control a java class that implements the |
| <code>org.apache.jmeter.protocol.java.sampler.JavaSamplerClient</code> interface. |
| By writing your own implementation of this interface, |
| you can use JMeter to harness multiple threads, input parameter control, and |
| data collection.</p> |
| <p>The pull-down menu provides the list of all such implementations found by |
| JMeter in its classpath. The parameters can then be specified in the |
| table below - as defined by your implementation. Two simple examples (<code>JavaTest</code> and <code>SleepTest</code>) are provided. |
| </p> |
| <p> |
| The <code>JavaTest</code> example sampler can be useful for checking test plans, because it allows one to set |
| values in almost all the fields. These can then be used by Assertions, etc. |
| The fields allow variables to be used, so the values of these can readily be seen. |
| </p> |
| </description> |
| |
| <note>If the method <code>teardownTest</code> is not overridden by a subclass of <code><a href="../api/org/apache/jmeter/protocol/java/sampler/AbstractJavaSamplerClient.html">AbstractJavaSamplerClient</a></code>, its <code>teardownTest</code> method will not be called. |
| This reduces JMeter memory requirements. |
| This will not have any impact on existing Test plans. |
| </note> |
| <note>The Add/Delete buttons don't serve any purpose at present.</note> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler |
| that is shown in the tree.</property> |
| <property name="Classname" required="Yes">The specific implementation of |
| the JavaSamplerClient interface to be sampled.</property> |
| <property name="Send Parameters with Request" required="No">A list of |
| arguments that will be passed to the sampled class. All arguments |
| are sent as Strings. See below for specific settings.</property> |
| </properties> |
| |
| <p>The following parameters apply to the <code>SleepTest</code> and <code>JavaTest</code> implementations:</p> |
| |
| <properties> |
| <property name="Sleep_time" required="Yes">How long to sleep for (ms)</property> |
| <property name="Sleep_mask" required="Yes">How much "randomness" to add:<br></br> |
| The sleep time is calculated as follows: |
| <source>totalSleepTime = SleepTime + (System.currentTimeMillis() % SleepMask)</source> |
| </property> |
| </properties> |
| |
| <p>The following parameters apply additionally to the <code>JavaTest</code> implementation:</p> |
| |
| <properties> |
| <property name="Label" required="No">The label to use. If provided, overrides <code>Name</code></property> |
| <property name="ResponseCode" required="No">If provided, sets the SampleResult ResponseCode.</property> |
| <property name="ResponseMessage" required="No">If provided, sets the SampleResult ResponseMessage.</property> |
| <property name="Status" required="No">If provided, sets the SampleResult Status. If this equals "<code>OK</code>" (ignoring case) then the status is set to success, otherwise the sample is marked as failed.</property> |
| <property name="SamplerData" required="No">If provided, sets the SampleResult SamplerData.</property> |
| <property name="ResultData" required="No">If provided, sets the SampleResult ResultData.</property> |
| </properties> |
| </component> |
| |
| <component name="SOAP/XML-RPC Request" index="§-num;.1.5" width="426" height="276" screenshot="soap_sampler.png"> |
| <note> |
| See <a href="build-ws-test-plan.html">Building a WebService Test Plan</a> for up to date way of test SOAP and REST Webservices |
| </note> |
| <description><p>This sampler lets you send a SOAP request to a webservice. It can also be |
| used to send XML-RPC over HTTP. It creates an HTTP POST request, with the specified XML as the |
| POST content. |
| To change the "<code>Content-type</code>" from the default of "<code>text/xml</code>", use a <complink name="HTTP Header Manager" />. |
| Note that the sampler will use all the headers from the <complink name="HTTP Header Manager"/>. |
| If a SOAP action is specified, that will override any <code>SOAPaction</code> in the <complink name="HTTP Header Manager"/>. |
| The primary difference between the soap sampler and |
| webservice sampler, is the soap sampler uses raw post and does not require conformance to |
| SOAP 1.1.</p> |
| <note>The sampler no longer uses chunked encoding by default.<br/> |
| For screen input, it now always uses the size of the data.<br/> |
| File input uses the file length as determined by Java.<br/> |
| On some OSes this may not work for all files, in which case add a child <complink name="HTTP Header Manager"/> |
| with <code>Content-Length</code> set to the actual length of the file.<br/> |
| Or set <code>Content-Length</code> to <code>-1</code> to force chunked encoding. |
| </note> |
| </description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler |
| that is shown in the tree.</property> |
| <property name="URL" required="Yes">The URL to direct the SOAP request to.</property> |
| <property name="Send SOAP action" required="No">Send a SOAP action header? (overrides the <complink name="HTTP Header Manager"/>)</property> |
| <property name="Use KeepAlive" required="No">If set, sends <code>Connection: keep-alive</code>, else sends <code>Connection: close</code></property> |
| <property name="Soap/XML-RPC Data" required="No">The Soap XML message, or XML-RPC instructions. |
| Not used if the filename is provided. |
| </property> |
| <property name="Filename" required="No">If specified, then the contents of the file are sent, and the Data field is ignored</property> |
| </properties> |
| </component> |
| |
| <component name="LDAP Request" index="§-num;.1.7" width="621" height="462" screenshot="ldap_request.png"> |
| <description>This Sampler lets you send a different Ldap request(<code>Add</code>, <code>Modify</code>, <code>Delete</code> and <code>Search</code>) to an LDAP server. |
| <p>If you are going to send multiple requests to the same LDAP server, consider |
| using an <complink name="LDAP Request Defaults"/> |
| Configuration Element so you do not have to enter the same information for each |
| LDAP Request.</p> The same way the <complink name="Login Config Element"/> also using for Login and password. |
| </description> |
| |
| <p>There are two ways to create test cases for testing an LDAP Server.</p> |
| <ol> |
| <li>Inbuilt Test cases.</li> |
| <li>User defined Test cases.</li> |
| </ol> |
| |
| <p>There are four test scenarios of testing LDAP. The tests are given below:</p> |
| <ol> |
| <li>Add Test |
| <ol> |
| <li>Inbuilt test: |
| <p>This will add a pre-defined entry in the LDAP Server and calculate |
| the execution time. After execution of the test, the created entry will be |
| deleted from the LDAP |
| Server.</p> |
| </li> |
| <li>User defined test: |
| <p>This will add the entry in the LDAP Server. User has to enter all the |
| attributes in the table.The entries are collected from the table to add. The |
| execution time is calculated. The created entry will not be deleted after the |
| test.</p> |
| </li> |
| </ol> |
| </li> |
| <li>Modify Test |
| <ol> |
| <li>Inbuilt test: |
| <p>This will create a pre-defined entry first, then will modify the |
| created entry in the LDAP Server.And calculate the execution time. After |
| execution |
| of the test, the created entry will be deleted from the LDAP Server.</p> |
| </li> |
| <li>User defined test: |
| <p>This will modify the entry in the LDAP Server. User has to enter all the |
| attributes in the table. The entries are collected from the table to modify. |
| The execution time is calculated. The entry will not be deleted from the LDAP |
| Server.</p> |
| </li> |
| </ol> |
| </li> |
| <li>Search Test |
| <ol> |
| <li>Inbuilt test: |
| <p>This will create the entry first, then will search if the attributes |
| are available. It calculates the execution time of the search query. At the |
| end of the execution,created entry will be deleted from the LDAP Server.</p> |
| </li> |
| <li>User defined test: |
| <p>This will search the user defined entry(Search filter) in the Search |
| base (again, defined by the user). The entries should be available in the LDAP |
| Server. The execution time is calculated.</p> |
| </li> |
| </ol> |
| </li> |
| <li>Delete Test |
| <ol> |
| <li>Inbuilt test: |
| <p>This will create a pre-defined entry first, then it will be deleted |
| from the LDAP Server. The execution time is calculated.</p> |
| </li> |
| <li>User defined test: |
| <p>This will delete the user-defined entry in the LDAP Server. The entries |
| should be available in the LDAP Server. The execution time is calculated.</p> |
| </li> |
| </ol> |
| </li> |
| </ol> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| <property name="Server Name or IP" required="Yes">Domain name or IP address of the LDAP server. |
| JMeter assumes the LDAP server is listening on the default port (<code>389</code>).</property> |
| <property name="Port" required="Yes">Port to connect to (default is <code>389</code>).</property> |
| <property name="root DN" required="Yes">Base DN to use for ldap operations</property> |
| <property name="Username" required="Usually">LDAP server username.</property> |
| <property name="Password" required="Usually">LDAP server password. (N.B. this is stored unencrypted in the test plan)</property> |
| <property name="Entry DN" required="Yes, if User Defined Test and Add Test or Modify Test is selected">the name of the context to create or Modify; may not be empty. |
| <note>You have to set the right attributes of the object yourself. So if you want to add <code>cn=apache,ou=test</code> |
| you have to add in the table <code>name</code> and <code>value</code> to <code>cn</code> and <code>apache</code>. |
| </note> |
| </property> |
| <property name="Delete" required="Yes, if User Defined Test and Delete Test is selected">the name of the context to Delete; may not be empty</property> |
| <property name="Search base" required="Yes, if User Defined Test and Search Test is selected">the name of the context or object to search</property> |
| <property name="Search filter" required="Yes, if User Defined Test and Search Test is selected"> the filter expression to use for the search; may not be null</property> |
| <property name="add test" required="Yes, if User Defined Test and add Test is selected">Use these <code>name</code>, <code>value</code> pairs for creation of the new object in the given context</property> |
| <property name="modify test" required="Yes, if User Defined Test and Modify Test is selected">Use these <code>name</code>, <code>value</code> pairs for modification of the given context object</property> |
| </properties> |
| |
| <links> |
| <link href="build-ldap-test-plan.html">Building an Ldap Test Plan</link> |
| <complink name="LDAP Request Defaults"/> |
| </links> |
| |
| </component> |
| |
| <component name="LDAP Extended Request" index="§-num;.1.8" width="619" height="371" screenshot="ldapext_request.png"> |
| <description>This Sampler can send all 8 different LDAP requests to an LDAP server. It is an extended version of the LDAP sampler, |
| therefore it is harder to configure, but can be made much closer resembling a real LDAP session. |
| <p>If you are going to send multiple requests to the same LDAP server, consider |
| using an <complink name="LDAP Extended Request Defaults"/> |
| Configuration Element so you do not have to enter the same information for each |
| LDAP Request.</p> </description> |
| |
| <p>There are nine test operations defined. These operations are given below:</p> |
| <dl> |
| <dt><b>Thread bind</b></dt> |
| <dd> |
| <p>Any LDAP request is part of an LDAP session, so the first thing that should be done is starting a session to the LDAP server. |
| For starting this session a thread bind is used, which is equal to the LDAP "<code>bind</code>" operation. |
| The user is requested to give a <code>username</code> (Distinguished name) and <code>password</code>, |
| which will be used to initiate a session. |
| When no password, or the wrong password is specified, an anonymous session is started. Take care, |
| omitting the password will not fail this test, a wrong password will. |
| (N.B. this is stored unencrypted in the test plan)</p> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| <property name="Servername" required="Yes">The name (or IP-address) of the LDAP server.</property> |
| <property name="Port" required="No">The port number that the LDAP server is listening to. If this is omitted |
| JMeter assumes the LDAP server is listening on the default port(389).</property> |
| <property name="DN" required="No">The distinguished name of the base object that will be used for any subsequent operation. |
| It can be used as a starting point for all operations. You cannot start any operation on a higher level than this DN!</property> |
| <property name="Username" required="No">Full distinguished name of the user as which you want to bind.</property> |
| <property name="Password" required="No">Password for the above user. If omitted it will result in an anonymous bind. |
| If it is incorrect, the sampler will return an error and revert to an anonymous bind. (N.B. this is stored unencrypted in the test plan)</property> |
| </properties> |
| </dd> |
| <dt><b>Thread unbind</b></dt> |
| <dd> |
| <p>This is simply the operation to end a session. |
| It is equal to the LDAP "<code>unbind</code>" operation.</p> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| </properties> |
| </dd> |
| <dt><b>Single bind/unbind</b></dt> |
| <dd> |
| <p> This is a combination of the LDAP "<code>bind</code>" and "<code>unbind</code>" operations. |
| It can be used for an authentication request/password check for any user. It will open a new session, just to |
| check the validity of the user/password combination, and end the session again.</p> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| <property name="Username" required="Yes">Full distinguished name of the user as which you want to bind.</property> |
| <property name="Password" required="No">Password for the above user. If omitted it will result in an anonymous bind. |
| If it is incorrect, the sampler will return an error. (N.B. this is stored unencrypted in the test plan)</property> |
| </properties> |
| </dd> |
| <dt><b>Rename entry</b></dt> |
| <dd> |
| <p>This is the LDAP "<code>moddn</code>" operation. It can be used to rename an entry, but |
| also for moving an entry or a complete subtree to a different place in |
| the LDAP tree.</p> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| <property name="Old entry name" required="Yes">The current distinguished name of the object you want to rename or move, |
| relative to the given DN in the thread bind operation.</property> |
| <property name="New distinguished name" required="Yes">The new distinguished name of the object you want to rename or move, |
| relative to the given DN in the thread bind operation.</property> |
| </properties> |
| </dd> |
| <dt><b>Add test</b></dt> |
| <dd> |
| <p>This is the ldap "<code>add</code>" operation. It can be used to add any kind of |
| object to the LDAP server.</p> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| <property name="Entry DN" required="Yes">Distinguished name of the object you want to add, relative to the given DN in the thread bind operation.</property> |
| <property name="Add test" required="Yes">A list of attributes and their values you want to use for the object. |
| If you need to add a multiple value attribute, you need to add the same attribute with their respective |
| values several times to the list.</property> |
| </properties> |
| </dd> |
| <dt><b>Delete test</b></dt> |
| <dd> |
| <p> This is the LDAP "<code>delete</code>" operation, it can be used to delete an |
| object from the LDAP tree</p> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| <property name="Delete" required="Yes">Distinguished name of the object you want to delete, relative to the given DN in the thread bind operation.</property> |
| </properties> |
| </dd> |
| <dt><b>Search test</b></dt> |
| <dd> |
| <p>This is the LDAP "<code>search</code>" operation, and will be used for defining searches.</p> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| <property name="Search base" required="No">Distinguished name of the subtree you want your |
| search to look in, relative to the given DN in the thread bind operation.</property> |
| <property name="Search Filter" required="Yes">searchfilter, must be specified in LDAP syntax.</property> |
| <property name="Scope" required="No">Use <code>0</code> for baseobject-, <code>1</code> for onelevel- and <code>2</code> for a subtree search. (Default=<code>0</code>)</property> |
| <property name="Size Limit" required="No">Specify the maximum number of results you want back from the server. (default=<code>0</code>, which means no limit.) When the sampler hits the maximum number of results, it will fail with errorcode <code>4</code></property> |
| <property name="Time Limit" required="No">Specify the maximum amount of (cpu)time (in milliseconds) that the server can spend on your search. Take care, this does not say anything about the response time. (default is <code>0</code>, which means no limit)</property> |
| <property name="Attributes" required="No">Specify the attributes you want to have returned, separated by a semicolon. An empty field will return all attributes</property> |
| <property name="Return object" required="No">Whether the object will be returned (<code>true</code>) or not (<code>false</code>). Default=<code>false</code></property> |
| <property name="Dereference aliases" required="No">If <code>true</code>, it will dereference aliases, if <code>false</code>, it will not follow them (default=<code>false</code>)</property> |
| <property name="Parse the search results?" required="No">If <code>true</code>, the search results will be added to the response data. If <code>false</code>, a marker - whether results where found or not - will be added to the response data.</property> |
| </properties> |
| </dd> |
| <dt><b>Modification test</b></dt> |
| <dd> |
| <p>This is the LDAP "<code>modify</code>" operation. It can be used to modify an object. It |
| can be used to add, delete or replace values of an attribute. </p> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| <property name="Entry name" required="Yes">Distinguished name of the object you want to modify, relative |
| to the given DN in the thread bind operation</property> |
| <property name="Modification test" required="Yes">The attribute-value-opCode triples. The opCode can be any |
| valid LDAP operationCode (<code>add</code>, <code>delete</code>/<code>remove</code> or <code>replace</code>). |
| If you don't specify a value with a <code>delete</code> operation, |
| all values of the given attribute will be deleted. If you do specify a value in a <code>delete</code> operation, only |
| the given value will be deleted. If this value is non-existent, the sampler will fail the test.</property> |
| </properties> |
| </dd> |
| <dt><b>Compare</b></dt> |
| <dd> |
| <p>This is the LDAP "<code>compare</code>" operation. It can be used to compare the value |
| of a given attribute with some already known value. In reality this is mostly |
| used to check whether a given person is a member of some group. In such a case |
| you can compare the DN of the user as a given value, with the values in the |
| attribute "<code>member</code>" of an object of the type <code>groupOfNames</code>. |
| If the compare operation fails, this test fails with errorcode <code>49</code>.</p> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| <property name="Entry DN" required="Yes">The current distinguished name of the object of |
| which you want to compare an attribute, relative to the given DN in the thread bind operation.</property> |
| <property name="Compare filter" required="Yes">In the form "<code>attribute=value</code>"</property> |
| </properties> |
| </dd> |
| </dl> |
| <links> |
| <link href="build-ldapext-test-plan.html">Building an LDAP Test Plan</link> |
| <complink name="LDAP Extended Request Defaults"/> |
| </links> |
| </component> |
| |
| |
| |
| |
| <component name="Access Log Sampler" index="§-num;.1.9" width="702" height="305" screenshot="accesslogsampler.png"> |
| <center><h2>(Beta Code)</h2></center> |
| <description><p>AccessLogSampler was designed to read access logs and generate http requests. |
| For those not familiar with the access log, it is the log the webserver maintains of every |
| request it accepted. This means every image, css file, javascript file, html file, … |
| The current implementation is complete, but some features have not been enabled. |
| There is a filter for the access log parser, but I haven't figured out how to link to the pre-processor. |
| Once I do, changes to the sampler will be made to enable that functionality.</p> |
| <p>Tomcat uses the common format for access logs. This means any webserver that uses the |
| common log format can use the AccessLogSampler. Server that use common log format include: |
| Tomcat, Resin, Weblogic, and SunOne. Common log format looks |
| like this:</p> |
| <source>127.0.0.1 - - [21/Oct/2003:05:37:21 -0500] "GET /index.jsp?%2Findex.jsp= HTTP/1.1" 200 8343</source> |
| <note>The current implementation of the parser only looks at the text within the quotes that contains one of the HTTP protocol methods (<code>GET</code>, <code>PUT</code>, <code>POST</code>, <code>DELETE</code>, …). |
| Everything else is stripped out and ignored. For example, the response code is completely |
| ignored by the parser. </note> |
| <p>For the future, it might be nice to filter out entries that |
| do not have a response code of <code>200</code>. Extending the sampler should be fairly simple. There |
| are two interfaces you have to implement:</p> |
| <ul> |
| <li><code>org.apache.jmeter.protocol.http.util.accesslog.LogParser</code></li> |
| <li><code>org.apache.jmeter.protocol.http.util.accesslog.Generator</code></li> |
| </ul> |
| <p>The current implementation of AccessLogSampler uses the generator to create a new |
| HTTPSampler. The servername, port and get images are set by AccessLogSampler. Next, |
| the parser is called with integer <code>1</code>, telling it to parse one entry. After that, |
| <code>HTTPSampler.sample()</code> is called to make the request.</p> |
| <source> |
| samp = (HTTPSampler) GENERATOR.generateRequest(); |
| samp.setDomain(this.getDomain()); |
| samp.setPort(this.getPort()); |
| samp.setImageParser(this.isImageParser()); |
| PARSER.parse(1); |
| res = samp.sample(); |
| res.setSampleLabel(samp.toString()); |
| </source> |
| The required methods in <code>LogParser</code> are: |
| <ul> |
| <li><code>setGenerator(Generator)</code></li> |
| <li><code>parse(int)</code></li> |
| </ul> |
| <p> |
| Classes implementing <code>Generator</code> interface should provide concrete implementation |
| for all the methods. For an example of how to implement either interface, refer to |
| <code>StandardGenerator</code> and <code>TCLogParser</code>. |
| </p> |
| </description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| <property name="Server" required="Yes">Domain name or IP address of the web server.</property> |
| <property name="Protocol" required="No (defaults to http">Scheme</property> |
| <property name="Port" required="No (defaults to 80)">Port the web server is listening to.</property> |
| <property name="Log parser class" required="Yes (default provided)">The log parser class is responsible for parsing the logs.</property> |
| <property name="Filter" required="No">The filter class is used to filter out certain lines.</property> |
| <property name="Location of log file" required="Yes">The location of the access log file.</property> |
| </properties> |
| <p> |
| The <code>TCLogParser</code> processes the access log independently for each thread. |
| The <code>SharedTCLogParser</code> and <code>OrderPreservingLogParser</code> share access to the file, |
| i.e. each thread gets the next entry in the log. |
| </p> |
| <p> |
| The <code>SessionFilter</code> is intended to handle Cookies across threads. |
| It does not filter out any entries, but modifies the cookie manager so that the cookies for a given IP are |
| processed by a single thread at a time. If two threads try to process samples from the same client IP address, |
| then one will be forced to wait until the other has completed. |
| </p> |
| <p> |
| The <code>LogFilter</code> is intended to allow access log entries to be filtered by filename and regex, |
| as well as allowing for the replacement of file extensions. However, it is not currently possible |
| to configure this via the GUI, so it cannot really be used. |
| </p> |
| </component> |
| |
| <component name="BeanShell Sampler" index="§-num;.1.10" width="848" height="566" screenshot="beanshellsampler.png"> |
| <description><p>This sampler allows you to write a sampler using the BeanShell scripting language. |
| </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 <code>ThreadListener</code> and <code>TestListener</code> interface methods. |
| These must be defined in the initialisation file. |
| See the file <code>BeanShellListeners.bshrc</code> for example definitions. |
| </p> |
| <p> |
| The BeanShell sampler also supports the <code>Interruptible</code> interface. |
| The <code>interrupt()</code> method can be defined in the script or the init file. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree. |
| The name is stored in the script variable Label</property> |
| <property name="Reset bsh.Interpreter before each call" required="Yes"> |
| If this option is selected, then the interpreter will be recreated for each sample. |
| This may be necessary for some long running scripts. |
| For further information, see <a href="best-practices#bsh_scripting">Best Practices - BeanShell scripting</a>. |
| </property> |
| <property name="Parameters" required="No">Parameters to pass to the BeanShell script. |
| This is intended for use with script files; for scripts defined in the GUI, you can use whatever |
| variable and function references you need within the script itself. |
| The parameters are stored in the following variables: |
| <dl> |
| <dt><code>Parameters</code></dt><dd>string containing the parameters as a single variable</dd> |
| <dt><code>bsh.args</code></dt><dd>String array containing parameters, split on white-space</dd> |
| </dl></property> |
| <property name="Script file" required="No">A file containing the BeanShell script to run. |
| The file name is stored in the script variable <code>FileName</code></property> |
| <property name="Script" required="Yes (unless script file is provided)">The BeanShell script to run. |
| The return value (if not <code>null</code>) is stored as the sampler result.</property> |
| </properties> |
| <note> |
| N.B. Each Sampler instance has its own BeanShell interpreter, |
| and Samplers are only called from a single thread |
| </note><p> |
| If the property "<code>beanshell.sampler.init</code>" is defined, it is passed to the Interpreter |
| as the name of a sourced file. |
| This can be used to define common methods and variables. |
| There is a sample init file in the bin directory: <code>BeanShellSampler.bshrc</code>. |
| </p><p> |
| If a script file is supplied, that will be used, otherwise the script will be used.</p> |
| <note> |
| JMeter processes function and variable references before passing the script field to the interpreter, |
| so the references will only be resolved once. |
| Variable and function references in script files will be passed |
| verbatim to the interpreter, which is likely to cause a syntax error. |
| In order to use runtime variables, please use the appropriate props methods, |
| e.g.<code>props.get("START.HMS"); props.put("PROP1","1234");</code> |
| <br/> |
| BeanShell does not currently support Java 5 syntax such as generics and the enhanced for loop. |
| </note> |
| <p>Before invoking the script, some variables are set up in the BeanShell interpreter:</p> |
| <p>The contents of the Parameters field is put into the variable "<code>Parameters</code>". |
| The string is also split into separate tokens using a single space as the separator, and the resulting list |
| is stored in the String array <code>bsh.args</code>.</p> |
| <p>The full list of BeanShell variables that is set up is as follows:</p> |
| <ul> |
| <li><code>log</code> - the <a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a></li> |
| <li><code>Label</code> - the Sampler label</li> |
| <li><code>FileName</code> - the file name, if any</li> |
| <li><code>Parameters</code> - text from the Parameters field</li> |
| <li><code>bsh.args</code> - the parameters, split as described above</li> |
| <li><code>SampleResult</code> - pointer to the current SampleResult</li> |
| <li><code>ResponseCode</code> defaults to <code>200</code></li> |
| <li><code>ResponseMessage</code> defaults to "<code>OK</code>"</li> |
| <li><code>IsSuccess</code> defaults to <code>true</code></li> |
| <li><code>ctx</code> - <a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a></li> |
| <li><code>vars</code> - <a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a> - e.g. |
| <source>vars.get("VAR1"); |
| vars.put("VAR2","value"); |
| vars.remove("VAR3"); |
| vars.putObject("OBJ1",new Object());</source></li> |
| <li><code>props</code> - JMeterProperties (class <code>java.util.Properties</code>) - e.g. |
| <source>props.get("START.HMS"); |
| props.put("PROP1","1234");</source></li> |
| </ul> |
| <p>When the script completes, control is returned to the Sampler, and it copies the contents |
| of the following script variables into the corresponding variables in the <a href="../api/org/apache/jmeter/samplers/SampleResult.html"><code>SampleResult</code></a>:</p> |
| <ul> |
| <li><code>ResponseCode</code> - for example <code>200</code></li> |
| <li><code>ResponseMessage</code> - for example "<code>OK</code>"</li> |
| <li><code>IsSuccess</code> - <code>true</code> or <code>false</code></li> |
| </ul> |
| <p>The SampleResult ResponseData is set from the return value of the script. |
| If the script returns null, it can set the response directly, by using the method |
| <code>SampleResult.setResponseData(data)</code>, where data is either a String or a byte array. |
| The data type defaults to "<code>text</code>", but can be set to binary by using the method |
| <code>SampleResult.setDataType(SampleResult.BINARY)</code>. |
| </p> |
| <p>The <code>SampleResult</code> variable gives the script full access to all the fields and |
| methods in the <code>SampleResult</code>. For example, the script has access to the methods |
| <code>setStopThread(boolean)</code> and <code>setStopTest(boolean)</code>. |
| |
| Here is a simple (not very useful!) example script:</p> |
| |
| <source> |
| if (bsh.args[0].equalsIgnoreCase("StopThread")) { |
| log.info("Stop Thread detected!"); |
| SampleResult.setStopThread(true); |
| } |
| return "Data from sample with Label "+Label; |
| //or |
| SampleResult.setResponseData("My data"); |
| return null; |
| </source> |
| <p>Another example:<br></br> ensure that the property <code>beanshell.sampler.init=BeanShellSampler.bshrc</code> is defined in <code>jmeter.properties</code>. |
| The following script will show the values of all the variables in the <code>ResponseData</code> field: |
| </p> |
| <source> |
| return getVariables(); |
| </source> |
| <p> |
| For details on the methods available for the various classes (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html"><code>JMeterVariables</code></a>, <a href="../api/org/apache/jmeter/samplers/SampleResult.html"><code>SampleResult</code></a> etc.) please check the Javadoc or the source code. |
| Beware however that misuse of any methods can cause subtle faults that may be difficult to find. |
| </p> |
| </component> |
| |
| |
| <component name="BSF Sampler" index="§-num;.1.11" width="848" height="590" screenshot="bsfsampler.png"> |
| <description><p>This sampler allows you to write a sampler using a BSF scripting language.<br></br> |
| See the <a href="http://commons.apache.org/bsf/index.html">Apache Bean Scripting Framework</a> |
| website for details of the languages supported. |
| You may need to download the appropriate jars for the language; they should be put in the JMeter <code>lib</code> directory. |
| </p> |
| <note> |
| The BSF API has been largely superseded by JSR-223, which is included in Java 6 onwards. |
| Most scripting languages now include support for JSR-223; please use the JSR223 Sampler instead. |
| The BSF Sampler should only be needed for supporting legacy languages/test scripts. |
| </note> |
| <p>By default, JMeter supports the following languages:</p> |
| <ul> |
| <li>javascript</li> |
| <li>jexl</li> |
| <li>xslt</li> |
| </ul> |
| <note>Unlike the BeanShell sampler, the interpreter is not saved between invocations.</note> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| <property name="Scripting Language" required="Yes">Name of the BSF scripting language to be used. |
| <note>N.B. Not all the languages in the drop-down list are supported by default. |
| The following are supported: jexl, javascript, xslt. |
| Others may be available if the appropriate jar is installed in the JMeter lib directory. |
| </note> |
| </property> |
| <property name="Script File" required="No">Name of a file to be used as a BSF script, if a relative file path is used, then it will be relative to directory referenced by "<code>user.dir</code>" System property</property> |
| <property name="Parameters" required="No">List of parameters to be passed to the script file or the script.</property> |
| <property name="Script" required="Yes (unless script file is provided)">Script to be passed to BSF language</property> |
| </properties> |
| <p> |
| If a script file is supplied, that will be used, otherwise the script will be used.</p> |
| <note> |
| JMeter processes function and variable references before passing the script field to the interpreter, |
| so the references will only be resolved once. |
| Variable and function references in script files will be passed |
| verbatim to the interpreter, which is likely to cause a syntax error. |
| In order to use runtime variables, please use the appropriate props methods, |
| e.g.<code>props.get("START.HMS"); props.put("PROP1","1234");</code> |
| </note> |
| <p> |
| Before invoking the script, some variables are set up. |
| Note that these are BSF variables - i.e. they can be used directly in the script. |
| </p> |
| <ul> |
| <li><code>log</code> - the <a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a></li> |
| <li><code>Label</code> - the Sampler label</li> |
| <li><code>FileName</code> - the file name, if any</li> |
| <li><code>Parameters</code> - text from the Parameters field</li> |
| <li><code>args</code> - the parameters, split as described above</li> |
| <li><code>SampleResult</code> - pointer to the current <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a></li> |
| <li><code>sampler</code> - <a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a> - pointer to current Sampler</li> |
| <li><code>ctx</code> - <a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a></li> |
| <li><code>vars</code> - <a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a> - e.g. |
| <source>vars.get("VAR1"); |
| vars.put("VAR2","value"); |
| vars.remove("VAR3"); |
| vars.putObject("OBJ1",new Object());</source></li> |
| <li><code>props</code> - JMeterProperties (class <code>java.util.Properties</code>) - e.g. |
| <source>props.get("START.HMS"); |
| props.put("PROP1","1234");</source></li> |
| <li><code>OUT</code> - System.out - e.g. <code>OUT.println("message")</code></li> |
| </ul> |
| <p> |
| The <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a> ResponseData is set from the return value of the script. |
| If the script returns <code>null</code>, it can set the response directly, by using the method |
| <code>SampleResult.setResponseData(data)</code>, where data is either a String or a byte array. |
| The data type defaults to "<code>text</code>", but can be set to binary by using the method |
| <code>SampleResult.setDataType(SampleResult.BINARY)</code>. |
| </p> |
| <p> |
| The SampleResult variable gives the script full access to all the fields and |
| methods in the SampleResult. For example, the script has access to the methods |
| <code>setStopThread(boolean)</code> and <code>setStopTest(boolean)</code>. |
| </p> |
| <p> |
| Unlike the BeanShell Sampler, the BSF Sampler does not set the <code>ResponseCode</code>, <code>ResponseMessage</code> and sample status via script variables. |
| Currently the only way to change these is via the <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a> methods: |
| </p> |
| <ul> |
| <li><code>SampleResult.setSuccessful(true/false)</code></li> |
| <li><code>SampleResult.setResponseCode("code")</code></li> |
| <li><code>SampleResult.setResponseMessage("message")</code></li> |
| </ul> |
| </component> |
| |
| <component name="JSR223 Sampler" index="§-num;.1.11.1" width="861" height="502" screenshot="jsr223-sampler.png"> |
| <description> |
| <p> |
| The JSR223 Sampler allows JSR223 script code to be used to perform a sample. |
| </p> |
| <p> |
| The JSR223 test elements have a feature (compilation) that can significantly increase performance. |
| To benefit from this feature: |
| </p> |
| <ul> |
| <li>Use Script files instead of inlining them. This will make JMeter compile them if this feature is available on ScriptEngine and cache them.</li> |
| <li>Or Use Script Text and check <code>Cache compiled script if available</code> property. |
| <note>When using this feature, ensure your script code does not use JMeter variables directly in script code as caching would only cache first replacement. Instead use script parameters.</note> |
| <note>To benefit from caching and compilation, the language engine used for scripting must implement JSR223 <code>Compilable</code> interface (Groovy is one of these, java, beanshell and javascript are not)</note> |
| <note>When using Groovy as scripting language and not checking <code>Cache compiled script if available</code> (while caching is recommended), you should set this JVM Property <code>-Dgroovy.use.classvalue=true</code> |
| due to a Groovy Memory leak as of version 2.4.6, see: |
| <ul> |
| <li><a href="https://issues.apache.org/jira/browse/GROOVY-7683" >GROOVY-7683</a></li> |
| <li><a href="https://issues.apache.org/jira/browse/GROOVY-7591">GROOVY-7591</a></li> |
| <li><a href="https://bugs.openjdk.java.net/browse/JDK-8136353">JDK-8136353</a></li> |
| </ul> |
| </note> |
| </li> |
| </ul> |
| Cache size is controlled by the following jmeter property (<code>jmeter.properties</code>): |
| <source>jsr223.compiled_scripts_cache_size=100</source> |
| <note>Unlike the <complink name="BeanShell Sampler" />, the interpreter is not saved between invocations.</note> |
| <note> |
| JSR223 Test Elements using Script file or Script text + checked <code>Cache compiled script if available</code> are now compiled if ScriptEngine supports this feature, this enables great performance enhancements. |
| </note> |
| </description> |
| <note> |
| JMeter processes function and variable references before passing the script field to the interpreter, |
| so the references will only be resolved once. |
| Variable and function references in script files will be passed |
| verbatim to the interpreter, which is likely to cause a syntax error. |
| In order to use runtime variables, please use the appropriate props methods, |
| e.g. <source>props.get("START.HMS"); |
| props.put("PROP1","1234");</source> |
| </note> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| <property name="Scripting Language" required="Yes">Name of the JSR223 scripting language to be used. |
| <note>N.B. Not all the languages in the drop-down list are supported by default. |
| The following are supported: jexl, javascript, xslt. |
| Others may be available if the appropriate jar is installed in the JMeter lib directory. |
| </note> |
| </property> |
| <property name="Script File" required="No">Name of a file to be used as a JSR223 script, if a relative file path is used, then it will be relative to directory referenced by "<code>user.dir</code>" System property</property> |
| <property name="Parameters" required="No">List of parameters to be passed to the script file or the script.</property> |
| <property name="Cache compiled script if available" required="No">If checked (advised) and the language used supports <code>Compilable</code> interface (Groovy is one of these, java, beanshell and javascript are not), JMeter will compile the Script and cache it using it's MD5 hash as unique cache key</property> |
| <property name="Script" required="Yes (unless script file is provided)">Script to be passed to JSR223 language</property> |
| </properties> |
| <p> |
| If a script file is supplied, that will be used, otherwise the script will be used.</p> |
| |
| <p> |
| Before invoking the script, some variables are set up. |
| Note that these are JSR223 variables - i.e. they can be used directly in the script. |
| </p> |
| <ul> |
| <li><code>log</code> - the <a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a></li> |
| <li><code>Label</code> - the Sampler label</li> |
| <li><code>FileName</code> - the file name, if any</li> |
| <li><code>Parameters</code> - text from the Parameters field</li> |
| <li><code>args</code> - the parameters, split as described above</li> |
| <li><code>SampleResult</code> - pointer to the current <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a></li> |
| <li><code>sampler</code> - (<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>) - pointer to current Sampler</li> |
| <li><code>ctx</code> - <a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a></li> |
| <li><code>vars</code> - <a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a> - e.g. |
| <source>vars.get("VAR1"); |
| vars.put("VAR2","value"); |
| vars.remove("VAR3"); |
| vars.putObject("OBJ1",new Object());</source></li> |
| <li><code>props</code> - JMeterProperties (class <code>java.util.Properties</code>) - e.g. |
| <source>props.get("START.HMS"); |
| props.put("PROP1","1234");</source></li> |
| <li><code>OUT</code> - System.out - e.g. <code>OUT.println("message")</code></li> |
| </ul> |
| <p> |
| The <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a> ResponseData is set from the return value of the script. |
| If the script returns <code>null</code>, it can set the response directly, by using the method |
| <code>SampleResult.setResponseData(data)</code>, where data is either a String or a byte array. |
| The data type defaults to "<code>text</code>", but can be set to binary by using the method |
| <code>SampleResult.setDataType(SampleResult.BINARY)</code>. |
| </p> |
| <p> |
| The SampleResult variable gives the script full access to all the fields and |
| methods in the SampleResult. For example, the script has access to the methods |
| <code>setStopThread(boolean)</code> and <code>setStopTest(boolean)</code>. |
| </p> |
| <p> |
| Unlike the BeanShell Sampler, the JSR223 Sampler does not set the <code>ResponseCode</code>, <code>ResponseMessage</code> and sample status via script variables. |
| Currently the only way to changes these is via the <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a> methods: |
| </p> |
| <ul> |
| <li><code>SampleResult.setSuccessful(true/false)</code></li> |
| <li><code>SampleResult.setResponseCode("code")</code></li> |
| <li><code>SampleResult.setResponseMessage("message")</code></li> |
| </ul> |
| </component> |
| |
| <component name="TCP Sampler" index="§-num;.1.12" width="827" height="521" screenshot="tcpsampler.png"> |
| <description> |
| <p> |
| The TCP Sampler opens a TCP/IP connection to the specified server. |
| It then sends the text, and waits for a response. |
| </p><p> |
| If "<code>Re-use connection</code>" is selected, connections are shared between Samplers in the same thread, |
| provided that the exact same host name string and port are used. |
| Different hosts/port combinations will use different connections, as will different threads. |
| If both of "<code>Re-use connection</code>" and "<code>Close connection</code>" are selected, the socket will be closed after running the sampler. |
| On the next sampler, another socket will be created. You may want to close a socket at the end of each thread loop. |
| </p><p> |
| If an error is detected - or "<code>Re-use connection</code>" is not selected - the socket is closed. |
| Another socket will be reopened on the next sample. |
| </p><p> |
| The following properties can be used to control its operation: |
| </p> |
| <dl> |
| <dt><code>tcp.status.prefix</code></dt><dd>text that precedes a status number</dd> |
| <dt><code>tcp.status.suffix</code></dt><dd>text that follows a status number</dd> |
| <dt><code>tcp.status.properties</code></dt><dd>name of property file to convert status codes to messages</dd> |
| <dt><code>tcp.handler</code></dt><dd>Name of TCP Handler class (default <code>TCPClientImpl</code>) - only used if not specified on the GUI</dd> |
| </dl> |
| The class that handles the connection is defined by the GUI, failing that the property <code>tcp.handler</code>. |
| If not found, the class is then searched for in the package <code>org.apache.jmeter.protocol.tcp.sampler</code>. |
| <p> |
| Users can provide their own implementation. |
| The class must extend <code>org.apache.jmeter.protocol.tcp.sampler.TCPClient</code>. |
| </p> |
| <p> |
| The following implementations are currently provided. |
| </p> |
| <ul> |
| <li><code>TCPClientImpl</code></li> |
| <li><code>BinaryTCPClientImpl</code></li> |
| <li><code>LengthPrefixedBinaryTCPClientImpl</code></li> |
| </ul> |
| The implementations behave as follows: |
| <dl> |
| <dt><code>TCPClientImpl</code></dt> |
| <dd> |
| This implementation is fairly basic. |
| When reading the response, it reads until the end of line byte, if this is defined |
| by setting the property <code>tcp.eolByte</code>, otherwise until the end of the input stream. |
| You can control charset encoding by setting <code>tcp.charset</code>, which will default to Platform default encoding. |
| </dd> |
| <dt><code>BinaryTCPClientImpl</code></dt> |
| <dd> |
| This implementation converts the GUI input, which must be a hex-encoded string, into binary, |
| and performs the reverse when reading the response. |
| When reading the response, it reads until the end of message byte, if this is defined |
| by setting the property <code>tcp.BinaryTCPClient.eomByte</code>, otherwise until the end of the input stream. |
| </dd> |
| <dt><code>LengthPrefixedBinaryTCPClientImpl</code></dt> |
| <dd> |
| This implementation extends BinaryTCPClientImpl by prefixing the binary message data with a binary length byte. |
| The length prefix defaults to 2 bytes. |
| This can be changed by setting the property <code>tcp.binarylength.prefix.length</code>. |
| </dd> |
| <dt><b>Timeout handling</b></dt> |
| <dd> |
| If the timeout is set, the read will be terminated when this expires. |
| So if you are using an <code>eolByte</code>/<code>eomByte</code>, make sure the timeout is sufficiently long, |
| otherwise the read will be terminated early. |
| </dd> |
| <dt><b>Response handling</b></dt> |
| <dd> |
| If <code>tcp.status.prefix</code> is defined, then the response message is searched for the text following |
| that up to the suffix. If any such text is found, it is used to set the response code. |
| The response message is then fetched from the properties file (if provided). |
| <example title="Usage of pre- and suffix" anchor="tcp-prefix-example"> |
| For example, if the prefix = "<code>[</code>" and the suffix = "<code>]</code>", then the following response: |
| <source>[J28] XI123,23,GBP,CR</source> |
| would have the response code <code>J28</code>. |
| </example> |
| Response codes in the range "<code>400</code>"-"<code>499</code>" and "<code>500</code>"-"<code>599</code>" are currently regarded as failures; |
| all others are successful. [This needs to be made configurable!] |
| </dd> |
| </dl> |
| <note>The login name/password are not used by the supplied TCP implementations.</note> |
| <br></br> |
| Sockets are disconnected at the end of a test run. |
| </description> |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="TCPClient classname" required="No">Name of the TCPClient class. Defaults to the property <code>tcp.handler</code>, failing that <code>TCPClientImpl</code>.</property> |
| <property name="ServerName or IP" required="Yes">Name or IP of TCP server</property> |
| <property name="Port Number" required="Yes">Port to be used</property> |
| <property name="Re-use connection" required="Yes">If selected, the connection is kept open. Otherwise it is closed when the data has been read.</property> |
| <property name="Close connection" required="Yes">If selected, the connection will be closed after running the sampler.</property> |
| <property name="SO_LINGER" required="No">Enable/disable <code>SO_LINGER</code> with the specified linger time in seconds when a socket is created. If you set "<code>SO_LINGER</code>" value as <code>0</code>, you may prevent large numbers of sockets sitting around with a <code>TIME_WAIT</code> status.</property> |
| <property name="End of line(EOL) byte value" required="No">Byte value for end of line, set this to a value outside the range <code>-128</code> to <code>+127</code> to skip <code>eol</code> checking. You may set this in <code>jmeter.properties</code> file as well with <code>eolByte</code> property. If you set this in TCP Sampler Config and in <code>jmeter.properties</code> file at the same time, the setting value in the TCP Sampler Config will be used.</property> |
| <property name="Connect Timeout" required="No">Connect Timeout (milliseconds, <code>0</code> disables).</property> |
| <property name="Response Timeout" required="No">Response Timeout (milliseconds, <code>0</code> disables).</property> |
| <property name="Set NoDelay" required="Yes">See <code>java.net.Socket.setTcpNoDelay()</code>. |
| If selected, this will disable Nagle's algorithm, otherwise Nagle's algorithm will be used.</property> |
| <property name="Text to Send" required="Yes">Text to be sent</property> |
| <property name="Login User" required="No">User Name - not used by default implementation</property> |
| <property name="Password" required="No">Password - not used by default implementation (N.B. this is stored unencrypted in the test plan)</property> |
| </properties> |
| </component> |
| |
| <component name="JMS Publisher" index="§-num;.1.13" width="854" height="796" screenshot="jmspublisher.png"> |
| <note>BETA CODE - the code is still subject to change</note> |
| <description> |
| <p> |
| JMS Publisher will publish messages to a given destination (topic/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> |
| <br></br> |
| <note>JMeter does not include any JMS implementation jar; this must be downloaded from the JMS provider and put in the lib directory</note> |
| </description> |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="use JNDI properties file" required="Yes">use <code>jndi.properties</code>. |
| Note that the file must be on the classpath - e.g. by updating the <code>user.classpath</code> JMeter property. |
| If this option is not selected, JMeter uses the "<code>JNDI Initial Context Factory</code>" and "<code>Provider URL</code>" fields |
| to create the connection. |
| </property> |
| <property name="JNDI Initial Context Factory" required="No">Name of the context factory</property> |
| <property name="Provider URL" required="Yes, unless using jndi.properties">The URL for the jms provider</property> |
| <property name="Destination" required="Yes">The message destination (topic or queue name)</property> |
| <property name="Setup" required="Yes">The destination setup type. With <code>At startup</code>, the destination name is static (i.e. always same name during the test), with <code>Each sample</code>, the destination name is dynamic and is evaluate at each sample (i.e. the destination name may be a variable)</property> |
| <property name="Authentication" required="Yes">Authentication requirement for the JMS provider</property> |
| <property name="User" required="No">User Name</property> |
| <property name="Password" required="No">Password (N.B. this is stored unencrypted in the test plan)</property> |
| <property name="Expiration" required="No"> |
| The expiration time (in milliseconds) of the message before it becomes obsolete. |
| If you do not specify an expiration time, the default value is <code>0</code> (never expires). |
| </property> |
| <property name="Priority" required="No"> |
| The priority level of the message. There are ten priority levels from <code>0</code> (lowest) to <code>9</code> (highest). |
| If you do not specify a priority level, the default level is <code>4</code>. |
| </property> |
| <property name="Number of samples to aggregate" required="Yes">Number of samples to aggregate</property> |
| <property name="Message source" required="Yes">Where to obtain the message: |
| <dl> |
| <dt><code>From File</code></dt><dd>means the referenced file will be read and reused by all samples. If file name changes it is reloaded since JMeter 3.0</dd> |
| <dt><code>Random File from folder specified below</code></dt><dd>means a random file will be selected from folder specified below, this folder must contain either files with extension <code>.dat</code> for Bytes Messages, or files with extension <code>.txt</code> or <code>.obj</code> for Object or Text messages</dd> |
| <dt><code>Text area</code></dt><dd>The Message to use either for Text or Object message</dd> |
| </dl> |
| </property> |
| <property name="Message type" required="Yes">Text, Map, Object message or Bytes Message</property> |
| <property name="Use non-persistent delivery mode?" required="No"> |
| Whether to set <code>DeliveryMode.NON_PERSISTENT</code> (defaults to <code>false</code>) |
| </property> |
| <property name="JMS Properties" required="No"> |
| The JMS Properties are properties specific for the underlying messaging system. |
| You can setup the name, the value and the class (type) of value. Default type is <code>String</code>. |
| For example: for WebSphere 5.1 web services you will need to set the JMS Property targetService to test |
| webservices through JMS. |
| </property> |
| |
| </properties> |
| <p> |
| For the MapMessage type, JMeter reads the source as lines of text. |
| Each line must have 3 fields, delimited by commas. |
| The fields are:</p> |
| <ul> |
| <li>Name of entry</li> |
| <li>Object class name, e.g. "<code>String</code>" (assumes <code>java.lang</code> package if not specified)</li> |
| <li>Object string value</li> |
| </ul> |
| For each entry, JMeter adds an Object with the given name. |
| The value is derived by creating an instance of the class, and using the <code>valueOf(String)</code> method to convert the value if necessary. |
| For example: |
| <source> |
| name,String,Example |
| size,Integer,1234 |
| </source> |
| This is a very simple implementation; it is not intended to support all possible object types. |
| <note> |
| The Object message is implemented and works as follow: |
| <ul> |
| <li>Put the JAR that contains your object and its dependencies in <code>jmeter_home/lib/</code> folder</li> |
| <li>Serialize your object as XML using XStream</li> |
| <li>Either put result in a file suffixed with <code>.txt</code> or <code>.obj</code> or put XML content directly in Text Area</li> |
| </ul> |
| Note that if message is in a file, replacement of properties will not occur while it will if you use Text Area. |
| </note> |
| |
| <p> |
| The following table shows some values which may be useful when configuring JMS: |
| </p> |
| <table> |
| <tr> |
| <!-- Anakia does not like th cell without any text --> |
| <th>Apache <a href="http://activemq.apache.org/">ActiveMQ</a></th> |
| <th>Value(s)</th> |
| <th>Comment</th> |
| </tr> |
| <tr><td>Context Factory</td><td><code>org.apache.activemq.jndi.ActiveMQInitialContextFactory</code></td><td>.</td></tr> |
| <tr><td>Provider URL</td><td><code>vm://localhost</code></td><td></td></tr> |
| <tr><td>Provider URL</td><td><code>vm:(broker:(vm://localhost)?persistent=false)</code></td><td>Disable persistence</td></tr> |
| <tr><td>Queue Reference</td><td><code>dynamicQueues/QUEUENAME</code></td> |
| <td><a href="http://activemq.apache.org/jndi-support.html#JNDISupport-Dynamicallycreatingdestinations">Dynamically define</a> the QUEUENAME to JNDI</td></tr> |
| <tr><td>Topic Reference</td><td><code>dynamicTopics/TOPICNAME</code></td> |
| <td><a href="http://activemq.apache.org/jndi-support.html#JNDISupport-Dynamicallycreatingdestinations">Dynamically define</a> the TOPICNAME to JNDI</td></tr> |
| </table> |
| </component> |
| |
| <component name="JMS Subscriber" index="§-num;.1.14" width="739" height="607" screenshot="jmssubscriber.png"> |
| <note>BETA CODE - the code is still subject to change</note> |
| <description> |
| <p> |
| JMS Publisher 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> |
| <br></br> |
| <note>JMeter does not include any JMS implementation jar; this must be downloaded from the JMS provider and put in the lib directory</note> |
| </description> |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="use JNDI properties file" required="Yes">use <code>jndi.properties</code>. |
| Note that the file must be on the classpath - e.g. by updating the <code>user.classpath</code> JMeter property. |
| If this option is not selected, JMeter uses the "<code>JNDI Initial Context Factory</code>" and "<code>Provider URL</code>" fields |
| to create the connection. |
| </property> |
| <property name="JNDI Initial Context Factory" required="No">Name of the context factory</property> |
| <property name="Provider URL" required="No">The URL for the jms provider</property> |
| <property name="Destination" required="Yes">the message destination (topic or queue name)</property> |
| <property name="Durable Subscription ID" required="No">The ID to use for a durable subscription. On first |
| use the respective queue will automatically be generated by the JMS provider if it does not exist yet.</property> |
| <property name="Client ID" required="No">The Client ID to use when you use a durable subscription. |
| Be sure to add a variable like <code>${__threadNum}</code> when you have more than one Thread.</property> |
| <property name="JMS Selector" required="No">Message Selector as defined by JMS specification to extract only |
| messages that respect the Selector condition. Syntax uses subpart of SQL 92.</property> |
| <property name="Setup" required="Yes">The destination setup type. With <code>At startup</code>, the destination name is static (i.e. always same name during the test), with <code>Each sample</code>, the destination name is dynamic and is evaluate at each sample (i.e. the destination name may be a variable)</property> |
| <property name="Authentication" required="Yes">Authentication requirement for the JMS provider</property> |
| <property name="User" required="No">User Name</property> |
| <property name="Password" required="No">Password (N.B. this is stored unencrypted in the test plan)</property> |
| <property name="Number of samples to aggregate" required="Yes">number of samples to aggregate</property> |
| <property name="Save response" required="Yes">should the sampler store the response. If not, only the response length is returned.</property> |
| <property name="Timeout" required="Yes">Specify the timeout to be applied, in milliseconds. <code>0</code>=none. |
| This is the overall aggregate timeout, not per sample.</property> |
| <property name="Client" required="Yes">Which client implementation to use. |
| Both of them create connections which can read messages. However they use a different strategy, as described below: |
| <dl> |
| <dt><code>MessageConsumer.receive()</code></dt><dd>calls <code>receive()</code> for every requested message. |
| Retains the connection between samples, but does not fetch messages unless the sampler is active. |
| This is best suited to Queue subscriptions. |
| </dd> |
| <dt><code>MessageListener.onMessage()</code></dt><dd>establishes a Listener that stores all incoming messages on a queue. |
| The listener remains active after the sampler completes. |
| This is best suited to Topic subscriptions.</dd> |
| </dl> |
| </property> |
| <property name="Stop between samples?" required="Yes"> |
| If selected, then JMeter calls <code>Connection.stop()</code> at the end of each sample (and calls <code>start()</code> before each sample). |
| This may be useful in some cases where multiple samples/threads have connections to the same queue. |
| If not selected, JMeter calls <code>Connection.start()</code> at the start of the thread, and does not call <code>stop()</code> until the end of the thread. |
| </property> |
| <property name="Separator" required="No"> |
| Separator used to separate messages when there is more than one (related to setting Number of samples to aggregate). |
| Note that <code>\n</code>, <code>\r</code>, <code>\t</code> are accepted. |
| </property> |
| </properties> |
| </component> |
| |
| <component name="JMS Point-to-Point" index="§-num;.1.15" width="882" height="804" screenshot="jms/JMS_Point-to-Point.png"> |
| <note>BETA CODE - the code is still subject to change</note> |
| <description> |
| <p> |
| This sampler sends and optionally receives JMS Messages through point-to-point connections (queues). |
| It is different from pub/sub messages and is generally used for handling transactions. |
| </p> |
| <p> |
| <code>Request Only</code> will typically be used to put load on a JMS System.<br></br> |
| <code>Request Response</code> 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></br> |
| </p> |
| <p> |
| JMeter use the properties <code>java.naming.security.[principal|credentials]</code> - if present - |
| when creating the Queue Connection. If this behaviour is not desired, set the JMeter property |
| <code>JMSSampler.useSecurity.properties=false</code> |
| </p> |
| <br></br> |
| <note>JMeter does not include any JMS implementation jar; this must be downloaded from the JMS provider and put in the lib directory</note> |
| </description> |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="QueueConnection Factory" required="Yes"> |
| The JNDI name of the queue connection factory to use for connecting to the messaging system. |
| </property> |
| <property name="JNDI Name Request queue" required="Yes"> |
| This is the JNDI name of the queue to which the messages are sent. |
| </property> |
| <property name="JNDI Name Reply queue" required="No"> |
| The JNDI name of the receiving queue. If a value is provided here and the communication style is <code>Request Response</code> |
| this queue will be monitored for responses to the requests sent. |
| </property> |
| <property name="JMS Selector" required="No"> |
| Message Selector as defined by JMS specification to extract only |
| messages that respect the Selector condition. Syntax uses subpart of SQL 92. |
| </property> |
| <property name="Communication style" required="Yes"> |
| The Communication style can be <code>Request Only</code> (also known as Fire and Forget) or <code>Request Response</code>: |
| <dl> |
| <dt><code>Request Only</code></dt><dd> will only send messages and will not monitor replies. As such it can be used to put load on a system.</dd> |
| <dt><code>Request Response</code></dt><dd> will send messages and monitor the replies it receives. Behaviour depends on the value of the JNDI Name Reply Queue. |
| If JNDI Name Reply Queue has a value, this queue is used to monitor the results. Matching of request and reply is done with |
| the message id of the request and the correlation id of the reply. If the JNDI Name Reply Queue is empty, then |
| temporary queues will be used for the communication between the requestor and the server. |
| This is very different from the fixed reply queue. With temporary queues the sending thread will block until the reply message has been received. |
| With <code>Request Response</code> mode, you need to have a Server that listens to messages sent to Request Queue and sends replies to |
| queue referenced by <code>message.getJMSReplyTo()</code>.</dd> |
| </dl> |
| </property> |
| <property name="Use alternate fields for message correlation" required="Yes"> |
| These check-boxes select the fields which will be used for matching the response message with the original request. |
| <dl> |
| <dt><code>Use Request Message Id</code></dt><dd>if selected, the request JMSMessageID will be used, |
| otherwise the request JMSCorrelationID will be used. |
| In the latter case the correlation id must be specified in the request.</dd> |
| <dt><code>Use Response Message Id</code></dt><dd>if selected, the response JMSMessageID will be used, |
| otherwise the response JMSCorrelationID will be used. |
| </dd> |
| </dl> |
| There are two frequently used JMS Correlation patterns: |
| <dl> |
| <dt>JMS Correlation ID Pattern</dt> |
| <dd> i.e. match request and response on their correlation Ids |
| => deselect both checkboxes, and provide a correlation id.</dd> |
| <dt>JMS Message ID Pattern</dt> |
| <dd>i.e. match request message id with response correlation id |
| => select "Use Request Message Id" only. |
| </dd> |
| </dl> |
| In both cases the JMS application is responsible for populating the correlation ID as necessary. |
| <note>if the same queue is used to send and receive messages, |
| then the response message will be the same as the request message. |
| In which case, either provide a correlation id and clear both checkboxes; |
| or select both checkboxes to use the message Id for correlation. |
| This can be useful for checking raw JMS throughput.</note> |
| </property> |
| <property name="Timeout" required="Yes"> |
| 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 <code>2000</code> ms. |
| </property> |
| <property name="Expiration" required="No"> |
| The expiration time (in milliseconds) of the message before it becomes obsolete. |
| If you do not specify an expiration time, the default value is <code>0</code> (never expires). |
| </property> |
| <property name="Priority" required="No"> |
| The priority level of the message. There are ten priority levels from <code>0</code> (lowest) to <code>9</code> (highest). |
| If you do not specify a priority level, the default level is <code>4</code>. |
| </property> |
| <property name="Use non-persistent delivery mode?" required="Yes"> |
| Whether to set <code>DeliveryMode.NON_PERSISTENT</code>. |
| </property> |
| <property name="Content" required="No"> |
| The content of the message. |
| </property> |
| <property name="JMS Properties" required="No"> |
| The JMS Properties are properties specific for the underlying messaging system. |
| You can setup the name, the value and the class (type) of value. Default type is <code>String</code>. |
| For example: for WebSphere 5.1 web services you will need to set the JMS Property targetService to test |
| webservices through JMS. |
| </property> |
| <property name="Initial Context Factory" required="No"> |
| The Initial Context Factory is the factory to be used to look up the JMS Resources. |
| </property> |
| <property name="JNDI properties" required="No"> |
| The JNDI Properties are the specific properties for the underlying JNDI implementation. |
| </property> |
| <property name="Provider URL" required="No"> |
| The URL for the jms provider. |
| </property> |
| </properties> |
| </component> |
| |
| |
| |
| <component name="JUnit Request" index="§-num;.1.16" width="397" height="536" screenshot="junit_sampler.png"> |
| <description> |
| The current implementation supports standard JUnit convention and extensions. It also |
| includes extensions like <code>oneTimeSetUp</code> and <code>oneTimeTearDown</code>. The sampler works like the |
| <complink name="Java Request" /> with some differences. |
| <ul> |
| <li>rather than use Jmeter's test interface, it scans the jar files for classes extending JUnit's <code>TestCase</code> class. That includes any class or subclass.</li> |
| <li>JUnit test jar files should be placed in <code>jmeter/lib/junit</code> instead of <code>/lib</code> directory. |
| You can also use the "<code>user.classpath</code>" property to specify where to look for <code>TestCase</code> classes.</li> |
| <li>JUnit sampler does not use name/value pairs for configuration like the <complink name="Java Request" />. The sampler assumes <code>setUp</code> and <code>tearDown</code> will configure the test correctly.</li> |
| <li>The sampler measures the elapsed time only for the test method and does not include <code>setUp</code> and <code>tearDown</code>.</li> |
| <li>Each time the test method is called, Jmeter will pass the result to the listeners.</li> |
| <li>Support for <code>oneTimeSetUp</code> and <code>oneTimeTearDown</code> is done as a method. Since Jmeter is multi-threaded, we cannot call <code>oneTimeSetUp</code>/<code>oneTimeTearDown</code> the same way Maven does it.</li> |
| <li>The sampler reports unexpected exceptions as errors. |
| There are some important differences between standard JUnit test runners and JMeter's |
| implementation. Rather than make a new instance of the class for each test, JMeter |
| creates 1 instance per sampler and reuses it. |
| This can be changed with checkbox "<code>Create a new instance per sample</code>".</li> |
| </ul> |
| The current implementation of the sampler will try to create an instance using the string constructor first. If the test class does not declare a string constructor, the sampler will look for an empty constructor. Example below: |
| <example title="JUnit Constructors" anchor="junit_constructor_example"> |
| Empty Constructor: |
| <source> |
| public class myTestCase { |
| public myTestCase() {} |
| } |
| </source> |
| String Constructor: |
| <source> |
| public class myTestCase { |
| public myTestCase(String text) { |
| super(text); |
| } |
| } |
| </source> |
| </example> |
| By default, Jmeter will provide some default values for the success/failure code and message. Users should define a set of unique success and failure codes and use them uniformly across all tests. |
| <note> |
| <h3>General Guidelines</h3> |
| If you use <code>setUp</code> and <code>tearDown</code>, make sure the methods are declared public. If you do not, the test may not run properly. |
| <br></br> |
| Here are some general guidelines for writing JUnit tests so they work well with Jmeter. Since Jmeter runs multi-threaded, it is important to keep certain things in mind. |
| <ul> |
| <li>Write the <code>setUp</code> and <code>tearDown</code> methods so they are thread safe. This generally means avoid using static members.</li> |
| <li>Make the test methods discrete units of work and not long sequences of actions. By keeping the test method to a discrete operation, it makes it easier to combine test methods to create new test plans.</li> |
| <li>Avoid making test methods depend on each other. Since Jmeter allows arbitrary sequencing of test methods, the runtime behavior is different than the default JUnit behavior.</li> |
| <li>If a test method is configurable, be careful about where the properties are stored. Reading the properties from the Jar file is recommended.</li> |
| <li>Each sampler creates an instance of the test class, so write your test so the setup happens in <code>oneTimeSetUp</code> and <code>oneTimeTearDown</code>.</li> |
| </ul> |
| </note> |
| </description> |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Search for JUnit4 annotations" required="Yes">Select this to search for JUnit4 tests (<code>@Test</code> annotations)</property> |
| <property name="Package filter" required="">Comma separated list of packages to show. Example, <code>org.apache.jmeter</code>,<code>junit.framework</code>.</property> |
| <property name="Class name" required="Yes">Fully qualified name of the JUnit test class.</property> |
| <property name="Constructor string" required="">String pass to the string constructor. If a string is set, the sampler will use the |
| string constructor instead of the empty constructor.</property> |
| <property name="Test method" required="Yes">The method to test.</property> |
| <property name="Success message" required="">A descriptive message indicating what success means.</property> |
| <property name="Success code" required="">An unique code indicating the test was successful.</property> |
| <property name="Failure message" required="">A descriptive message indicating what failure means.</property> |
| <property name="Failure code" required="">An unique code indicating the test failed.</property> |
| <property name="Error message" required="">A description for errors.</property> |
| <property name="Error code" required="">Some code for errors. Does not need to be unique.</property> |
| <property name="Do not call setUp and tearDown" required="Yes">Set the sampler not to call <code>setUp</code> and <code>tearDown</code>. |
| By default, <code>setUp</code> and <code>tearDown</code> should be called. Not calling those methods could affect the test and make it inaccurate. |
| This option should only be used with calling <code>oneTimeSetUp</code> and <code>oneTimeTearDown</code>. If the selected method is <code>oneTimeSetUp</code> or <code>oneTimeTearDown</code>, |
| this option should be checked.</property> |
| <property name="Append assertion errors" required="Yes">Whether or not to append assertion errors to the response message.</property> |
| <property name="Append runtime exceptions" required="Yes">Whether or not to append runtime exceptions to the response message. Only applies if "<code>Append assertion errors</code>" is not selected.</property> |
| <property name="Create a new Instance per sample" required="Yes">Whether or not to create a new JUnit instance for each sample. Defaults to false, meaning JUnit <code>TestCase</code> is created one and reused.</property> |
| </properties> |
| <p> |
| The following JUnit4 annotations are recognised: |
| </p> |
| <dl> |
| <dt><code>@Test</code></dt><dd>used to find test methods and classes. The "<code>expected</code>" and "<code>timeout</code>" attributes are supported.</dd> |
| <dt><code>@Before</code></dt><dd>treated the same as <code>setUp()</code> in JUnit3</dd> |
| <dt><code>@After</code></dt><dd>treated the same as <code>tearDown()</code> in JUnit3</dd> |
| <dt><code>@BeforeClass</code>, <code>@AfterClass</code></dt><dd>treated as test methods so they can be run independently as required</dd> |
| </dl> |
| <note> |
| Note that JMeter currently runs the test methods directly, rather than leaving it to JUnit. |
| This is to allow the <code>setUp</code>/<code>tearDown</code> methods to be excluded from the sample time. |
| </note> |
| </component> |
| |
| <component name="Mail Reader Sampler" index="§-num;.1.17" width="547" height="409" screenshot="mailreader_sampler.png"> |
| <description> |
| <p> |
| The Mail Reader Sampler can read (and optionally delete) mail messages using POP3(S) or IMAP(S) protocols. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Server Type" required="Yes">The protocol used by the provider: e.g. <code>pop3</code>, <code>pop3s</code>, <code>imap</code>, <code>imaps</code>. |
| or another string representing the server protocol. |
| For example <code>file</code> for use with the read-only mail file provider. |
| The actual provider names for POP3 and IMAP are <code>pop3</code> and <code>imap</code> |
| </property> |
| <property name="Server" required="Yes">Hostname or IP address of the server. See below for use with <code>file</code> protocol.</property> |
| <property name="Port" required="No">Port to be used to connect to the server (optional)</property> |
| <property name="Username" required="">User login name</property> |
| <property name="Password" required="">User login password (N.B. this is stored unencrypted in the test plan)</property> |
| <property name="Folder" required="Yes, if using IMAP(S)">The IMAP(S) folder to use. See below for use with <code>file</code> protocol.</property> |
| <property name="Number of messages to retrieve" required="Yes">Set this to retrieve all or some messages</property> |
| <property name="Fetch headers only" required="Yes">If selected, only the message headers will be retrieved.</property> |
| <property name="Delete messages from the server" required="Yes">If set, messages will be deleted after retrieval</property> |
| <property name="Store the message using MIME" required="Yes">Whether to store the message as MIME. |
| If so, then the entire raw message is stored in the Response Data; the headers are not stored as they are available in the data. |
| If not, the message headers are stored as Response Headers. |
| A few headers are stored (<code>Date</code>, <code>To</code>, <code>From</code>, <code>Subject</code>) in the body. |
| </property> |
| <property name="Use no security features" required="">Indicates that the connection to the server does not use any security protocol.</property> |
| <property name="Use SSL" required="">Indicates that the connection to the server must use the SSL protocol.</property> |
| <property name="Use StartTLS" required="">Indicates that the connection to the server should attempt to start the TLS protocol.</property> |
| <property name="Enforce StartTLS" required="">If the server does not start the TLS protocol the connection will be terminated.</property> |
| <property name="Trust All Certificates" required="">When selected it will accept all certificates independent of the CA.</property> |
| <property name="Use local truststore" required="">When selected it will only accept certificates that are locally trusted.</property> |
| <property name="Local truststore" required="">Path to file containing the trusted certificates. |
| Relative paths are resolved against the current directory. |
| <br />Failing that, against the directory containing the test script (JMX file). |
| </property> |
| </properties> |
| <p> |
| Messages are stored as subsamples of the main sampler. |
| Multipart message parts are stored as subsamples of the message. |
| </p> |
| <p> |
| <b>Special handling for "<code>file</code>" protocol:</b><br></br> |
| The <code>file</code> JavaMail provider can be used to read raw messages from files. |
| The <code>server</code> field is used to specify the path to the parent of the <code>folder</code>. |
| Individual message files should be stored with the name <code>n.msg</code>, |
| where <code>n</code> is the message number. |
| Alternatively, the <code>server</code> field can be the name of a file which contains a single message. |
| The current implementation is quite basic, and is mainly intended for debugging purposes. |
| </p> |
| </component> |
| |
| <component name="Test Action" index="§-num;.1.18" width="467" height="184" screenshot="test_action.png"> |
| <description> |
| The Test Action sampler is a sampler that is intended for use in a conditional controller. |
| Rather than generate a sample, the test element either pauses or stops the selected target. |
| <p>This sampler can also be useful in conjunction with the Transaction Controller, as it allows |
| pauses to be included without needing to generate a sample. |
| For variable delays, set the pause time to zero, and add a Timer as a child.</p> |
| <p> |
| The "<code>Stop</code>" action stops the thread or test after completing any samples that are in progress. |
| The "<code>Stop Now</code>" action stops the test without waiting for samples to complete; it will interrupt any active samples. |
| If some threads fail to stop within the 5 second time-limit, a message will be displayed in GUI mode. |
| You can try using the <code>Stop</code> command to see if this will stop the threads, but if not, you should exit JMeter. |
| In non-GUI mode, JMeter will exit if some threads fail to stop within the 5 second time limit. |
| <note>The time to wait can be changed using the JMeter property <code>jmeterengine.threadstop.wait</code>. The time is given in milliseconds.</note> |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Target" required="Yes"><code>Current Thread</code> / <code>All Threads</code> (ignored for Pause)</property> |
| <property name="Action" required="Yes"><code>Pause</code> / <code>Stop</code> / <code>Stop Now</code> / <code>Go to next loop iteration</code></property> |
| <property name="Duration" required="Yes, if Pause is selected">How long to pause for (milliseconds)</property> |
| </properties> |
| </component> |
| |
| |
| <component name="SMTP Sampler" index="§-num;.1.19" width="825" height="728" screenshot="smtp_sampler.png"> |
| <description> |
| <p> |
| The SMTP Sampler can send mail messages using SMTP/SMTPS protocol. |
| It is possible to set security protocols for the connection (SSL and TLS), as well as user authentication. |
| If a security protocol is used a verification on the server certificate will occur. <br></br> |
| Two alternatives to handle this verification are available:<br></br> |
| </p> |
| <dl> |
| <dt><code>Trust all certificates</code></dt><dd>This will ignore certificate chain verification</dd> |
| <dt><code>Use a local truststore</code></dt><dd>With this option the certificate chain will be validated against the local truststore file.</dd> |
| </dl> |
| </description> |
| <properties> |
| <property name="Server" required="Yes">Hostname or IP address of the server. See below for use with <code>file</code> protocol.</property> |
| <property name="Port" required="No">Port to be used to connect to the server. |
| Defaults are: SMTP=25, SSL=465, StartTLS=587 |
| </property> |
| <property name="Connection timeout" required="No">Connection timeout value in milliseconds (socket level). Default is infinite timeout.</property> |
| <property name="Read timeout" required="No">Read timeout value in milliseconds (socket level). Default is infinite timeout.</property> |
| <property name="Address From" required="Yes">The from address that will appear in the e-mail</property> |
| <property name="Address To" required="Yes, unless CC or BCC is specified">The destination e-mail address (multiple values separated by "<code>;</code>")</property> |
| <property name="Address To CC" required="No">Carbon copy destinations e-mail address (multiple values separated by "<code>;</code>")</property> |
| <property name="Address To BCC" required="No">Blind carbon copy destinations e-mail address (multiple values separated by "<code>;</code>")</property> |
| <property name="Address Reply-To" required="No">Alternate Reply-To address (multiple values separated by "<code>;</code>")</property> |
| <property name="Use Auth" required="">Indicates if the SMTP server requires user authentication</property> |
| <property name="Username" required="">User login name</property> |
| <property name="Password" required="">User login password (N.B. this is stored unencrypted in the test plan)</property> |
| <property name="Use no security features" required="">Indicates that the connection to the SMTP server does not use any security protocol.</property> |
| <property name="Use SSL" required="">Indicates that the connection to the SMTP server must use the SSL protocol.</property> |
| <property name="Use StartTLS" required="">Indicates that the connection to the SMTP server should attempt to start the TLS protocol.</property> |
| <property name="Enforce StartTLS" required="">If the server does not start the TLS protocol the connection will be terminated.</property> |
| <property name="Trust All Certificates" required="">When selected it will accept all certificates independent of the CA.</property> |
| <property name="Use local truststore" required="">When selected it will only accept certificates that are locally trusted.</property> |
| <property name="Local truststore" required="">Path to file containing the trusted certificates. |
| Relative paths are resolved against the current directory. |
| <br />Failing that, against the directory containing the test script (JMX file). |
| </property> |
| <property name="Subject" required="">The e-mail message subject.</property> |
| <property name="Suppress Subject Header" required="">If selected, the "<code>Subject:</code>" header is omitted from the mail that is sent. |
| This is different from sending an empty "<code>Subject:</code>" header, though some e-mail clients may display it identically.</property> |
| <property name="Include timestamp in subject" required="">Includes the <code>System.currentTimemillis()</code> in the subject line.</property> |
| <property name="Add Header" required="No">Additional headers can be defined using this button.</property> |
| <property name="Message" required="">The message body.</property> |
| <property name="Send plain body (i.e. not multipart/mixed)"> |
| If selected, then send the body as a plain message, i.e. not <code>multipart/mixed</code>, if possible. |
| If the message body is empty and there is a single file, then send the file contents as the message body. |
| <note> |
| Note: If the message body is not empty, and there is at least one attached file, then the body is sent as <code>multipart/mixed</code>. |
| </note> |
| </property> |
| <property name="Attach files" required="">Files to be attached to the message.</property> |
| <property name="Send .eml" required="">If set, the <code>.eml</code> file will be sent instead of the entries in the <code>Subject</code>, <code>Message</code>, and <code>Attach file(s)</code> fields</property> |
| <property name="Calculate message size" required="">Calculates the message size and stores it in the sample result.</property> |
| <property name="Enable debug logging?" required="">If set, then the "<code>mail.debug</code>" property is set to "<code>true</code>"</property> |
| </properties> |
| </component> |
| |
| <component name="OS Process Sampler" index="§-num;.1.20" width="683" height="582" screenshot="os_process_sampler.png"> |
| <description> |
| <p> |
| The OS Process Sampler is a sampler that can be used to execute commands on the local machine.<br></br> |
| It should allow execution of any command that can be run from the command line.<br></br> |
| Validation of the return code can be enabled, and the expected return code can be specified.<br></br> |
| </p> |
| <p> |
| Note that OS shells generally provide command-line parsing. |
| This varies between OSes, but generally the shell will split parameters on white-space. |
| Some shells expand wild-card file names; some don't. |
| The quoting mechanism also varies between OSes. |
| The sampler deliberately does not do any parsing or quote handling. |
| The command and its parameters must be provided in the form expected by the executable. |
| This means that the sampler settings will not be portable between OSes. |
| </p> |
| <p> |
| Many OSes have some built-in commands which are not provided as separate executables. |
| For example the Windows <code>DIR</code> command is part of the command interpreter (<code>CMD.EXE</code>). |
| These built-ins cannot be run as independent programs, but have to be provided as arguments to the appropriate command interpreter. |
| </p> |
| <p> |
| For example, the Windows command-line: <code>DIR C:\TEMP</code> needs to be specified as follows: |
| </p> |
| <dl> |
| <dt>Command:</dt><dd><code>CMD</code></dd> |
| <dt>Param 1:</dt><dd><code>/C</code></dd> |
| <dt>Param 2:</dt><dd><code>DIR</code></dd> |
| <dt>Param 3:</dt><dd><code>C:\TEMP</code></dd> |
| </dl> |
| </description> |
| <properties> |
| <property name="Command" required="Yes">The program name to execute.</property> |
| <property name="Working directory" required="No">Directory from which command will be executed, defaults to folder referenced by "<code>user.dir</code>" System property</property> |
| <property name="Command Parameters" required="No">Parameters passed to the program name.</property> |
| <property name="Environment Parameters" required="No">Key/Value pairs added to environment when running command.</property> |
| <property name="Standard input (stdin)" required="No">Name of file from which input is to be taken (<code>STDIN</code>).</property> |
| <property name="Standard output (stdout" required="No">Name of output file for standard output (<code>STDOUT</code>). |
| If omitted, output is captured and returned as the response data.</property> |
| <property name="Standard error (stderr)" required="No">Name of output file for standard error (<code>STDERR</code>). |
| If omitted, output is captured and returned as the response data.</property> |
| <property name="Check Return Code" required="No">If checked, sampler will compare return code with <code>Expected Return Code</code>.</property> |
| <property name="Expected Return Code" required="No">Expected return code for System Call, required if "<code>Check Return Code</code>" is checked.</property> |
| <property name="Timeout" required="No">Timeout for command in milliseconds, defaults to <code>0</code>, which means <em>no</em> timeout. |
| If the timeout expires before the command finishes, JMeter will attempt to kill the OS process. |
| </property> |
| </properties> |
| </component> |
| |
| <component name="MongoDB Script (DEPRECATED)" index="§-num;.1.21" width="847" height="635" screenshot="mongodb-script.png"> |
| <description><p>This sampler lets you send a Request to a MongoDB.</p> |
| <p>Before using this you need to set up a |
| <complink name="MongoDB Source Config"/> Configuration element |
| </p> |
| <note>This Element currently uses <code>com.mongodb.DB#eval</code> which takes a global write lock causing a performance impact on the database, see <a href="http://docs.mongodb.org/manual/reference/method/db.eval/"><code>db.eval()</code></a>. |
| So it is better to avoid using this element for load testing and use JSR223+Groovy scripting using <a href="../api/org/apache/jmeter/protocol/mongodb/config/MongoDBHolder.html">MongoDBHolder</a> instead. |
| MongoDB Script is more suitable for functional testing or test setup (setup/teardown threads)</note> |
| </description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this sampler that is shown in the tree.</property> |
| <property name="MongoDB Source" required="Yes"> |
| Name of the JMeter variable that the MongoDB connection is bound to. |
| This must agree with the '<code>MongoDB Source</code>' field of a MongoDB Source Config. |
| </property> |
| <property name="Database Name" required="Yes">Database Name, will be used in your script |
| </property> |
| <property name="Username" required="No"> |
| </property> |
| <property name="Password" required="No"> |
| </property> |
| <property name="Script" required="Yes"> |
| Mongo script as it would be used in MongoDB shell |
| </property> |
| </properties> |
| |
| <links> |
| <complink name="MongoDB Source Config"/> |
| </links> |
| <note>Ensure Variable Name is unique across Test Plan.</note> |
| </component> |
| |
| <a href="#">^</a> |
| |
| </section> |
| |
| <section name="§-num;.2 Logic Controllers" anchor="logic_controllers"> |
| <description> |
| <br>Logic Controllers determine the order in which Samplers are processed.</br> |
| </description> |
| |
| <component name="Simple Controller" index="§-num;.2.1" anchor="simple_controller" width="330" height="77" screenshot="logic-controller/simple-controller.png"> |
| <description> |
| <p>The Simple Logic Controller lets you organize your Samplers and other |
| Logic Controllers. Unlike other Logic Controllers, this controller provides no functionality beyond that of a |
| storage device.</p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property> |
| </properties> |
| |
| <example title="Using the Simple Controller" anchor="simple_controller_example"> |
| <p><a href="../demos/SimpleTestPlan.jmx">Download</a> this example (see Figure 6). |
| In this example, we created a Test Plan that sends two Ant HTTP requests and two |
| Log4J HTTP requests. We grouped the Ant and Log4J requests by placing them inside |
| Simple Logic Controllers. Remember, the Simple Logic Controller has no effect on how JMeter |
| processes the controller(s) you add to it. So, in this example, JMeter sends the requests in the |
| following order: Ant Home Page, Ant News Page, Log4J Home Page, Log4J History Page.</p> |
| <p> |
| Note, the File Reporter |
| is configured to store the results in a file named "<code>simple-test.dat</code>" in the current directory.</p> |
| <figure width="585" height="213" image="logic-controller/simple-example.png">Figure 6 Simple Controller Example</figure> |
| |
| </example> |
| </component> |
| |
| <component name="Loop Controller" index="§-num;.2.2" anchor="loop" width="326" height="114" screenshot="logic-controller/loop-controller.png"> |
| <description><p>If you add Generative or Logic Controllers to a Loop Controller, JMeter will |
| loop through them a certain number of times, in addition to the loop value you |
| 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 <code>2 * 3 = 6</code> HTTP Requests. |
| </p></description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property> |
| <property name="Loop Count" required="Yes, unless "Forever" is checked"> |
| The number of times the subelements of this controller will be iterated each time |
| through a test run. |
| <p>The value <code>-1</code> is equivalent to checking the <code>Forever</code> toggle.</p> |
| <p><b>Special Case:</b> The Loop Controller embedded in the <a href="test_plan.html#thread_group">Thread Group</a> |
| element behaves slightly different. Unless set to forever, it stops the test after |
| the given number of iterations have been done.</p> |
| <note>When using a function in this field, be aware it may be evaluated multiple times. |
| Example using <code>__Random</code> will evaluate it to a different value for each child samplers of Loop Controller and result into unwanted behaviour.</note></property> |
| </properties> |
| |
| <example title="Looping Example" anchor="loop_example"> |
| |
| <p><a href="../demos/LoopTestPlan.jmx">Download</a> this example (see Figure 4). |
| In this example, we created a Test Plan that sends a particular HTTP Request |
| only once and sends another HTTP Request five times.</p> |
| |
| <figure width="506" height="158" image="logic-controller/loop-example.png">Figure 4 - Loop Controller Example</figure> |
| |
| <p>We configured the Thread Group for a single thread and a loop count value of |
| one. Instead of letting the Thread Group control the looping, we used a Loop |
| Controller. You can see that we added one HTTP Request to the Thread Group and |
| another HTTP Request to a Loop Controller. We configured the Loop Controller |
| with a loop count value of five.</p> |
| <p>JMeter will send the requests in the following order: Home Page, News Page, |
| News Page, News Page, News Page, and News Page.</p> |
| <note>Note, the File Reporter |
| is configured to store the results in a file named "<code>loop-test.dat</code>" in the current directory.</note> |
| |
| </example> |
| |
| </component> |
| |
| <component name="Once Only Controller" index="§-num;.2.3" anchor="once_only_controller" width="330" height="78" screenshot="logic-controller/once-only-controller.png"> |
| <description> |
| <p>The Once Only Logic Controller tells JMeter to process the controller(s) inside it only once per Thread, and pass over any requests under it |
| during further iterations through the test plan.</p> |
| |
| <p>The Once Only Controller will now execute always during the first iteration of any looping parent controller. |
| Thus, if the Once Only Controller is placed under a Loop Controller specified to loop 5 times, then the Once Only Controller will execute only on the first iteration through the Loop Controller |
| (i.e. every 5 times).</p> |
| <p> |
| Note this means the Once Only Controller will still behave as previously expected if put under a Thread Group (runs only once per test per Thread), |
| but now the user has more flexibility in the use of the Once Only Controller.</p> |
| |
| <p>For testing that requires a login, consider placing the login request in this controller since each thread only needs |
| to login once to establish a session.</p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property> |
| </properties> |
| |
| <example title="Once Only Example" anchor="once_only_example"> |
| <p><a href="../demos/OnceOnlyTestPlan.jmx">Download</a> this example (see Figure 5). |
| In this example, we created a Test Plan that has two threads that send HTTP request. |
| Each thread sends one request to the Home Page, followed by three requests to the Bug Page. |
| Although we configured the Thread Group to iterate three times, each JMeter thread only |
| sends one request to the Home Page because this request lives inside a Once Only Controller.</p> |
| <figure width="233" height="138" image="logic-controller/once-only-example.png">Figure 5. Once Only Controller Example</figure> |
| <p>Each JMeter thread will send the requests in the following order: Home Page, Bug Page, |
| Bug Page, Bug Page.</p> |
| <p>Note, the File Reporter is configured to store the results in a file named "<code>loop-test.dat</code>" in the current directory.</p> |
| |
| </example> |
| <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.</note> |
| </component> |
| |
| <component name="Interleave Controller" index="§-num;.2.4" width="329" height="104" screenshot="logic-controller/interleave-controller.png"> |
| <description><p>If you add Generative or Logic Controllers to an Interleave Controller, JMeter will alternate among each of the |
| other controllers for each loop iteration. </p> |
| </description> |
| <properties> |
| <property name="name" required="No">Descriptive name for this controller that is shown in the tree.</property> |
| <property name="ignore sub-controller blocks" required="No">If checked, the interleave controller will treat sub-controllers like single request elements and only allow one request per controller at a time. </property> |
| </properties> |
| |
| <!-- |
| For example, if you |
| add three HTTP Requests to an Interleave Controller and configure the Thread |
| Group to loop, here is the sequence in which JMeter sends the requests: |
| </p> |
| <table border="1" cellspacing="0" cellpadding="4"> |
| <tr valign="top"><th>Loop Iteration</th><th>Description</th></tr> |
| <tr valign="top"><td>1</td><td>JMeter sends the first HTTP Request.</td></tr> |
| <tr valign="top"><td>2</td><td>JMeter sends the second HTTP Request.</td></tr> |
| <tr valign="top"><td>3</td><td>JMeter sends the third HTTP Request.</td></tr> |
| <tr valign="top"><td>4</td><td>Because there are no more requests in controller, JMeter start over and sends the first HTTP Request.</td></tr> |
| <tr valign="top"><td>5</td><td>JMeter sends the second HTTP Request.</td></tr> |
| <tr valign="top"><td>(and so on)</td><td>…</td></tr> |
| </table> |
| --> |
| <example title="Simple Interleave Example" anchor="simple_interleave_example"> |
| |
| <p><a href="../demos/InterleaveTestPlan.jmx">Download</a> this example (see Figure 1). In this example, |
| we configured the Thread Group to have two threads and a loop count of five, for a total of ten |
| requests per thread. See the table below for the sequence JMeter sends the HTTP Requests.</p> |
| |
| <figure width="231" height="153" image="logic-controller/interleave.png">Figure 1 - Interleave Controller Example 1</figure> |
| |
| <table border="1" cellspacing="0" cellpadding="4"> |
| <tr valign="top"><th>Loop Iteration</th><th>Each JMeter Thread Sends These HTTP Requests</th></tr> |
| <tr valign="top"><td>1</td><td>News Page</td></tr> |
| <tr valign="top"><td>1</td><td>Log Page</td></tr> |
| <tr valign="top"><td>2</td><td>FAQ Page</td></tr> |
| <tr valign="top"><td>2</td><td>Log Page</td></tr> |
| <tr valign="top"><td>3</td><td>Gump Page</td></tr> |
| <tr valign="top"><td>3</td><td>Log Page</td></tr> |
| <tr valign="top"><td>4</td><td>Because there are no more requests in the controller,<br> </br> JMeter starts over and sends the first HTTP Request, which is the News Page.</td></tr> |
| <tr valign="top"><td>4</td><td>Log Page</td></tr> |
| <tr valign="top"><td>5</td><td>FAQ Page</td></tr> |
| <tr valign="top"><td>5</td><td>Log Page</td></tr> |
| </table> |
| |
| |
| </example> |
| |
| <example title="Useful Interleave Example" anchor="useful_interleave_example"> |
| |
| <p><a href="../demos/InterleaveTestPlan2.jmx">Download</a> another example (see Figure 2). In this |
| example, we configured the Thread Group |
| to have a single thread and a loop count of eight. Notice that the Test Plan has an outer Interleave Controller with |
| two Interleave Controllers inside of it.</p> |
| |
| <figure width="251" height="250" image="logic-controller/interleave2.png"> |
| Figure 2 - Interleave Controller Example 2 |
| </figure> |
| |
| <p>The outer Interleave Controller alternates between the |
| two inner ones. Then, each inner Interleave Controller alternates between each of the HTTP Requests. Each JMeter |
| thread will send the requests in the following order: Home Page, Interleaved, Bug Page, Interleaved, CVS Page, Interleaved, and FAQ Page, Interleaved.</p> |
| <p>Note, the File Reporter is configured to store the results in a file named "<code>interleave-test2.dat</code>" in the current directory.</p> |
| |
| <figure width="257" height="253" image="logic-controller/interleave3.png"> |
| Figure 3 - Interleave Controller Example 3 |
| </figure> |
| <p>If the two interleave controllers under the main interleave controller were instead simple controllers, then the order would be: Home Page, CVS Page, Interleaved, Bug Page, FAQ Page, Interleaved.</p> |
| <p>However, if "<code>ignore sub-controller blocks</code>" was checked on the main interleave controller, then the order would be: Home Page, Interleaved, Bug Page, Interleaved, CVS Page, Interleaved, and FAQ Page, Interleaved.</p> |
| </example> |
| </component> |
| |
| <component name="Random Controller" index="§-num;.2.5" width="328" height="100" screenshot="logic-controller/random-controller.png"> |
| <description> |
| <p>The Random Logic Controller acts similarly to the Interleave Controller, except that |
| instead of going in order through its sub-controllers and samplers, it picks one |
| at random at each pass.</p> |
| <note>Interactions between multiple controllers can yield complex behavior. |
| This is particularly true of the Random Controller. Experiment before you assume |
| what results any given interaction will give</note> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property> |
| <property name="ignore sub-controller blocks" required="No">If checked, the interleave controller will treat sub-controllers like single request elements and only allow one request per controller at a time. </property> |
| </properties> |
| |
| </component> |
| |
| |
| |
| <component name="Random Order Controller" index="§-num;.2.6" width="328" height="76" screenshot="randomordercontroller.png"> |
| <description> |
| <p>The Random Order Controller is much like a Simple Controller in that it will execute each child |
| element at most once, but the order of execution of the nodes will be random.</p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property> |
| </properties> |
| </component> |
| |
| <component name="Throughput Controller" index="§-num;.2.7" width="329" height="167" screenshot="throughput_controller.png"> |
| <description> |
| <p> |
| <b>This controller is badly named, as it does not control throughput.</b> |
| Please refer to the <complink name="Constant Throughput Timer"/> for an element that can be used to adjust the throughput. |
| </p> |
| <p>The Throughput Controller allows the user to control how often it is executed. There are two modes - percent execution and total executions.</p> |
| <dl> |
| <dt><code>Percent executions</code></dt><dd>causes the controller to execute a certain percentage of the iterations through the test plan.</dd> |
| <dt><code>Total executions</code></dt><dd>causes the controller to stop executing after a certain number of executions have occurred.</dd> |
| </dl> |
| <p> |
| Like the Once Only Controller, this |
| setting is reset when a parent Loop Controller restarts. |
| </p> |
| </description> |
| <note>The Throughput Controller can yield very complex behavior when combined with other controllers - in particular with interleave or random controllers as parents (also very useful).</note> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property> |
| <property name="Execution Style" required="Yes">Whether the controller will run in percent executions or total executions mode.</property> |
| <property name="Throughput" required="Yes">A number. For percent execution mode, a number from <code>0</code>-<code>100</code> that indicates the percentage of times the controller will execute. "<code>50</code>" means the controller will execute during half the iterations through the test plan. For total execution mode, the number indicates the total number of times the controller will execute.</property> |
| <property name="Per User" required="No">If checked, per user will cause the controller to calculate whether it should execute on a per user (per thread) basis. If unchecked, then the calculation will be global for all users. For example, if using total execution mode, and uncheck "<code>per user</code>", then the number given for throughput will be the total number of executions made. If "<code>per user</code>" is checked, then the total number of executions would be the number of users times the number given for throughput.</property> |
| </properties> |
| |
| </component> |
| |
| <component name="Runtime Controller" index="§-num;.2.8" width="328" height="100" screenshot="runtimecontroller.png"> |
| <description> |
| <p>The Runtime Controller controls how long its children are allowed to run. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="Yes">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</property> |
| <property name="Runtime (seconds)" required="Yes">Desired runtime in seconds</property> |
| </properties> |
| </component> |
| |
| <component name="If Controller" index="§-num;.2.9" width="497" height="131" screenshot="ifcontroller.png"> |
| <description> |
| <p>The If Controller allows the user to control whether the test elements below it (its children) are run or not.</p> |
| <p> |
| By default, the condition is evaluated only once on initial entry, but you have the option to have it evaluated for every runnable element contained in the controller. |
| </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 "<code>true</code>" or "<code>false</code>"; |
| now this can be done without the overhead of using Javascript as well. For example, previously one could use the condition: |
| <code>${__jexl(${VAR} == 23)}</code> and this would be evaluated as <code>true</code>/<code>false</code>, the result would then be passed to Javascript |
| which would then return <code>true</code>/<code>false</code>. If the Variable Expression option is selected, then the expression is evaluated |
| and compared with "<code>true</code>", without needing to use Javascript. |
| Also, variable expressions can return any value, whereas the |
| Javascript condition must return "<code>true</code>"/"<code>false</code>" or an error is logged. |
| </p> |
| <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 "<code>Interpret Condition as Variable Expression?</code>" and use |
| a <code>__javaScript()</code> function call. You can then use the objects "<code>vars</code>", "<code>log</code>", "<code>ctx</code>" etc. in the script. |
| </note> |
| <note> |
| To test if a variable is undefined (or null) do the following, suppose var is named <code>myVar</code>, expression will be: |
| <source>"${myVar}" == "\${myVar}"</source> |
| Or use: |
| <source>"${myVar}" != "\${myVar}"</source> |
| to test if a variable is defined and is not null. |
| </note> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property> |
| <property name="Condition (default Javascript)" required="Yes">By default the condition is interpreted as <b>Javascript</b> code that returns "<code>true</code>" or "<code>false</code>", |
| but this can be overridden (see below)</property> |
| <property name="Interpret Condition as Variable Expression?" required="Yes">If this is selected, then the condition must be an expression that evaluates to "<code>true</code>" (case is ignored). |
| For example, <code>${FOUND}</code> or <code>${__jexl(${VAR} > 100)}</code>. |
| Unlike the Javascript case, the condition is only checked to see if it matches "<code>true</code>" (case is ignored). |
| </property> |
| <property name="Evaluate for all children" required="Yes"> |
| Should condition be evaluated for all children? |
| If not checked, then the condition is only evaluated on entry. |
| </property> |
| </properties> |
| <example title="Examples (Javascript)" anchor="example_if_javascript"> |
| <ul> |
| <li><code>${COUNT} < 10</code></li> |
| <li><code>"${VAR}" == "abcd"</code></li> |
| <li><code>${JMeterThread.last_sample_ok}</code> (check if the last sample succeeded)</li> |
| </ul> |
| If there is an error interpreting the code, the condition is assumed to be <code>false</code>, and a message is logged in <code>jmeter.log</code>. |
| </example> |
| <example title="Examples (Variable Expression)" anchor="example_if_variable"> |
| <ul> |
| <li><code>${__jexl(${COUNT} < 10)}</code></li> |
| <li><code>${RESULT}</code></li> |
| </ul> |
| </example> |
| </component> |
| |
| |
| |
| |
| |
| |
| |
| |
| <component name="While Controller" index="§-num;.2.10" width="362" height="102" screenshot="whilecontroller.png"> |
| <description> |
| <p> |
| The While Controller runs its children until the condition is "<code>false</code>". |
| </p> |
| |
| <p>Possible condition values:</p> |
| <ul> |
| <li>blank - exit loop when last sample in loop fails</li> |
| <li><code>LAST</code> - exit loop when last sample in loop fails. |
| If the last sample just before the loop failed, don't enter loop.</li> |
| <li>Otherwise - exit (or don't enter) the loop when the condition is equal to the string "<code>false</code>"</li> |
| </ul> |
| <note> |
| The condition can be any variable or function that eventually evaluates to the string "<code>false</code>". |
| This allows the use of JavaScript, BeanShell, properties or variables as needed. |
| </note> |
| <br></br> |
| <note> |
| Note that the condition is evaluated twice, once before starting sampling children and once at end of children sampling, so putting |
| non idempotent functions in Condition (like <code>__counter</code>) can introduce issues. |
| </note> |
| <br></br> |
| For example: |
| <ul> |
| <li><code>${VAR}</code> - where <code>VAR</code> is set to false by some other test element</li> |
| <li><code>${__javaScript(${C}==10)}</code></li> |
| <li><code>${__javaScript("${VAR2}"=="abcd")}</code></li> |
| <li><code>${_P(property)}</code> - where property is set to "<code>false</code>" somewhere else</li> |
| </ul> |
| </description> |
| <properties> |
| <property name="Name" required="Yes">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</property> |
| <property name="Condition" required="Yes">blank, <code>LAST</code>, or variable/function</property> |
| </properties> |
| </component> |
| |
| <component name="Switch Controller" index="§-num;.2.11" width="361" height="106" screenshot="switchcontroller.png"> |
| <description> |
| <p> |
| The Switch Controller acts like the <complink name="Interleave Controller"/> |
| in that it runs one of the subordinate elements on each iteration, but rather than |
| run them in sequence, the controller runs the element defined by the switch value. |
| </p> |
| <note> |
| The switch value can also be a name. |
| </note> |
| <p>If the switch value is out of range, it will run the zeroth element, |
| which therefore acts as the default for the numeric case. |
| It also runs the zeroth element if the value is the empty string.</p> |
| <p> |
| If the value is non-numeric (and non-empty), then the Switch Controller looks for the |
| element with the same name (case is significant). |
| If none of the names match, then the element named "<code>default</code>" (case not significant) is selected. |
| If there is no default, then no element is selected, and the controller will not run anything. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="Yes">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</property> |
| <property name="Switch Value" required="Yes">The number (or name) of the subordinate element to be invoked. Elements are numbered from 0.</property> |
| </properties> |
| </component> |
| |
| <component name="ForEach Controller" index="§-num;.2.12" anchor="loop" width="342" height="193" screenshot="logic-controller/foreach-controller.png"> |
| <description><p>A ForEach controller loops through the values of a set of related variables. |
| When you add samplers (or controllers) to a ForEach controller, every sample (or controller) |
| is executed one or more times, where during every loop the variable has a new value. |
| The input should consist of several variables, each extended with an underscore and a number. |
| Each such variable must have a value. |
| So for example when the input variable has the name <code>inputVar</code>, the following variables should have been defined:</p> |
| <ul> |
| <li><code>inputVar_1 = wendy</code></li> |
| <li><code>inputVar_2 = charles</code></li> |
| <li><code>inputVar_3 = peter</code></li> |
| <li><code>inputVar_4 = john</code></li> |
| </ul> |
| <p>Note: the "<code>_</code>" separator is now optional.</p> |
| <p> |
| When the return variable is given as "<code>returnVar</code>", the collection of samplers and controllers under the ForEach controller will be executed <code>4</code> consecutive times, |
| with the return variable having the respective above values, which can then be used in the samplers. |
| </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 "<code>_</code>" separator, the ForEach Controller can be used to loop through the groups by using |
| the input variable <code>refName_g</code>, and can also loop through all the groups in all the matches |
| by using an input variable of the form <code>refName_${C}_g</code>, where <code>C</code> is a counter variable. |
| </p> |
| <note>The ForEach Controller does not run any samples if <code>inputVar_1</code> is <code>null</code>. |
| This would be the case if the Regular Expression returned no matches.</note> |
| </description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property> |
| <property name="Input variable prefix" required="Yes">Prefix for the variable names to be used as input.</property> |
| <property name="Start index for loop" required="No">Start index (exclusive) for loop over variables (first element is at start index + 1)</property> |
| <property name="End index for loop" required="No">End index (inclusive) for loop over variables</property> |
| <property name="Output variable" required="Yes"> |
| The name of the variable which can be used in the loop for replacement in the samplers</property> |
| <property required="Yes" name="Use Separator">If not checked, the "<code>_</code>" separator is omitted.</property> |
| </properties> |
| |
| <example title="ForEach Example" anchor="foreach_example"> |
| |
| <p><a href="../demos/forEachTestPlan.jmx">Download</a> this example (see Figure 7). |
| In this example, we created a Test Plan that sends a particular HTTP Request |
| only once and sends another HTTP Request to every link that can be found on the page.</p> |
| |
| <figure width="300" height="158" image="logic-controller/foreach-example.png">Figure 7 - ForEach Controller Example</figure> |
| |
| <p>We configured the Thread Group for a single thread and a loop count value of |
| one. You can see that we added one HTTP Request to the Thread Group and |
| another HTTP Request to the ForEach Controller.</p> |
| <p>After the first HTTP request, a regular expression extractor is added, which extracts all the html links |
| out of the return page and puts them in the <code>inputVar</code> variable</p> |
| <p>In the ForEach loop, a HTTP sampler is added which requests all the links that were extracted from the first returned HTML page. |
| </p></example> |
| <example title="ForEach Example" anchor="foreach_example2"> |
| <p>Here is <a href="../demos/ForEachTest2.jmx">another example</a> you can download. |
| This has two Regular Expressions and ForEach Controllers. |
| The first RE matches, but the second does not match, |
| so no samples are run by the second ForEach Controller</p> |
| <figure width="237" height="249" image="logic-controller/foreach-example2.png">Figure 8 - ForEach Controller Example 2</figure> |
| <p>The Thread Group has a single thread and a loop count of two. |
| </p><p> |
| Sample 1 uses the JavaTest Sampler to return the string "<code>a b c d</code>". |
| </p><p>The Regex Extractor uses the expression <code>(\w)\s</code> which matches a letter followed by a space, |
| and returns the letter (not the space). Any matches are prefixed with the string "<code>inputVar</code>". |
| </p><p>The ForEach Controller extracts all variables with the prefix "<code>inputVar_</code>", and executes its |
| sample, passing the value in the variable "<code>returnVar</code>". In this case it will set the variable to the values "<code>a</code>" "<code>b</code>" and "<code>c</code>" in turn. |
| </p><p>The <code>For 1</code> Sampler is another Java Sampler which uses the return variable "<code>returnVar</code>" as part of the sample Label |
| and as the sampler Data. |
| </p><p><code>Sample 2</code>, <code>Regex 2</code> and <code>For 2</code> are almost identical, except that the Regex has been changed to "<code>(\w)\sx</code>", |
| which clearly won't match. Thus the <code>For 2</code> Sampler will not be run. |
| </p> |
| </example> |
| </component> |
| |
| <component name="Module Controller" index="§-num;.2.13" width="526" height="318" screenshot="module_controller.png"> |
| <description> |
| <p> |
| The Module Controller provides a mechanism for substituting test plan fragments into the current test plan at run-time. |
| </p> |
| <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 <complink name="WorkBench" />. |
| 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. |
| </p> |
| <p> |
| There can be multiple fragments, each with a different series of |
| samplers under them. The module controller can then be used to easily switch between these multiple test cases simply by choosing |
| the appropriate controller in its drop down box. This provides convenience for running many alternate test plans quickly and easily. |
| </p> |
| <p> |
| A fragment name is made up of the Controller name and all its parent names. |
| For example: |
| </p> |
| <pre> |
| Test Plan / Protocol: JDBC / Control / Interleave Controller (Module1) |
| </pre> |
| <p> |
| Any <b>fragments used by the Module Controller must have a unique name</b>, |
| as the name is used to find the target controller when a test plan is reloaded. |
| For this reason it is best to ensure that the Controller name is changed from the default |
| - as shown in the example above - |
| otherwise a duplicate may be accidentally created when new elements are added to the test plan. |
| </p> |
| </description> |
| <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 <code>.jmx</code> files. Any such test will fail.</note> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property> |
| <property name="Module to Run" required="Yes">The module controller provides a list of all controllers loaded into the gui. Select |
| the one you want to substitute in at runtime.</property> |
| </properties> |
| </component> |
| |
| <component name="Include Controller" index="§-num;.2.14" width="417" height="130" screenshot="includecontroller.png"> |
| <description> |
| <p> |
| The include controller is designed to use an external jmx file. To use it, create a Test Fragment |
| underneath the Test Plan and add any desired samplers, controllers etc. below it. |
| Then save the Test Plan. The file is now ready to be included as part of other Test Plans. |
| </p> |
| <p> |
| For convenience, a <complink name="Thread Group" /> can also be added in the external JMX file for debugging purposes. |
| A <complink name="Module Controller" /> can be used to reference the Test Fragment. The <complink name="Thread Group" /> will be ignored during the |
| include process. |
| </p> |
| <p> |
| If the test uses a Cookie Manager or User Defined Variables, these should be placed in the top-level |
| test plan, not the included file, otherwise they are not guaranteed to work. |
| </p> |
| <note> |
| This element does not support variables/functions in the filename field.<br></br> |
| However, if the property <code>includecontroller.prefix</code> is defined, |
| the contents are used to prefix the pathname. |
| </note> |
| <note> |
| When using Include Controller and including the same JMX file, ensure you name the Include Controller differently to avoid facing known issue <bugzilla>50898</bugzilla>. |
| </note> |
| <p> |
| If the file cannot be found at the location given by <code>prefix</code>+<code>Filename</code>, then the controller |
| attempts to open the <code>Filename</code> relative to the JMX launch directory. |
| </p> |
| </description> |
| <properties> |
| <property name="Filename" required="Yes">The file to include.</property> |
| </properties> |
| </component> |
| |
| <component name="Transaction Controller" index="§-num;.2.15" width="622" height="140" screenshot="transactioncontroller.png"> |
| <description> |
| <p> |
| The Transaction Controller generates an additional |
| sample which measures the overall time taken to perform the nested test elements. |
| </p> |
| <note> |
| Note: when the check box "<code>Include duration of timer and pre-post processors in generated sample</code>" is checked, |
| the time includes all processing within the controller scope, not just the samples. |
| </note> |
| <p> |
| There are two modes of operation: |
| </p> |
| <ul> |
| <li>additional sample is added after the nested samples</li> |
| <li>additional sample is added as a parent of the nested samples</li> |
| </ul> |
| <p> |
| The generated sample time includes all the times for the nested samplers excluding by default (since 2.11) timers and processing time of pre/post processors |
| unless checkbox "<code>Include duration of timer and pre-post processors in generated sample</code>" is checked. |
| Depending on the clock resolution, it may be slightly longer than the sum of the individual samplers plus timers. |
| The clock might tick after the controller recorded the start time but before the first sample starts. |
| Similarly at the end. |
| </p> |
| <p>The generated sample is only regarded as successful if all its sub-samples are successful.</p> |
| <p> |
| In parent mode, the individual samples can still be seen in the Tree View Listener, |
| but no longer appear as separate entries in other Listeners. |
| Also, the sub-samples do not appear in CSV log files, but they can be saved to XML files. |
| </p> |
| <note> |
| In parent mode, Assertions (etc.) can be added to the Transaction Controller. |
| However by default they will be applied to both the individual samples and the overall transaction sample. |
| To limit the scope of the Assertions, use a Simple Controller to contain the samples, and add the Assertions |
| to the Simple Controller. |
| Parent mode controllers do not currently properly support nested transaction controllers of either type. |
| </note> |
| </description> |
| <properties> |
| <property name="Name" required="Yes">Descriptive name for this controller that is shown in the tree, and used to name the transaction.</property> |
| <property name="Generate Parent Sample" required="Yes"> |
| If checked, then the sample is generated as a parent of the other samples, |
| otherwise the sample is generated as an independent sample. |
| </property> |
| <property name="Include duration of timer and pre-post processors in generated sample" required="Yes"> |
| Whether to include timer, pre- and post-processing delays in the generated sample. |
| Default is <code>false</code> |
| </property> |
| </properties> |
| </component> |
| |
| <component name="Recording Controller" index="§-num;.2.16" width="420" height="79" screenshot="logic-controller/recording-controller.png"> |
| <description> |
| <p>The Recording Controller is a place holder indicating where the proxy server should |
| record samples to. During test run, it has no effect, similar to the Simple Controller. But during |
| recording using the <complink name="HTTP(S) Test Script Recorder" />, all recorded samples will by default |
| be saved under the Recording Controller.</p> |
| |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this controller that is shown in the tree.</property> |
| </properties> |
| |
| </component> |
| |
| <component name="Critical Section Controller" index="§-num;.2.17" width="469" height="129" screenshot="logic-controller/critical-section-controller.png"> |
| <description> |
| <p>The Critical Section Controller ensures that its children elements (samplers/controllers, etc.) will be executed |
| by only one thread as a named lock will be taken before executing children of controller.</p> |
| </description> |
| <p> |
| The figure below shows an example of using Critical Section Controller, in the figure below 2 Critical Section Controllers ensure |
| that: |
| </p> |
| <ul> |
| <li><code>DS2-${__threadNum}</code> is executed only by one thread at a time</li> |
| <li><code>DS4-${__threadNum}</code> is executed only by one thread at a time</li> |
| </ul> |
| <figure width="276" height="237" image="logic-controller/critical-section-controller-tp.png">Test Plan using Critical Section Controller</figure> |
| |
| <properties> |
| <property name="Lock Name" required="Yes">Lock that will be taken by controller, ensure you use different lock names for unrelated sections</property> |
| </properties> |
| <note> |
| Critical Section Controller takes locks only within one JVM, so if using Distributed testing ensure your use case does not rely on all threads of all JVMs blocking. |
| </note> |
| |
| </component> |
| |
| <a href="#">^</a> |
| |
| </section> |
| |
| <section name="§-num;.3 Listeners" anchor="listeners"> |
| <description> |
| <br></br> |
| Most of the listeners perform several roles in addition to "listening" |
| to the test results. |
| They also provide means to view, save, and read saved test results. |
| <p>Note that Listeners are processed at the end of the scope in which they are found.</p> |
| <p> |
| The saving and reading of test results is generic. The various |
| listeners have a panel whereby one can specify the file to |
| which the results will be written (or read from). |
| By default, the results are stored as XML |
| files, typically with a "<code>.jtl</code>" extension. |
| Storing as CSV is the most efficient option, but is less detailed than XML (the other available option). |
| </p> |
| <p> |
| <b>Listeners do <i>not</i> process sample data in non-GUI mode, but the raw data will be saved if an output |
| file has been configured.</b> |
| In order to analyse the data generated by a non-GUI test run, you need to load the file into the appropriate |
| Listener. |
| </p> |
| <note> |
| To read existing results and display them, use the file panel Browse button to open the file. |
| </note> |
| <p> |
| If you want to clear any current data before loading a new file, use the menu item |
| <menuchoice> |
| <guimenuitem>Run</guimenuitem> |
| <guimenuitem>Clear</guimenuitem> |
| <shortcut> |
| <keycombo><keysym>Ctrl</keysym><keysym>Shift</keysym><keysym>E</keysym></keycombo> |
| </shortcut> |
| </menuchoice> |
| or |
| <menuchoice> |
| <guimenuitem>Run</guimenuitem> |
| <guimenuitem>Clear All</guimenuitem> |
| <shortcut> |
| <keycombo><keysym>Ctrl</keysym><keysym>E</keysym></keycombo> |
| </shortcut> |
| </menuchoice> |
| before loading the file. |
| </p> |
| <p>Results can be read from XML or CSV format files. |
| When reading from CSV results files, the header (if present) is used to determine which fields are present. |
| <b>In order to interpret a header-less CSV file correctly, the appropriate properties must be set in <code>jmeter.properties</code>.</b> |
| </p> |
| <note> |
| The file name can contain function and/or variable references. |
| However variable references do not work in client-server mode (functions work OK). |
| This is because the file is created on the client, and the client does not run the test locally so does not set up variables. |
| </note> |
| <p><b>Listeners can use a lot of memory if there are a lot of samples.</b> |
| Most of the listeners currently keep a copy of every sample in their scope, apart from: |
| </p> |
| <ul> |
| <li>Simple Data Writer</li> |
| <li>BeanShell/BSF Listener</li> |
| <li>Mailer Visualizer</li> |
| <li>Monitor Results</li> |
| <li>Summary Report</li> |
| </ul> |
| <p> |
| The following Listeners no longer need to keep copies of every single sample. |
| Instead, samples with the same elapsed time are aggregated. |
| Less memory is now needed, especially if most samples only take a second or two at most. |
| </p> |
| <ul> |
| <li>Aggregate Report</li> |
| <li>Aggregate Graph</li> |
| </ul> |
| <p>To minimise the amount of memory needed, use the Simple Data Writer, and use the CSV format.</p> |
| <note> |
| JMeter variables can be saved to the output files. |
| This can only be specified using a property. |
| See the <a href="listeners.html#sample_variables">Listener Sample Variables</a> for details |
| </note> |
| <p> |
| For full details on setting up the default items to be saved |
| see the <a href="listeners.html#defaults">Listener Default Configuration</a> documentation. |
| For details of the contents of the output files, |
| see the <a href="listeners.html#csvlogformat">CSV log</a> format or |
| the <a href="listeners.html#xmlformat2.1">XML log</a> format. |
| </p> |
| <note>The entries in <code>jmeter.properties</code> are used to define the defaults; |
| these can be overridden for individual listeners by using the Configure button, |
| as shown below. |
| The settings in <code>jmeter.properties</code> also apply to the listener that is added |
| by using the <code>-l</code> command-line flag. |
| </note> |
| <p> |
| The figure below shows an example of the result file configuration panel |
| </p> |
| <figure width="741" height="141" image="simpledatawriter.png">Result file configuration panel</figure> |
| <properties> |
| <property name="Filename" required="No">Name of the file containing sample results. |
| The file name can be specified using either a relative or an absolute path name. |
| Relative paths are resolved relative to the current working directory (which defaults to the <code>bin/</code> directory). |
| JMeter also support paths relative to the directory containing the current test plan (JMX file). |
| If the path name begins with "<code>~/</code>" (or whatever is in the <code>jmeter.save.saveservice.base_prefix</code> JMeter property), |
| then the path is assumed to be relative to the JMX file location. |
| </property> |
| <property name="Browse …" required="No">File Browse Button</property> |
| <property name="Errors" required="No">Select this to write/read only results with errors</property> |
| <property name="Successes" required="No">Select this to write/read only results without errors. |
| If neither <code>Errors</code> nor <code>Successes</code> is selected, then all results are processed.</property> |
| <property name="Configure" required="No">Configure Button, see below</property> |
| </properties> |
| </description> |
| |
| <component name="Sample Result Save Configuration" index="§-num;.3.1" width="760" height="304" screenshot="sample_result_config.png"> |
| <description> |
| <p> |
| Listeners can be configured to save different items to the result log files (JTL) by using the Config popup as shown below. |
| The defaults are defined as described in the <a href="listeners.html#defaults">Listener Default Configuration</a> documentation. |
| Items with (<code>CSV</code>) after the name only apply to the CSV format; items with (<code>XML</code>) only apply to XML format. |
| CSV format cannot currently be used to save any items that include line-breaks. |
| </p> |
| <p> |
| Note that cookies, method and the query string are saved as part of the "<code>Sampler Data</code>" option. |
| </p> |
| </description> |
| </component> |
| |
| <component name="Graph Results" index="§-num;.3.3" width="915" height="686" screenshot="graph_results.png"> |
| <description> |
| <note> |
| Graph Results 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. |
| </note> |
| <p>The Graph Results listener generates a simple graph that plots all sample times. Along |
| the bottom of the graph, the current sample (black), the current average of all samples (blue), the |
| current standard deviation (red), and the current throughput rate (green) are displayed in milliseconds.</p> |
| <p>The throughput number represents the actual number of requests/minute the server handled. This calculation |
| includes any delays you added to your test and JMeter's own internal processing time. The advantage |
| of doing the calculation like this is that this number represents something |
| real - your server in fact handled that many requests per minute, and you can increase the number of threads |
| and/or decrease the delays to discover your server's maximum throughput. Whereas if you made calculations |
| that factored out delays and JMeter's processing, it would be unclear what you could conclude from that |
| number.</p></description> |
| <p>The following table briefly describes the items on the graph. |
| Further details on the precise meaning of the statistical terms can be found on the web |
| - e.g. Wikipedia - or by consulting a book on statistics. |
| </p> |
| <ul> |
| <li><code>Data</code> - plot the actual data values</li> |
| <li><code>Average</code> - plot the Average</li> |
| <li><code>Median</code> - plot the <a href="glossary.html#Median">Median</a> (midway value)</li> |
| <li><code>Deviation</code> - plot the <a href="glossary.html#StandardDeviation">Standard Deviation</a> (a measure of the variation)</li> |
| <li><code>Throughput</code> - plot the number of samples per unit of time</li> |
| </ul> |
| <p>The individual figures at the bottom of the display are the current values. |
| "<code>Latest Sample</code>" is the current elapsed sample time, shown on the graph as "<code>Data</code>".</p> |
| <p>The value displayed on the top left of graph is the max of 90<sup>th</sup> percentile of response time.</p> |
| </component> |
| |
| <component name="Spline Visualizer (DEPRECATED)" index="§-num;.3.4" width="737" height="489" screenshot="spline_visualizer.png"> |
| <note> |
| Spline Visualizer 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. |
| </note> |
| <description> |
| <p> |
| The Spline Visualizer provides a view of all sample times from the start |
| of the test till the end, regardless of how many samples have been taken. The spline |
| has 10 points, each representing 10% of the samples, and connected using spline |
| logic to show a single continuous line. |
| </p> |
| <p> |
| The graph is automatically scaled to fit within the window. |
| This needs to be borne in mind when comparing graphs. |
| </p> |
| </description> |
| </component> |
| |
| <component name="Assertion Results" index="§-num;.3.5" width="954" height="365" screenshot="assertion_results.png"> |
| <description> |
| <note> |
| Assertion Results 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. |
| </note> |
| <p>The Assertion Results visualizer shows the Label of each sample taken. |
| It also reports failures of any <a href="test_plan.html#assertions">Assertions</a> that |
| are part of the test plan.</p></description> |
| |
| <links> |
| <complink name="Response Assertion"/> |
| </links> |
| </component> |
| |
| <component name="View Results Tree" index="§-num;.3.6" width="910" height="659" screenshot="view_results_tree.png"> |
| <description> |
| <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. |
| </note> |
| The View Results Tree shows a tree of all sample responses, allowing you to view the |
| response for any sample. In addition to showing the response, you can see the time it took to get |
| this response, and some response codes. |
| Note that the Request panel only shows the headers added by JMeter. |
| It does not show any headers (such as <code>Host</code>) that may be added by the HTTP protocol implementation. |
| <p> |
| There are several ways to view the response, selectable by a drop-down box at the bottom of the left hand panel.</p> |
| |
| <table> |
| <tr><th><b>Renderer</b></th><th><b>Description</b></th></tr> |
| <tr><td><code>CSS/JQuery Tester</code></td> |
| <td>The <i>CSS/JQuery Tester</i> only works for text responses. It shows the plain text in the upper panel. |
| The "<code>Test</code>" button allows the user to apply the CSS/JQuery to the upper panel and the results |
| will be displayed in the lower panel.<br/> |
| The CSS/JQuery expression engine can be JSoup or Jodd, syntax of these 2 implementation differs slightly.<br/> |
| For example, the Selector <code>a[class=sectionlink]</code> with attribute <code>href</code> applied to the current JMeter functions page gives the following output: |
| <br/> |
| <source> |
| Match count: 74 |
| Match[1]=#functions |
| Match[2]=#what_can_do |
| Match[3]=#where |
| Match[4]=#how |
| Match[5]=#function_helper |
| Match[6]=#functions |
| Match[7]=#__regexFunction |
| Match[8]=#__regexFunction_parms |
| Match[9]=#__counter |
| … and so on … |
| </source> |
| <br/></td></tr> |
| <tr><td><code>Document</code></td> |
| <td>The <i>Document view</i> will show the extract text from various type of documents like Microsoft Office |
| (Word, Excel, PowerPoint 97-2003, 2007-2010 (openxml), Apache OpenOffice (writer, calc, impress), HTML, |
| gzip, jar/zip files (list of content), and some meta-data on "multimedia" files like mp3, mp4, flv, etc. The complete list of |
| support format is available on <a href="http://tika.apache.org/1.2/formats.html">Apache Tika format page.</a> |
| <note>A requirement to the <code>Document view</code> is to download the <a href="http://tika.apache.org/download.html"> |
| Apache Tika binary package</a> (<code>tika-app-x.x.jar</code>) and put this in <code>JMETER_HOME/lib</code> directory. |
| </note> |
| If the document is larger than 10 MB, then it won't be displayed. |
| To change this limit, set the JMeter property <code>document.max_size</code> (unit is byte) or set to <code>0</code> to remove the limit. |
| <br/></td></tr> |
| <tr><td><code>HTML</code></td> |
| <td>The <i>HTML view</i> attempts to render the response as |
| HTML. The rendered HTML is likely to compare poorly to the view one |
| would get in any web browser; however, it does provide a quick |
| approximation that is helpful for initial result evaluation.<br/> |
| Images, style-sheets, etc. aren't downloaded. |
| <br/></td></tr> |
| <tr><td><code>HTML (download resources)</code></td> |
| <td>If the <i>HTML (download resources) view</i> option is selected, the renderer |
| may download images, style-sheets, etc. referenced by the HTML code. |
| <br/></td></tr> |
| <tr><td><code>JSON</code></td> |
| <td>The <i>JSON view</i> will show the response in tree style (also handles JSON embedded in JavaScript). |
| <br/></td></tr> |
| <tr><td><code>JSON Path Tester</code></td> |
| <td>The <i>JSON Path Tester view</i> will let you test your JSON-PATH expressions and see the extracted data from a particular response. |
| <br/></td></tr> |
| <tr><td><code>Regexp Tester</code></td> |
| <td>The <i>Regexp Tester view</i> only works for text responses. It shows the plain text in the upper panel. |
| The "<code>Test</code>" button allows the user to apply the Regular Expression to the upper panel and the results |
| will be displayed in the lower panel.<br/> |
| The regular expression engine is the same as that used in the Regular Expression Extractor.<br/> |
| For example, the RE <code>(JMeter\w*).*</code> applied to the current JMeter home page gives the following output: |
| <br/> |
| <source> |
| Match count: 26 |
| Match[1][0]=JMeter - Apache JMeter</title> |
| Match[1][1]=JMeter |
| Match[2][0]=JMeter" title="JMeter" border="0"/></a> |
| Match[2][1]=JMeter |
| Match[3][0]=JMeterCommitters">Contributors</a> |
| Match[3][1]=JMeterCommitters |
| … and so on … |
| </source> |
| <br/> |
| The first number in <code>[]</code> is the match number; the second number is the group. |
| Group <code>[0]</code> is whatever matched the whole RE. |
| Group <code>[1]</code> is whatever matched the 1<sup>st</sup> group, i.e. <code>(JMeter\w*)</code> in this case. |
| See Figure 9b (below). |
| <br/></td></tr> |
| <tr><td><code>Text</code></td> |
| <td> |
| The default <i>Text view</i> shows all of the text contained in the response. |
| Note that this will only work if the response <code>content-type</code> is considered to be text. |
| If the <code>content-type</code> begins with any of the following, it is considered as binary, |
| otherwise it is considered to be text. |
| <source> |
| image/ |
| audio/ |
| video/ |
| </source> |
| <br/></td></tr> |
| <tr><td><code>XML</code></td> |
| <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. |
| <br/></td></tr> |
| <tr><td><code>XPath Tester</code></td> |
| <td>The <i>XPath Tester</i> only works for text responses. It shows the plain text in the upper panel. |
| The "<code>Test</code>" button allows the user to apply the XPath query to the upper panel and the results |
| will be displayed in the lower panel.<br/> |
| </td></tr> |
| </table> |
| <p><code>Scroll automatically?</code> option permit to have last node display in tree selection</p> |
| <p> |
| With <code>Search</code> option, most of the views also allow the displayed data to be searched; the result of the search will be high-lighted |
| in the display above. For example the Control panel screenshot below shows one result of searching for "<code>Java</code>". |
| Note that the search operates on the visible text, so you may get different results when searching |
| the Text and HTML views. |
| <br/>Note: The regular expression uses the Java engine (not ORO engine like the Regular Expression Extractor or Regexp Tester view). |
| </p> |
| <p> |
| If there is no <code>content-type</code> provided, then the content |
| will not be displayed in the any of the Response Data panels. |
| You can use <complink name="Save Responses to a file"/> to save the data in this case. |
| Note that the response data will still be available in the sample result, |
| so can still be accessed using Post-Processors. |
| </p> |
| <p>If the response data is larger than 200K, then it won't be displayed. |
| To change this limit, set the JMeter property <code>view.results.tree.max_size</code>. |
| You can also use save the entire response to a file using |
| <complink name="Save Responses to a file"/>. |
| </p> |
| <p> |
| Additional renderers can be created. |
| The class must implement the interface <code>org.apache.jmeter.visualizers.ResultRenderer</code> |
| and/or extend the abstract class <code>org.apache.jmeter.visualizers.SamplerResultTab</code>, and the |
| compiled code must be available to JMeter (e.g. by adding it to the <code>lib/ext</code> directory). |
| </p> |
| </description> |
| <p> |
| The Control Panel (above) shows an example of an HTML display.<br/> |
| Figure 9 (below) shows an example of an XML display.<br/> |
| Figure 9a (below) shows an example of a Regexp tester display.<br/> |
| Figure 9b (below) shows an example of a Document display.<br/> |
| </p> |
| <div align="center"> |
| <figure width="903" height="657" image="view_results_tree_xml.png">Figure 9 Sample XML display</figure> |
| <figure width="904" height="653" image="view_results_tree_regex.png">Figure 9a Sample Regexp Test display</figure> |
| <figure width="849" height="655" image="view_results_tree_document.png">Figure 9b Sample Document (here PDF) display</figure> |
| </div> |
| </component> |
| |
| <component name="Aggregate Report" index="§-num;.3.7" width="1140" height="266" screenshot="aggregate_report.png"> |
| <description>The aggregate report creates a table row for each differently named request in your |
| test. For each request, it totals the response information and provides request count, min, max, |
| average, error rate, approximate throughput (request/second) and Kilobytes per second throughput. |
| Once the test is done, the throughput is the actual through for the duration of the entire test. |
| <p> |
| The throughput is calculated from the point of view of the sampler target |
| (e.g. the remote server in the case of HTTP samples). |
| JMeter takes into account the total time over which the requests have been generated. |
| If other samplers and timers are in the same thread, these will increase the total time, |
| and therefore reduce the throughput value. |
| So two identical samplers with different names will have half the throughput of two samplers with the same name. |
| It is important to choose the sampler names correctly to get the best results from |
| the Aggregate Report. |
| </p> |
| <p> |
| Calculation of the <a href="glossary.html#Median">Median</a> and 90% Line (90<sup>th</sup> <a href="glossary.html#Percentile">percentile</a>) values requires additional memory. |
| JMeter now combines samples with the same elapsed time, so far less memory is used. |
| However, for samples that take more than a few seconds, the probability is that fewer samples will have identical times, |
| in which case more memory will be needed. |
| Note you can use this listener afterwards to reload a CSV or XML results file which is the recommended way to avoid performance impacts. |
| See the <complink name="Summary Report"/> for a similar Listener that does not store individual samples and so needs constant memory. |
| </p> |
| <note> |
| Starting with JMeter 2.12, you can configure the 3 percentile values you want to compute, this can be done by setting properties: |
| <ul> |
| <li><code>aggregate_rpt_pct1</code>: defaults to 90<sup>th</sup> <a href="glossary.html#Percentile">percentile</a></li> |
| <li><code>aggregate_rpt_pct2</code>: defaults to 95<sup>th</sup> <a href="glossary.html#Percentile">percentile</a></li> |
| <li><code>aggregate_rpt_pct3</code>: defaults to 99<sup>th</sup> <a href="glossary.html#Percentile">percentile</a></li> |
| </ul> |
| </note> |
| <ul> |
| <li><code>Label</code> - The label of the sample. |
| If "<code>Include group name in label?</code>" is selected, then the name of the thread group is added as a prefix. |
| This allows identical labels from different thread groups to be collated separately if required. |
| </li> |
| <li><code># Samples</code> - The number of samples with the same label</li> |
| <li><code>Average</code> - The average time of a set of results</li> |
| <li><code>Median</code> - The <a href="glossary.html#Median">median</a> is the time in the middle of a set of results. |
| 50% of the samples took no more than this time; the remainder took at least as long.</li> |
| <li><code>90% Line</code> - 90% of the samples took no more than this time. |
| The remaining samples took at least as long as this. (90<sup>th</sup> <a href="glossary.html#Percentile">percentile</a>)</li> |
| <li><code>95% Line</code> - 95% of the samples took no more than this time. |
| The remaining samples took at least as long as this. (95<sup>th</sup> <a href="glossary.html#Percentile">percentile</a>)</li> |
| <li><code>99% Line</code> - 99% of the samples took no more than this time. |
| The remaining samples took at least as long as this. (99<sup>th</sup> <a href="glossary.html#Percentile">percentile</a>)</li> |
| <li><code>Min</code> - The shortest time for the samples with the same label</li> |
| <li>Max - The longest time for the samples with the same label</li> |
| <li><code>Error %</code> - Percent of requests with errors</li> |
| <li><code>Throughput</code> - the <a href="glossary.html#Throughput">Throughput</a> is measured in requests per second/minute/hour. |
| The time unit is chosen so that the displayed rate is at least 1.0. |
| When the throughput is saved to a CSV file, it is expressed in requests/second, |
| i.e. 30.0 requests/minute is saved as 0.5. |
| </li> |
| <li><code>Kb/sec</code> - The throughput measured in Kilobytes per second</li> |
| </ul> |
| <p>Times are in milliseconds.</p> |
| </description> |
| <div align="center"> |
| <p> |
| The figure below shows an example of selecting the "<code>Include group name</code>" checkbox. |
| </p> |
| <figure width="1140" height="276" image="aggregate_report_grouped.png">Sample "<code>Include group name</code>" display</figure> |
| </div> |
| </component> |
| |
| <component name="View Results in Table" index="§-num;.3.8" width="966" height="683" screenshot="table_results.png"> |
| <description>This visualizer creates a row for every sample result. |
| Like the <complink name="View Results Tree"/>, this visualizer uses a lot of memory. |
| <p> |
| By default, it only displays the main (parent) samples; it does not display the sub-samples (child samples). |
| JMeter has a "<code>Child Samples?</code>" check-box. |
| If this is selected, then the sub-samples are displayed instead of the main samples. |
| </p> |
| </description> |
| </component> |
| |
| <component name="Simple Data Writer" index="§-num;.3.9" width="741" height="141" screenshot="simpledatawriter.png"> |
| <description>This listener can record results to a file |
| but not to the UI. It is meant to provide an efficient means of |
| recording data by eliminating GUI overhead. |
| When running in non-GUI mode, the <code>-l</code> flag can be used to create a data file. |
| The fields to save are defined by JMeter properties. |
| See the <code>jmeter.properties</code> file for details. |
| </description> |
| </component> |
| |
| <component name="Monitor Results" index="§-num;.3.10" width="762" height="757" screenshot="monitor_screencap.png"> |
| <description> |
| <p>Monitor Results is a new Visualizer for displaying server |
| status. It is designed for Tomcat 5, but any servlet container |
| can port the status servlet and use this monitor. There are two primary |
| tabs for the monitor. The first is the "<code>Health</code>" tab, which will show the |
| status of one or more servers. The second tab labled "<code>Performance</code>" shows |
| the performance for one server for the last 1000 samples. The equations |
| used for the load calculation is included in the Visualizer.</p> |
| <p>Currently, the primary limitation of the monitor is system memory. A |
| quick benchmark of memory usage indicates a buffer of 1000 data points for |
| 100 servers would take roughly 10Mb of RAM. On a 1.4Ghz centrino |
| laptop with 1Gb of ram, the monitor should be able to handle several |
| hundred servers.</p> |
| <p>As a general rule, monitoring production systems should take care to |
| set an appropriate interval. Intervals shorter than 5 seconds are too |
| aggressive and have a potential of impacting the server. With a buffer of |
| 1000 data points at 5 second intervals, the monitor would check the server |
| status 12 times a minute or 720 times a hour. This means the buffer shows |
| the performance history of each machine for the last hour.</p> |
| <note> |
| The monitor requires Tomcat 5 or above. |
| Use a browser to check that you can access the Tomcat status servlet OK. |
| </note> |
| <p> |
| For a detailed description of how to use the monitor, please refer to |
| <a href="build-monitor-test-plan.html">Building a Monitor Test Plan</a> |
| </p> |
| </description> |
| </component> |
| |
| <component name="Distribution Graph (DEPRECATED)" index="§-num;.3.11" width="819" height="626" screenshot="distribution_graph.png"> |
| <description> |
| <note> |
| Distribution Graph 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. |
| </note> |
| |
| <p>The distribution graph will display a bar for every unique response time. Since the |
| granularity of <code>System.currentTimeMillis()</code> is 10 milliseconds, the 90% threshold should be |
| within the width of the graph. The graph will draw two threshold lines: 50% and 90%. |
| What this means is 50% of the response times finished between 0 and the line. The same |
| is true of 90% line. Several tests with Tomcat were performed using 30 threads for 600K |
| requests. The graph was able to display the distribution without any problems and both |
| the 50% and 90% line were within the width of the graph. A performant application will |
| generally produce results that clump together. A poorly written application that has |
| memory leaks may result in wild fluctuations. In those situations, the threshold lines |
| may be beyond the width of the graph. The recommended solution to this specific problem |
| is fix the webapp so it performs well. If your test plan produces distribution graphs |
| with no apparent clumping or pattern, it may indicate a memory leak. The only way to |
| know for sure is to use a profiling tool.</p> |
| </description> |
| </component> |
| |
| <component name="Aggregate Graph" index="§-num;.3.12" width="1132" height="872" screenshot="aggregate_graph.png"> |
| <description>The aggregate graph is similar to the aggregate report. The primary |
| difference is the aggregate graph provides an easy way to generate bar graphs and save |
| the graph as a PNG file.</description> |
| <div align="center"> |
| <p> |
| The figure below shows an example of settings to draw this graph. |
| </p> |
| <figure width="1147" height="420" image="aggregate_graph_settings.png">Aggregate graph settings</figure> |
| </div> |
| <note>Please note: All this parameters <em>aren't</em> saved in JMeter jmx script.</note> |
| <properties> |
| <property name="Column settings" required="Yes"> |
| <ul> |
| <li><code>Columns to display:</code> Choose the column(s) to display in graph.</li> |
| <li><code>Rectangles color:</code> Click on right color rectangle open a popup dialog to choose a custom color for column.</li> |
| <li><code>Foreground color</code> Allow to change the value text color.</li> |
| <li><code>Value font:</code> Allow to define font settings for the text.</li> |
| <li><code>Draw outlines bar?</code> To draw or not the border line on bar chart</li> |
| <li><code>Show number grouping?</code> Show or not the number grouping in Y Axis labels.</li> |
| <li><code>Value labels vertical?</code> Change orientation for value label. (Default is horizontal)</li> |
| <li><code>Column label selection:</code> Filter by result label. A regular expression can be used, example: <code>.*Transaction.*</code> |
| <br></br>Before display the graph, click on <code>Apply filter</code> button to refresh internal data.</li> |
| </ul> |
| </property> |
| <property name="Title" required="No">Define the graph's title on the head of chart. Empty value is the default value : "<code>Aggregate Graph</code>". |
| The button <code>Synchronize with name</code> define the title with the label of the listener. And define font settings for graph title</property> |
| <property name="Graph size" required="No">Compute the graph size by the width and height depending of the current JMeter's window size. |
| Use <code>Width</code> and <code>Height</code> fields to define a custom size. The unit is pixel. </property> |
| <property name="X Axis settings" required="No">Define the max length of X Axis label (in pixel).</property> |
| <property name="Y Axis settings" required="No">Define a custom maximum value for Y Axis.</property> |
| <property name="Legend" required="Yes">Define the placement and font settings for chart legend</property> |
| </properties> |
| </component> |
| |
| <component name="Response Time Graph" index="§-num;.3.13" width="921" height="616" screenshot="response_time_graph.png"> |
| <description> |
| The Response Time Graph draws a line chart showing the evolution of response time during the test, for each labelled request. |
| If many samples exist for the same timestamp, the mean value is displayed. |
| </description> |
| <div align="center"> |
| <p> |
| The figure below shows an example of settings to draw this graph. |
| </p> |
| <figure width="919" height="481" image="response_time_graph_settings.png">Response time graph settings</figure> |
| </div> |
| <note>Please note: All this parameters are saved in JMeter <code>.jmx</code> file.</note> |
| <properties> |
| <property name="Interval (ms)" required="Yes">The time in milli-seconds for X axis interval. Samples are grouped according to this value. |
| Before display the graph, click on <code>Apply interval</code> button to refresh internal data.</property> |
| <property name="Sampler label selection" required="No">Filter by result label. A regular expression can be used, ex. <code>.*Transaction.*</code>. |
| Before display the graph, click on <code>Apply filter</code> button to refresh internal data.</property> |
| <property name="Title" required="No">Define the graph's title on the head of chart. Empty value is the default value : "<code>Response Time Graph</code>". |
| The button <code>Synchronize with name</code> define the title with the label of the listener. And define font settings for graph title</property> |
| <property name="Line settings" required="Yes">Define the width of the line. Define the type of each value point. Choose <code>none</code> to have a line without mark</property> |
| <property name="Graph size" required="No">Compute the graph size by the width and height depending of the current JMeter's window size. |
| Use <code>Width</code> and <code>Height</code> fields to define a custom size. The unit is pixel. </property> |
| <property name="X Axis settings" required="No">Customize the date format of X axis label. |
| The syntax is the Java <a href="http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat API</a>.</property> |
| <property name="Y Axis settings" required="No">Define a custom maximum value for Y Axis in milli-seconds. Define the increment for the scale (in ms) Show or not the number grouping in Y Axis labels.</property> |
| <property name="Legend" required="Yes">Define the placement and font settings for chart legend</property> |
| </properties> |
| </component> |
| |
| <component name="Mailer Visualizer" index="§-num;.3.14" width="860" height="403" screenshot="mailervisualizer.png"> |
| <description><p>The mailer visualizer can be set up to send email if a test run receives too many |
| failed responses from the server.</p></description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="From" required="Yes">Email address to send messages from.</property> |
| <property name="Addressee(s)" required="Yes">Email address to send messages to, comma-separated.</property> |
| <property name="Success Subject" required="No">Email subject line for success messages.</property> |
| <property name="Success Limit" required="Yes">Once this number of successful responses is exceeded |
| <strong>after previously reaching the failure limit</strong>, a success email |
| is sent. The mailer will thus only send out messages in a sequence of failed-succeeded-failed-succeeded, etc.</property> |
| <property name="Failure Subject" required="No">Email subject line for fail messages.</property> |
| <property name="Failure Limit" required="Yes">Once this number of failed responses is exceeded, a failure |
| email is sent - i.e. set the count to <code>0</code> to send an e-mail on the first failure.</property> |
| |
| <property name="Host" required="No">IP address or host name of SMTP server (email redirector) |
| server.</property> |
| <property name="Port" required="No">Port of SMTP server (defaults to <code>25</code>).</property> |
| <property name="Login" required="No">Login used to authenticate.</property> |
| <property name="Password" required="No">Password used to authenticate.</property> |
| <property name="Connection security" required="No">Type of encryption for SMTP authentication (SSL, TLS or none).</property> |
| |
| <property name="Test Mail" required="No">Press this button to send a test mail</property> |
| <property name="Failures" required="No">A field that keeps a running total of number |
| of failures so far received.</property> |
| </properties> |
| </component> |
| |
| <component name="BeanShell Listener" index="§-num;.3.15" width="844" height="633" screenshot="beanshell_listener.png"> |
| <description> |
| <p> |
| The BeanShell Listener allows the use of BeanShell for processing samples for saving etc. |
| </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 <code>ThreadListener</code> and <code>TestListener</code> methods. |
| These should be defined in the initialisation file. |
| See the file <code>BeanShellListeners.bshrc</code> for example definitions. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree. |
| The name is stored in the script variable Label</property> |
| <property name="Reset bsh.Interpreter before each call" required="Yes"> |
| If this option is selected, then the interpreter will be recreated for each sample. |
| This may be necessary for some long running scripts. |
| For further information, see <a href="best-practices#bsh_scripting">Best Practices - BeanShell scripting</a>. |
| </property> |
| <property name="Parameters" required="No">Parameters to pass to the BeanShell script. |
| The parameters are stored in the following variables: |
| <dl> |
| <dt><code>Parameters</code></dt><dd>string containing the parameters as a single variable</dd> |
| <dt><code>bsh.args</code></dt><dd>String array containing parameters, split on white-space</dd> |
| </dl></property> |
| <property name="Script file" required="No">A file containing the BeanShell script to run. |
| The file name is stored in the script variable <code>FileName</code></property> |
| <property name="Script" required="Yes (unless script file is provided)">The BeanShell script to run. The return value is ignored.</property> |
| </properties> |
| <p>Before invoking the script, some variables are set up in the BeanShell interpreter:</p> |
| <ul> |
| <li><code>log</code> - (<a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a>) - can be used to write to the log file</li> |
| <li><code>ctx</code> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li> |
| <li><code>vars</code> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <source>vars.get(key); |
| vars.put(key,val); |
| vars.putObject("OBJ1",new Object()); |
| </source></li> |
| <li><code>props</code> - (JMeterProperties - class <code>java.util.Properties</code>) - e.g. <code>props.get("START.HMS");</code> <code>props.put("PROP1","1234");</code></li> |
| <li><code>sampleResult</code>, <code>prev</code> - (<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the previous <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a></li> |
| <li><code>sampleEvent</code> (<a href="../api/org/apache/jmeter/samplers/SampleEvent.html">SampleEvent</a>) gives access to the current sample event</li> |
| </ul> |
| <p>For details of all the methods available on each of the above variables, please check the Javadoc</p> |
| <p>If the property <code>beanshell.listener.init</code> is defined, this is used to load an initialisation file, which can be used to define methods etc. for use in the BeanShell script.</p> |
| </component> |
| |
| <component name="Summary Report" index="§-num;.3.16" width="926" height="324" screenshot="summary_report.png"> |
| <description>The summary report creates a table row for each differently named request in your |
| test. This is similar to the <complink name="Aggregate Report"/> , except that it uses less memory. |
| <p> |
| The throughput is calculated from the point of view of the sampler target |
| (e.g. the remote server in the case of HTTP samples). |
| JMeter takes into account the total time over which the requests have been generated. |
| If other samplers and timers are in the same thread, these will increase the total time, |
| and therefore reduce the throughput value. |
| So two identical samplers with different names will have half the throughput of two samplers with the same name. |
| It is important to choose the sampler labels correctly to get the best results from |
| the Report. |
| </p> |
| <ul> |
| <li><code>Label</code> - The label of the sample. |
| If "<code>Include group name in label?</code>" is selected, then the name of the thread group is added as a prefix. |
| This allows identical labels from different thread groups to be collated separately if required. |
| </li> |
| <li><code># Samples</code> - The number of samples with the same label</li> |
| <li><code>Average</code> - The average elapsed time of a set of results</li> |
| <li><code>Min</code> - The lowest elapsed time for the samples with the same label</li> |
| <li><code>Max</code> - The longest elapsed time for the samples with the same label</li> |
| <li><code>Std. Dev.</code> - the <a href="glossary.html#StandardDeviation">Standard Deviation</a> of the sample elapsed time</li> |
| <li><code>Error %</code> - Percent of requests with errors</li> |
| <li><code>Throughput</code> - the <a href="glossary.html#Throughput">Throughput</a> is measured in requests per second/minute/hour. |
| The time unit is chosen so that the displayed rate is at least <code>1.0</code>. |
| When the throughput is saved to a CSV file, it is expressed in requests/second, |
| i.e. 30.0 requests/minute is saved as <code>0.5</code>. |
| </li> |
| <li><code>Kb/sec</code> - The throughput measured in Kilobytes per second</li> |
| <li><code>Avg. Bytes</code> - average size of the sample response in bytes.</li> |
| </ul> |
| <p>Times are in milliseconds.</p> |
| </description> |
| <div align="center"> |
| <p> |
| The figure below shows an example of selecting the "<code>Include group name</code>" checkbox. |
| </p> |
| <figure width="923" height="325" image="summary_report_grouped.png">Sample "<code>Include group name</code>" display</figure> |
| </div> |
| </component> |
| |
| <component name="Save Responses to a file" index="§-num;.3.17" width="488" height="251" screenshot="savetofile.png"> |
| <description> |
| <p> |
| This test element can be placed anywhere in the test plan. |
| For each sample in its scope, it will create a file of the response Data. |
| The primary use for this is in creating functional tests, but it can also |
| be useful where the response is too large to be displayed in the |
| <complink name="View Results Tree"/> Listener. |
| The file name is created from the specified prefix, plus a number (unless this is disabled, see below). |
| The file extension is created from the document type, if known. |
| If not known, the file extension is set to '<code>unknown</code>'. |
| If numbering is disabled, and adding a suffix is disabled, then the file prefix is |
| taken as the entire file name. This allows a fixed file name to be generated if required. |
| The generated file name is stored in the sample response, and can be saved |
| in the test log output file if required. |
| </p> |
| <p> |
| The current sample is saved first, followed by any sub-samples (child samples). |
| If a variable name is provided, then the names of the files are saved in the order |
| that the sub-samples appear. See below. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Filename Prefix" required="Yes">Prefix for the generated file names; this can include a directory name. |
| Relative paths are resolved relative to the current working directory (which defaults to the <code>bin/</code> directory). |
| JMeter also supports paths relative to the directory containing the current test plan (JMX file). |
| If the path name begins with "<code>~/</code>" (or whatever is in the <code>jmeter.save.saveservice.base_prefix</code> JMeter property), |
| then the path is assumed to be relative to the JMX file location. |
| </property> |
| <property name="Variable Name" required="No"> |
| Name of a variable in which to save the generated file name (so it can be used later in the test plan). |
| If there are sub-samples then a numeric suffix is added to the variable name. |
| E.g. if the variable name is <code>FILENAME</code>, then the parent sample file name is saved in the variable <code>FILENAME</code>, |
| and the filenames for the child samplers are saved in <code>FILENAME1</code>, <code>FILENAME2</code> etc. |
| </property> |
| <property name="Save Failed Responses only" required="Yes">If selected, then only failed responses are saved</property> |
| <property name="Save Successful Responses only" required="Yes">If selected, then only successful responses are saved</property> |
| <property name="Don't add number to prefix" required="Yes">If selected, then no number is added to the prefix. If you select this option, make sure that the prefix is unique or the file may be overwritten.</property> |
| <property name="Don't add suffix" required="Yes">If selected, then no suffix is added. If you select this option, make sure that the prefix is unique or the file may be overwritten.</property> |
| <property name="Minimum Length of sequence number" required="No">If "<code>Don't add number to prefix</code>" is not checked, then numbers added to prefix will be padded by <code>0</code> so that prefix is has size of this value. Defaults to <code>0</code>.</property> |
| </properties> |
| </component> |
| |
| <component name="BSF Listener" index="§-num;.3.18" width="847" height="634" screenshot="bsf_listener.png"> |
| <description> |
| <p> |
| The BSF Listener allows BSF script code to be applied to sample results. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Language" required="Yes">The BSF language to be used</property> |
| <property name="Parameters" required="No">Parameters to pass to the script. |
| The parameters are stored in the following variables: |
| <dl> |
| <dt><code>Parameters</code></dt><dd>string containing the parameters as a single variable</dd> |
| <dt><code>args</code></dt><dd>String array containing parameters, split on white-space</dd> |
| </dl></property> |
| <property name="Script file" required="No">A file containing the script to run, if a relative file path is used, then it will be relative to directory referenced by "<code>user.dir</code>" System property</property> |
| <property name="Script" required="Yes (unless script file is provided)">The script to run.</property> |
| </properties> |
| <p> |
| The script (or file) is processed using the <code>BSFEngine.exec()</code> method, which does not return a value. |
| </p> |
| <p> |
| Before invoking the script, some variables are set up. |
| Note that these are BSF variables - i.e. they can be used directly in the script. |
| </p> |
| <dl> |
| <dt><code>log</code></dt><dd>(<a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a>) - can be used to write to the log file</dd> |
| <dt><code>Label</code></dt><dd>the String Label</dd> |
| <dt><code>FileName</code></dt><dd>the script file name (if any)</dd> |
| <dt><code>Parameters</code></dt><dd>the parameters (as a String)</dd> |
| <dt><code>args</code></dt><dd>the parameters as a String array (split on whitespace)</dd> |
| <dt><code>ctx</code></dt><dd>(<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</dd> |
| <dt><code>vars</code></dt><dd>(<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <source>vars.get(key); |
| vars.put(key,val); |
| vars.putObject("OBJ1",new Object()); |
| vars.getObject("OBJ2");</source></dd> |
| <dt><code>props</code></dt><dd>(JMeterProperties - class <code>java.util.Properties</code>) - e.g. <code>props.get("START.HMS");</code> <code>props.put("PROP1","1234");</code></dd> |
| <dt><code>sampleResult</code>, <code>prev</code></dt><dd>(<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the SampleResult</dd> |
| <dt><code>sampleEvent</code></dt><dd>(<a href="../api/org/apache/jmeter/samplers/SampleEvent.html">SampleEvent</a>) - gives access to the SampleEvent</dd> |
| <dt><code>sampler</code></dt><dd>(<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>)- gives access to the last sampler</dd> |
| <dt><code>OUT</code></dt><dd><code>System.out</code> - e.g. <code>OUT.println("message")</code></dd> |
| </dl> |
| <p>For details of all the methods available on each of the above variables, please check the Javadoc</p> |
| </component> |
| |
| <component name="JSR223 Listener" index="§-num;.3.18.1"> |
| <description> |
| <p> |
| The JSR223 Listener allows JSR223 script code to be applied to sample results. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Language" required="Yes">The JSR223 language to be used</property> |
| <property name="Parameters" required="No">Parameters to pass to the script. |
| The parameters are stored in the following variables: |
| <dl> |
| <dt><code>Parameters</code></dt><dd>string containing the parameters as a single variable</dd> |
| <dt><code>args</code></dt><dd>String array containing parameters, split on white-space</dd> |
| </dl></property> |
| <property name="Script file" required="No">A file containing the script to run, if a relative file path is used, then it will be relative to directory referenced by "<code>user.dir</code>" System property</property> |
| <property name="Script compilation caching" required="No">Unique String across Test Plan that JMeter will use to cache result of Script compilation if language used supports <code>Compilable</code> interface (Groovy is one of these, java, beanshell and javascript are not). |
| <note>See note in JSR223 Sampler Java System property if you're using Groovy without checking this option</note> |
| </property> |
| <property name="Script" required="Yes (unless script file is provided)">The script to run.</property> |
| </properties> |
| |
| <p> |
| Before invoking the script, some variables are set up. |
| Note that these are JSR223 variables - i.e. they can be used directly in the script. |
| </p> |
| <dl> |
| <dt><code>log</code></dt><dd>(<a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a>) - can be used to write to the log file</dd> |
| <dt><code>Label</code></dt><dd>the String Label</dd> |
| <dt><code>FileName</code></dt><dd>the script file name (if any)</dd> |
| <dt><code>Parameters</code></dt><dd>the parameters (as a String)</dd> |
| <dt><code>args</code></dt><dd>the parameters as a String array (split on whitespace)</dd> |
| <dt><code>ctx</code></dt><dd>(<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</dd> |
| <dt><code>vars</code></dt><dd>(<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <source>vars.get(key); |
| vars.put(key,val); |
| vars.putObject("OBJ1",new Object()); |
| vars.getObject("OBJ2");</source></dd> |
| <dt><code>props</code></dt><dd>(JMeterProperties - class <code>java.util.Properties</code>) - e.g. <code>props.get("START.HMS");</code> <code>props.put("PROP1","1234");</code></dd> |
| <dt><code>sampleResult</code>, <code>prev</code></dt><dd>(<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the SampleResult</dd> |
| <dt><code>sampleEvent</code></dt><dd>(<a href="../api/org/apache/jmeter/samplers/SampleEvent.html">SampleEvent</a>) - gives access to the SampleEvent</dd> |
| <dt><code>sampler</code></dt><dd>(<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>)- gives access to the last sampler</dd> |
| <dt><code>OUT</code></dt><dd><code>System.out</code> - e.g. <code>OUT.println("message")</code></dd> |
| </dl> |
| <p>For details of all the methods available on each of the above variables, please check the Javadoc</p> |
| </component> |
| |
| <component name="Generate Summary Results" index="§-num;.3.19" width="364" height="76" screenshot="summary.png"> |
| <description>This test element can be placed anywhere in the test plan. |
| Generates a summary of the test run so far to the log file and/or |
| standard output. Both running and differential totals are shown. |
| Output is generated every <code>n</code> seconds (default 30 seconds) on the appropriate |
| time boundary, so that multiple test runs on the same time will be synchronised. |
| See <code>jmeter.properties</code> file for the summariser configuration items: |
| <source> |
| # Define the following property to automatically start a summariser with that name |
| # (applies to non-GUI mode only) |
| #summariser.name=summary |
| # |
| # interval between summaries (in seconds) default 3 minutes |
| #summariser.interval=30 |
| # |
| # Write messages to log file |
| #summariser.log=true |
| # |
| # Write messages to System.out |
| #summariser.out=true |
| </source> |
| This element is mainly intended for batch (non-GUI) runs. |
| The output looks like the following: |
| <source> |
| label + 16 in 0:00:12 = 1.3/s Avg: 1608 Min: 1163 Max: 2009 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0 |
| label + 82 in 0:00:30 = 2.7/s Avg: 1518 Min: 1003 Max: 2020 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0 |
| label = 98 in 0:00:42 = 2.3/s Avg: 1533 Min: 1003 Max: 2020 Err: 0 (0.00%) |
| label + 85 in 0:00:30 = 2.8/s Avg: 1505 Min: 1008 Max: 2005 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0 |
| label = 183 in 0:01:13 = 2.5/s Avg: 1520 Min: 1003 Max: 2020 Err: 0 (0.00%) |
| label + 79 in 0:00:30 = 2.7/s Avg: 1578 Min: 1089 Max: 2012 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0 |
| label = 262 in 0:01:43 = 2.6/s Avg: 1538 Min: 1003 Max: 2020 Err: 0 (0.00%) |
| label + 80 in 0:00:30 = 2.7/s Avg: 1531 Min: 1013 Max: 2014 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0 |
| label = 342 in 0:02:12 = 2.6/s Avg: 1536 Min: 1003 Max: 2020 Err: 0 (0.00%) |
| label + 83 in 0:00:31 = 2.7/s Avg: 1512 Min: 1003 Max: 1982 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0 |
| label = 425 in 0:02:43 = 2.6/s Avg: 1531 Min: 1003 Max: 2020 Err: 0 (0.00%) |
| label + 83 in 0:00:29 = 2.8/s Avg: 1487 Min: 1023 Max: 2013 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0 |
| label = 508 in 0:03:12 = 2.6/s Avg: 1524 Min: 1003 Max: 2020 Err: 0 (0.00%) |
| label + 78 in 0:00:30 = 2.6/s Avg: 1594 Min: 1013 Max: 2016 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0 |
| label = 586 in 0:03:43 = 2.6/s Avg: 1533 Min: 1003 Max: 2020 Err: 0 (0.00%) |
| label + 80 in 0:00:30 = 2.7/s Avg: 1516 Min: 1013 Max: 2005 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0 |
| label = 666 in 0:04:12 = 2.6/s Avg: 1531 Min: 1003 Max: 2020 Err: 0 (0.00%) |
| label + 86 in 0:00:30 = 2.9/s Avg: 1449 Min: 1004 Max: 2017 Err: 0 (0.00%) Active: 5 Started: 5 Finished: 0 |
| label = 752 in 0:04:43 = 2.7/s Avg: 1522 Min: 1003 Max: 2020 Err: 0 (0.00%) |
| label + 65 in 0:00:24 = 2.7/s Avg: 1579 Min: 1007 Max: 2003 Err: 0 (0.00%) Active: 0 Started: 5 Finished: 5 |
| label = 817 in 0:05:07 = 2.7/s Avg: 1526 Min: 1003 Max: 2020 Err: 0 (0.00%) |
| </source> |
| The "<code>label</code>" is the name of the element. |
| The <code>"+"</code> means that the line is a delta line, i.e. shows the changes since the last output.<br/> |
| The <code>"="</code> means that the line is a total line, i.e. it shows the running total.<br/> |
| Entries in the JMeter log file also include time-stamps. |
| The example "<code>817 in 0:05:07 = 2.7/s</code>" means that there were 817 samples recorded in 5 minutes and 7 seconds, |
| and that works out at 2.7 samples per second.<br/> |
| The <code>Avg</code> (Average), <code>Min</code> (Minimum) and <code>Max</code> (Maximum) times are in milliseconds.<br/> |
| "<code>Err</code>" means number of errors (also shown as percentage).<br/> |
| The last two lines will appear at the end of a test. |
| They will not be synchronised to the appropriate time boundary. |
| Note that the initial and final deltas may be for less than the interval (in the example above this is 30 seconds). |
| The first delta will generally be lower, as JMeter synchronizes to the interval boundary. |
| The last delta will be lower, as the test will generally not finish on an exact interval boundary. |
| <p> |
| The label is used to group sample results together. |
| So if you have multiple Thread Groups and want to summarize across them all, then use the same label |
| - or add the summariser to the Test Plan (so all thread groups are in scope). |
| Different summary groupings can be implemented |
| by using suitable labels and adding the summarisers to appropriate parts of the test plan. |
| </p> |
| <note> |
| In Non-GUI mode by default a Generate Summary Results listener named "<code>summariser</code>" is configured, if you have already added one to your Test Plan, ensure you name it differently |
| otherwise results will be accumulated under this label (summary) leading to wrong results (sum of total samples + samples located under the Parent of Generate Summary Results listener).<br/> |
| This is not a bug but a design choice allowing to summarize across thread groups. |
| </note> |
| </description> |
| <properties> |
| <property name="Name" required="Yes">Descriptive name for this element that is shown in the tree. |
| It appears as the "<code>label</code>" in the output. Details for all elements with the same label will be added together. |
| </property> |
| </properties> |
| </component> |
| |
| <component name="Comparison Assertion Visualizer" index="§-num;.3.20" width="718" height="454" screenshot="comparison_assertion_visualizer.png"> |
| <description> |
| The Comparison Assertion Visualizer shows the results of any <complink name="Compare Assertion"/> elements. |
| </description> |
| <properties> |
| <property name="Name" required="Yes">Descriptive name for this element that is shown in the tree. |
| </property> |
| </properties> |
| </component> |
| |
| <component name="Backend Listener" index="§-num;.3.21" width="705" height="350" screenshot="backend_listener.png"> |
| <description> |
| The backend listener is an Asynchronous listener that enables you to plug custom implementations of <a href="../api/org/apache/jmeter/visualizers/backend/BackendListenerClient.html">BackendListenerClient</a>. |
| By default, a Graphite implementation is provided. |
| </description> |
| <properties> |
| <property name="Name" required="Yes">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Backend Listener implementation" required="Yes">Class of the <code>BackendListenerClient</code> implementation.</property> |
| <property name="Async Queue size" required="Yes">Size of the queue that holds the SampleResults while they are processed asynchronously.</property> |
| <property name="Parameters" required="Yes">Parameters of the <code>BackendListenerClient</code> implementation.</property> |
| </properties> |
| |
| |
| <p>The following parameters apply to the <code>GraphiteBackendListenerClient</code> implementation:</p> |
| |
| <properties> |
| <property name="graphiteMetricsSender" required="Yes"><code>org.apache.jmeter.visualizers.backend.graphite.TextGraphiteMetricsSender</code> or <code>org.apache.jmeter.visualizers.backend.graphite.PickleGraphiteMetricsSender</code></property> |
| <property name="graphiteHost" required="Yes">Graphite or InfluxDB (with Graphite plugin enabled) server host</property> |
| <property name="graphitePort" required="Yes">Graphite or InfluxDB (with Graphite plugin enabled) server port, defaults to <code>2003</code>. Note <code>PickleGraphiteMetricsSender</code> (port <code>2004</code>) can only talk to Graphite server.</property> |
| <property name="rootMetricsPrefix" required="Yes">Prefix of metrics sent to backend. Defaults to "<code>jmeter</code>." |
| Note that JMeter does not add a separator between the root prefix and the samplerName which is why the trailing dot is currently needed.</property> |
| <property name="summaryOnly" required="Yes">Only send a summary with no detail. Defaults to <code>true</code>.</property> |
| <property name="samplersList" required="Yes">Defines the names (labels) of sample results to be sent to the back end. |
| If <code>useRegexpForSamplersList=false</code> this is a list of semi-colon separated names. |
| If <code>useRegexpForSamplersList=true</code> this is a regular expression which will be matched against the names.</property> |
| <property name="useRegexpForSamplersList" required="Yes">Consider samplersList as a regular expression to select the samplers for which you want to report metrics to backend. Defaults to <code>false</code>.</property> |
| <property name="percentiles" required="Yes">The percentiles you want to send to the backend. |
| A percentile may contain a fractional part, for example <code>12.5</code>. |
| (The separator is always ".") |
| List must be semicolon separated. Generally 3 or 4 values should be sufficient.</property> |
| </properties> |
| <p>See also <a href="realtime-results.html" >Real-time results</a> for more details.</p> |
| <figure width="1265" height="581" image="grafana_dashboard.png">Grafana dashboard</figure> |
| </component> |
| |
| <a href="#">^</a> |
| |
| </section> |
| |
| <section name="§-num;.4 Configuration Elements" anchor="config_elements"> |
| <description> |
| <br></br> |
| Configuration elements can be used to set up defaults and variables for later use by samplers. |
| Note that these elements are processed at the start of the scope in which they are found, |
| i.e. before any samplers in the same scope. |
| <br></br> |
| </description> |
| |
| <component name="CSV Data Set Config" index="§-num;.4.1" width="433" height="281" screenshot="csvdatasetconfig.png"> |
| <description> |
| <p> |
| CSV Data Set Config is used to read lines from a file, and split them into variables. |
| It is easier to use than the <code>__CSVRead()</code> and <code>_StringFromFile()</code> functions. |
| It is well suited to handling large numbers of variables, and is also useful for testing with |
| "random" and unique values.</p> |
| <p>Generating unique random values at run-time is expensive in terms of CPU and memory, so just create the data |
| in advance of the test. If necessary, the "random" data from the file can be used in conjunction with |
| a run-time parameter to create different sets of values from each run - e.g. using concatenation - which is |
| much cheaper than generating everything at run-time. |
| </p> |
| <p> |
| JMeter allows values to be quoted; this allows the value to contain a delimiter. |
| If "<code>allow quoted data</code>" is enabled, a value may be enclosed in double-quotes. |
| These are removed. To include double-quotes within a quoted field, use two double-quotes. |
| For example: |
| </p> |
| <source> |
| 1,"2,3","4""5" => |
| 1 |
| 2,3 |
| 4"5 |
| </source> |
| <p> |
| JMeter supports CSV files which have a header line defining the column names. |
| To enable this, leave the "<code>Variable Names</code>" field empty. The correct delimiter must be provided. |
| </p> |
| <p> |
| JMeter supports CSV files with quoted data that includes new-lines. |
| </p> |
| <p> |
| By default, the file is only opened once, and each thread will use a different line from the file. |
| However the order in which lines are passed to threads depends on the order in which they execute, |
| which may vary between iterations. |
| Lines are read at the start of each test iteration. |
| The file name and mode are resolved in the first iteration. |
| </p> |
| <p> |
| See the description of the Share mode below for additional options. |
| If you want each thread to have its own set of values, then you will need to create a set of files, |
| one for each thread. For example <code>test1.csv</code>, <code>test2.csv</code>, …, <code>test<em>n</em>.csv</code>. Use the filename |
| <code>test${__threadNum}.csv</code> and set the "<code>Sharing mode</code>" to "<code>Current thread</code>". |
| </p> |
| <note>CSV Dataset variables are defined at the start of each test iteration. |
| As this is after configuration processing is completed, |
| they cannot be used for some configuration items - such as JDBC Config - |
| that process their contents at configuration time (see <bugzilla>40394</bugzilla>) |
| However the variables do work in the HTTP Auth Manager, as the <code>username</code> etc. are processed at run-time. |
| </note> |
| <p> |
| As a special case, the string "<code>\t</code>" (without quotes) in the delimiter field is treated as a Tab. |
| </p> |
| <p> |
| When the end of file (<code>EOF</code>) is reached, and the recycle option is <code>true</code>, reading starts again with the first line of the file. |
| </p> |
| <p> |
| If the recycle option is <code>false</code>, and stopThread is <code>false</code>, then all the variables are set to <code><EOF></code> when the end of file is reached. |
| This value can be changed by setting the JMeter property <code>csvdataset.eofstring</code>. |
| </p> |
| <p> |
| If the Recycle option is <code>false</code>, and Stop Thread is <code>true</code>, then reaching <code>EOF</code> will cause the thread to be stopped. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Filename" required="Yes">Name of the file to be read. |
| <b>Relative file names are resolved with respect to the path of the active test plan.</b> |
| <b>For distributed testing, the CSV file must be stored on the server host system in the correct relative directory to where the jmeter server is started.</b> |
| Absolute file names are also supported, but note that they are unlikely to work in remote mode, |
| unless the remote server has the same directory structure. |
| If the same physical file is referenced in two different ways - e.g. <code>csvdata.txt</code> and <code>./csvdata.txt</code> - |
| then these are treated as different files. |
| If the OS does not distinguish between upper and lower case, <code>csvData.TXT</code> would also be opened separately. |
| </property> |
| <property name="File Encoding" required="No">The encoding to be used to read the file, if not the platform default.</property> |
| <property name="Variable Names" required="Yes">List of variable names (comma-delimited). |
| JMeter supports CSV header lines: |
| if the variable name field empty, then the first line of the file is read and interpreted as the list of column names. |
| The names must be separated by the delimiter character. They can be quoted using double-quotes. |
| </property> |
| <property name="Delimiter" required="Yes">Delimiter to be used to split the records in the file. |
| If there are fewer values on the line than there are variables the remaining variables are not updated - |
| so they will retain their previous value (if any).</property> |
| <property name="Allow quoted data?" required="Yes">Should the CSV file allow values to be quoted? |
| If enabled, then values can be enclosed in <code>"</code> - double-quote - allowing values to contain a delimiter. |
| </property> |
| <property name="Recycle on EOF?" required="Yes">Should the file be re-read from the beginning on reaching <code>EOF</code>? (default is <code>true</code>)</property> |
| <property name="Stop thread on EOF?" required="Yes">Should the thread be stopped on <code>EOF</code>, if Recycle is false? (default is <code>false</code>)</property> |
| <property name="Sharing mode" required="Yes"> |
| <ul> |
| <li><code>All threads</code> - (the default) the file is shared between all the threads.</li> |
| <li><code>Current thread group</code> - each file is opened once for each thread group in which the element appears</li> |
| <li><code>Current thread</code> - each file is opened separately for each thread</li> |
| <li><code>Identifier</code> - all threads sharing the same identifier share the same file. |
| So for example if you have 4 thread groups, you could use a common id for two or more of the groups |
| to share the file between them. |
| Or you could use the thread number to share the file between the same thread numbers in different thread groups. |
| </li> |
| </ul> |
| </property> |
| </properties> |
| </component> |
| |
| <component name="FTP Request Defaults" index="§-num;.4.2" width="520" height="202" screenshot="ftp-config/ftp-request-defaults.png"> |
| <description></description> |
| </component> |
| |
| <component name="DNS Cache Manager" index="§-num;.4.3" width="712" height="387" screenshot="dns-cache-manager.png"> |
| <note>DNS Cache Manager is designed for using in the root of Thread Group or Test Plan. Do not place it as child element of particular HTTP Sampler |
| </note> |
| <note>DNS Cache Manager working only with the HTTP request using HTTPClient4 implementation.</note> |
| <description><p>The DNS Cache Manager element allows to test applications, which have several servers behind load balancers (CDN, etc.), |
| when user receives content from different IP's. By default JMeter uses JVM DNS cache. That's why |
| only one server from the cluster receives load. DNS Cache Manager resolves name for each thread separately each iteration and |
| saves results of resolving to its internal DNS Cache, which independent from both JVM and OS DNS caches. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree. </property> |
| <property name="Clear cache each Iteration" required="No">If selected, DNS cache of every Thread is cleared each time new iteration is started.</property> |
| <property name="Use system DNS resolver" required="N/A">System DNS resolver will be used. For correct work edit |
| <code>$JAVA_HOME/jre/lib/security/java.security</code> and add <code>networkaddress.cache.ttl=0</code> |
| </property> |
| <property name="Use custom DNS resolver" required="N/A">Custom DNS resolver(from dnsjava library) will be used.</property> |
| <property name="Hostname or IP address" required="No">List of DNS servers to use. If empty, network configuration DNS will used.</property> |
| <property name="Add Button" required="N/A">Add an entry to the DNS servers table.</property> |
| <property name="Delete Button" required="N/A">Delete the currently selected table entry.</property> |
| </properties> |
| </component> |
| |
| <component name="HTTP Authorization Manager" index="§-num;.4.4" width="538" height="340" screenshot="http-config/http-auth-manager.png"> |
| <note>If there is more than one Authorization Manager in the scope of a Sampler, |
| there is currently no way to specify which one is to be used.</note> |
| |
| <description> |
| <p>The Authorization Manager lets you specify one or more user logins for web pages that are |
| restricted using server authentication. You see this type of authentication when you use |
| your browser to access a restricted page, and your browser displays a login dialog box. JMeter |
| transmits the login information when it encounters this type of page.</p> |
| <p> |
| The Authorization headers may not be shown in the Tree View Listener "<code>Request</code>" tab. |
| The Java implementation does pre-emptive authentication, but it does not |
| return the Authorization header when JMeter fetches the headers. |
| The Commons HttpClient (3.1) implementation defaults to pre-emptive and the header will be shown. |
| The HttpComponents (HC 4.5.X) implementation does not do pre-emptive auth |
| (it is supported by the library but JMeter does not enable it) |
| </p> |
| <p> |
| The HttpClient3.1 implementation defaults to pre-emptive authentication |
| if the setting has not been defined. To disable this, set the values as below, in which case |
| authentication will only be performed in response to a challenge. |
| </p> |
| <p> |
| In the file <code>jmeter.properties</code> set <code>httpclient.parameters.file=httpclient.parameters</code> |
| and in <code>httpclient.parameters</code> set <code>http.authentication.preemptive$Boolean=false</code> |
| </p> |
| <note> |
| Note: the above settings only apply to the HttpClient sampler. |
| </note> |
| <note> |
| When looking for a match against a URL, JMeter checks each entry in turn, and stops when it finds the first match. |
| Thus the most specific URLs should appear first in the list, followed by less specific ones. |
| Duplicate URLs will be ignored. |
| If you want to use different usernames/passwords for different threads, you can use variables. |
| These can be set up using a <complink name="CSV Data Set Config"/> Element (for example). |
| </note> |
| </description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree. </property> |
| <property name="Clear auth on each iteration?" required="Yes">Used by Kerberos authentication. If checked, authentication will be done on each iteration of Main Thread Group loop even if it has already been done in a previous one. |
| This is usually useful if each main thread group iteration represents behaviour of one Virtual User. |
| </property> |
| <property name="Base URL" required="Yes">A partial or complete URL that matches one or more HTTP Request URLs. As an example, |
| say you specify a Base URL of "<code>http://localhost/restricted/</code>" with a <code>Username</code> of "<code>jmeter</code>" and |
| a <code>Password</code> of "<code>jmeter</code>". If you send an HTTP request to the URL |
| "<code>http://localhost/restricted/ant/myPage.html</code>", the Authorization Manager sends the login |
| information for the user named, "<code>jmeter</code>".</property> |
| <property name="Username" required="Yes">The username to authorize.</property> |
| <property name="Password" required="Yes">The password for the user. (N.B. this is stored unencrypted in the test plan)</property> |
| <property name="Domain" required="No">The domain to use for NTLM.</property> |
| <property name="Realm" required="No">The realm to use for NTLM.</property> |
| <property name="Mechanism" required="No">Type of authentication to perform. JMeter can perform different types of authentications based on used Http Samplers: |
| <dl> |
| <dt>Java</dt><dd><code>BASIC</code></dd> |
| <dt>HttpClient 3.1</dt><dd><code>BASIC</code> and <code>DIGEST</code></dd> |
| <dt>HttpClient 4</dt><dd><code>BASIC</code>, <code>DIGEST</code> and <code>Kerberos</code></dd> |
| </dl> |
| </property> |
| </properties> |
| <note> |
| The Realm only applies to the HttpClient sampler. |
| </note> |
| <br></br> |
| <b>Kerberos Configuration:</b> |
| <p>To configure Kerberos you need to setup at least two JVM system properties:</p> |
| <ul> |
| <li><code>-Djava.security.krb5.conf=krb5.conf</code></li> |
| <li><code>-Djava.security.auth.login.config=jaas.conf</code></li> |
| </ul> |
| <p> |
| You can also configure those two properties in the file <code>bin/system.properties</code>. |
| Look at the two sample configuration files (<code>krb5.conf</code> and <code>jaas.conf</code>) located in the jmeter <code>bin</code> folder |
| for references to more documentation, and tweak them to match your Kerberos configuration. |
| </p> |
| <p> |
| When generating a SPN for Kerberos SPNEGO authentication IE and Firefox will omit the port number |
| from the URL. Chrome has an option (<code>--enable-auth-negotiate-port</code>) to include the port |
| number if it differs from the standard ones (<code>80</code> and <code>443</code>). That behavior |
| can be emulated by setting the following jmeter property as below. |
| </p> |
| <p> |
| In <code>jmeter.properties</code> or <code>user.properties</code>, set: |
| </p> |
| <ul> |
| <li><code>kerberos.spnego.strip_port=false</code></li> |
| </ul> |
| <br></br> |
| <b>Controls:</b> |
| <ul> |
| <li><code>Add</code> Button - Add an entry to the authorization table.</li> |
| <li><code>Delete</code> Button - Delete the currently selected table entry.</li> |
| <li><code>Load</code> Button - Load a previously saved authorization table and add the entries to the existing |
| authorization table entries.</li> |
| <li><code>Save As</code> Button - Save the current authorization table to a file.</li> |
| </ul> |
| |
| <note>When you save the Test Plan, JMeter automatically saves all of the authorization |
| table entries - including any passwords, which are not encrypted.</note> |
| |
| <example title="Authorization Example" anchor="authorization_example"> |
| |
| <p><a href="../demos/AuthManagerTestPlan.jmx">Download</a> this example. In this example, we created a Test Plan on a local server that sends three HTTP requests, two requiring a login and the |
| other is open to everyone. See figure 10 to see the makeup of our Test Plan. On our server, we have a restricted |
| directory named, "<code>secret</code>", which contains two files, "<code>index.html</code>" and "<code>index2.html</code>". We created a login id named, "<code>kevin</code>", |
| which has a password of "<code>spot</code>". So, in our Authorization Manager, we created an entry for the restricted directory and |
| a username and password (see figure 11). The two HTTP requests named "<code>SecretPage1</code>" and "<code>SecretPage2</code>" make requests |
| to "<code>/secret/index.html</code>" and "<code>/secret/index2.html</code>". The other HTTP request, named "<code>NoSecretPage</code>" makes a request to |
| "<code>/index.html</code>".</p> |
| |
| <figure width="452" height="177" image="http-config/auth-manager-example1a.png">Figure 10 - Test Plan</figure> |
| <figure width="641" height="329" image="http-config/auth-manager-example1b.png">Figure 11 - Authorization Manager Control Panel</figure> |
| |
| <p>When we run the Test Plan, JMeter looks in the Authorization table for the URL it is requesting. If the Base URL matches |
| the URL, then JMeter passes this information along with the request.</p> |
| |
| <note>You can download the Test Plan, but since it is built as a test for our local server, you will not |
| be able to run it. However, you can use it as a reference in constructing your own Test Plan.</note> |
| </example> |
| |
| </component> |
| |
| <component name="HTTP Cache Manager" index="§-num;.4.5" width="511" height="196" screenshot="http-config/http-cache-manager.png"> |
| <description> |
| <p> |
| The HTTP Cache Manager is used to add caching functionality to HTTP requests within its scope to simulate browser cache feature. |
| Each Virtual User thread has its own Cache. By default, Cache Manager will store up to 5000 items in cache per Virtual User thread, using LRU algorithm. |
| Use property "<code>maxSize</code>" to modify this value. Note that the more you increase this value the more HTTP Cache Manager will consume memory, so be sure to adapt the <code>-Xmx</code> jvm option accordingly. |
| </p> |
| <p> |
| If a sample is successful (i.e. has response code <code>2xx</code>) then the <code>Last-Modified</code> and <code>Etag</code> (and <code>Expired</code> if relevant) values are saved for the URL. |
| Before executing the next sample, the sampler checks to see if there is an entry in the cache, |
| and if so, the <code>If-Last-Modified</code> and <code>If-None-Match</code> conditional headers are set for the request. |
| </p> |
| <p> |
| Additionally, if the "<code>Use Cache-Control/Expires header</code>" option is selected, then the <code>Cache-Control</code>/<code>Expires</code> value is checked against the current time. |
| If the request is a <code>GET</code> request, and the timestamp is in the future, then the sampler returns immediately, |
| without requesting the URL from the remote server. This is intended to emulate browser behaviour. |
| Note that if <code>Cache-Control</code> header is "<code>no-cache</code>", the response will be stored in cache as pre-expired, |
| so will generate a conditional <code>GET</code> request. |
| If <code>Cache-Control</code> has any other value, |
| the "<code>max-age</code>" expiry option is processed to compute entry lifetime, if missing then expire header will be used, if also missing entry will be cached |
| as specified in <a href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a> section 13.2.4. using <code>Last-Modified</code> time and response Date. |
| </p> |
| <note> |
| If the requested document has not changed since it was cached, then the response body will be empty. |
| Likewise if the <code>Expires</code> date is in the future. |
| This may cause problems for Assertions. |
| </note> |
| <note>Responses with a <code>Vary</code> header will not be cached.</note> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree. </property> |
| <property name="Clear cache each iteration" required="Yes"> |
| If selected, then the cache is cleared at the start of the thread. |
| </property> |
| <property name="Use Cache Control/Expires header when processing GET requests" required="Yes">See description above.</property> |
| <property name="Max Number of elements in cache" required="Yes">See description above.</property> |
| </properties> |
| </component> |
| |
| <component name="HTTP Cookie Manager" index="§-num;.4.6" width="653" height="373" screenshot="http-config/http-cookie-manager.png"> |
| |
| <note>If there is more than one Cookie Manager in the scope of a Sampler, |
| there is currently no way to specify which one is to be used. |
| Also, a cookie stored in one cookie manager is not available to any other manager, |
| so use multiple Cookie Managers with care.</note> |
| |
| <description><p>The Cookie Manager element has two functions:<br></br> |
| First, it stores and sends cookies just like a web browser. If you have an HTTP Request and |
| the response contains a cookie, the Cookie Manager automatically stores that cookie and will |
| use it for all future requests to that particular web site. Each JMeter thread has its own |
| "cookie storage area". So, if you are testing a web site that uses a cookie for storing |
| session information, each JMeter thread will have its own session. |
| Note that such cookies do not appear on the Cookie Manager display, but they can be seen using |
| the <complink name="View Results Tree"/> Listener. |
| </p> |
| <p> |
| JMeter checks that received cookies are valid for the URL. |
| This means that cross-domain cookies are not stored. |
| If you have bugged behaviour or want Cross-Domain cookies to be used, define the JMeter property "<code>CookieManager.check.cookies=false</code>". |
| </p> |
| <p> |
| Received Cookies can be stored as JMeter thread variables. |
| To save cookies as variables, define the property "<code>CookieManager.save.cookies=true</code>". |
| Also, cookies names are prefixed with "<code>COOKIE_</code>" before they are stored (this avoids accidental corruption of local variables) |
| To revert to the original behaviour, define the property "<code>CookieManager.name.prefix= </code>" (one or more spaces). |
| If enabled, the value of a cookie with the name <code>TEST</code> can be referred to as <code>${COOKIE_TEST}</code>. |
| </p> |
| <p>Second, you can manually add a cookie to the Cookie Manager. However, if you do this, |
| the cookie will be shared by all JMeter threads.</p> |
| <p>Note that such Cookies are created with an Expiration time far in the future</p> |
| <p> |
| Cookies with <code>null</code> values are ignored by default. |
| This can be changed by setting the JMeter property: <code>CookieManager.delete_null_cookies=false</code>. |
| Note that this also applies to manually defined cookies - any such cookies will be removed from the display when it is updated. |
| Note also that the cookie name must be unique - if a second cookie is defined with the same name, it will replace the first. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree. </property> |
| <property name="Clear Cookies each Iteration" required="Yes">If selected, all server-defined cookies are cleared each time the main Thread Group loop is executed. |
| Any cookie defined in the GUI are not cleared.</property> |
| <property name="Cookie Policy" required="Yes">The cookie policy that will be used to manage the cookies. |
| "<code>standard</code>" is the default since 3.0, and should work in most cases. |
| See <a href="https://hc.apache.org/httpcomponents-client-ga/tutorial/html/statemgmt.html#d5e515">Cookie specifications</a> and |
| <a href="http://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/cookie/CookieSpec.html">CookieSpec implementations</a> |
| [Note: "<code>ignoreCookies</code>" is equivalent to omitting the CookieManager.] |
| |
| If you still use HC3CookieHandler (which is DEPRECATED as of 3.0 version, so migration is highly advised), default Cookie Policy is "<code>compatibility</code>", and should work in most cases. |
| See <a href="http://hc.apache.org/httpclient-3.x/cookies.html">http://hc.apache.org/httpclient-3.x/cookies.html</a> and |
| <a href="http://hc.apache.org/httpclient-3.x/apidocs/org/apache/commons/httpclient/cookie/CookiePolicy.html">http://hc.apache.org/httpclient-3.x/apidocs/org/apache/commons/httpclient/cookie/CookiePolicy.html</a> |
| </property> |
| <property name="Implementation" required="Yes"><code>HC4CookieHandler</code> (HttpClient 4.5.X API) or <code>HC3CookieHandler (deprecated)</code> (HttpClient 3 API). |
| Default is <code>HC4CookieHandler</code> since 3.0. |
| <br></br> |
| <i>[Note: If you have a website to test with IPv6 address, choose <code>HC4CookieHandler</code> (IPv6 compliant)]</i></property> |
| <property name="User-Defined Cookies" required="No (discouraged, unless you know what you're doing)">This |
| gives you the opportunity to use hardcoded cookies that will be used by all threads during the test execution. |
| <br></br> |
| The "<code>domain</code>" is the hostname of the server (without <code>http://</code>); the port is currently ignored. |
| </property> |
| <property name="Add Button" required="N/A">Add an entry to the cookie table.</property> |
| <property name="Delete Button" required="N/A">Delete the currently selected table entry.</property> |
| <property name="Load Button" required="N/A">Load a previously saved cookie table and add the entries to the existing |
| cookie table entries.</property> |
| <property name="Save As Button" required="N/A"> |
| Save the current cookie table to a file (does not save any cookies extracted from HTTP Responses). |
| </property> |
| </properties> |
| |
| </component> |
| |
| <component name="HTTP Request Defaults" index="§-num;.4.7" width="879" height="469" |
| screenshot="http-config/http-request-defaults.png"> |
| <description><p>This element lets you set default values that your HTTP Request controllers use. For example, if you are |
| creating a Test Plan with 25 HTTP Request controllers and all of the requests are being sent to the same server, |
| you could add a single HTTP Request Defaults element with the "<code>Server Name or IP</code>" field filled in. Then, when |
| you add the 25 HTTP Request controllers, leave the "<code>Server Name or IP</code>" field empty. The controllers will inherit |
| this field value from the HTTP Request Defaults element.</p> |
| <note> |
| All port values are treated equally; a sampler that does not specify a port will use the HTTP Request Defaults port, if one is provided. |
| </note> |
| </description> |
| <figure width="881" height="256" image="http-config/http-request-defaults-advanced-tab.png">HTTP Request Advanced config fields</figure> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Server" required="No">Domain name or IP address of the web server. e.g. <code>www.example.com</code>. [Do not include the <code>http://</code> prefix.</property> |
| <property name="Port" required="No">Port the web server is listening to.</property> |
| <property name="Connect Timeout" required="No">Connection Timeout. Number of milliseconds to wait for a connection to open.</property> |
| <property name="Response Timeout" required="No">Response Timeout. Number of milliseconds to wait for a response.</property> |
| <property name="Implementation" required="No"><code>Java</code>, <code>HttpClient3.1 (DEPRECATED SINCE 3.0)</code>, <code>HttpClient4</code>. |
| If not specified the default depends on the value of the JMeter property |
| <code>jmeter.httpsampler</code>, failing that, the <code>Java</code> implementation is used.</property> |
| <property name="Protocol" required="No"><code>HTTP</code> or <code>HTTPS</code>.</property> |
| <property name="Content encoding" required="No">The encoding to be used for the request.</property> |
| <property name="Path" required="No">The path to resource (for example, <code>/servlets/myServlet</code>). If the |
| resource requires query string parameters, add them below in the "<code>Send Parameters With the Request</code>" section. |
| Note that the path is the default for the full path, not a prefix to be applied to paths |
| specified on the HTTP Request screens. |
| </property> |
| <property name="Send Parameters With the Request" required="No">The query string will |
| be generated from the list of parameters you provide. Each parameter has a <i>name</i> and |
| <i>value</i>. The query string will be generated in the correct fashion, depending on |
| the choice of "<code>Method</code>" you made (i.e. if you chose <code>GET</code>, the query string will be |
| appended to the URL, if <code>POST</code>, then it will be sent separately). Also, if you are |
| sending a file using a multipart form, the query string will be created using the |
| multipart form specifications.</property> |
| <property name="Server (proxy)" required="No">Hostname or IP address of a proxy server to perform request. [Do not include the <code>http://</code> prefix.]</property> |
| <property name="Port" required="No, unless proxy hostname is specified">Port the proxy server is listening to.</property> |
| <property name="Username" required="No">(Optional) username for proxy server.</property> |
| <property name="Password" required="No">(Optional) password for proxy server. (N.B. this is stored unencrypted in the test plan)</property> |
| <property name="Retrieve All Embedded Resources from HTML Files" required="No">Tell JMeter to parse the HTML file |
| and send HTTP/HTTPS requests for all images, Java applets, JavaScript files, CSSs, etc. referenced in the file. |
| </property> |
| <property name="Use concurrent pool" required="No">Use a pool of concurrent connections to get embedded resources.</property> |
| <property name="Size" required="No">Pool size for concurrent connections used to get embedded resources.</property> |
| <property name="Embedded URLs must match:" required="No"> |
| If present, this must be a regular expression that is used to match against any embedded URLs found. |
| So if you only want to download embedded resources from <code>http://example.com/</code>, use the expression: |
| <code>http://example\.com/.*</code> |
| </property> |
| </properties> |
| <note> |
| Note: radio buttons only have two states - on or off. |
| This makes it impossible to override settings consistently |
| - does off mean off, or does it mean use the current default? |
| JMeter uses the latter (otherwise defaults would not work at all). |
| So if the button is off, then a later element can set it on, |
| but if the button is on, a later element cannot set it off. |
| </note> |
| </component> |
| |
| <component name="HTTP Header Manager" index="§-num;.4.8" width="767" height="239" screenshot="http-config/http-header-manager.png"> |
| <description> |
| <p>The Header Manager lets you add or override HTTP request headers.</p> |
| <p> |
| <b>JMeter now supports multiple Header Managers</b>. The header entries are merged to form the list for the sampler. |
| If an entry to be merged matches an existing header name, it replaces the previous entry, |
| unless the entry value is empty, in which case any existing entry is removed. |
| This allows one to set up a default set of headers, and apply adjustments to particular samplers. |
| </p> |
| </description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree. </property> |
| <property name="Name (Header)" required="No (You should have at least one, however)">Name of the request header. |
| Two common request headers you may want to experiment with |
| are "<code>User-Agent</code>" and "<code>Referer</code>".</property> |
| <property name="Value" required="No (You should have at least one, however)">Request header value.</property> |
| <property name="Add Button" required="N/A">Add an entry to the header table.</property> |
| <property name="Delete Button" required="N/A">Delete the currently selected table entry.</property> |
| <property name="Load Button" required="N/A">Load a previously saved header table and add the entries to the existing |
| header table entries.</property> |
| <property name="Save As Button" required="N/A">Save the current header table to a file.</property> |
| </properties> |
| |
| <example title="Header Manager example" anchor="header_manager_example"> |
| |
| <p><a href="../demos/HeaderManagerTestPlan.jmx">Download</a> this example. In this example, we created a Test Plan |
| that tells JMeter to override the default "<code>User-Agent</code>" request header and use a particular Internet Explorer agent string |
| instead. (see figures 12 and 13).</p> |
| |
| <figure width="247" height="121" image="http-config/header-manager-example1a.png">Figure 12 - Test Plan</figure> |
| <figure image="http-config/header-manager-example1b.png">Figure 13 - Header Manager Control Panel</figure> |
| </example> |
| |
| </component> |
| |
| <component name="Java Request Defaults" index="§-num;.4.9" width="685" height="373" screenshot="java_defaults.png"> |
| <description><p>The Java Request Defaults component lets you set default values for Java testing. See the <complink name="Java Request" />.</p> |
| </description> |
| |
| </component> |
| |
| <component name="JDBC Connection Configuration" index="§-num;.4.10" |
| width="474" height="458" screenshot="jdbc-config/jdbc-conn-config.png"> |
| <description>Creates a database connection (used by <complink name="JDBC Request"/>Sampler) |
| from the supplied JDBC Connection settings. The connection may be optionally pooled between threads. |
| Otherwise each thread gets its own connection. |
| The connection configuration name is used by the JDBC Sampler to select the appropriate |
| connection. |
| The used pool is DBCP, see <a href="https://commons.apache.org/proper/commons-dbcp/configuration.html" >BasicDataSource Configuration Parameters</a> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for the connection configuration that is shown in the tree.</property> |
| <property name="Variable Name" required="Yes">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. |
| <note>Each name must be different. If there are two configuration elements using the same name, |
| only one will be saved. JMeter logs a message if a duplicate name is detected.</note> |
| </property> |
| <property name="Max Number of Connections" required="Yes"> |
| Maximum number of connections allowed in the pool. |
| In most cases, <b>set this to zero (0)</b>. |
| This means that each thread will get its own pool with a single connection in it, i.e. |
| the connections are not shared between threads. |
| <br /> |
| If you really want to use shared pooling (why?), then set the max count to the same as the number of threads |
| to ensure threads don't wait on each other. |
| </property> |
| <property name="Max Wait (ms)" required="Yes">Pool throws an error if the timeout period is exceeded in the |
| process of trying to retrieve a connection, see <a href="https://commons.apache.org/proper/commons-dbcp/api-2.1.1/org/apache/commons/dbcp2/BasicDataSource.html#getMaxWaitMillis--" >BasicDataSource.html#getMaxWaitMillis</a></property> |
| <property name="Time Between Eviction Runs (ms)" required="Yes">The number of milliseconds to sleep between runs of the idle object evictor thread. When non-positive, no idle object evictor thread will be run. (Defaults to "<code>60000</code>", 1 minute). |
| See <a href="https://commons.apache.org/proper/commons-dbcp/api-2.1.1/org/apache/commons/dbcp2/BasicDataSource.html#getTimeBetweenEvictionRunsMillis--" >BasicDataSource.html#getTimeBetweenEvictionRunsMillis</a></property> |
| <property name="Auto Commit" required="Yes">Turn auto commit on or off for the connections.</property> |
| <property name="Test While Idle" required="Yes">Test idle connections of the pool, see <a href="https://commons.apache.org/proper/commons-dbcp/api-2.1.1/org/apache/commons/dbcp2/BasicDataSource.html#getTestWhileIdle--">BasicDataSource.html#getTestWhileIdle</a>. |
| Validation Query will be used to test it.</property> |
| <property name="Soft Min Evictable Idle Time(ms)" required="Yes">Minimum amount of time a connection may sit idle in the pool before it is eligible for eviction by the idle object evictor, with the extra condition that at least <code>minIdle</code> connections remain in the pool. |
| See <a href="https://commons.apache.org/proper/commons-dbcp/api-2.1.1/org/apache/commons/dbcp2/BasicDataSource.html#getSoftMinEvictableIdleTimeMillis--">BasicDataSource.html#getSoftMinEvictableIdleTimeMillis</a>. |
| Defaults to 5000 (5 seconds) |
| </property> |
| <property name="Validation Query" required="No">A simple query used to determine if the database is still responding. |
| This defaults to the '<code>isValid()</code>' method of the jdbc driver, which is suitable for many databases. |
| However some may require a different query; for example Oracle something like '<code>SELECT 1 FROM DUAL</code>' could be used. |
| Note this validation query is used on pool creation to validate it even if "<code>Test While Idle</code>" suggests query would only be used on idle connections. |
| This is DBCP behaviour. |
| </property> |
| <property name="Database URL" required="Yes">JDBC Connection string for the database.</property> |
| <property name="JDBC Driver class" required="Yes">Fully qualified name of driver class. (Must be in |
| JMeter's classpath - easiest to copy <code>.jar</code> file into JMeter's <code>/lib</code> directory).</property> |
| <property name="Username" required="No">Name of user to connect as.</property> |
| <property name="Password" required="No">Password to connect with. (N.B. this is stored unencrypted in the test plan)</property> |
| </properties> |
| <p>Different databases and JDBC drivers require different JDBC settings. |
| The Database URL and JDBC Driver class are defined by the provider of the JDBC implementation.</p> |
| <p>Some possible settings are shown below. Please check the exact details in the JDBC driver documentation.</p> |
| |
| <p> |
| If JMeter reports <code>No suitable driver</code>, then this could mean either: |
| </p> |
| <ul> |
| <li>The driver class was not found. In this case, there will be a log message such as <code>DataSourceElement: Could not load driver: {classname} java.lang.ClassNotFoundException: {classname}</code></li> |
| <li>The driver class was found, but the class does not support the connection string. This could be because of a syntax error in the connection string, or because the wrong classname was used.</li> |
| </ul> |
| If the database server is not running or is not accessible, then JMeter will report a <code>java.net.ConnectException</code>. |
| <table> |
| <tr><th>Database</th><th>Driver class</th><th>Database URL</th></tr> |
| <tr><td>MySQL</td><td><code>com.mysql.jdbc.Driver</code></td><td><code>jdbc:mysql://host[:port]/dbname</code></td></tr> |
| <tr><td>PostgreSQL</td><td><code>org.postgresql.Driver</code></td><td><code>jdbc:postgresql:{dbname}</code></td></tr> |
| <tr><td>Oracle</td><td><code>oracle.jdbc.OracleDriver</code></td><td><code>jdbc:oracle:thin:@//host:port/service</code> |
| OR<br/><code>jdbc:oracle:thin:@(description=(address=(host={mc-name})(protocol=tcp)(port={port-no}))(connect_data=(sid={sid})))</code></td></tr> |
| <tr><td>Ingres (2006)</td><td><code>ingres.jdbc.IngresDriver</code></td><td><code>jdbc:ingres://host:port/db[;attr=value]</code></td></tr> |
| <tr><td>SQL Server (MS JDBC driver)</td><td><code>com.microsoft.sqlserver.jdbc.SQLServerDriver</code></td><td><code>jdbc:sqlserver://host:port;DatabaseName=dbname</code></td></tr> |
| <tr><td>Apache Derby</td><td><code>org.apache.derby.jdbc.ClientDriver</code></td><td><code>jdbc:derby://server[:port]/databaseName[;URLAttributes=value[;…]]</code></td></tr> |
| </table> |
| <note>The above may not be correct - please check the relevant JDBC driver documentation.</note> |
| </component> |
| |
| |
| <component name="Keystore Configuration" index="§-num;.4.11" width="441" height="189" screenshot="keystore_config.png"> |
| <description><p>The Keystore Config Element lets you configure how Keystore will be loaded and which keys it will use. |
| This component is typically used in HTTPS scenarios where you don't want to take into account keystore initialization into account in response time.</p> |
| <p>To use this element, you need to setup first a Java Key Store with the client certificates you want to test, to do that: |
| </p> |
| <ol> |
| <li>Create your certificates either with Java <code>keytool</code> utility or through your PKI</li> |
| <li>If created by PKI, import your keys in Java Key Store by converting them to a format acceptable by JKS</li> |
| <li>Then reference the keystore file through the two JVM properties (or add them in <code>system.properties</code>): |
| <ul> |
| <li><code>-Djavax.net.ssl.keyStore=path_to_keystore</code></li> |
| <li><code>-Djavax.net.ssl.keyStorePassword=password_of_keystore</code></li> |
| </ul> |
| </li> |
| </ol> |
| </description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree. </property> |
| <property name="Preload" required="Yes">Wether or not to preload Keystore. Setting it to <code>true</code> is usually the best option.</property> |
| <property name="Variable name holding certificate alias" required="False">Variable name that will contain the alias to use for authentication by client certificate. Variable value will be filled from CSV Data Set for example. In the screenshot, "<code>certificat_ssl</code>" will also be a variable in CSV Data Set.</property> |
| <property name="Alias Start Index" required="Yes">The index of the first key to use in Keystore, 0-based.</property> |
| <property name="Alias End Index" required="Yes">The index of the last key to use in Keystore, 0-based. When using "<code>Variable name holding certificate alias</code>" ensure it is large enough so that all keys are loaded at startup.</property> |
| </properties> |
| <note> |
| To make JMeter use more than one certificate you need to ensure that: |
| <ul> |
| <li><code>https.use.cached.ssl.context=false</code> is set in <code>jmeter.properties</code> or <code>user.properties</code></li> |
| <li>You use either HTTPClient 4 (ADVISED) or HTTPClient 3.1 (DEPRECATED SINCE 3.0) implementations for HTTP Request</li> |
| </ul> |
| </note> |
| </component> |
| |
| <component name="Login Config Element" index="§-num;.4.12" width="459" height="126" screenshot="login-config.png"> |
| <description><p>The Login Config Element lets you add or override username and password settings in samplers that use username and password as part of their setup.</p> |
| </description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree. </property> |
| <property name="Username" required="No">The default username to use.</property> |
| <property name="Password" required="No">The default password to use. (N.B. this is stored unencrypted in the test plan)</property> |
| </properties> |
| |
| </component> |
| |
| <component name="LDAP Request Defaults" index="§-num;.4.13" width="689" height="232" screenshot="ldap_defaults.png"> |
| <description><p>The LDAP Request Defaults component lets you set default values for LDAP testing. See the <complink name="LDAP Request"/>.</p> |
| </description> |
| |
| </component> |
| |
| <component name="LDAP Extended Request Defaults" index="§-num;.4.14" width="686" height="184" screenshot="ldapext_defaults.png"> |
| <description><p>The LDAP Extended Request Defaults component lets you set default values for extended LDAP testing. See the <complink name="LDAP Extended Request"/>.</p> |
| </description> |
| |
| </component> |
| |
| <component name="TCP Sampler Config" index="§-num;.4.15" width="826" height="450" screenshot="tcpsamplerconfig.png"> |
| <description> |
| <p> |
| The TCP Sampler Config provides default data for the TCP Sampler |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="TCPClient classname" required="No">Name of the TCPClient class. Defaults to the property <code>tcp.handler</code>, failing that <code>TCPClientImpl</code>.</property> |
| <property name="ServerName or IP" required="">Name or IP of TCP server</property> |
| <property name="Port Number" required="">Port to be used</property> |
| <property name="Re-use connection" required="Yes">If selected, the connection is kept open. Otherwise it is closed when the data has been read.</property> |
| <property name="Close connection" required="Yes">If selected, the connection will be closed after running the sampler.</property> |
| <property name="SO_LINGER" required="No">Enable/disable <code>SO_LINGER</code> with the specified linger time in seconds when a socket is created. If you set "<code>SO_LINGER</code>" value as <code>0</code>, you may prevent large numbers of sockets sitting around with a <code>TIME_WAIT</code> status.</property> |
| <property name="End of line(EOL) byte value" required="No">Byte value for end of line, set this to a value outside the range <code>-128</code> to <code>+127</code> to skip eol checking. You may set this in <code>jmeter.properties</code> file as well with the <code>tcp.eolByte</code> property. If you set this in TCP Sampler Config and in <code>jmeter.properties</code> file at the same time, the setting value in the TCP Sampler Config will be used.</property> |
| <property name="Connect Timeout" required="No">Connect Timeout (milliseconds, 0 disables).</property> |
| <property name="Response Timeout" required="No">Response Timeout (milliseconds, 0 disables).</property> |
| <property name="Set Nodelay" required="">Should the nodelay property be set?</property> |
| <property name="Text to Send" required="">Text to be sent</property> |
| </properties> |
| </component> |
| |
| <component name="User Defined Variables" index="§-num;.4.16" width="741" height="266" screenshot="user_defined_variables.png"> |
| <description><p>The User Defined Variables element lets you define an <b>initial set of variables</b>, just as in the <complink name="Test Plan" />. |
| <note> |
| Note that all the UDV elements in a test plan - no matter where they are - are processed at the start. |
| </note> |
| So you cannot reference variables which are defined as part of a test run, e.g. in a Post-Processor. |
| </p> |
| <p> |
| <b> |
| UDVs should not be used with functions that generate different results each time they are called. |
| Only the result of the first function call will be saved in the variable. |
| </b> |
| However, UDVs can be used with functions such as <code>__P()</code>, for example: |
| </p> |
| <source> |
| HOST ${__P(host,localhost)} |
| </source> |
| <p> |
| which would define the variable "<code>HOST</code>" to have the value of the JMeter property "<code>host</code>", defaulting to "<code>localhost</code>" if not defined. |
| </p> |
| <p> |
| For defining variables during a test run, see <complink name="User Parameters"/>. |
| UDVs are processed in the order they appear in the Plan, from top to bottom. |
| </p> |
| <p> |
| For simplicity, it is suggested that UDVs are placed only at the start of a Thread Group |
| (or perhaps under the Test Plan itself). |
| </p> |
| <p> |
| Once the Test Plan and all UDVs have been processed, the resulting set of variables is |
| copied to each thread to provide the initial set of variables. |
| </p> |
| <p> |
| If a runtime element such as a User Parameters Pre-Processor or Regular Expression Extractor defines a variable |
| with the same name as one of the UDV variables, then this will replace the initial value, and all other test |
| elements in the thread will see the updated value. |
| </p> |
| </description> |
| <note> |
| If you have more than one Thread Group, make sure you use different names for different values, as UDVs are shared between Thread Groups. |
| Also, the variables are not available for use until after the element has been processed, |
| so you cannot reference variables that are defined in the same element. |
| You can reference variables defined in earlier UDVs or on the Test Plan. |
| </note> |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="User Defined Variables" required="">Variable name/value pairs. The string under the "<code>Name</code>" |
| column is what you'll need to place inside the brackets in <code>${…}</code> constructs to use the variables later on. The |
| whole <code>${…}</code> will then be replaced by the string in the "<code>Value</code>" column.</property> |
| </properties> |
| </component> |
| |
| <component name="Random Variable" index="§-num;.4.17" width="495" height="286" screenshot="random_variable.png"> |
| <description> |
| <p> |
| The Random Variable Config Element is used to generate random numeric strings and store them in variable for use later. |
| It's simpler than using <complink name="User Defined Variables"/> together with the <code>__Random()</code> function. |
| </p> |
| <p> |
| The output variable is constructed by using the random number generator, |
| and then the resulting number is formatted using the format string. |
| The number is calculated using the formula <code>minimum+Random.nextInt(maximum-minimum+1)</code>. |
| <code>Random.nextInt()</code> requires a positive integer. |
| This means that <code>maximum-minimum</code> - i.e. the range - must be less than <code>2147483647</code>, |
| however the <code>minimum</code> and <code>maximum</code> values can be any <code>long</code> values so long as the range is OK. |
| </p> |
| </description> |
| |
| <properties> |
| <property name="Name" required="Yes">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Variable Name" required="Yes">The name of the variable in which to store the random string.</property> |
| <property name="Format String" required="No">The <code>java.text.DecimalFormat</code> format string to be used. |
| For example "<code>000</code>" which will generate numbers with at least 3 digits, |
| or "<code>USER_000</code>" which will generate output of the form <code>USER_nnn</code>. |
| If not specified, the default is to generate the number using <code>Long.toString()</code></property> |
| <property name="Minimum Value" required="Yes">The minimum value (<code>long</code>) of the generated random number.</property> |
| <property name="Maximum Value" required="Yes">The maximum value (<code>long</code>) of the generated random number.</property> |
| <property name="Random Seed" required="No">The seed for the random number generator. Default is the current time in milliseconds. |
| If you use the same seed value with Per Thread set to <code>true</code>, you will get the same value for each Thread as per |
| <a href="http://docs.oracle.com/javase/7/docs/api/java/util/Random.html" >Random</a> class. |
| </property> |
| <property name="Per Thread(User)?" required="Yes">If <code>False</code>, the generator is shared between all threads in the thread group. |
| If <code>True</code>, then each thread has its own random generator.</property> |
| </properties> |
| |
| </component> |
| |
| <component name="Counter" index="§-num;.4.18" width="404" height="262" screenshot="counter.png"> |
| <description><p>Allows the user to create a counter that can be referenced anywhere |
| in the Thread Group. The counter config lets the user configure a starting point, a maximum, |
| and the increment. The counter will loop from the start to the max, and then start over |
| with the start, continuing on like that until the test is ended. </p> |
| <p>The counter uses a long to store the value, so the range is from <code>-2^63</code> to <code>2^63-1</code>.</p> |
| </description> |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Start" required="Yes">The starting number for the counter. The counter will equal this |
| number during the first iteration.</property> |
| <property name="Increment" required="Yes">How much to increment the counter by after each |
| iteration.</property> |
| <property name="Maximum" required="No">If the counter exceeds the maximum, then it is reset to the <code>Start</code> value. |
| Default is <code>Long.MAX_VALUE</code> |
| </property> |
| <property name="Format" required="No">Optional format, e.g. <code>000</code> will format as <code>001</code>, <code>002</code>, etc. |
| This is passed to <code>DecimalFormat</code>, so any valid formats can be used. |
| If there is a problem interpreting the format, then it is ignored. |
| [The default format is generated using <code>Long.toString()</code>] |
| </property> |
| <property name="Reference Name" required="Yes">This controls how you refer to this value in other elements. Syntax is |
| as in <a href="functions.html">user-defined values</a>: <code>$(reference_name}</code>.</property> |
| <property name="Track Counter Independently for each User" required="No">In other words, is this a global counter, or does each user get their |
| own counter? If unchecked, the counter is global (i.e., user #1 will get value "<code>1</code>", and user #2 will get value "<code>2</code>" on |
| the first iteration). If checked, each user has an independent counter.</property> |
| <property name="Reset counter on each Thread Group Iteration" required="No">This option is only available when counter is tracked per User, if checked, |
| counter will be reset to <code>Start</code> value on each Thread Group iteration. This can be useful when Counter is inside a Loop Controller.</property> |
| </properties> |
| </component> |
| |
| <component name="Simple Config Element" index="§-num;.4.19" width="627" height="282" screenshot="simple_config_element.png"> |
| <description><p>The Simple Config Element lets you add or override arbitrary values in samplers. You can choose the name of the value |
| and the value itself. Although some adventurous users might find a use for this element, it's here primarily for developers as a basic |
| GUI that they can use while developing new JMeter components.</p> |
| </description> |
| |
| <properties> |
| <property name="Name" required="Yes">Descriptive name for this element that is shown in the tree. </property> |
| <property name="Parameter Name" required="Yes">The name of each parameter. These values are internal to JMeter's workings and |
| are not generally documented. Only those familiar with the code will know these values.</property> |
| <property name="Parameter Value" required="Yes">The value to apply to that parameter.</property> |
| </properties> |
| |
| </component> |
| |
| |
| <component name="MongoDB Source Config (DEPRECATED)" index="§-num;.4.20" |
| width="1233" height="618" screenshot="mongodb-source-config.png"> |
| <description>Creates a MongoDB connection (used by <complink name="MongoDB Script"/>Sampler) |
| from the supplied Connection settings. Each thread gets its own connection. |
| The connection configuration name is used by the JDBC Sampler to select the appropriate |
| connection. |
| <p> |
| You can then access <code>com.mongodb.DB</code> object in Beanshell or JSR223 Test Elements through the element <a href="../api/org/apache/jmeter/protocol/mongodb/config/MongoDBHolder.html">MongoDBHolder</a> |
| using this code</p> |
| |
| <source> |
| import com.mongodb.DB; |
| import org.apache.jmeter.protocol.mongodb.config.MongoDBHolder; |
| DB db = MongoDBHolder.getDBFromSource("value of property MongoDB Source", |
| "value of property Database Name"); |
| … |
| </source> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for the connection configuration that is shown in the tree.</property> |
| <property name="Server Address List" required="Yes">Mongo DB Servers</property> |
| <property name="MongoDB Source" required="Yes">The name of the variable the connection is tied to. |
| <note>Each name must be different. If there are two configuration elements using the same name, only one will be saved.</note> |
| </property> |
| |
| <property name="Keep Trying" required="No"> |
| If <code>true</code>, the driver will keep trying to connect to the same server in case that the socket cannot be established.<br/> |
| There is maximum amount of time to keep retrying, which is 15s by default.<br/>This can be useful to avoid some exceptions being thrown when a server is down temporarily by blocking the operations. |
| <br/>It can also be useful to smooth the transition to a new master (so that a new master is elected within the retry time).<br/> |
| <note>Note that when using this flag |
| <ul> |
| <li>for a replica set, the driver will try to connect to the old master for that time, instead of failing over to the new one right away </li> |
| <li>this does not prevent exception from being thrown in read/write operations on the socket, which must be handled by application.</li> |
| </ul> |
| Even if this flag is false, the driver already has mechanisms to automatically recreate broken connections and retry the read operations. |
| </note> |
| Default is <code>false</code>. |
| </property> |
| <property name="Maximum connections per host" required="No"></property> |
| <property name="Connection timeout" required="No"> |
| The connection timeout in milliseconds.<br/>It is used solely when establishing a new connection <code>Socket.connect(java.net.SocketAddress, int)</code><br/>Default is <code>0</code> and means no timeout. |
| </property> |
| <property name="Maximum retry time" required="No"> |
| The maximum amount of time in milliseconds to spend retrying to open connection to the same server.<br/>Default is <code>0</code>, which means to use the default 15s if <code>autoConnectRetry</code> is on. |
| </property> |
| <property name="Maximum wait time" required="No"> |
| The maximum wait time in milliseconds that a thread may wait for a connection to become available.<br/>Default is <code>120,000</code>. |
| </property> |
| <property name="Socket timeout" required="No"> |
| The socket timeout in milliseconds It is used for I/O socket read and write operations <code>Socket.setSoTimeout(int)</code><br/>Default is <code>0</code> and means no timeout. |
| </property> |
| <property name="Socket keep alive" required="No"> |
| This flag controls the socket keep alive feature that keeps a connection alive through firewalls <code>Socket.setKeepAlive(boolean)</code><br/> |
| Default is <code>false</code>. |
| </property> |
| <property name="ThreadsAllowedToBlockForConnectionMultiplier" required="No"> |
| This multiplier, multiplied with the connectionsPerHost setting, gives the maximum number of threads that may be waiting for a connection to become available from the pool.<br/> |
| All further threads will get an exception right away.<br/> |
| For example if <code>connectionsPerHost</code> is <code>10</code> and <code>threadsAllowedToBlockForConnectionMultiplier</code> is <code>5</code>, then up to 50 threads can wait for a connection.<br/> |
| Default is <code>5</code>. |
| </property> |
| <property name="Write Concern : Safe" required="No"> |
| If <code>true</code> the driver will use a <code>WriteConcern</code> of <code>WriteConcern.SAFE</code> for all operations.<br/> |
| If <code>w</code>, <code>wtimeout</code>, <code>fsync</code> or <code>j</code> are specified, this setting is ignored.<br/> |
| Default is <code>false</code>. |
| </property> |
| <property name="Write Concern : Fsync" required="No"> |
| The <code>fsync</code> value of the global <code>WriteConcern</code>.<br/> |
| Default is <code>false</code>. |
| </property> |
| <property name="Write Concern : Wait for Journal" required="No"> |
| The <code>j</code> value of the global <code>WriteConcern</code>.<br/> |
| Default is <code>false</code>. |
| </property> |
| <property name="Write Concern : Wait for servers" required="No"> |
| The <code>w</code> value of the global <code>WriteConcern</code>.<br/>Default is <code>0</code>. |
| </property> |
| <property name="Write Concern : Wait timeout" required="No"> |
| The <code>wtimeout</code> value of the global <code>WriteConcern</code>.<br/>Default is <code>0</code>. |
| </property> |
| <property name="Write Concern : Continue on error" required="No"> |
| If batch inserts should continue after the first error |
| </property> |
| </properties> |
| </component> |
| |
| <a href="#">^</a> |
| |
| </section> |
| |
| <section name="§-num;.5 Assertions" anchor="assertions"> |
| <description> |
| <p> |
| Assertions are used to perform additional checks on samplers, and are processed after <b>every sampler</b> |
| in the same scope. |
| To ensure that an Assertion is applied only to a particular sampler, add it as a child of the sampler. |
| </p> |
| <note> |
| Note: Unless documented otherwise, Assertions are not applied to sub-samples (child samples) - |
| only to the parent sample. |
| In the case of BSF and BeanShell Assertions, the script can retrieve sub-samples using the method |
| <code>prev.getSubResults()</code> which returns an array of SampleResults. |
| The array will be empty if there are none. |
| </note> |
| <p> |
| Assertions can be applied to either the main sample, the sub-samples or both. |
| The default is to apply the assertion to the main sample only. |
| If the Assertion supports this option, then there will be an entry on the GUI which looks like the following: |
| </p> |
| <figure width="658" height="54" image="assertion/assertionscope.png">Assertion Scope</figure> |
| or the following |
| <figure width="841" height="55" image="assertion/assertionscopevar.png">Assertion Scope</figure> |
| <p> |
| If a sub-sampler fails and the main sample is successful, |
| then the main sample will be set to failed status and an Assertion Result will be added. |
| If the JMeter variable option is used, it is assumed to relate to the main sample, and |
| any failure will be applied to the main sample only. |
| </p> |
| <note> |
| The variable <code>JMeterThread.last_sample_ok</code> is updated to |
| "<code>true</code>" or "<code>false</code>" after all assertions for a sampler have been run. |
| </note> |
| </description> |
| <component name="Response Assertion" index="§-num;.5.1" anchor="basic_assertion" width="921" height="423" screenshot="assertion/assertion.png"> |
| |
| <description><p>The response assertion control panel lets you add pattern strings to be compared against various |
| fields of the response. |
| The pattern strings are: |
| </p> |
| <ul> |
| <li><code>Contains</code>, <code>Matches</code>: Perl5-style regular expressions</li> |
| <li><code>Equals</code>, <code>Substring</code>: plain text, case-sensitive</li> |
| </ul> |
| <p> |
| A summary of the pattern matching characters can be found at <a href="http://jakarta.apache.org/oro/api/org/apache/oro/text/regex/package-summary.html">ORO Perl5 regular expressions.</a> |
| </p> |
| <p>You can also choose whether the strings will be expected |
| to <b>match</b> the entire response, or if the response is only expected to <b>contain</b> the |
| pattern. You can attach multiple assertions to any controller for additional flexibility.</p> |
| <p>Note that the pattern string should not include the enclosing delimiters, |
| i.e. use <code>Price: \d+</code> not <code>/Price: \d+/</code>. |
| </p> |
| <p> |
| By default, the pattern is in multi-line mode, which means that the "<code>.</code>" meta-character does not match newline. |
| In multi-line mode, "<code>^</code>" and "<code>$</code>" match the start or end of any line anywhere within the string |
| - not just the start and end of the entire string. Note that <code>\s</code> does match new-line. |
| Case is also significant. To override these settings, one can use the <i>extended regular expression</i> syntax. |
| For example: |
| </p> |
| <dl> |
| <dt><code>(?i)</code></dt><dd>ignore case</dd> |
| <dt><code>(?s)</code></dt><dd>treat target as single line, i.e. "<code>.</code>" matches new-line</dd> |
| <dt><code>(?is)</code></dt><dd>both the above</dd> |
| </dl> |
| These can be used anywhere within the expression and remain in effect until overridden. E.g. |
| <dl> |
| <dt><code>(?i)apple(?-i) Pie</code></dt><dd>matches "<code>ApPLe Pie</code>", but not "<code>ApPLe pIe</code>"</dd> |
| <dt><code>(?s)Apple.+?Pie</code></dt><dd>matches <code>Apple</code> followed by <code>Pie</code>, which may be on a subsequent line.</dd> |
| <dt><code>Apple(?s).+?Pie</code></dt><dd>same as above, but it's probably clearer to use the <code>(?s)</code> at the start.</dd> |
| </dl> |
| |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Apply to:" required="Yes"> |
| 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><code>Main sample only</code> - assertion only applies to the main sample</li> |
| <li><code>Sub-samples only</code> - assertion only applies to the sub-samples</li> |
| <li><code>Main sample and sub-samples</code> - assertion applies to both.</li> |
| <li><code>JMeter Variable</code> - assertion is to be applied to the contents of the named variable</li> |
| </ul> |
| </property> |
| <property name="Response Field to Test" required="Yes">Instructs JMeter which field of the Response to test. |
| <ul> |
| <li><code>Text Response</code> - the response text from the server, i.e. the body, excluding any HTTP headers.</li> |
| <li><code>Document (text)</code> - the extract text from various type of documents via Apache Tika (see <complink name="View Results Tree"/> Document view section).</li> |
| <li><code>URL sampled</code></li> |
| <li><code>Response Code</code> - e.g. <code>200</code></li> |
| <li><code>Response Message</code> - e.g. <code>OK</code></li> |
| <li><code>Response Headers</code>, including Set-Cookie headers (if any)</li> |
| </ul> |
| </property> |
| <property name="Ignore status" required="Yes">Instructs JMeter to set the status to success initially. |
| <p> |
| The overall success of the sample is determined by combining the result of the |
| assertion with the existing Response status. |
| When the <code>Ignore Status</code> checkbox is selected, the Response status is forced |
| to successful before evaluating the Assertion. |
| </p> |
| HTTP Responses with statuses in the <code>4xx</code> and <code>5xx</code> ranges are normally |
| regarded as unsuccessful. |
| The "<code>Ignore status</code>" checkbox can be used to set the status successful before performing further checks. |
| Note that this will have the effect of clearing any previous assertion failures, |
| so make sure that this is only set on the first assertion. |
| </property> |
| <property name="Pattern Matching Rules" required="Yes">Indicates how the text being tested |
| is checked against the pattern. |
| <ul> |
| <li><code>Contains</code> - true if the text contains the regular expression pattern</li> |
| <li><code>Matches</code> - true if the whole text matches the regular expression pattern</li> |
| <li><code>Equals</code> - true if the whole text equals the pattern string (case-sensitive)</li> |
| <li><code>Substring</code> - true if the text contains the pattern string (case-sensitive)</li> |
| </ul> |
| <code>Equals</code> and <code>Substring</code> patterns are plain strings, not regular expressions. |
| <code>NOT</code> may also be selected to invert the result of the check.</property> |
| <property name="Patterns to Test" required="Yes">A list of patterns to |
| be tested. |
| Each pattern is tested separately. |
| If a pattern fails, then further patterns are not checked. |
| There is no difference between setting up |
| one Assertion with multiple patterns and setting up multiple Assertions with one |
| pattern each (assuming the other options are the same). |
| <note>However, when the <code>Ignore Status</code> checkbox is selected, this has the effect of cancelling any |
| previous assertion failures - so make sure that the <code>Ignore Status</code> checkbox is only used on |
| the first Assertion.</note> |
| </property> |
| </properties> |
| <p> |
| The pattern is a Perl5-style regular expression, but without the enclosing brackets. |
| </p> |
| <example title="Assertion Examples" anchor="assertion_examples"> |
| <center> |
| <figure image="assertion/example1a.png" width="266" height="117">Figure 14 - Test Plan</figure> |
| <figure image="assertion/example1b.png" width="920" height="451">Figure 15 - Assertion Control Panel with Pattern</figure> |
| <figure image="assertion/example1c-pass.png" width="801" height="230">Figure 16 - Assertion Listener Results (Pass)</figure> |
| <figure image="assertion/example1c-fail.png" width="800" height="233">Figure 17 - Assertion Listener Results (Fail)</figure> |
| </center> |
| </example> |
| |
| |
| </component> |
| |
| <component name="Duration Assertion" index="§-num;.5.2" width="606" height="187" screenshot="duration_assertion.png"> |
| <description><p>The Duration Assertion tests that each response was received within a given amount |
| of time. Any response that takes longer than the given number of milliseconds (specified by the |
| user) is marked as a failed response.</p></description> |
| |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Duration in Milliseconds" required="Yes">The maximum number of milliseconds |
| each response is allowed before being marked as failed.</property> |
| </properties> |
| </component> |
| |
| <component name="Size Assertion" index="§-num;.5.3" width="732" height="358" screenshot="size_assertion.png"> |
| <description><p>The Size Assertion tests that each response contains the right number of bytes in it. You can specify that |
| the size be equal to, greater than, less than, or not equal to a given number of bytes.</p> |
| <note>An empty response is treated as being 0 bytes rather than reported as an error.</note> |
| </description> |
| |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Apply to:" required="Yes"> |
| 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><code>Main sample only</code> - assertion only applies to the main sample</li> |
| <li><code>Sub-samples only</code> - assertion only applies to the sub-samples</li> |
| <li><code>Main sample and sub-samples</code> - assertion applies to both.</li> |
| <li><code>JMeter Variable</code> - assertion is to be applied to the contents of the named variable</li> |
| </ul> |
| </property> |
| <property name="Size in bytes" required="Yes">The number of bytes to use in testing the size of the response (or value of the JMeter variable).</property> |
| <property name="Type of Comparison" required="Yes">Whether to test that the response is equal to, greater than, less than, |
| or not equal to, the number of bytes specified.</property> |
| |
| </properties> |
| </component> |
| |
| <component name="XML Assertion" index="§-num;.5.4" width="470" height="85" screenshot="xml_assertion.png"> |
| <description><p>The XML Assertion tests that the response data consists of a formally correct XML document. It does not |
| validate the XML based on a DTD or schema or do any further validation.</p></description> |
| |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| |
| </properties> |
| </component> |
| |
| <component name="BeanShell Assertion" index="§-num;.5.5" width="849" height="633" screenshot="beanshell_assertion.png"> |
| <description><p>The BeanShell Assertion allows the user to perform assertion checking using a BeanShell script. |
| </p> |
| <p> |
| <b>For full details on using BeanShell, please see the <a href="http://www.beanshell.org/">BeanShell website.</a></b> |
| </p><p> |
| Note that a different Interpreter is used for each independent occurrence of the assertion |
| in each thread in a test script, but the same Interpreter is used for subsequent invocations. |
| This means that variables persist across calls to the assertion. |
| </p> |
| <p> |
| All Assertions are called from the same thread as the sampler. |
| </p> |
| <p> |
| If the property "<code>beanshell.assertion.init</code>" is defined, it is passed to the Interpreter |
| as the name of a sourced file. This can be used to define common methods and variables. |
| There is a sample init file in the <code>bin</code> directory: <code>BeanShellAssertion.bshrc</code> |
| </p> |
| <p> |
| The test element supports the <code>ThreadListener</code> and <code>TestListener</code> methods. |
| These should be defined in the initialisation file. |
| See the file <code>BeanShellListeners.bshrc</code> for example definitions. |
| </p> |
| </description> |
| |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree. |
| The name is stored in the script variable <code>Label</code></property> |
| <property name="Reset bsh.Interpreter before each call" required="Yes"> |
| If this option is selected, then the interpreter will be recreated for each sample. |
| This may be necessary for some long running scripts. |
| For further information, see <a href="best-practices#bsh_scripting">Best Practices - BeanShell scripting</a>. |
| </property> |
| <property name="Parameters" required="No">Parameters to pass to the BeanShell script. |
| The parameters are stored in the following variables: |
| <ul> |
| <li><code>Parameters</code> - string containing the parameters as a single variable</li> |
| <li><code>bsh.args</code> - String array containing parameters, split on white-space</li> |
| </ul></property> |
| <property name="Script file" required="No">A file containing the BeanShell script to run. This overrides the script. |
| The file name is stored in the script variable <code>FileName</code></property> |
| <property name="Script" required="Yes (unless script file is provided)">The BeanShell script to run. The return value is ignored.</property> |
| </properties> |
| <p>There's a <a href="../demos/BeanShellAssertion.bsh">sample script</a> you can try.</p> |
| <p> |
| Before invoking the script, some variables are set up in the BeanShell interpreter. |
| These are strings unless otherwise noted: |
| </p> |
| <ul> |
| <li><code>log</code> - the <a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a> Object. (e.g.) <code>log.warn("Message"[,Throwable])</code></li> |
| <li><code>SampleResult</code> - the <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a> Object; read-write</li> |
| <li><code>Response</code> - the response Object; read-write</li> |
| <li><code>Failure</code> - boolean; read-write; used to set the Assertion status</li> |
| <li><code>FailureMessage</code> - String; read-write; used to set the Assertion message</li> |
| <li><code>ResponseData</code> - the response body (byte [])</li> |
| <li><code>ResponseCode</code> - e.g. <code>200</code></li> |
| <li><code>ResponseMessage</code> - e.g. <code>OK</code></li> |
| <li><code>ResponseHeaders</code> - contains the HTTP headers</li> |
| <li><code>RequestHeaders</code> - contains the HTTP headers sent to the server</li> |
| <li><code>SampleLabel</code></li> |
| <li><code>SamplerData</code> - data that was sent to the server</li> |
| <li><code>ctx</code> - <a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a></li> |
| <li><code>vars</code> - <a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a> - e.g. |
| <source>vars.get("VAR1"); |
| vars.put("VAR2","value"); |
| vars.putObject("OBJ1",new Object());</source></li> |
| <li><code>props</code> - JMeterProperties (class <code>java.util.Properties</code>) - e.g. |
| <source>props.get("START.HMS"); |
| props.put("PROP1","1234");</source></li> |
| </ul> |
| <p>The following methods of the Response object may be useful:</p> |
| <ul> |
| <li><code>setStopThread(boolean)</code></li> |
| <li><code>setStopTest(boolean)</code></li> |
| <li><code>String getSampleLabel()</code></li> |
| <li><code>setSampleLabel(String)</code></li> |
| </ul> |
| </component> |
| |
| <component name="MD5Hex Assertion" index="§-num;.5.6" width="398" height="130" screenshot="assertion/MD5HexAssertion.png"> |
| <description><p>The MD5Hex Assertion allows the user to check the MD5 hash of the response data.</p></description> |
| |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="MD5 sum" required="Yes">32 hex digits representing the MD5 hash (case not significant)</property> |
| |
| </properties> |
| </component> |
| |
| <component name="HTML Assertion" index="§-num;.5.7" width="505" height="341" screenshot="assertion/HTMLAssertion.png"> |
| <description><p>The HTML Assertion allows the user to check the HTML syntax of the response data using JTidy.</p></description> |
| |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="doctype" required="Yes"><code>omit</code>, <code>auto</code>, <code>strict</code> or <code>loose</code></property> |
| <property name="Format" required="Yes"><code>HTML</code>, <code>XHTML</code> or <code>XML</code></property> |
| <property name="Errors only" required="Yes">Only take note of errors?</property> |
| <property name="Error threshold" required="Yes">Number of errors allowed before classing the response as failed</property> |
| <property name="Warning threshold" required="Yes">Number of warnings allowed before classing the response as failed</property> |
| <property name="Filename" required="No">Name of file to which report is written</property> |
| |
| </properties> |
| </component> |
| <component name="XPath Assertion" index="§-num;.5.8" width="800" height="317" screenshot="xpath_assertion.png"> |
| <description><p>The XPath Assertion tests a document for well formedness, has the option |
| of validating against a DTD, or putting the document through JTidy and testing for an |
| XPath. If that XPath exists, the Assertion is true. Using "<code>/</code>" will match any well-formed |
| document, and is the default XPath Expression. |
| The assertion also supports boolean expressions, such as "<code>count(//*error)=2</code>". |
| See <a href="http://www.w3.org/TR/xpath">http://www.w3.org/TR/xpath</a> for more information |
| on XPath. |
| </p> |
| Some sample expressions: |
| <ul> |
| <li><code>//title[text()='Text to match']</code> - matches <code><text>Text to match</text></code> anywhere in the response</li> |
| <li><code>/title[text()='Text to match']</code> - matches <code><text>Text to match</text></code> at root level in the response</li> |
| </ul> |
| </description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Use Tidy (tolerant parser)" required="Yes">Use Tidy, i.e. be tolerant of XML/HTML errors</property> |
| <property name="Quiet" required="If Tidy is selected">Sets the Tidy Quiet flag</property> |
| <property name="Report Errors" required="If Tidy is selected">If a Tidy error occurs, then set the Assertion accordingly</property> |
| <property name="Show warnings" required="If Tidy is selected">Sets the Tidy showWarnings option</property> |
| <property name="Use Namespaces" required="If Tidy is not selected">Should namespaces be honoured?</property> |
| <property name="Validate XML" required="If Tidy is not selected">Check the document against its schema.</property> |
| <property name="Ignore Whitespace" required="If Tidy is not selected">Ignore Element Whitespace.</property> |
| <property name="Fetch External DTDs" required="If Tidy is not selected">If selected, external DTDs are fetched.</property> |
| <property name="XPath Assertion" required="Yes">XPath to match in the document.</property> |
| <property name="True if nothing matches" required="No">True if a XPath expression is not matched</property> |
| </properties> |
| <note> |
| The non-tolerant parser can be quite slow, as it may need to download the DTD etc. |
| </note> |
| <note> |
| As a work-round for namespace limitations of the Xalan XPath parser implementation on which JMeter is based, |
| you can provide a Properties file which contains mappings for the namespace prefixes: |
| <source> |
| prefix1=Full Namespace 1 |
| prefix2=Full Namespace 2 |
| … |
| </source> |
| |
| You reference this file in <code>jmeter.properties</code> file using the property: |
| <source>xpath.namespace.config</source> |
| </note> |
| </component> |
| <component name="XML Schema Assertion" index="§-num;.5.9" width="472" height="132" screenshot="assertion/XMLSchemaAssertion.png"> |
| <description><p>The XML Schema Assertion allows the user to validate a response against an XML Schema.</p></description> |
| |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="File Name" required="Yes">Specify XML Schema File Name</property> |
| </properties> |
| </component> |
| |
| <component name="BSF Assertion" index="§-num;.5.10" width="847" height="634" screenshot="bsf_assertion.png"> |
| <description> |
| <p> |
| The BSF Assertion allows BSF script code to be used to check the status of the previous sample. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Language" required="Yes">The BSF language to be used</property> |
| <property name="Parameters" required="No">Parameters to pass to the script. |
| The parameters are stored in the following variables: |
| <ul> |
| <li><code>Parameters</code> - string containing the parameters as a single variable</li> |
| <li><code>args</code> - String array containing parameters, split on white-space</li> |
| </ul></property> |
| <property name="Script file" required="No">A file containing the script to run, if a relative file path is used, then it will be relative to directory referenced by "<code>user.dir</code>" System property</property> |
| <property name="Script" required="Yes (unless script file is provided)">The script to run.</property> |
| </properties> |
| <p> |
| The script (or file) is processed using the <code>BSFEngine.exec()</code> method, which does not return a value. |
| </p> |
| <p>The following variables are set up for use by the script:</p> |
| <ul> |
| <li><code>log</code> - (<a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a>) - can be used to write to the log file</li> |
| <li><code>Label</code> - the String Label</li> |
| <li><code>Filename</code> - the script file name (if any)</li> |
| <li><code>Parameters</code> - the parameters (as a String)</li> |
| <li><code>args</code> - the parameters as a String array (split on whitespace)</li> |
| <li><code>ctx</code> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li> |
| <li><code>vars</code> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: |
| <source> |
| vars.get(key); |
| vars.put(key,val); |
| vars.putObject("OBJ1",new Object()); |
| vars.getObject("OBJ2"); |
| </source></li> |
| <li><code>props</code> - (JMeterProperties - class <code>java.util.Properties</code>) - e.g. |
| <source> |
| props.get("START.HMS"); |
| props.put("PROP1","1234"); |
| </source></li> |
| <li><code>SampleResult</code>, <code>prev</code> - (<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the previous SampleResult (if any)</li> |
| <li><code>sampler</code> - (<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>) - gives access to the current sampler</li> |
| <li><code>OUT</code> - <code>System.out</code> - e.g. <code>OUT.println("message")</code></li> |
| <li><code>AssertionResult</code> - the assertion result</li> |
| </ul> |
| <p> |
| The script can check various aspects of the <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>. |
| If an error is detected, the script should use <code>AssertionResult.setFailureMessage("message")</code> and <code>AssertionResult.setFailure(true)</code>. |
| </p> |
| <p>For further details of all the methods available on each of the above variables, please check the Javadoc</p> |
| </component> |
| |
| <component name="JSR223 Assertion" index="§-num;.5.11"> |
| <description> |
| <p> |
| The JSR223 Assertion allows JSR223 script code to be used to check the status of the previous sample. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Language" required="Yes">The JSR223 language to be used</property> |
| <property name="Parameters" required="No">Parameters to pass to the script. |
| The parameters are stored in the following variables: |
| <ul> |
| <li><code>Parameters</code> - string containing the parameters as a single variable</li> |
| <li><code>args</code> - String array containing parameters, split on white-space</li> |
| </ul></property> |
| <property name="Script file" required="No">A file containing the script to run, if a relative file path is used, then it will be relative to directory referenced by "<code>user.dir</code>" System property</property> |
| <property name="Script compilation caching" required="No">Unique String across Test Plan that JMeter will use to cache result of Script compilation if language used supports <code>Compilable</code> interface (Groovy is one of these, java, beanshell and javascript are not) |
| <note>See note in JSR223 Sampler Java System property if you're using Groovy without checking this option</note> |
| </property> |
| <property name="Script" required="Yes (unless script file is provided)">The script to run.</property> |
| </properties> |
| <p>The following variables are set up for use by the script:</p> |
| <ul> |
| <li><code>log</code> - (<a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a>) - can be used to write to the log file</li> |
| <li><code>Label</code> - the String Label</li> |
| <li><code>Filename</code> - the script file name (if any)</li> |
| <li><code>Parameters</code> - the parameters (as a String)</li> |
| <li><code>args</code> - the parameters as a String array (split on whitespace)</li> |
| <li><code>ctx</code> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li> |
| <li><code>vars</code> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: |
| <source> |
| vars.get(key); |
| vars.put(key,val); |
| vars.putObject("OBJ1",new Object()); |
| vars.getObject("OBJ2"); |
| </source></li> |
| <li><code>props</code> - (JMeterProperties - class <code>java.util.Properties</code>) - e.g. |
| <source> |
| props.get("START.HMS"); |
| props.put("PROP1","1234"); |
| </source></li> |
| <li><code>SampleResult</code>, <code>prev</code> - (<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the previous SampleResult (if any)</li> |
| <li><code>sampler</code> - (<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>) - gives access to the current sampler</li> |
| <li><code>OUT</code> - <code>System.out</code> - e.g. <code>OUT.println("message")</code></li> |
| <li><code>AssertionResult</code> - the assertion result</li> |
| </ul> |
| <p> |
| The script can check various aspects of the <a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>. |
| If an error is detected, the script should use <code>AssertionResult.setFailureMessage("message")</code> and <code>AssertionResult.setFailure(true)</code>. |
| </p> |
| <p>For further details of all the methods available on each of the above variables, please check the Javadoc</p> |
| </component> |
| |
| <component name="Compare Assertion" index="§-num;.5.12" width="580" height="302" screenshot="assertion/compare.png"> |
| <description> |
| <note> |
| Compare Assertion <b>must not be used</b> 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. |
| </note> |
| |
| The Compare Assertion can be used to compare sample results within its scope. |
| Either the contents or the elapsed time can be compared, and the contents can be filtered before comparison. |
| The assertion comparisons can be seen in the <complink name="Comparison Assertion Visualizer"/>. |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Compare Content" required="Yes">Whether or not to compare the content (response data)</property> |
| <property name="Compare Time" required="Yes">If the value is ≥0, then check if the response time difference is no greater than the value. |
| I.e. if the value is <code>0</code>, then the response times must be exactly equal.</property> |
| <property name="Comparison Filters" required="No">Filters can be used to remove strings from the content comparison. |
| For example, if the page has a time-stamp, it might be matched with: "<code>Time: \d\d:\d\d:\d\d</code>" and replaced with a dummy fixed time "<code>Time: HH:MM:SS</code>". |
| </property> |
| </properties> |
| </component> |
| |
| <component name="SMIME Assertion" index="§-num;.5.13" width="471" height="428" screenshot="assertion/smime.png"> |
| <description> |
| The SMIME Assertion can be used to evaluate the sample results from the Mail Reader Sampler. |
| This assertion verifies if the body of a mime message is signed or not. The signature can also be verified against a specific signer certificate. |
| As this is a functionality that is not necessarily needed by most users, additional jars need to be downloaded and added to <code>JMETER_HOME/lib</code>:<br></br> |
| <ul> |
| <li><code>bcmail-xxx.jar</code> (BouncyCastle SMIME/CMS)</li> |
| <li><code>bcprov-xxx.jar</code> (BouncyCastle Provider)</li> |
| </ul> |
| These need to be <a href="http://www.bouncycastle.org/latest_releases.html">downloaded from BouncyCastle.</a> |
| <p> |
| If using the <complink name="Mail Reader Sampler">Mail Reader Sampler</complink>, |
| please ensure that you select "<code>Store the message using MIME (raw)</code>" otherwise the Assertion won't be able to process the message correctly. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Verify Signature" required="Yes">If selected, the assertion will verify if it is a valid signature according to the parameters defined in the <code>Signer Certificate</code> box.</property> |
| <property name="Message not signed" required="Yes">Whether or not to expect a signature in the message</property> |
| <property name="Signer Cerificate" required="Yes">"<code>No Check</code>" means that it will not perform signature verification. "<code>Check values</code>" is used to verify the signature against the inputs provided. And "<code>Certificate file</code>" will perform the verification against a specific certificate file.</property> |
| <property name="Message Position" required="Yes"> |
| The Mail sampler can retrieve multiple messages in a single sample. |
| Use this field to specify which message will be checked. |
| Messages are numbered from <code>0</code>, so <code>0</code> means the first message. |
| Negative numbers count from the LAST message; <code>-1</code> means LAST, <code>-2</code> means penultimate etc. |
| </property> |
| </properties> |
| </component> |
| |
| <a href="#">^</a> |
| |
| </section> |
| |
| <section name="§-num;.6 Timers" anchor="timers"> |
| <description> |
| <br></br> |
| <note> |
| Note that timers are processed <b>before</b> each sampler in the scope in which they are found; |
| if there are several timers in the same scope, <b>all</b> the timers will be processed <b>before |
| each</b> sampler. |
| <br></br> |
| Timers are only processed in conjunction with a sampler. |
| A timer which is not in the same scope as a sampler will not be processed at all. |
| <br></br> |
| To apply a timer to a single sampler, add the timer as a child element of the sampler. |
| The timer will be applied before the sampler is executed. |
| To apply a timer after a sampler, either add it to the next sampler, or add it as the |
| child of a <complink name="Test Action"/> Sampler. |
| </note> |
| </description> |
| <component name="Constant Timer" index="§-num;.6.1" anchor="constant" width="372" height="100" screenshot="timers/constant_timer.png"> |
| <description> |
| <p>If you want to have each thread pause for the same amount of time between |
| requests, use this timer.</p></description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this timer that is shown in the tree.</property> |
| <property name="Thread Delay" required="Yes">Number of milliseconds to pause.</property> |
| </properties> |
| </component> |
| |
| <component name="Gaussian Random Timer" index="§-num;.6.2" width="372" height="156" screenshot="timers/gauss_random_timer.png"> |
| |
| <description><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 Gaussian distributed value (with mean <code>0.0</code> and standard deviation <code>1.0</code>) times |
| the deviation value you specify, and the offset value. |
| Another way to explain it, in Gaussian Random Timer, the variation around constant offset has a gaussian curve distribution. |
| |
| </p></description> |
| |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this timer that is shown in the tree</property> |
| <property name="Deviation" required="Yes">Deviation in milliseconds.</property> |
| <property name="Constant Delay Offset" required="Yes">Number of milliseconds to pause in addition |
| to the random delay.</property> |
| </properties> |
| |
| </component> |
| |
| <component name="Uniform Random Timer" index="§-num;.6.3" width="372" height="157" screenshot="timers/uniform_random_timer.png"> |
| |
| <description><p>This timer pauses each thread request for a random amount of time, with |
| each time interval having the same probability of occurring. The total delay |
| is the sum of the random value and the offset value.</p></description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this timer that is shown in the tree. </property> |
| <property name="Random Delay Maximum" required="Yes">Maximum random number of milliseconds to |
| pause.</property> |
| <property name="Constant Delay Offset" required="Yes">Number of milliseconds to pause in addition |
| to the random delay.</property> |
| </properties> |
| |
| </component> |
| |
| <component name="Constant Throughput Timer" index="§-num;.6.4" width="636" height="146" screenshot="timers/constant_throughput_timer.png"> |
| |
| <description><p>This timer introduces variable pauses, calculated to keep the total throughput (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 time-consuming test elements prevent it.</p> |
| <p> |
| N.B. although the Timer is called the Constant Throughput timer, the throughput value does not need to be constant. |
| It can be defined in terms of a variable or function call, and the value can be changed during a test. |
| The value can be changed in various ways: |
| </p> |
| <ul> |
| <li>using a counter variable</li> |
| <li>using a JavaScript or BeanShell function to provide a changing value</li> |
| <li>using the remote BeanShell server to change a JMeter property</li> |
| </ul> |
| <p>See <a href="best-practices.html">Best Practices</a> for further details. |
| <note> |
| Note that the throughput value should not be changed too often during a test |
| - it will take a while for the new value to take effect. |
| </note> |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this timer that is shown in the tree. </property> |
| <property name="Target Throughput" required="Yes">Throughput we want the timer to try to generate.</property> |
| <property name="Calculate Throughput based on" required="Yes"> |
| <ul> |
| <li><code>this thread only</code> - each thread will try to maintain the target throughput. The overall throughput will be proportional to the number of active threads.</li> |
| <li><code>all active threads in current thread group</code> - the target throughput is divided amongst all the active threads in the group. |
| Each thread will delay as needed, based on when it last ran.</li> |
| <li><code>all active threads</code> - the target throughput is divided amongst all the active threads in all Thread Groups. |
| Each thread will delay as needed, based on when it last ran. |
| In this case, each other Thread Group will need a Constant Throughput timer with the same settings.</li> |
| <li><code>all active threads in current thread group (shared)</code> - as above, but each thread is delayed based on when any thread in the group last ran.</li> |
| <li><code>all active threads (shared)</code> - as above; each thread is delayed based on when any thread last ran.</li> |
| </ul> |
| </property> |
| <p>The shared and non-shared algorithms both aim to generate the desired throughput, and will produce similar results. |
| The shared algorithm should generate a more accurate overall transaction rate. |
| The non-shared algorithm should generate a more even spread of transactions across threads.</p> |
| </properties> |
| </component> |
| |
| <component name="Synchronizing Timer" index="§-num;.6.5" width="410" height="145" screenshot="timers/sync_timer.png"> |
| |
| <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> |
| </description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this timer that is shown in the tree. </property> |
| <property name="Number of Simultaneous Users to Group by" required="Yes">Number of threads to release at once. Setting it to <code>0</code> is equivalent to setting it to Number of threads in Thread Group.</property> |
| <property name="Timeout in milliseconds" required="No">If set to <code>0</code>, Timer will wait for the number of threads to reach the value in "<code>Number of Simultaneous Users to Group</code>". If superior to <code>0</code>, then timer will wait at max "<code>Timeout in milliseconds</code>" for the number of Threads. If after the timeout interval the number of users waiting is not reached, timer will stop waiting. Defaults to <code>0</code></property> |
| </properties> |
| <note> |
| If timeout in milliseconds is set to <code>0</code> and number of threads never reaches "<code>Number of Simultaneous Users to Group by</code>" then Test will pause infinitely. |
| Only a forced stop will stop it. Setting Timeout in milliseconds is an option to consider in this case. |
| </note> |
| <note> |
| Synchronizing timer blocks only within one JVM, so if using Distributed testing ensure you never set "<code>Number of Simultaneous Users to Group by</code>" to a value superior to the number of users |
| of its containing Thread group considering 1 injector only. |
| </note> |
| |
| </component> |
| |
| <component name="BeanShell Timer" index="§-num;.6.6" width="846" height="636" screenshot="timers/beanshell_timer.png"> |
| <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 <code>ThreadListener</code> and <code>TestListener</code> methods. |
| These should be defined in the initialisation file. |
| See the file <code>BeanShellListeners.bshrc</code> for example definitions. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree. |
| The name is stored in the script variable <code>Label</code></property> |
| <property name="Reset bsh.Interpreter before each call" required="Yes"> |
| If this option is selected, then the interpreter will be recreated for each sample. |
| This may be necessary for some long running scripts. |
| For further information, see <a href="best-practices#bsh_scripting">Best Practices - BeanShell scripting</a>. |
| </property> |
| <property name="Parameters" required="No">Parameters to pass to the BeanShell script. |
| The parameters are stored in the following variables: |
| <ul> |
| <li><code>Parameters</code> - string containing the parameters as a single variable</li> |
| <li><code>bsh.args</code> - String array containing parameters, split on white-space</li> |
| </ul> |
| </property> |
| <property name="Script file" required="No"> |
| A file containing the BeanShell script to run. |
| The file name is stored in the script variable <code>FileName</code> |
| The return value is used as the number of milliseconds to wait. |
| </property> |
| <property name="Script" required="Yes (unless script file is provided)"> |
| The BeanShell script. The return value is used as the number of milliseconds to wait. |
| </property> |
| </properties> |
| <p>Before invoking the script, some variables are set up in the BeanShell interpreter:</p> |
| <ul> |
| <li><code>log</code> - (<a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a>) - can be used to write to the log file</li> |
| <li><code>ctx</code> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li> |
| <li><code>vars</code> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <source> |
| vars.get(key); |
| vars.put(key,val); |
| vars.putObject("OBJ1",new Object()); |
| </source></li> |
| <li><code>props</code> - (JMeterProperties - class java.util.Properties) - e.g. <code>props.get("START.HMS");</code> <code>props.put("PROP1","1234");</code></li> |
| <li><code>prev</code> - (<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the previous <code>SampleResult</code> (if any)</li> |
| </ul> |
| <p>For details of all the methods available on each of the above variables, please check the Javadoc</p> |
| <p>If the property <code>beanshell.timer.init</code> is defined, this is used to load an initialisation file, which can be used to define methods etc. for use in the BeanShell script.</p> |
| </component> |
| |
| |
| <component name="BSF Timer" index="§-num;.6.7" width="844" height="636" screenshot="timers/bsf_timer.png"> |
| <description> |
| <p> |
| The BSF Timer can be used to generate a delay using a BSF scripting language. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="ScriptLanguage" required="Yes"> |
| The scripting language to be used. |
| </property> |
| <property name="Parameters" required="No">Parameters to pass to the script. |
| The parameters are stored in the following variables: |
| <ul> |
| <li><code>Parameters</code> - string containing the parameters as a single variable</li> |
| <li><code>args</code> - String array containing parameters, split on white-space</li> |
| </ul> |
| </property> |
| <property name="Script file" required="No"> |
| A file containing the script to run, if a relative file path is used, then it will be relative to directory referenced by "<code>user.dir</code>" System property |
| The return value is converted to a long integer and used as the number of milliseconds to wait. |
| </property> |
| <property name="Script" required="Yes (unless script file is provided)"> |
| The script. The return value is used as the number of milliseconds to wait. |
| </property> |
| </properties> |
| <p>Before invoking the script, some variables are set up in the script interpreter:</p> |
| <ul> |
| <li><code>log</code> - (<a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a>) - can be used to write to the log file</li> |
| <li><code>ctx</code> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li> |
| <li><code>vars</code> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <source> |
| vars.get(key); |
| vars.put(key,val); |
| vars.putObject("OBJ1",new Object());</source></li> |
| <li><code>props</code> - (JMeterProperties - class java.util.Properties) - e.g. <code>props.get("START.HMS");</code> <code>props.put("PROP1","1234");</code></li> |
| <li><code>sampler</code> - (<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>) - the current Sampler</li> |
| <li><code>Label</code> - the name of the Timer</li> |
| <li><code>FileName</code> - the file name (if any)</li> |
| <li><code>OUT</code> - System.out</li> |
| </ul> |
| <p>For details of all the methods available on each of the above variables, please check the Javadoc</p> |
| </component> |
| |
| <component name="JSR223 Timer" index="§-num;.6.8"> |
| <description> |
| <p> |
| The JSR223 Timer can be used to generate a delay using a JSR223 scripting language, |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="ScriptLanguage" required="Yes"> |
| The scripting language to be used. |
| </property> |
| <property name="Parameters" required="No">Parameters to pass to the script. |
| The parameters are stored in the following variables: |
| <ul> |
| <li><code>Parameters</code> - string containing the parameters as a single variable</li> |
| <li><code>args</code> - String array containing parameters, split on white-space</li> |
| </ul> |
| </property> |
| <property name="Script file" required="No"> |
| A file containing the script to run, if a relative file path is used, then it will be relative to directory referenced by "<code>user.dir</code>" System property |
| The return value is converted to a long integer and used as the number of milliseconds to wait. |
| </property> |
| <property name="Script compilation caching" required="No">Unique String across Test Plan that JMeter will use to cache result of Script compilation if language used supports <code>Compilable</code> interface (Groovy is one of these, java, beanshell and javascript are not) |
| <note>See note in JSR223 Sampler Java System property if you're using Groovy without checking this option</note> |
| </property> |
| <property name="Script" required="Yes (unless script file is provided)"> |
| The script. The return value is used as the number of milliseconds to wait. |
| </property> |
| </properties> |
| <p>Before invoking the script, some variables are set up in the script interpreter:</p> |
| <ul> |
| <li><code>log</code> - (<a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a>) - can be used to write to the log file</li> |
| <li><code>ctx</code> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li> |
| <li><code>vars</code> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <source>vars.get(key); |
| vars.put(key,val); |
| vars.putObject("OBJ1",new Object());</source></li> |
| <li><code>props</code> - (JMeterProperties - class java.util.Properties) - e.g. <code>props.get("START.HMS");</code> <code>props.put("PROP1","1234");</code></li> |
| <li><code>sampler</code> - (<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>) - the current Sampler</li> |
| <li><code>Label</code> - the name of the Timer</li> |
| <li><code>FileName</code> - the file name (if any)</li> |
| <li><code>OUT</code> - System.out</li> |
| </ul> |
| <p>For details of all the methods available on each of the above variables, please check the Javadoc</p> |
| </component> |
| |
| <component name="Poisson Random Timer" index="§-num;.6.9" width="341" height="182" screenshot="timers/poisson_random_timer.png"> |
| |
| <description><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></description> |
| |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this timer that is shown in the tree</property> |
| <property name="Lambda" required="Yes">Lambda value in milliseconds.</property> |
| <property name="Constant Delay Offset" required="Yes">Number of milliseconds to pause in addition |
| to the random delay.</property> |
| </properties> |
| |
| </component> |
| |
| <a href="#">^</a> |
| |
| </section> |
| |
| <section name="§-num;.7 Pre Processors" anchor="preprocessors"> |
| <description> |
| <br></br> |
| Preprocessors are used to modify the Samplers in their scope. |
| <br></br> |
| </description> |
| <component name="HTML Link Parser" index="§-num;.7.1" width="373" height="79" screenshot="html_link_parser.png" anchor="html_link_parser"> |
| <description> |
| <p>This modifier parses HTML response from the server and extracts |
| links and forms. A URL test sample that passes through this modifier will be examined to |
| see if it "matches" any of the links or forms extracted |
| from the immediately previous response. It would then replace the values in the URL |
| test sample with appropriate values from the matching link or form. Perl-type regular |
| expressions are used to find matches.</p> |
| </description> |
| <note> |
| Matches are performed using <code>protocol</code>, <code>host</code>, <code>path</code> and <code>parameter names</code>. |
| The target sampler cannot contain parameters that are not in the response links. |
| </note> |
| <note> |
| If using distributed testing, ensure you switch mode (see <code>jmeter.properties</code>) so that it's not a stripping one, see <bugzilla>56376</bugzilla> |
| </note> |
| |
| <example title="Spidering Example" anchor="spider_example"> |
| <p>Consider a simple example: let's say you wanted JMeter to "spider" through your site, |
| hitting link after link parsed from the HTML returned from your server (this is not |
| actually the most useful thing to do, but it serves as a good example). You would create |
| a <complink name="Simple Controller"/>, and add the "HTML Link Parser" to it. Then, create an |
| HTTP Request, and set the domain to "<code>.*</code>", and the path likewise. This will |
| cause your test sample to match with any link found on the returned pages. If you wanted to |
| restrict the spidering to a particular domain, then change the domain value |
| to the one you want. Then, only links to that domain will be followed. |
| </p> |
| </example> |
| |
| <example title="Poll Example" anchor="poll_example"> |
| <p>A more useful example: given a web polling application, you might have a page with |
| several poll options as radio buttons for the user to select. Let's say the values |
| of the poll options are very dynamic - maybe user generated. If you wanted JMeter to |
| test the poll, you could either create test samples with hardcoded values chosen, or you |
| could let the HTML Link Parser parse the form, and insert a random poll option into |
| your URL test sample. To do this, follow the above example, except, when configuring |
| your Web Test controller's URL options, be sure to choose "<code>POST</code>" as the |
| method. Put in hard-coded values for the <code>domain</code>, <code>path</code>, and any additional form parameters. |
| Then, for the actual radio button parameter, put in the name (let's say it's called "<code>poll_choice</code>"), |
| and then "<code>.*</code>" for the value of that parameter. When the modifier examines |
| this URL test sample, it will find that it "matches" the poll form (and |
| it shouldn't match any other form, given that you've specified all the other aspects of |
| the URL test sample), and it will replace your form parameters with the matching |
| parameters from the form. Since the regular expression "<code>.*</code>" will match with |
| anything, the modifier will probably have a list of radio buttons to choose from. It |
| will choose at random, and replace the value in your URL test sample. Each time through |
| the test, a new random value will be chosen.</p> |
| |
| <figure width="1250" height="493" image="modification.png">Figure 18 - Online Poll Example</figure> |
| |
| <note>One important thing to remember is that you must create a test sample immediately |
| prior that will return an HTML page with the links and forms that are relevant to |
| your dynamic test sample.</note> |
| </example> |
| |
| </component> |
| |
| <component name="HTTP URL Re-writing Modifier" index="§-num;.7.2" width="579" height="239" screenshot="url_rewriter.png"> |
| <description><p>This modifier works similarly to the HTML Link Parser, except it has a specific purpose for which |
| it is easier to use than the HTML Link Parser, and more efficient. For web applications that |
| use URL Re-writing to store session ids instead of cookies, this element can be attached at the |
| ThreadGroup level, much like the <complink name="HTTP Cookie Manager"/>. Simply give it the name |
| of the session id parameter, and it will find it on the page and add the argument to every |
| request of that ThreadGroup.</p> |
| <p>Alternatively, this modifier can be attached to select requests and it will modify only them. |
| Clever users will even determine that this modifier can be used to grab values that elude the |
| <complink name="HTML Link Parser"/>.</p> |
| </description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name given to this element in the test tree.</property> |
| <property name="Session Argument Name" required="Yes">The name of the parameter to grab from |
| previous response. This modifier will find the parameter anywhere it exists on the page, and |
| grab the value assigned to it, whether it's in an HREF or a form.</property> |
| <property name="Path Extension" required="No">Some web apps rewrite URLs by appending |
| a semi-colon plus the session id parameter. Check this box if that is so.</property> |
| <property name="Do not use equals in path extension" required="No">Some web apps rewrite URLs without using an "<code>=</code>" sign between the parameter name and value (such as Intershop Enfinity).</property> |
| <property name="Do not use questionmark in path extension" required="No">Prevents the query string to end up in the path extension (such as Intershop Enfinity).</property> |
| <property name="Cache Session Id?" required="Yes"> |
| Should the value of the session Id be saved for later use when the session Id is not present? |
| </property> |
| <property name="URL Encode" required="No"> |
| URL Encode value when writing parameter |
| </property> |
| </properties> |
| |
| <note> |
| If using distributed testing, ensure you switch mode (see <code>jmeter.properties</code>) so that it's not a stripping one, see <bugzilla>56376</bugzilla>. |
| </note> |
| |
| </component> |
| |
| <component name="User Parameters" index="§-num;.7.5" width="703" height="303" screenshot="user_params.png"> |
| <description><p>Allows the user to specify values for User Variables specific to individual threads.</p> |
| <p>User Variables can also be specified in the Test Plan but not specific to individual threads. This panel allows |
| you to specify a series of values for any User Variable. For each thread, the variable will be assigned one of the values from the series |
| in sequence. If there are more threads than values, the values get re-used. For example, this can be used to assign a distinct |
| user id to be used by each thread. User variables can be referenced in any field of any jMeter Component.</p> |
| |
| <p>The variable is specified by clicking the <code>Add Variable</code> button in the bottom of the panel and filling in the Variable name in the '<code>Name:</code>' column. |
| To add a new value to the series, click the '<code>Add User</code>' button and fill in the desired value in the newly added column.</p> |
| |
| <p>Values can be accessed in any test component in the same thread group, using the <a href="functions.html">function syntax</a>: <code>${variable}</code>.</p> |
| <p>See also the <complink name="CSV Data Set Config"/> element, which is more suitable for large numbers of parameters</p> |
| </description> |
| |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Update Once Per Iteration" required="Yes">A flag to indicate whether the User Parameters element |
| should update its variables only once per iteration. if you embed functions into the UP, then you may need greater |
| control over how often the values of the variables are updated. Keep this box checked to ensure the values are |
| updated each time through the UP's parent controller. Uncheck the box, and the UP will update the parameters for |
| every sample request made within its <a href="test_plan.html#scoping_rules">scope</a>.</property> |
| |
| </properties> |
| </component> |
| |
| <component name="BeanShell PreProcessor" index="§-num;.7.7" width="845" height="633" screenshot="beanshell_preprocessor.png"> |
| <description> |
| <p> |
| The BeanShell PreProcessor allows arbitrary code to be applied before taking a sample. |
| </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 <code>ThreadListener</code> and <code>TestListener</code> methods. |
| These should be defined in the initialisation file. |
| See the file <code>BeanShellListeners.bshrc</code> for example definitions. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree. |
| The name is stored in the script variable <code>Label</code></property> |
| <property name="Reset bsh.Interpreter before each call" required="Yes"> |
| If this option is selected, then the interpreter will be recreated for each sample. |
| This may be necessary for some long running scripts. |
| For further information, see <a href="best-practices#bsh_scripting">Best Practices - BeanShell scripting</a>. |
| </property> |
| <property name="Parameters" required="No">Parameters to pass to the BeanShell script. |
| The parameters are stored in the following variables: |
| <ul> |
| <li><code>Parameters</code> - string containing the parameters as a single variable</li> |
| <li><code>bsh.args</code> - String array containing parameters, split on white-space</li> |
| </ul></property> |
| <property name="Script file" required="No">A file containing the BeanShell script to run. |
| The file name is stored in the script variable <code>FileName</code></property> |
| <property name="Script" required="Yes (unless script file is provided)">The BeanShell script. The return value is ignored.</property> |
| </properties> |
| <p>Before invoking the script, some variables are set up in the BeanShell interpreter:</p> |
| <ul> |
| <li><code>log</code> - (<a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a>) - can be used to write to the log file</li> |
| <li><code>ctx</code> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li> |
| <li><code>vars</code> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <source>vars.get(key); |
| vars.put(key,val); |
| vars.putObject("OBJ1",new Object());</source></li> |
| <li><code>props</code> - (JMeterProperties - class java.util.Properties) - e.g. <code>props.get("START.HMS");</code> <code>props.put("PROP1","1234");</code></li> |
| <li><code>prev</code> - (<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the previous SampleResult (if any)</li> |
| <li><code>sampler</code> - (<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>)- gives access to the current sampler</li> |
| </ul> |
| <p>For details of all the methods available on each of the above variables, please check the Javadoc</p> |
| <p>If the property <code>beanshell.preprocessor.init</code> is defined, this is used to load an initialisation file, which can be used to define methods etc. for use in the BeanShell script.</p> |
| </component> |
| |
| <component name="BSF PreProcessor" index="§-num;.7.8" width="844" height="632" screenshot="bsf_preprocessor.png"> |
| <description> |
| <p> |
| The BSF PreProcessor allows BSF script code to be applied before taking a sample. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Language" required="Yes">The BSF language to be used</property> |
| <property name="Parameters" required="No">Parameters to pass to the script. |
| The parameters are stored in the following variables: |
| <ul> |
| <li><code>Parameters</code> - string containing the parameters as a single variable</li> |
| <li><code>args</code> - String array containing parameters, split on white-space</li> |
| </ul></property> |
| <property name="Script file" required="No">A file containing the script to run, if a relative file path is used, then it will be relative to directory referenced by "<code>user.dir</code>" System property</property> |
| <property name="Script" required="Yes (unless script file is provided)">The script to run.</property> |
| </properties> |
| <p> |
| The script (or file) is processed using the <code>BSFEngine.exec()</code> method, which does not return a value. |
| </p> |
| <p>The following BSF variables are set up for use by the script:</p> |
| <ul> |
| <li><code>log</code> - (<a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a>) - can be used to write to the log file</li> |
| <li><code>Label</code> - the String Label</li> |
| <li><code>FileName</code> - the script file name (if any)</li> |
| <li><code>Parameters</code> - the parameters (as a String)</li> |
| <li><code>args</code> - the parameters as a String array (split on whitespace)</li> |
| <li><code>ctx</code> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li> |
| <li><code>vars</code> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <source>vars.get(key); |
| vars.put(key,val); |
| vars.putObject("OBJ1",new Object()); |
| vars.getObject("OBJ2");</source></li> |
| <li><code>props</code> - (JMeterProperties - class java.util.Properties) - e.g. <code>props.get("START.HMS");</code> <code>props.put("PROP1","1234");</code></li> |
| <li><code>sampler</code> - (<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>)- gives access to the current sampler</li> |
| <li><code>OUT</code> - System.out - e.g. <code>OUT.println("message")</code></li> |
| </ul> |
| <p>For details of all the methods available on each of the above variables, please check the Javadoc</p> |
| </component> |
| |
| <component name="JSR223 PreProcessor" index="§-num;.7.8"> |
| <description> |
| <p> |
| The JSR223 PreProcessor allows JSR223 script code to be applied before taking a sample. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Language" required="Yes">The JSR223 language to be used</property> |
| <property name="Parameters" required="No">Parameters to pass to the script. |
| The parameters are stored in the following variables: |
| <ul> |
| <li><code>Parameters</code> - string containing the parameters as a single variable</li> |
| <li><code>args</code> - String array containing parameters, split on white-space</li> |
| </ul></property> |
| <property name="Script file" required="No">A file containing the script to run, if a relative file path is used, then it will be relative to directory referenced by "<code>user.dir</code>" System property</property> |
| <property name="Script compilation caching" required="No">Unique String across Test Plan that JMeter will use to cache result of Script compilation if language used supports <code>Compilable</code> interface (Groovy is one of these, java, beanshell and javascript are not) |
| <note>See note in JSR223 Sampler Java System property if you're using Groovy without checking this option</note> |
| </property> |
| <property name="Script" required="Yes (unless script file is provided)">The script to run.</property> |
| </properties> |
| <p>The following JSR223 variables are set up for use by the script:</p> |
| <ul> |
| <li><code>log</code> - (<a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a>) - can be used to write to the log file</li> |
| <li><code>Label</code> - the String Label</li> |
| <li><code>FileName</code> - the script file name (if any)</li> |
| <li><code>Parameters</code> - the parameters (as a String)</li> |
| <li><code>args</code> - the parameters as a String array (split on whitespace)</li> |
| <li><code>ctx</code> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li> |
| <li><code>vars</code> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <source>vars.get(key); |
| vars.put(key,val); |
| vars.putObject("OBJ1",new Object()); |
| vars.getObject("OBJ2");</source></li> |
| <li><code>props</code> - (JMeterProperties - class java.util.Properties) - e.g. <code>props.get("START.HMS");</code> <code>props.put("PROP1","1234");</code></li> |
| <li><code>sampler</code> - (<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>)- gives access to the current sampler</li> |
| <li><code>OUT</code> - System.out - e.g. <code>OUT.println("message")</code></li> |
| </ul> |
| <p>For details of all the methods available on each of the above variables, please check the Javadoc</p> |
| </component> |
| |
| <component name="JDBC PreProcessor" index="§-num;.7.9"> |
| <description> |
| <p> |
| The JDBC PreProcessor enables you to run some SQL statement just before a sample runs. |
| This can be useful if your JDBC Sample requires some data to be in DataBase and you cannot compute this in a setup Thread group. |
| For details, see <complink name="JDBC Request"/>. |
| </p> |
| <p> |
| See the following Test plan: |
| </p> |
| <links> |
| <link href="../demos/JDBC-Pre-Post-Processor.jmx">Test Plan using JDBC Pre/Post Processor</link> |
| </links> |
| <p> |
| In the linked test plan, "<code>Create Price Cut-Off</code>" JDBC PreProcessor calls a stored procedure to create a Price Cut-Off in Database, |
| this one will be used by "<code>Calculate Price cut off</code>". |
| </p> |
| <figure width="818" height="394" image="jdbc-pre-processor.png">Create Price Cut-Off Preprocessor</figure> |
| |
| </description> |
| </component> |
| |
| <component name="RegEx User Parameters" index="§-num;.7.10" width="727" height="138" screenshot="regex_user_params.png"> |
| <description><p>Allows to specify dynamic values for HTTP parameters extracted from another HTTP Request using regular expressions. |
| RegEx User Parameters are specific to individual threads.</p> |
| <p>This component allows you to specify reference name of a regular expression that extracts names and values of HTTP request parameters. |
| Regular expression group numbers must be specified for parameter's name and also for parameter's value. |
| Replacement will only occur for parameters in the Sampler that uses this RegEx User Parameters which name matches </p> |
| </description> |
| |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Regular Expression Reference Name" required="Yes">Name of a reference to a regular expression</property> |
| <property name="Parameter names regexp group number" required="Yes">Group number of regular expression used to extract parameter names</property> |
| <property name="Parameter values regex group number" required="Yes">Group number of regular expression used to extract parameter values</property> |
| </properties> |
| |
| <example title="Regexp Example" anchor="regex_user_param_example"> |
| <p>Suppose we have a request which returns a form with 3 input parameters and we want to extract the value of 2 of them to inject them in next request</p> |
| <ol> |
| <li>Create Post Processor Regular Expression for first HTTP Request |
| <ul> |
| <li><code>refName</code> - set name of a regular expression Expression (<code>listParams</code>)</li> |
| <li><code>regular expression</code> - expression that will extract input names and input values attributes |
| <br/> |
| Ex: <code>input name="([^"]+?)" value="([^"]+?)"</code></li> |
| <li><code>template</code> - would be empty</li> |
| <li><code>match nr</code> - <code>-1</code> (in order to iterate through all the possible matches)</li> |
| </ul> |
| </li> |
| <li>Create Pre Processor RegEx User Parameters for second HTTP Request |
| <ul> |
| <li><code>refName</code> - set the same reference name of a regular expression, would be <code>listParams</code> in our example</li> |
| <li><code>parameter names group number</code> - group number of regular expression for parameter names, would be <code>1</code> in our example</li> |
| <li><code>parameter values group number</code> - group number of regular expression for parameter values, would be <code>2</code> in our example</li> |
| </ul> |
| </li> |
| </ol> |
| </example> |
| |
| <p>See also the <complink name="Regular Expression Extractor"/> element, which is used to extract parametes names and values</p> |
| </component> |
| <links> |
| <link href="../demos/RegEx-User-Parameters.jmx">Test Plan showing how to use RegEx User Parameters</link> |
| </links> |
| |
| <component name="Sample Timeout" index="§-num;.7.11" anchor="interrupt" width="316" height="138" screenshot="sample_timeout.png"> |
| <description> |
| <note>BETA CODE - the test element may be moved or replaced in a future release</note> |
| <p>This Pre-Processor schedules a timer task to interrupt a sample if it takes too long to complete. |
| The timeout is ignored if it is zero or negative. |
| For this to work, the sampler must implement Interruptible. |
| The following samplers are known to do so:<br></br> |
| AJP, BeanShell, FTP, HTTP, Soap, AccessLog, MailReader, JMS Subscriber, TCPSampler, TestAction, JavaSampler |
| </p> |
| <p> |
| The test element is intended for use where individual timeouts such as Connection Timeout or Response Timeout are insufficient, |
| or where the Sampler does not support timeouts. |
| The timeout should be set sufficiently long so that it is not triggered in normal tests, but short enough that it interrupts samples |
| that are stuck. |
| </p> |
| <p> |
| [By default, JMeter uses a Callable to interrupt the sampler. |
| This executes in the same thread as the timer, so if the interrupt takes a long while, |
| it may delay the processing of subsequent timeouts. |
| This is not expected to be a problem, but if necessary the property <code>InterruptTimer.useRunnable</code> |
| can be set to <code>true</code> to use a separate Runnable thread instead of the Callable.] |
| </p> |
| </description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this timer that is shown in the tree.</property> |
| <property name="Sample Timeout" required="Yes">If the sample takes longer to complete, it will be interrupted.</property> |
| </properties> |
| </component> |
| |
| <a href="#">^</a> |
| |
| </section> |
| |
| <section name="§-num;.8 Post-Processors" anchor="postprocessors"> |
| <description> |
| <p> |
| As the name suggests, Post-Processors are applied after samplers. Note that they are |
| applied to <b>all</b> the samplers in the same scope, so to ensure that a post-processor |
| is applied only to a particular sampler, add it as a child of the sampler. |
| </p> |
| <note> |
| Note: Unless documented otherwise, Post-Processors are not applied to sub-samples (child samples) - |
| only to the parent sample. |
| In the case of BSF and BeanShell post-processors, the script can retrieve sub-samples using the method |
| <code>prev.getSubResults()</code> which returns an array of SampleResults. |
| The array will be empty if there are none. |
| </note> |
| <p> |
| Post-Processors are run before Assertions, so they do not have access to any Assertion Results, nor will |
| the sample status reflect the results of any Assertions. If you require access to Assertion Results, try |
| using a Listener instead. Also note that the variable <code>JMeterThread.last_sample_ok</code> is set to "<code>true</code>" or "<code>false</code>" |
| after all Assertions have been run. |
| </p> |
| </description> |
| <component name="Regular Expression Extractor" index="§-num;.8.1" width="1127" height="277" screenshot="regex_extractor.png"> |
| <description><p>Allows the user to extract values from a server response using a Perl-type regular expression. As a post-processor, |
| this element will execute after each Sample request in its scope, applying the regular expression, extracting the requested values, |
| generate the template string, and store the result into the given variable name.</p></description> |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Apply to:" required="Yes"> |
| 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><code>Main sample only</code> - only applies to the main sample</li> |
| <li><code>Sub-samples only</code> - only applies to the sub-samples</li> |
| <li><code>Main sample and sub-samples</code> - applies to both.</li> |
| <li><code>JMeter Variable</code> - 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 for the regex, |
| (i.e. 4 matches in total). |
| For match number = <code>3</code>, Sub-samples only, the extractor will match the 3<sup>rd</sup> sub-sample. |
| For match number = <code>3</code>, 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 = <code>0</code> or negative, all qualifying samples will be processed. |
| For match number > <code>0</code>, matching will stop as soon as enough matches have been found. |
| </property> |
| <property name="Field to check" required="Yes"> |
| The following fields can be checked: |
| <ul> |
| <li><code>Body</code> - the body of the response, e.g. the content of a web-page (excluding headers)</li> |
| <li><code>Body (unescaped)</code> - 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. |
| <note>Note that this option highly impacts performances, so use it only when absolutely necessary and be aware of its impacts</note> |
| </li> |
| <li><code>Body as a Document</code> - the extract text from various type of documents via Apache Tika (see <complink name="View Results Tree"/> Document view section). |
| <note>Note that the Body as a Document option can impact performances, so ensure it is OK for your test</note> |
| </li> |
| <li><code>Request Headers</code> - may not be present for non-HTTP samples</li> |
| <li><code>Response Headers</code> - may not be present for non-HTTP samples</li> |
| <li><code>URL</code></li> |
| <li><code>Response Code</code> - e.g. <code>200</code></li> |
| <li><code>Response Message</code> - e.g. <code>OK</code></li> |
| </ul> |
| Headers can be useful for HTTP samples; it may not be present for other sample types. |
| </property> |
| <property name="Reference Name" required="Yes">The name of the JMeter variable in which to store the result. Also note that each group is stored as <code>[refname]_g#</code>, where <code>[refname]</code> is the string you entered as the reference name, and <code>#</code> is the group number, where group <code>0</code> is the entire match, group <code>1</code> is the match from the first set of parentheses, etc.</property> |
| <property name="Regular Expression" required="Yes">The regular expression used to parse the response data. |
| This must contain at least one set of parentheses "<code>()</code>" to capture a portion of the string, unless using the group <code>$0$</code>. |
| Do not enclose the expression in <code>/ /</code> - unless of course you want to match these characters as well. |
| </property> |
| <property name="Template" required="Yes">The template used to create a string from the matches found. This is an arbitrary string |
| with special elements to refer to groups within the regular expression. The syntax to refer to a group is: '<code>$1$</code>' to refer to |
| group <code>1</code>, '<code>$2$</code>' to refer to group <code>2</code>, etc. <code>$0$</code> refers to whatever the entire expression matches.</property> |
| <property name="Match No." required="Yes">Indicates which match to use. The regular expression 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 <complink name="ForEach Controller"/> - see below.</li> |
| </ul> |
| </property> |
| <property name="Default Value" required="No, but recommended"> |
| If the regular expression does 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 regular expression did not match, or the RE element was not processed 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> |
| </property> |
| <property name="Use empty default value" required="No"> |
| If the checkbox is checked and <code>Default Value</code> is empty, then JMeter will set the variable to empty string instead of not setting it. |
| Thus when you will for example use <code>${var}</code> (if <code>Reference Name</code> is var) in your Test Plan, if the extracted value is not found then |
| <code>${var}</code> will be equal to empty string instead of containing <code>${var}</code> which may be useful if extracted value is optional. |
| </property> |
| </properties> |
| <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><code>refName</code> - the value of the template</li> |
| <li><code>refName_g<em>n</em></code>, where <code>n</code>=<code>0</code>,<code>1</code>,<code>2</code> - the groups for the match</li> |
| <li><code>refName_g</code> - the number of groups in the Regex (excluding <code>0</code>)</li> |
| </ul> |
| <p> |
| If no match occurs, then the <code>refName</code> variable is set to the default (unless this is absent). |
| Also, the following variables are removed: |
| </p> |
| <ul> |
| <li><code>refName_g0</code></li> |
| <li><code>refName_g1</code></li> |
| <li><code>refName_g</code></li> |
| </ul> |
| <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><code>refName_matchNr</code> - the number of matches found; could be <code>0</code></li> |
| <li><code>refName_<em>n</em></code>, where <code>n</code> = <code>1</code>, <code>2</code>, <code>3</code> etc. - the strings as generated by the template</li> |
| <li><code>refName_<em>n</em>_g<em>m</em></code>, where <code>m</code>=<code>0</code>, <code>1</code>, <code>2</code> - the groups for match <code>n</code></li> |
| <li><code>refName</code> - always set to the default value</li> |
| <li><code>refName_g<em>n</em></code> - not set</li> |
| </ul> |
| <p> |
| Note that the <code>refName</code> variable is always set to the default value in this case, |
| and the associated group variables are not set. |
| </p> |
| <p>See also <complink name="Response Assertion"/> for some examples of how to specify modifiers, |
| and <a href="regular_expressions.html"> for further information on JMeter regular expressions.</a></p> |
| </component> |
| |
| <component name="CSS/JQuery Extractor" index="§-num;.8.2" width="826" height="276" screenshot="css_extractor_attr.png"> |
| <description><p>Allows the user to extract values from a server response using a CSS/JQuery selector like syntax. As a post-processor, |
| this element will execute after each Sample request in its scope, applying the CSS/JQuery expression, extracting the requested nodes, |
| extracting the node as text or attribute value and store the result into the given variable name.</p></description> |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Apply to:" required="Yes"> |
| 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><code>Main sample only</code> - only applies to the main sample</li> |
| <li><code>Sub-samples only</code> - only applies to the sub-samples</li> |
| <li><code>Main sample and sub-samples</code> - applies to both.</li> |
| <li><code>JMeter Variable</code> - 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 for the regex, |
| (i.e. 4 matches in total). |
| For match number = <code>3</code>, Sub-samples only, the extractor will match the 3<sup>rd</sup> sub-sample. |
| For match number = <code>3</code>, 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 = <code>0</code> or negative, all qualifying samples will be processed. |
| For match number > <code>0</code>, matching will stop as soon as enough matches have been found. |
| </property> |
| <property name="CSS/JQuery extractor Implementation" required="False"> |
| 2 Implementations for CSS/JQuery based syntax are supported: |
| <ul> |
| <li><a href="http://jsoup.org/" >JSoup</a></li> |
| <li><a href="http://jodd.org/doc/lagarto/index.html" >Jodd-Lagarto (CSSelly)</a></li> |
| </ul> |
| If selector is set to empty, default implementation(JSoup) will be used. |
| </property> |
| <property name="Reference Name" required="Yes">The name of the JMeter variable in which to store the result.</property> |
| <property name="CSS/JQuery expression" required="Yes">The CSS/JQuery selector used to select nodes from the response data. |
| Selector, selectors combination and pseudo-selectors are supported, examples: |
| <ul> |
| <li><code>E[foo]</code> - an <code>E</code> element with a "<code>foo</code>" attribute</li> |
| <li><code>ancestor child</code> - child elements that descend from ancestor, e.g. <code>.body p</code> finds <code>p</code> elements anywhere under a block with class "<code>body</code>"</li> |
| <li><code>:lt(n)</code> - find elements whose sibling index (i.e. its position in the DOM tree relative to its parent) is less than <code>n</code>; e.g. <code>td:lt(3)</code></li> |
| <li><code>:contains(text)</code> - find elements that contain the given <code>text</code>. The search is case-insensitive; e.g. <code>p:contains(jsoup)</code></li> |
| <li>…</li> |
| </ul> |
| For more details on syntax, see: |
| <ul> |
| <li><a href="http://jsoup.org/cookbook/extracting-data/selector-syntax" >JSoup</a></li> |
| <li><a href="http://jodd.org/doc/csselly/" >Jodd-Lagarto (CSSelly)</a></li> |
| </ul> |
| </property> |
| <property name="Attribute" required="false"> |
| Name of attribute (as per HTML syntax) to extract from nodes that matched the selector. If empty, then the combined text of this element and all its children will be returned.<br/> |
| This is the equivalent <a href="http://jsoup.org/apidocs/org/jsoup/nodes/Node.html#attr%28java.lang.String%29">Element#attr(name)</a> function for JSoup if an atttribute is set.<br/> |
| <figure width="826" height="275" image="css_extractor_attr.png">CSS Extractor with attribute value set</figure><br/> |
| If empty this is the equivalent of <a href="http://jsoup.org/apidocs/org/jsoup/nodes/Element.html#text%28%29">Element#text()</a> function for JSoup if not value is set for attribute. |
| <figure width="825" height="275" image="css_extractor_noattr.png">CSS Extractor with no attribute set</figure> |
| </property> |
| <property name="Match No." required="Yes">Indicates which match to use. The CSS/JQuery selector 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 <code>N</code> means to select the n<sup>th</sup> match.</li> |
| <li> Negative numbers are used in conjunction with the <complink name="ForEach Controller"/> - see below.</li> |
| </ul> |
| </property> |
| <property name="Default Value" required="No, but recommended"> |
| If the expression does 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 expression did not match, or the CSS/JQuery element was not processed 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> |
| </property> |
| <property name="Use empty default value" required="No"> |
| If the checkbox is checked and <code>Default Value</code> is empty, then JMeter will set the variable to empty string instead of not setting it. |
| Thus when you will for example use <code>${var}</code> (if <code>Reference Name</code> is var) in your Test Plan, if the extracted value is not found then |
| <code>${var}</code> will be equal to empty string instead of containing <code>${var}</code> which may be useful if extracted value is optional. |
| </property> |
| </properties> |
| <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><code>refName</code> - the value of the template</li> |
| </ul> |
| <p> |
| If no match occurs, then the <code>refName</code> 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><code>refName_matchNr</code> - the number of matches found; could be <code>0</code></li> |
| <li><code>refName_n</code>, where <code>n</code> = <code>1</code>, <code>2</code>, <code>3</code>, etc. - the strings as generated by the template</li> |
| <li><code>refName</code> - always set to the default value</li> |
| </ul> |
| <p> |
| Note that the refName variable is always set to the default value in this case. |
| </p> |
| </component> |
| |
| <component name="XPath Extractor" index="§-num;.8.3" width="729" height="317" screenshot="xpath_extractor.png"> |
| <description>This test element allows the user to extract value(s) from |
| structured response - XML or (X)HTML - using XPath |
| query language. |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Apply to:" required="Yes"> |
| 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><code>Main sample only</code> - only applies to the main sample</li> |
| <li><code>Sub-samples only</code> - only applies to the sub-samples</li> |
| <li><code>Main sample and sub-samples</code> - applies to both.</li> |
| <li><code>JMeter Variable</code> - assertion 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. |
| </property> |
| <property name="Use Tidy (tolerant parser)" required="Yes">If checked use Tidy to parse HTML response into XHTML. |
| <ul> |
| <li>"<code>Use Tidy</code>" should be checked on for HTML response. Such response is converted to valid XHTML (XML compatible HTML) using Tidy</li> |
| <li>"<code>Use Tidy</code>" should be unchecked for both XHTML or XML response (for example RSS)</li> |
| </ul> |
| </property> |
| <property name="Quiet" required="If Tidy is selected">Sets the Tidy Quiet flag</property> |
| <property name="Report Errors" required="If Tidy is selected">If a Tidy error occurs, then set the Assertion accordingly</property> |
| <property name="Show warnings" required="If Tidy is selected">Sets the Tidy showWarnings option</property> |
| <property name="Use Namespaces" required="If Tidy is not selected"> |
| If checked, then the XML parser will use namespace resolution. |
| 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: |
| <source>//mynamespace:tagname</source> |
| by |
| <source>//*[local-name()='tagname' and namespace-uri()='uri-for-namespace']</source> |
| where "<code>uri-for-namespace</code>" is the uri for the "<code>mynamespace</code>" namespace. |
| (not applicable if Tidy is selected) |
| </property> |
| <property name="Validate XML" required="If Tidy is not selected">Check the document against its schema.</property> |
| <property name="Ignore Whitespace" required="If Tidy is not selected">Ignore Element Whitespace.</property> |
| <property name="Fetch External DTDs" required="If Tidy is not selected">If selected, external DTDs are fetched.</property> |
| <property name="Return entire XPath fragment instead of text content?" required="Yes"> |
| If selected, the fragment will be returned rather than the text content.<br></br> |
| For example <code>//title</code> would return "<code><title>Apache JMeter</title></code>" rather than "<code>Apache JMeter</code>".<br></br> |
| In this case, <code>//title/text()</code> would return "<code>Apache JMeter</code>". |
| </property> |
| <property name="Reference Name" required="Yes">The name of the JMeter variable in which to store the result.</property> |
| <property name="XPath Query" required="Yes">Element query in XPath language. Can return more than one match.</property> |
| <property name="Default Value" required="">Default value returned when no match found. |
| It is also returned if the node has no value and the fragment option is not selected.</property> |
| </properties> |
| <p>To allow for use in a <complink name="ForEach Controller"/>, the following variables are set on return:</p> |
| <ul> |
| <li><code>refName</code> - set to first (or only) match; if no match, then set to default</li> |
| <li><code>refName_matchNr</code> - set to number of matches (may be <code>0</code>)</li> |
| <li><code>refName_n</code> - <code>n</code>=<code>1</code>, <code>2</code>, <code>3</code>, etc. Set to the 1<sup>st</sup>, 2<sup>nd</sup> 3<sup>rd</sup> match etc. |
| </li> |
| </ul> |
| <note>Note: The next <code>refName_n</code> variable is set to <code>null</code> - e.g. if there are 2 matches, then <code>refName_3</code> is set to <code>null</code>, |
| and if there are no matches, then <code>refName_1</code> is set to <code>null</code>. |
| </note> |
| <p>XPath is query language targeted primarily for XSLT transformations. However it is useful as generic query language for structured data too. See |
| <a href="http://www.topxml.com/xsl/xpathref.asp">XPath Reference</a> or <a href="http://www.w3.org/TR/xpath">XPath specification</a> for more information. Here are few examples: |
| </p> |
| <dl> |
| <dt><code>/html/head/title</code></dt> |
| <dd>extracts title element from HTML response</dd> |
| <dt><code>/book/page[2]</code></dt> |
| <dd>extracts 2<sup>nd</sup> page from a book</dd> |
| <dt><code>/book/page</code></dt> |
| <dd>extracts all pages from a book</dd> |
| <dt><code>//form[@name='countryForm']//select[@name='country']/option[text()='Czech Republic'])/@value</code></dt> |
| <dd>extracts value attribute of option element that match text '<code>Czech Republic</code>' |
| inside of select element with name attribute '<code>country</code>' inside of |
| form with name attribute '<code>countryForm</code>'</dd> |
| </dl> |
| <note>When "<code>Use Tidy</code>" is checked on - resulting XML document may slightly differ from original HTML response: |
| <ul> |
| <li>All elements and attribute names are converted to lowercase</li> |
| <li>Tidy attempts to correct improperly nested elements. For example - original (incorrect) <code>ul/font/li</code> becomes correct <code>ul/li/font</code></li> |
| </ul> |
| See <a href="http://jtidy.sf.net">Tidy homepage</a> for more information. |
| </note> |
| |
| </component> |
| |
| <component name="Result Status Action Handler" index="§-num;.8.4" width="613" height="133" screenshot="resultstatusactionhandler.png"> |
| <description>This test element allows the user to stop the thread or the whole test if the relevant sampler failed. |
| </description> |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Action to be taken after a Sampler error"> |
| Determines what happens if a sampler error occurs, either because the sample itself failed or an assertion failed. |
| The possible choices are: |
| <ul> |
| <li><code>Continue</code> - ignore the error and continue with the test</li> |
| <li><code>Start next thread loop</code> - does not execute samplers following the sampler in error for the current iteration and restarts the loop on next iteration</li> |
| <li><code>Stop Thread</code> - current thread exits</li> |
| <li><code>Stop Test</code> - the entire test is stopped at the end of any current samples.</li> |
| <li><code>Stop Test Now</code> - the entire test is stopped abruptly. Any current samplers are interrupted if possible.</li> |
| </ul> |
| </property> |
| </properties> |
| </component> |
| |
| <component name="BeanShell PostProcessor" index="§-num;.8.5" width="847" height="633" screenshot="beanshell_postprocessor.png"> |
| <description> |
| <p> |
| The BeanShell PreProcessor allows arbitrary code to be applied after taking a sample. |
| </p> |
| <p>BeanShell Post-Processor no longer ignores samples with zero-length result data</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 <code>ThreadListener</code> and <code>TestListener</code> methods. |
| These should be defined in the initialisation file. |
| See the file <code>BeanShellListeners.bshrc</code> for example definitions. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree. |
| The name is stored in the script variable <code>Label</code></property> |
| <property name="Reset bsh.Interpreter before each call" required="Yes"> |
| If this option is selected, then the interpreter will be recreated for each sample. |
| This may be necessary for some long running scripts. |
| For further information, see <a href="best-practices#bsh_scripting">Best Practices - BeanShell scripting</a>. |
| </property> |
| <property name="Parameters" required="No">Parameters to pass to the BeanShell script. |
| The parameters are stored in the following variables: |
| <ul> |
| <li><code>Parameters</code> - string containing the parameters as a single variable</li> |
| <li><code>bsh.args</code> - String array containing parameters, split on white-space</li> |
| </ul></property> |
| <property name="Script file" required="No">A file containing the BeanShell script to run. |
| The file name is stored in the script variable <code>FileName</code></property> |
| <property name="Script" required="Yes (unless script file is provided)">The BeanShell script. The return value is ignored.</property> |
| </properties> |
| <p>The following BeanShell variables are set up for use by the script:</p> |
| <ul> |
| <li><code>log</code> - (<a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a>) - can be used to write to the log file</li> |
| <li><code>ctx</code> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li> |
| <li><code>vars</code> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <source>vars.get(key); |
| vars.put(key,val); |
| vars.putObject("OBJ1",new Object());</source></li> |
| <li><code>props</code> - (JMeterProperties - class java.util.Properties) - e.g. <code>props.get("START.HMS");</code> <code>props.put("PROP1","1234");</code></li> |
| <li><code>prev</code> - (<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the previous SampleResult</li> |
| <li><code>data</code> - (byte [])- gives access to the current sample data</li> |
| </ul> |
| <p>For details of all the methods available on each of the above variables, please check the Javadoc</p> |
| <p>If the property <code>beanshell.postprocessor.init</code> is defined, this is used to load an initialisation file, which can be used to define methods etc. for use in the BeanShell script.</p> |
| </component> |
| |
| <component name="BSF PostProcessor" index="§-num;.8.6" width="844" height="633" screenshot="bsf_postprocessor.png"> |
| <description> |
| <p> |
| The BSF PostProcessor allows BSF script code to be applied after taking a sample. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Language" required="Yes">The BSF language to be used</property> |
| <property name="Parameters" required="No">Parameters to pass to the script. |
| The parameters are stored in the following variables: |
| <ul> |
| <li><code>Parameters</code> - string containing the parameters as a single variable</li> |
| <li><code>args</code> - String array containing parameters, split on white-space</li> |
| </ul></property> |
| <property name="Script file" required="No">A file containing the script to run, if a relative file path is used, then it will be relative to directory referenced by "<code>user.dir</code>" System property</property> |
| <property name="Script" required="Yes (unless script file is provided)">The script to run.</property> |
| </properties> |
| <p> |
| The script (or file) is processed using the <code>BSFEngine.exec()</code> method, which does not return a value. |
| </p> |
| <p> |
| Before invoking the script, some variables are set up. |
| Note that these are BSF variables - i.e. they can be used directly in the script. |
| </p> |
| <ul> |
| <li><code>log</code> - (<a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a>) - can be used to write to the log file</li> |
| <li><code>Label</code> - the String Label</li> |
| <li><code>FileName</code> - the script file name (if any)</li> |
| <li><code>Parameters</code> - the parameters (as a String)</li> |
| <li><code>args</code> - the parameters as a String array (split on whitespace)</li> |
| <li><code>ctx</code> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li> |
| <li><code>vars</code> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <source>vars.get(key); |
| vars.put(key,val); |
| vars.putObject("OBJ1",new Object()); |
| vars.getObject("OBJ2");</source></li> |
| <li><code>props</code> - (JMeterProperties - class java.util.Properties) - e.g. <code>props.get("START.HMS");</code> <code>props.put("PROP1","1234");</code></li> |
| <li><code>prev</code> - (<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the previous SampleResult (if any)</li> |
| <li><code>sampler</code> - (<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>)- gives access to the current sampler</li> |
| <li><code>OUT</code> - System.out - e.g. <code>OUT.println("message")</code></li> |
| </ul> |
| <p>For details of all the methods available on each of the above variables, please check the Javadoc</p> |
| </component> |
| |
| <component name="JSR223 PostProcessor" index="§-num;.8.7"> |
| <description> |
| <p> |
| The JSR223 PostProcessor allows JSR223 script code to be applied after taking a sample. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Language" required="Yes">The JSR223 language to be used</property> |
| <property name="Parameters" required="No">Parameters to pass to the script. |
| The parameters are stored in the following variables: |
| <ul> |
| <li><code>Parameters</code> - string containing the parameters as a single variable</li> |
| <li><code>args</code> - String array containing parameters, split on white-space</li> |
| </ul></property> |
| <property name="Script file" required="No">A file containing the script to run, if a relative file path is used, then it will be relative to directory referenced by "<code>user.dir</code>" System property</property> |
| <property name="Script compilation caching" required="No">Unique String across Test Plan that JMeter will use to cache result of Script compilation if language used supports <code>Compilable</code> interface (Groovy is one of these, java, beanshell and javascript are not) |
| <note>See note in JSR223 Sampler Java System property if you're using Groovy without checking this option</note> |
| </property> |
| <property name="Script" required="Yes (unless script file is provided)">The script to run.</property> |
| </properties> |
| <p> |
| Before invoking the script, some variables are set up. |
| Note that these are JSR223 variables - i.e. they can be used directly in the script. |
| </p> |
| <ul> |
| <li><code>log</code> - (<a href="http://excalibur.apache.org/apidocs/org/apache/log/Logger.html">Logger</a>) - can be used to write to the log file</li> |
| <li><code>Label</code> - the String Label</li> |
| <li><code>FileName</code> - the script file name (if any)</li> |
| <li><code>Parameters</code> - the parameters (as a String)</li> |
| <li><code>args</code> - the parameters as a String array (split on whitespace)</li> |
| <li><code>ctx</code> - (<a href="../api/org/apache/jmeter/threads/JMeterContext.html">JMeterContext</a>) - gives access to the context</li> |
| <li><code>vars</code> - (<a href="../api/org/apache/jmeter/threads/JMeterVariables.html">JMeterVariables</a>) - gives read/write access to variables: <source>vars.get(key); |
| vars.put(key,val); |
| vars.putObject("OBJ1",new Object()); |
| vars.getObject("OBJ2");</source></li> |
| <li><code>props</code> - (JMeterProperties - class java.util.Properties) - e.g. <code>props.get("START.HMS");</code> <code>props.put("PROP1","1234");</code></li> |
| <li><code>prev</code> - (<a href="../api/org/apache/jmeter/samplers/SampleResult.html">SampleResult</a>) - gives access to the previous SampleResult (if any)</li> |
| <li><code>sampler</code> - (<a href="../api/org/apache/jmeter/samplers/Sampler.html">Sampler</a>)- gives access to the current sampler</li> |
| <li><code>OUT</code> - System.out - e.g. <code>OUT.println("message")</code></li> |
| </ul> |
| <p>For details of all the methods available on each of the above variables, please check the Javadoc</p> |
| </component> |
| |
| <component name="JDBC PostProcessor" index="§-num;.8.8"> |
| <description> |
| <p> |
| The JDBC PostProcessor enables you to run some SQL statement just after a sample has run. |
| This can be useful if your JDBC Sample changes some data and you want to reset state to what it was before the JDBC sample run. |
| </p> |
| </description> |
| <links> |
| <link href="../demos/JDBC-Pre-Post-Processor.jmx">Test Plan using JDBC Pre/Post Processor</link> |
| </links> |
| <p> |
| In the linked test plan, "<code>JDBC PostProcessor</code>" JDBC PostProcessor calls a stored procedure to delete from Database the Price Cut-Off that was created by PreProcessor. |
| </p> |
| <figure width="818" height="399" image="jdbc-post-processor.png">JDBC PostProcessor</figure> |
| </component> |
| |
| <component name="JSON Path PostProcessor" index="§-num;.8.9"> |
| <description> |
| <p> |
| The JSON PostProcessor enables you extract data from JSON responses using JSON-PATH syntax. This post processor is very similar to Regular expression extractor. |
| It must be placed as a child of HTTP Sampler or any other sampler that has responses. |
| It will allow you to extract in a very easy way text content, see <a href="http://goessner.net/articles/JsonPath/" >JSON Path syntax</a>. |
| |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Variable Names" required="Yes">Semi-colon separated names of variables that will contain the results of JSON-PATH expressions (must match number of JSON-PATH expressions)</property> |
| <property name="JSON Path Expressions" required="Yes">Semi-colon separated JSON-PATH expressions (must match number of variables)</property> |
| <property name="Default Values" required="No">Semi-colon separated default values if JSON-PATH expressions do not return any result(must match number of variables)</property> |
| <property name="Match Numbers" required="No">If the JSON Path query leads to many results, you can choose which one(s) to extract as Variables: |
| <ul> |
| <li><code>0</code> : means random (Default Value)</li> |
| <li><code>-1</code> means extract all results, they will be named as <code><em><variable name></em>_N</code> (where <code>N</code> goes from 1 to Number of results)</li> |
| <li><code>X</code> : means extract the X<sup>th</sup> result. If this X<sup>th</sup> is greater than number of matches, then nothing is returned. Default value will be used</li> |
| </ul> |
| </property> |
| <property name="Compute concatenation var" required="No">If many results are found, plugin will concatenate them using ‘<code>,</code>’ separator and store it in a var named <code><em><variable name></em>_ALL</code></property> |
| </properties> |
| <figure width="855" height="276" image="json-post-processor.png">JSON PostProcessor</figure> |
| </component> |
| |
| </section> |
| |
| <section name="§-num;.9 Miscellaneous Features" anchor="Miscellaneous_Features"> |
| <description> |
| <br></br> |
| </description> |
| <component name="Test Plan" index="§-num;.9.1" width="560" height="457" screenshot="testplan.png"> |
| <description> |
| <p> |
| The Test Plan is where the overall settings for a test are specified. |
| </p> |
| <p> |
| Static variables can be defined for values that are repeated throughout a test, such as server names. |
| For example the variable <code>SERVER</code> could be defined as <code>www.example.com</code>, and the rest of the test plan |
| could refer to it as <code>${SERVER}</code>. This simplifies changing the name later. |
| </p> |
| <p> |
| If the same variable name is reused on one of more |
| <complink name="User Defined Variables"/> Configuration elements, |
| the value is set to the last definition in the test plan (reading from top to bottom). |
| Such variables should be used for items that may change between test runs, |
| but which remain the same during a test run. |
| </p> |
| <p> |
| <note>Note that the Test Plan cannot refer to variables it defines.</note> |
| If you need to construct other variables from the Test Plan variables, |
| use a <complink name="User Defined Variables"/> test element. |
| </p> |
| <p> |
| Selecting Functional Testing instructs JMeter to save the additional sample information |
| - Response Data and Sampler Data - to all result files. |
| This increases the resources needed to run a test, and may adversely impact JMeter performance. |
| If more data is required for a particular sampler only, then add a Listener to it, and configure the fields as required. |
| <note>The option does not affect CSV result files, which cannot currently store such information.</note> |
| </p> |
| <p>Also, an option exists here to instruct JMeter to run the <complink name="Thread Group"/> serially rather than in parallel.</p> |
| <p>Run tearDown Thread Groups after shutdown of main threads: |
| if selected, the tearDown groups (if any) will be run after graceful shutdown of the main threads. |
| The tearDown threads won't be run if the test is forcibly stopped. |
| </p> |
| <p> |
| Test plan now provides an easy way to add classpath setting to a specific test plan. |
| The feature is additive, meaning that you can add jar files or directories, |
| but removing an entry requires restarting JMeter. |
| <note>Note that this cannot be used to add JMeter GUI plugins, because they are processed earlier.</note> |
| However it can be useful for utility jars such as JDBC drivers. The jars are only added to |
| the search path for the JMeter loader, not for the system class loader. |
| </p> |
| <p> |
| JMeter properties also provides an entry for loading additional classpaths. |
| In <code>jmeter.properties</code>, edit "<code>user.classpath</code>" or "<code>plugin_dependency_paths</code>" to include additional libraries. |
| See <a href="get-started.html#classpath">JMeter's Classpath</a> and |
| <a href="get-started.html#configuring_jmeter">Configuring JMeter</a> for details. |
| </p> |
| </description> |
| </component> |
| |
| <component name="Thread Group" index="§-num;.9.2" width="706" height="407" screenshot="threadgroup.png"> |
| <description> |
| <p>A Thread Group defines a pool of users that will execute a particular test case against your server. In the Thread Group GUI, you can control the number of users simulated (num of threads), the ramp up time (how long it takes to start all the threads), the number of times to perform the test, and optionally, a start and stop time for the test.</p> |
| <p> |
| See also <complink name="tearDown Thread Group"/> and <complink name="setUp Thread Group"/>. |
| </p> |
| <p> |
| When using the scheduler, JMeter runs the thread group until either the number of loops is reached or the duration/end-time is reached - whichever occurs first. |
| Note that the condition is only checked between samples; when the end condition is reached, that thread will stop. |
| JMeter does not interrupt samplers which are waiting for a response, so the end time may be delayed arbitrarily. |
| </p> |
| </description> |
| <p> |
| Since JMeter 3.0, you can run a selection of Thread Group by selecting them and right clicking. A popup menu will appear: |
| <figure width="461" height="818" image="threadgroup-popup-menu.png">Popup menu to start a selection of Thread Groups</figure> |
| |
| <br/>Notice you have 3 options to run the selection of Thread Groups: |
| <ul> |
| <li>Start : Start the selected thread groups only</li> |
| <li>Start no pauses : Start the selected thread groups only but without running the timers</li> |
| <li>Validate : Start the selected thread groups only using validation mode. Per default this runs the Thread Group in validation mode (see below)</li> |
| </ul> |
| |
| <b>Validation Mode:</b><br></br> |
| This mode enables rapid validation of a Thread Group by running it with 1 thread, 1 iteration, no timers and no <code>Startup delay</code> set to 0. |
| The 3 first properties can be modified by setting in user.properties: |
| <ul> |
| <li><code>testplan_validation.nb_threads_per_thread_group</code> : Number of threads to use to validate a Thread Group, by default 1</li> |
| <li><code>testplan_validation.ignore_timers</code> : Ignore timers when validating the thread group of plan, by default 1</li> |
| <li><code>testplan_validation.number_iterations</code> : Number of iterations to use to validate a Thread Group</li> |
| </ul> |
| </p> |
| |
| <properties> |
| <property name="Name" required="">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Action to be taken after a Sampler error"> |
| Determines what happens if a sampler error occurs, either because the sample itself failed or an assertion failed. |
| The possible choices are: |
| <ul> |
| <li><code>Continue</code> - ignore the error and continue with the test</li> |
| <li><code>Start Next Loop</code> - ignore the error, start next loop and continue with the test</li> |
| <li><code>Stop Thread</code> - current thread exits</li> |
| <li><code>Stop Test</code> - the entire test is stopped at the end of any current samples.</li> |
| <li><code>Stop Test Now</code> - the entire test is stopped abruptly. Any current samplers are interrupted if possible.</li> |
| </ul> |
| </property> |
| <property name="Number of Threads" required="Yes">Number of users to simulate.</property> |
| <property name="Ramp-up Period" required="Yes">How long JMeter should take to get all the threads started. If there are 10 threads and a ramp-up time of 100 seconds, then each thread will begin 10 seconds after the previous thread started, for a total time of 100 seconds to get the test fully up to speed.</property> |
| <property name="Loop Count" required="Yes, unless forever is selected">Number of times to perform the test case. Alternatively, "<code>forever</code>" can be selected causing the test to run until manually stopped.</property> |
| <property name="Delay Thread creation until needed" required="Yes"> |
| If selected, threads are created only when the appropriate proportion of the ramp-up time has elapsed. |
| This is most appropriate for tests with a ramp-up time that is significantly longer than the time to execute a single thread. |
| I.e. where earlier threads finish before later ones start. |
| <br></br> |
| If not selected, all threads are created when the test starts (they then pause for the appropriate proportion of the ramp-up time). |
| This is the original default, and is appropriate for tests where threads are active throughout most of the test. |
| </property> |
| <property name="Scheduler" required="Yes">If selected, enables the scheduler</property> |
| <property name="Start Time" required="No">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 <code>Startup Delay</code> field over-rides this - see below. |
| </property> |
| <property name="End Time" required="No">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 <code>Duration</code> field over-rides this - see below. |
| </property> |
| <property name="Duration (seconds)" required="No"> |
| 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 <code>End Time</code> value. |
| </property> |
| <property name="Startup delay (seconds)" required="No"> |
| 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 <code>Start Time</code> value. |
| </property> |
| </properties> |
| </component> |
| |
| <component name="WorkBench" index="§-num;.9.3" width="384" height="103" screenshot="workbench.png"> |
| <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 "<code>Save Workbench</code>" option. |
| Your WorkBench can be saved independently, if you like (right-click on <code>WorkBench</code> and choose <code>Save</code>).</p> |
| <p>Certain test elements are only available on the WorkBench:</p> |
| <ul> |
| <li><complink name="HTTP(S) Test Script Recorder"/></li> |
| <li><complink name="HTTP Mirror Server"/></li> |
| <li><complink name="Property Display"/></li> |
| </ul> |
| <properties> |
| <property name="Save WorkBench" required="No"> |
| Allow to save the WorkBench's elements into the JMX file. |
| </property> |
| </properties> |
| </description> |
| </component> |
| |
| <component name="SSL Manager" index="§-num;.9.4" screenshot=""> |
| <p> |
| The SSL Manager is a way to select a client certificate so that you can test |
| applications that use Public Key Infrastructure (PKI). |
| It is only needed if you have not set up the appropriate System properties. |
| </p> |
| |
| <b>Choosing a Client Certificate</b> |
| <p> |
| You may either use a Java Key Store (JKS) format key store, or a Public Key |
| Certificate Standard #12 (PKCS12) file for your client certificates. There |
| is a feature of the JSSE libraries that require you to have at least a six character |
| password on your key (at least for the keytool utility that comes with your |
| JDK). |
| </p> |
| <p> |
| To select the client certificate, choose <menuchoice><guimenuitem>Options</guimenuitem> |
| <guimenuitem>SSL Manager</guimenuitem></menuchoice> from the menu bar. |
| You will be presented with a file finder that looks for PKCS12 files by default. |
| Your PKCS12 file must have the extension '<code>.p12</code>' for SSL Manager to recognize it |
| as a PKCS12 file. Any other file will be treated like an average JKS key store. |
| If JSSE is correctly installed, you will be prompted for the password. The text |
| box does not hide the characters you type at this point -- so make sure no one is |
| looking over your shoulder. The current implementation assumes that the password |
| for the keystore is also the password for the private key of the client you want |
| to authenticate as. |
| </p> |
| <p>Or you can set the appropriate System properties - see the <code>system.properties</code> file.</p> |
| <p> |
| The next time you run your test, the SSL Manager will examine your key store to |
| see if it has at least one key available to it. If there is only one key, SSL |
| Manager will select it for you. If there is more than one key, it currently selects the first key. |
| There is currently no way to select other entries in the keystore, so the desired key must be the first. |
| </p> |
| <b>Things to Look Out For</b> |
| <p> |
| You must have your Certificate Authority (CA) certificate installed properly |
| if it is not signed by one of the five CA certificates that ships with your |
| JDK. One method to install it is to import your CA certificate into a JKS |
| file, and name the JKS file "<code>jssecacerts</code>". Place the file in your JRE's |
| <code>lib/security</code> folder. This file will be read before the "<code>cacerts</code>" file in |
| the same directory. Keep in mind that as long as the "<code>jssecacerts</code>" file |
| exists, the certificates installed in "<code>cacerts</code>" will not be used. This may |
| cause problems for you. If you don't mind importing your CA certificate into |
| the "<code>cacerts</code>" file, then you can authenticate against all of the CA certificates |
| installed. |
| </p> |
| </component> |
| |
| <component name="HTTP(S) Test Script Recorder" was="HTTP Proxy Server" index="§-num;.9.5" width="1052" height="694" screenshot="proxy_control.png"> |
| <description><p>The HTTP(S) Test Script Recorder allows JMeter to intercept and record your actions while you browse your web application |
| with your normal browser. JMeter will create test sample objects and store them |
| directly into your test plan as you go (so you can view samples interactively while you make them).<br/> |
| Ensure you read this <a href="https://wiki.apache.org/jmeter/TestRecording210">wiki page</a> to setup correctly JMeter. |
| </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 |
| (<menuchoice> |
| <guimenuitem>Add</guimenuitem> |
| <guimenuitem>Non-Test Elements</guimenuitem> |
| <guimenuitem>HTTP(S) Test Script Recorder</guimenuitem> |
| </menuchoice> |
| ).</p> |
| <p> |
| The recorder is implemented as an HTTP(S) proxy server. |
| You need to set up your browser use the proxy for all HTTP and HTTPS requests. |
| <note>Do not use JMeter as the proxy for any other request types - FTP, etc. - as JMeter cannot handle them.</note> |
| </p> |
| <p> |
| Ideally use private browsing mode when recording the session. |
| This should ensure that the browser starts with no stored cookies, and prevents certain changes from being saved. |
| For example, Firefox does not allow certificate overrides to be saved permanently. |
| </p> |
| <h4>HTTPS recording and certificates</h4> |
| <p> |
| HTTPS connections use certificates to authenticate the connection between the browser and the web server. |
| When connecting via HTTPS, the server presents the certificate to the browser. |
| To authenticate the certificate, the browser checks that the server certificate is signed |
| by a Certificate Authority (CA) that is linked to one of its in-built root CAs. |
| <note>Browsers also check that the certificate is for the correct host or domain, and that it is valid and not expired.</note> |
| If any of the browser checks fail, it will prompt the user who can then decide whether to allow the connection to proceed. |
| </p> |
| <p> |
| JMeter needs to use its own certificate to enable it to intercept the HTTPS connection from |
| the browser. Effectively JMeter has to pretend to be the target server. |
| </p> |
| <p> |
| JMeter will generate its own certificate(s). |
| These are generated with a validity period defined by the property <code>proxy.cert.validity</code>, default 7 days, and random passwords. |
| If JMeter detects that it is running under Java 7 or later, it will generate certificates for each target server as necessary (dynamic mode) |
| unless the following property is defined: <code>proxy.cert.dynamic_keys=false</code>. |
| When using dynamic mode, the certificate will be for the correct host name, and will be signed by a JMeter-generated CA certificate. |
| By default, this CA certificate won't be trusted by the browser, however it can be installed as a trusted certificate. |
| Once this is done, the generated server certificates will be accepted by the browser. |
| This has the advantage that even embedded HTTPS resources can be intercepted, and there is no need to override the browser checks for each new server. |
| <note>Browsers don't prompt for embedded resources. So with earlier versions, embedded resources would only be downloaded for servers that were already 'known' to the browser</note> |
| </p> |
| <p>Unless a keystore is provided (and you define the property <code>proxy.cert.alias</code>), |
| JMeter needs to use the keytool application to create the keystore entries. |
| JMeter includes code to check that keytool is available by looking in various standard places. |
| If JMeter is unable to find the keytool application, it will report an error. |
| If necessary, the system property <code>keytool.directory</code> can be used to tell JMeter where to find keytool. |
| This should be defined in the file <code>system.properties</code>. |
| </p> |
| <p> |
| The JMeter certificates are generated (if necessary) when the <code>Start</code> button is pressed. |
| <note>Certificate generation can take some while, during which time the GUI will be unresponsive.</note> |
| The cursor is changed to an hour-glass whilst this is happening. |
| When certificate generation is complete, the GUI will display a pop-up dialogue containing the details of the certificate for the root CA. |
| This certificate needs to be installed by the browser in order for it to accept the host certificates generated by JMeter; see <a href="#install_cert">below</a> for details. |
| </p> |
| <p> |
| If necessary, you can force JMeter to regenerate the keystore (and the exported certificates - <code>ApacheJMeterTemporaryRootCA[.usr|.crt]</code>) by deleting the keystore file <code>proxyserver.jks</code> from the JMeter directory. |
| </p> |
| <p> |
| This certificate is not one of the certificates that browsers normally trust, and will not be for the |
| correct host.<br/> |
| As a consequence: |
| </p> |
| <ul> |
| <li>The browser should display a dialogue asking if you want to accept the certificate or not. For example: |
| <source> |
| 1) The server's name "<code>www.example.com</code>" does not match the certificate's name |
| "<code>JMeter Proxy (DO NOT TRUST)</code>". Somebody may be trying to eavesdrop on you. |
| 2) The certificate for "<code>JMeter Proxy (DO NOT TRUST)</code>" is signed by the unknown Certificate Authority |
| "<code>JMeter Proxy (DO NOT TRUST)</code>". It is not possible to verify that this is a valid certificate. |
| </source> |
| You will need to accept the certificate in order to allow the JMeter Proxy to intercept the SSL traffic in order to |
| record it. |
| However, do not accept this certificate permanently; it should only be accepted temporarily. |
| Browsers only prompt this dialogue for the certificate of the main url, not for the resources loaded in the page, such as images, css or javascript files hosted on a secured external CDN. |
| If you have such resources (gmail has for example), you'll have to first browse manually to these other domains in order to accept JMeter's certificate for them. |
| Check in <code>jmeter.log</code> for secure domains that you need to register certificate for. |
| </li> |
| <li>If the browser has already registered a validated certificate for this domain, the browser will detect JMeter as a security breach and will refuse to load the page. If so, you have to remove the trusted certificate from your browser's keystore. |
| </li> |
| </ul> |
| <p> |
| Versions of JMeter from 2.10 onwards still support this method, and will continue to do so if you define the following property: |
| <code>proxy.cert.alias</code> |
| The following properties can be used to change the certificate that is used: |
| </p> |
| <ul> |
| <li><code>proxy.cert.directory</code> - the directory in which to find the certificate (default = JMeter <code>bin/</code>)</li> |
| <li><code>proxy.cert.file</code> - name of the keystore file (default "<code>proxyserver.jks</code>")</li> |
| <li><code>proxy.cert.keystorepass</code> - keystore password (default "<code>password</code>") [Ignored if using JMeter certificate]</li> |
| <li><code>proxy.cert.keypassword</code> - certificate key password (default "<code>password</code>") [Ignored if using JMeter certificate]</li> |
| <li><code>proxy.cert.type</code> - the certificate type (default "<code>JKS</code>") [Ignored if using JMeter certificate]</li> |
| <li><code>proxy.cert.factory</code> - the factory (default "<code>SunX509</code>") [Ignored if using JMeter certificate]</li> |
| <li><code>proxy.cert.alias</code> - the alias for the key to be used. If this is defined, JMeter does not attempt to generate its own certificate(s).</li> |
| <li><code>proxy.ssl.protocol</code> - the protocol to be used (default "<code>SSLv3</code>")</li> |
| </ul> |
| <note> |
| If your browser currently uses a proxy (e.g. a company intranet may route all external requests via a proxy), |
| then you need to <a href="get-started.html#proxy_server">tell JMeter to use that proxy</a> before starting JMeter, |
| using the <a href="get-started.html#options">command-line options</a> <code>-H</code> and <code>-P</code>. |
| This setting will also be needed when running the generated test plan. |
| </note> |
| <a name="install_cert"/> |
| <h4>Installing the JMeter CA certificate for HTTPS recording</h4> |
| <p> |
| As mentioned above, when run under Java 7, JMeter can generate certificates for each server. |
| For this to work smoothly, the root CA signing certificate used by JMeter needs to be trusted by the browser. |
| The first time that the recorder is started, it will generate the certificates if necessary. |
| The root CA certificate is exported into a file with the name <code>ApacheJMeterTemporaryRootCA</code> in the current launch directory. |
| When the certificates have been set up, JMeter will show a dialog with the current certificate details. |
| At this point, the certificate can be imported into the browser, as per the instructions below. |
| </p> |
| <p> |
| Note that once the root CA certificate has been installed as a trusted CA, the browser will trust any certificates signed by it. |
| Until such time as the certificate expires or the certificate is removed from the browser, it will not warn the user that the certificate is being relied upon. |
| So anyone that can get hold of the keystore and password can use the certificate to generate certificates which will be accepted |
| by any browsers that trust the JMeter root CA certificate. |
| For this reason, the password for the keystore and private keys are randomly generated and a short validity period used. |
| The passwords are stored in the local preferences area. |
| Please ensure that only trusted users have access to the host with the keystore. |
| </p> |
| <note> |
| The popup that displays once you start the Recorder is an informational popup: |
| <figure width="1024" height="749" image="recorder_popup_info.png">Recorder Install Certificate Popup</figure> |
| Just click ok and proceed further. |
| </note> |
| <h5>Installing the certificate in Firefox</h5> |
| <p> |
| Choose the following options: |
| </p> |
| <ul> |
| <li><code>Tools / Options</code></li> |
| <li><code>Advanced / Certificates</code></li> |
| <li><code>View Certificates</code></li> |
| <li><code>Authorities</code></li> |
| <li><code>Import …</code></li> |
| <li>Browse to the JMeter launch directory, and click on the file <code>ApacheJMeterTemporaryRootCA.crt</code>, press <code>Open</code></li> |
| <li>Click <code>View</code> and check that the certificate details agree with the ones displayed by the JMeter Test Script Recorder</li> |
| <li>If OK, select "<code>Trust this CA to identify web sites</code>", and press <code>OK</code></li> |
| <li>Close dialogs by pressing <code>OK</code> as necessary</li> |
| </ul> |
| <h5>Installing the certificate in Chrome or Internet Explorer</h5> |
| <p> |
| Both Chrome and Internet Explorer use the same trust store for certificates. |
| </p> |
| <ul> |
| <li>Browse to the JMeter launch directory, and click on the file <code>ApacheJMeterTemporaryRootCA.crt</code>, and open it</li> |
| <li>Click on the "<code>Details</code>" tab and check that the certificate details agree with the ones displayed by the JMeter Test Script Recorder</li> |
| <li>If OK, go back to the "<code>General</code>" tab, and click on "<code>Install Certificate …</code>" and follow the Wizard prompts</li> |
| </ul> |
| <h5>Installing the certificate in Opera</h5> |
| <ul> |
| <li><code>Tools / Preferences / Advanced / Security</code></li> |
| <li><code>Manage Certificates …</code></li> |
| <li>Select "<code>Intermediate</code>" tab, click "<code>Import …</code>"</li> |
| <li>Browse to the JMeter launch directory, and click on the file <code>ApacheJMeterTemporaryRootCA.usr</code>, and open it</li> |
| <li></li> |
| </ul> |
| </description> |
| |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="Port" required="Yes">The port that the HTTP(S) Test Script Recorder listens to. <code>8888</code> is the default, but you can change it.</property> |
| <property name="HTTPS Domains" required="No">List of domain (or host) names for HTTPS. Use this to pre-generate certificates for all servers you wish to record. |
| <br/> |
| For example, <code>*.example.com,*.subdomain.example.com</code> |
| <br/> |
| Note that wildcard domains only apply to one level, |
| i.e. <code>abc.subdomain.example.com</code> matches <code>*.subdomain.example.com</code> but not <code>*.example.com</code> |
| </property> |
| <property name="Target Controller" required="Yes">The controller where the proxy will store the generated samples. By default, it will look for a Recording Controller and store them there wherever it is.</property> |
| <property name="Grouping" required="Yes">Whether to group samplers for requests from a single "click" (requests received without significant time separation), and how to represent that grouping in the recording: |
| <ul> |
| <li><code>Do not group samplers</code> - store all recorded samplers sequentially, without any grouping.</li> |
| <li><code>Add separators between groups</code> - add a controller named "<code>--------------</code>" to create a visual separation between the groups. Otherwise the samplers are all stored sequentially.</li> |
| <li><code>Put each group in a new controller</code> - create a new <complink name="Simple Controller"/> for each group, and store all samplers for that group in it.</li> |
| <li><code>Store 1<sup>st</sup> sampler of each group only</code> - only the first request in each group will be recorded. The "<code>Follow Redirects</code>" and "<code>Retrieve All Embedded Resources …</code>" flags will be turned on in those samplers.</li> |
| <li><code>Put each group in a new transaction controller</code> - create a new <complink name="Transaction Controller"/> for each group, and store all samplers for that group in it.</li> |
| </ul> |
| The property <code>proxy.pause</code> determines the minimum gap that JMeter needs between requests |
| to treat them as separate "clicks". The default is <code>5000</code> (milliseconds) i.e. 5 seconds. |
| If you are using grouping, please ensure that you leave the required gap between clicks. |
| </property> |
| <!-- TODO:property name="Group Separation Interval">Inactivity time between two requests needed to consider them in two separate groups.</property--> |
| <property name="Capture HTTP Headers" required="Yes">Should headers be added to the plan? |
| If specified, a Header Manager will be added to each HTTP Sampler. |
| The Proxy server always removes Cookie and Authorization headers from the generated Header Managers. |
| By default it also removes <code>If-Modified-Since</code> and <code>If-None-Match</code> headers. |
| These are used to determine if the browser cache items are up to date; |
| when recording one normally wants to download all the content. |
| To change which additional headers are removed, define the JMeter property <code>proxy.headers.remove</code> |
| as a comma-separated list of headers. |
| </property> |
| <property name="Add Assertions" required="Yes">Add a blank assertion to each sampler?</property> |
| <property name="Regex Matching" required="Yes">Use Regex Matching when replacing variables? If checked replacement will use word boundaries, i.e. it will only replace word matching values of variable, not part of a word. A word boundary follows Perl5 definition and is equivalent to <code>\b</code>. More information below in the paragraph about "<code>User Defined Variable replacement</code>".</property> |
| <property name="Type" required="Yes">Which type of sampler to generate (the HTTPClient default or Java)</property> |
| <property name="Redirect Automatically" required="Yes">Set Redirect Automatically in the generated samplers?</property> |
| <property name="Follow Redirects" required="Yes">Set Follow Redirects in the generated samplers?<br/> |
| <note>Note: see "Recording and redirects" section below for important information.</note> |
| </property> |
| <property name="Use Keep-Alive" required="Yes">Set Use Keep-Alive in the generated samplers?</property> |
| <property name="Retrieve all Embedded Resources" required="Yes">Set Retrieve all Embedded Resources in the generated samplers?</property> |
| <property name="Content Type filter" required="No"> |
| Filter the requests based on the <code>content-type</code> - e.g. "<code>text/html [;charset=utf-8 ]</code>". |
| The fields are regular expressions which are checked to see if they are contained in the <code>content-type</code>. |
| [Does not have to match the entire field]. |
| The include filter is checked first, then the exclude filter. |
| Samples which are filtered out will not be stored. |
| <note>Note: this filtering is applied to the content type of the response</note> |
| </property> |
| <property name="Patterns to Include" required="No">Regular expressions that are matched against the full URL that is sampled. Allows filtering of requests that are recorded. All requests pass through, but only |
| those that meet the requirements of the <code>Include</code>/<code>Exclude</code> fields are <em>recorded</em>. If both <code>Include</code> and <code>Exclude</code> are |
| left empty, then everything is recorded (which can result in dozens of samples recorded for each page, as images, stylesheets, |
| etc. are recorded). <note>If there is at least one entry in the <code>Include</code> field, then only requests that match one or more <code>Include</code> patterns are |
| recorded</note>.</property> |
| <property name="Patterns to Exclude" required="No">Regular expressions that are matched against the URL that is sampled. |
| <note>Any requests that match one or more <code>Exclude</code> pattern are <em>not</em> recorded</note>.</property> |
| <property name="Notify Child Listeners of filtered samplers" required="No">Notify Child Listeners of filtered samplers |
| <note>Any response that match one or more <code>Exclude</code> pattern is <em>not</em> delivered to Child Listeners (View Results Tree)</note>.</property> |
| <property name="Start Button" required="N/A">Start the proxy server. JMeter writes the following message to the console once the proxy server has started up and is ready to take requests: "<code>Proxy up and running!</code>".</property> |
| <property name="Stop Button" required="N/A">Stop the proxy server.</property> |
| <property name="Restart Button" required="N/A">Stops and restarts the proxy server. This is |
| useful when you change/add/delete an include/exclude filter expression.</property> |
| </properties> |
| |
| <h4>Recording and redirects</h4> |
| <p> |
| During recording, the browser will follow a redirect response and generate an additional request. |
| The Proxy will record both the original request and the redirected request |
| (subject to whatever exclusions are configured). |
| The generated samples have "<code>Follow Redirects</code>" selected by default, because that is generally better. |
| <note>Redirects may depend on the original request, so repeating the originally recorded sample may not always work.</note> |
| </p> |
| <p> |
| Now if JMeter is set to follow the redirect during replay, it will issue the original request, |
| and then replay the redirect request that was recorded. |
| To avoid this duplicate replay, JMeter tries to detect when a sample is the result of a previous |
| redirect. If the current response is a redirect, JMeter will save the redirect URL. |
| When the next request is received, it is compared with the saved redirect URL and if there is a match, |
| JMeter will disable the generated sample. It also adds comments to the redirect chain. |
| This assumes that all the requests in a redirect chain will follow each other without any intervening requests. |
| To disable the redirect detection, set the property <code>proxy.redirect.disabling=false</code> |
| </p> |
| |
| <h4>Includes and Excludes</h4> |
| <p>The <b>include and exclude patterns</b> are treated as regular expressions (using Jakarta ORO). |
| They will be matched against the host name, port (actual or implied), path and query (if any) of each browser request. |
| If the URL you are browsing is <br></br> |
| "<code>http://localhost/jmeter/index.html?username=xxxx</code>",<br></br> |
| then the regular expression will be tested against the string:<br></br> |
| "<code>localhost:80/jmeter/index.html?username=xxxx</code>".<br></br> |
| Thus, if you want to include all <code>.html</code> files, your regular expression might look like: <br></br> |
| "<code>.*\.html(\?.*)?</code>" - or "<code>.*\.html</code> |
| if you know that there is no query string or you only want html pages without query strings. |
| </p> |
| <p> |
| If there are any include patterns, then the URL <b>must match at least one</b> of the patterns |
| , otherwise it will not be recorded. |
| If there are any exclude patterns, then the URL <b>must not match any</b> of the patterns |
| , otherwise it will not be recorded. |
| Using a combination of includes and excludes, |
| you should be able to record what you are interested in and skip what you are not. |
| </p> |
| |
| <note> |
| N.B. the string that is matched by the regular expression must be the same as the <b>whole</b> host+path string.<br></br>Thus "<code>\.html</code>" will <b>not</b> match <code>localhost:80/index.html</code> |
| </note> |
| |
| <h4>Capturing binary POST data</h4> |
| <p> |
| JMeter is able to capture binary POST data. |
| To configure which <code>content-types</code> are treated as binary, update the JMeter property <code>proxy.binary.types</code>. |
| The default settings are as follows: |
| </p> |
| <source> |
| # These content-types will be handled by saving the request in a file: |
| proxy.binary.types=application/x-amf,application/x-java-serialized-object |
| # The files will be saved in this directory: |
| proxy.binary.directory=user.dir |
| # The files will be created with this file filesuffix: |
| proxy.binary.filesuffix=.binary |
| </source> |
| |
| <h4>Adding timers</h4> |
| <p>It is also possible to have the proxy add timers to the recorded script. To |
| do this, create a timer directly within the HTTP(S) Test Script Recorder component. |
| The proxy will place a copy of this timer into each sample it records, or into |
| the first sample of each group if you're using grouping. This copy will then be |
| scanned for occurrences of variable <code>${T}</code> in its properties, and any such |
| occurrences will be replaced by the time gap from the previous sampler |
| recorded (in milliseconds).</p> |
| |
| <p>When you are ready to begin, hit "<code>start</code>".</p> |
| <note>You will need to edit the proxy settings of your browser to point at the |
| appropriate server and port, where the server is the machine JMeter is running on, and |
| the port # is from the Proxy Control Panel shown above.</note> |
| |
| <h4>Where Do Samples Get Recorded?</h4> |
| <p>JMeter places the recorded samples in the Target Controller you choose. If you choose the default option |
| "<code>Use Recording Controller</code>", they will be stored in the first Recording Controller found in the test object tree (so be |
| sure to add a Recording Controller before you start recording).</p> |
| |
| <p> |
| If the Proxy does not seem to record any samples, this could be because the browser is not actually using the proxy. |
| To check if this is the case, try stopping the proxy. |
| If the browser still downloads pages, then it was not sending requests via the proxy. |
| Double-check the browser options. |
| If you are trying to record from a server running on the same host, |
| then check that the browser is not set to "<code>Bypass proxy server for local addresses</code>" |
| (this example is from IE7, but there will be similar options for other browsers). |
| If JMeter does not record browser URLs such as <code>http://localhost/</code> or <code>http://127.0.0.1/</code>, |
| try using the non-loopback hostname or IP address, e.g. <code>http://myhost/</code> or <code>http://192.168.0.2/</code>. |
| </p> |
| |
| <h4>Handling of HTTP Request Defaults</h4> |
| <p>If the HTTP(S) Test Script Recorder finds enabled <complink name="HTTP Request Defaults"/> directly within the |
| controller where samples are being stored, or directly within any of its parent controllers, the recorded samples |
| will have empty fields for the default values you specified. You may further control this behaviour by placing an |
| HTTP Request Defaults element directly within the HTTP(S) Test Script Recorder, whose non-blank values will override |
| those in the other HTTP Request Defaults. See <a href="best-practices.html#proxy_server"> Best |
| Practices with the HTTP(S) Test Script Recorder</a> for more info.</p> |
| |
| <h4>User Defined Variable replacement</h4> |
| <p>Similarly, if the HTTP(S) Test Script Recorder finds <complink name="User Defined Variables"/> (UDV) directly within the |
| controller where samples are being stored, or directly within any of its parent controllers, the recorded samples |
| will have any occurrences of the values of those variables replaced by the corresponding variable. Again, you can |
| place User Defined Variables directly within the HTTP(S) Test Script Recorder to override the values to be replaced. See |
| <a href="best-practices.html#proxy_server"> Best Practices with the Test Script Recorder</a> for more info.</p> |
| |
| <note>Please note that matching is case-sensitive.</note> |
| |
| <p>Replacement by Variables: by default, the Proxy server looks for all occurrences of UDV values. |
| If you define the variable <code>WEB</code> with the value <code>www</code>, for example, |
| the string <code>www</code> will be replaced by <code>${WEB}</code> wherever it is found. |
| To avoid this happening everywhere, set the "<code>Regex Matching</code>" check-box. |
| This tells the proxy server to treat values as Regexes (using the perl5 compatible regex matchers provided by ORO).</p> |
| |
| <p>If "<code>Regex Matching</code>" is selected every variable will be compiled into a perl compatible regex enclosed in |
| <code>\b(</code> and <code>)\b</code>. That way each match will start and end at a word boundary.</p> |
| |
| <note>Note that the boundary characters are not part of the matching group, e.g. <code>n.*</code> to match <code>name</code> out |
| of <code>You can call me 'name'</code>.</note> |
| |
| <p>If you don't want your regex to be enclosed with those boundary matchers, you have to enclose your |
| regex within parens, e.g <code>('.*?')</code> to match <code>'name'</code> out of <code>You can call me 'name'</code>.</p> |
| |
| <note> |
| The variables will be checked in random order. So ensure, that the potential matches don't overlap. |
| Overlapping matchers would be <code>.*</code> (which matches anything) and <code>www</code> (which |
| matches <code>www</code> only). Non-overlapping matchers would be <code>a+</code> (matches a sequence |
| of <code>a</code>'s) and <code>b+</code> (matches a sequence of <code>b</code>'s). |
| </note> |
| |
| <p>If you want to match a whole string only, enclose it in <code>(^</code> and <code>$)</code>, e.g. <code>(^thus$)</code>. |
| The parens are necessary, since the normally added boundary characters will prevent <code>^</code> and |
| <code>$</code> to match.</p> |
| |
| <p>If you want to match <code>/images</code> at the start of a string only, use the value <code>(^/images)</code>. |
| Jakarta ORO also supports zero-width look-ahead, so one can match <code>/images/…</code> |
| but retain the trailing <code>/</code> in the output by using <code>(^/images(?=/))</code>.</p> |
| |
| <note> |
| Note that the current version of Jakara ORO does not support look-behind - i.e. <code>(?<=…)</code> or <code>(?<!…)</code>. |
| </note> |
| |
| <p>Look out for overlapping matchers. For example the value <code>.*</code> as a regex in a variable named |
| <code>regex</code> will partly match a previous replaced variable, which will result in something like |
| <code>${{regex}</code>, which is most probably not the desired result.</p> |
| |
| <p>If there are any problems interpreting any variables as patterns, these are reported in <code>jmeter.log</code>, |
| so be sure to check this if UDVs are not working as expected.</p> |
| |
| <p>When you are done recording your test samples, stop the proxy server (hit the "<code>stop</code>" button). Remember to reset |
| your browser's proxy settings. Now, you may want to sort and re-order the test script, add timers, listeners, a |
| cookie manager, etc.</p> |
| |
| <h4>How can I record the server's responses too?</h4> |
| <p>Just place a <complink name="View Results Tree"/> listener as a child of the HTTP(S) Test Script Recorder and the responses will be displayed. |
| You can also add a <complink name="Save Responses to a file"/> Post-Processor which will save the responses to files. |
| </p> |
| |
| <h4>Associating requests with responses</h4> |
| <p> |
| If you define the property <code>proxy.number.requests=true</code> |
| JMeter will add a number to each sampler and each response. |
| Note that there may be more responses than samplers if excludes or includes have been used. |
| Responses that have been excluded will have labels enclosed in <code>[</code> and <code>],</code> for example <code>[23 /favicon.ico]</code> |
| </p> |
| <h4>Cookie Manager</h4> |
| <p> |
| If the server you are testing against uses cookies, remember to add an <complink name="HTTP Cookie Manager"/> to the test plan |
| when you have finished recording it. |
| During recording, the browser handles any cookies, but JMeter needs a Cookie Manager |
| to do the cookie handling during a test run. |
| The JMeter Proxy server passes on all cookies sent by the browser during recording, but does not save them to the test |
| plan because they are likely to change between runs. |
| </p> |
| <h4>Authorization Manager</h4> |
| <p> |
| The HTTP(S) Test Script Recorder grabs "<code>Authentication</code>" header, tries to compute the Auth Policy. If Authorization Manager was added to target |
| controller manually, HTTP(S) Test Script Recorder will find it and add authorization (matching ones will be removed). Otherwise |
| Authorization Manager will be added to target controller with authorization object. |
| You may have to fix automatically computed values after recording. |
| |
| </p> |
| <h4>Uploading files</h4> |
| <p> |
| Some browsers (e.g. Firefox and Opera) don't include the full name of a file when uploading files. |
| This can cause the JMeter proxy server to fail. |
| One solution is to ensure that any files to be uploaded are in the JMeter working directory, |
| either by copying the files there or by starting JMeter in the directory containing the files. |
| </p> |
| <h4>Recording HTTP Based Non Textual Protocols not natively available in JMeter</h4> |
| <p> |
| You may have to record an HTTP protocol that is not handled by default by JMeter (Custom Binary Protocol, Adobe Flex, Microsoft Silverlight, … ). |
| Although JMeter does not provide a native proxy implementation to record these protocols, you have the ability to |
| record these protocols by implementing a custom <code>SamplerCreator</code>. This Sampler Creator will translate the binary format into a <code>HTTPSamplerBase</code> subclass |
| that can be added to the JMeter Test Case. |
| For more details see "Extending JMeter". |
| </p> |
| </component> |
| |
| <component name="HTTP Mirror Server" index="§-num;.9.6" width="794" height="157" screenshot="mirrorserver.png"> |
| <description> |
| <p> |
| The HTTP Mirror Server is a very simple HTTP server - it simply mirrors the data sent to it. |
| This is useful for checking the content of HTTP requests. |
| </p> |
| <p> |
| It uses default port <code>8081</code>. |
| </p> |
| </description> |
| <properties> |
| <property name="Port" required="Yes">Port on which Mirror server listens, defaults to <code>8081</code>.</property> |
| <property name="Max Number of threads" required="No">If set to a value > <code>0</code>, number of threads serving requests will be limited to the configured number, if set to a value ≤ <code>0</code> |
| a new thread will be created to serve each incoming request. Defaults to <code>0</code></property> |
| <property name="Max Queue size" required="No">Size of queue used for holding tasks before they are executed by Thread Pool, when Thread pool is exceeded, incoming requests will |
| be held in this queue and discarded when this queue is full. This parameter is only used if Max Number of Threads is greater than <code>0</code>. Defaults to <code>25</code></property> |
| </properties> |
| <note> |
| Note that you can get more control over the responses by adding an HTTP Header Manager with the following name/value pairs: |
| </note> |
| <properties> |
| <property name="X-Sleep" required="No">Time to sleep in ms before sending response</property> |
| <property name="X-SetCookie" required="No">Cookies to be set on response</property> |
| <property name="X-ResponseStatus" required="No">Response status, see <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html">HTTP Status responses</a>, example 200 OK, 500 Internal Server Error, ….</property> |
| <property name="X-ResponseLength" required="No">Size of response, this trims the response to the requested size if that is less than the total size</property> |
| <property name="X-SetHeaders" required="No">Pipe separated list of headers, example:<br/> |
| <code>headerA=valueA|headerB=valueB</code> would set <code>headerA</code> to <code>valueA</code> and <code>headerB</code> to <code>valueB</code>. |
| </property> |
| </properties> |
| <p> |
| You can also use the following query parameters: |
| </p> |
| <properties> |
| <property name="redirect" required="No">Generates a 302 (Temporary Redirect) with the provided location. |
| e.g. <code>?redirect=/path</code> |
| </property> |
| <property name="status" required="No">Overrides the default status return. e.g. <code>?status=404 Not Found</code></property> |
| <property name="v" required="No">Verbose flag, writes some details to standard output. e.g. first line and redirect location if specified</property> |
| </properties> |
| </component> |
| |
| <component name="Property Display" index="§-num;.9.7" width="804" height="508" screenshot="property_display.png"> |
| <description> |
| <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> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| </properties> |
| </component> |
| |
| <component name="Debug Sampler" index="§-num;.9.8" width="431" height="172" screenshot="debug_sampler.png"> |
| <description> |
| <p> |
| The Debug Sampler generates a sample containing the values of all JMeter variables and/or properties. |
| </p> |
| <p> |
| The values can be seen in the <complink name="View Results Tree"/> Listener Response Data pane. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="JMeter Properties" required="Yes">Include JMeter properties?</property> |
| <property name="JMeter Variables" required="Yes">Include JMeter variables?</property> |
| <property name="System Properties" required="Yes">Include System properties?</property> |
| </properties> |
| </component> |
| |
| <component name="Debug PostProcessor" index="§-num;.9.8" width="344" height="193" screenshot="debug_postprocessor.png"> |
| <description> |
| <p> |
| The Debug PostProcessor creates a subSample with the details of the previous Sampler properties, |
| JMeter variables, properties and/or System Properties. |
| </p> |
| <p> |
| The values can be seen in the <complink name="View Results Tree"/> Listener Response Data pane. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="No">Descriptive name for this element that is shown in the tree.</property> |
| <property name="JMeter Properties" required="Yes">Whether to show JMeter properties (default <code>false</code>).</property> |
| <property name="JMeter Variables" required="Yes">Whether to show JMeter variables (default <code>false</code>).</property> |
| <property name="Sampler Properties" required="Yes">Whether to show Sampler properties (default <code>true</code>).</property> |
| <property name="System Properties" required="Yes">Whether to show System properties (default <code>false</code>).</property> |
| </properties> |
| </component> |
| |
| <component name="Test Fragment" index="§-num;.9.9" width="236" height="94" screenshot="test_fragment.png"> |
| <description> |
| <p> |
| The Test Fragment is used in conjunction with the <complink name="Include Controller"/> and <complink name="Module Controller"/>. |
| </p> |
| </description> |
| <properties> |
| <property name="Name" required="Yes">Descriptive name for this element that is shown in the tree.</property> |
| </properties> |
| <note> |
| When using Test Fragment with <complink name="Module Controller"/>, ensure you disable the Test Fragment to avoid the execution of Test Fragment itself. |
| This is done by default since JMeter 2.13. |
| </note> |
| </component> |
| |
| <component name="setUp Thread Group" index="§-num;.9.10" width="678" height="377" screenshot="setup_thread_group.png"> |
| <description> |
| <p> |
| A special type of ThreadGroup that can be utilized to perform Pre-Test Actions. The behavior of these threads |
| is exactly like a normal <complink name="Thread Group"/> element. The difference is that these type of threads |
| execute before the test proceeds to the executing of regular Thread Groups. |
| </p> |
| </description> |
| </component> |
| |
| <component name="tearDown Thread Group" index="§-num;.9.11" width="677" height="379" screenshot="teardown_thread_group.png"> |
| <description> |
| <p> |
| A special type of ThreadGroup that can be utilized to perform Post-Test Actions. The behavior of these threads |
| is exactly like a normal <complink name="Thread Group"/> element. The difference is that these type of threads |
| execute after the test has finished executing its regular Thread Groups. |
| </p> |
| </description> |
| <note> |
| Note that by default it won't run if Test is gracefully shutdown, if you want to make it run in this case, |
| ensure you check option "<code>Run tearDown Thread Groups after shutdown of main threads</code>" on Test Plan element. |
| If Test Plan is stopped, tearDown will not run even if option is checked. |
| </note> |
| <figure width="1130" height="486" image="tear_down_on_shutdown.png">Figure 1 - Run tearDown Thread Groups after shutdown of main threads</figure> |
| </component> |
| |
| <a href="#">^</a> |
| |
| </section> |
| <!-- |
| <section name="§-num;.10 Reports" anchor="Reports"> |
| <description> |
| <br></br> |
| </description> |
| |
| <component name="Report Plan" index="§-num;.10.1" screenshot=""> |
| <description><p></p></description> |
| </component> |
| |
| <component name="Report Table" index="§-num;.10.2" screenshot=""> |
| <description><p></p></description> |
| </component> |
| |
| <component name="HTML Report Writer" index="§-num;.10.3" screenshot=""> |
| <description><p></p></description> |
| </component> |
| |
| <component name="Report Page" index="§-num;.10.4" screenshot=""> |
| <description><p></p></description> |
| </component> |
| |
| <component name="Line Graph" index="§-num;.10.5" screenshot=""> |
| <description><p></p></description> |
| </component> |
| |
| <component name="Bar Chart" index="§-num;.10.6" screenshot=""> |
| <description><p></p></description> |
| </component> |
| |
| <a href="#">^</a> |
| |
| </section> |
| --> |
| </body> |
| </document> |
| |
