Author: sebb
Date: Thu May 8 03:59:30 2008
New Revision: 654472
URL: http://svn.apache.org/viewvc?rev=654472&view=rev
Log:
Update documentation re UDV and global/local variables
Modified:
jakarta/jmeter/trunk/docs/usermanual/component_reference.html
jakarta/jmeter/trunk/docs/usermanual/test_plan.html
jakarta/jmeter/trunk/xdocs/usermanual/component_reference.xml
jakarta/jmeter/trunk/xdocs/usermanual/test_plan.xml
Modified: jakarta/jmeter/trunk/docs/usermanual/component_reference.html
URL:
http://svn.apache.org/viewvc/jakarta/jmeter/trunk/docs/usermanual/component_reference.html?rev=654472&r1=654471&r2=654472&view=diff
==============================================================================
--- jakarta/jmeter/trunk/docs/usermanual/component_reference.html (original)
+++ jakarta/jmeter/trunk/docs/usermanual/component_reference.html Thu May 8
03:59:30 2008
@@ -7936,7 +7936,27 @@
The User
Defined Variables lets you define variables for use in other test elements,
just as in the
<a href="../usermanual/component_reference.html#Test_Plan">Test
Plan</a>
.
-The variables in User Defined Variables components will take precedence over
those defined closer to the tree root -- including those defined in the Test
Plan.
+The variables in User Defined Variables components will take precedence over
those defined closer to the tree root -- including those defined in the Test
Plan.
+Note that all the UDV elements in a test plan - no matter where they are - are
processed at the start.
+
+ </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 >
+
+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 global variables, then other test elements
will see the local
+local value of the variable.
+The global value is not affected.
+
</p>
@@ -7947,7 +7967,7 @@
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 use variables that are defined in the same element.
-You can use variables defined in earlier UDVs or on the Test Plan.
+You can reference variables defined in earlier UDVs or on the Test Plan.
</td></tr>
</table></p>
@@ -11084,6 +11104,19 @@
<p >
+If the same variable name is reused on one of more
+
+
<a
href="../usermanual/component_reference.html#User_Defined_Variables">User
Defined Variables</a>
+
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 >
+
<b >
Note that the
Test Plan cannot refer to variables it defines.
@@ -11092,8 +11125,6 @@
If you need to construct other variables from the Test Plan variables,
use a
<a
href="../usermanual/component_reference.html#User_Defined_Variables">User
Defined Variables</a>
- or a
-
<a
href="../usermanual/component_reference.html#User_Parameters">User
Parameters</a>
test
element.
</p>
Modified: jakarta/jmeter/trunk/docs/usermanual/test_plan.html
URL:
http://svn.apache.org/viewvc/jakarta/jmeter/trunk/docs/usermanual/test_plan.html?rev=654472&r1=654471&r2=654472&view=diff
==============================================================================
--- jakarta/jmeter/trunk/docs/usermanual/test_plan.html (original)
+++ jakarta/jmeter/trunk/docs/usermanual/test_plan.html Thu May 8 03:59:30 2008
@@ -162,8 +162,11 @@
<tr><td>
<blockquote>
<p >
- Thread group
elements are the beginning points of any test plan. All elements
-of a test plan must be under a thread group. As the name implies, the thread
group
+ Thread group
elements are the beginning points of any test plan.
+All controllers and samplers must be under a thread group.
+Other elements, e.g. Listeners, may be placed directly under the test plan,
+in which case they will apply to all the thread groups.
+As the name implies, the thread group
element controls the number of threads JMeter will use to execute your test.
The
controls for a thread group allow you to:
@@ -205,7 +208,7 @@
</p>
<p >
-Start with Ramp-up = number of threads and adjust as needed.
+Start with Ramp-up = number of threads and adjust up or down as needed.
</p>
<p >
@@ -240,7 +243,10 @@
<tr><td>
<blockquote>
<p >
- JMeter has two
types of Controllers: Samplers and Logical Controllers.
+
+JMeter has two types of Controllers: Samplers and Logical Controllers.
+These drive the processing of a test.
+
</p>
<p >
Samplers tell
JMeter to send requests to a server. For
@@ -277,7 +283,14 @@
<tr><td>
<blockquote>
<p >
- Samplers tell
JMeter to send requests to a server.
+
+Samplers tell JMeter to send requests to a server and wait for a response.
+They are processed in the order they appear in the tree.
+Controllers can be used to modify the number of repetitions of a sampler.
+
+ </p>
+
<p >
+
JMeter samplers include:
<ul >
@@ -321,8 +334,8 @@
</ul>
Each sampler has several properties you can set.
-You can further customize a sampler by adding one or more Configuration
Elements to it.
-Note that JMeter sends requests in the order that the samplers appear in the
tree.
+You can further customize a sampler by adding one or more Configuration
Elements to the Test Plan.
+
</p>
<p >
If you are
going to send multiple requests of the same type (for example,
@@ -330,7 +343,7 @@
Element. Each controller has one or more Defaults elements (see below).
</p>
<p >
- Remember to add
a Listener to your Thread Group to view and/or store the
+ Remember to add
a Listener to your test plan to view and/or store the
results of your requests to disk.
</p>
<p >
@@ -340,7 +353,7 @@
Assertion
</a>
to
-the Request controller. For example, in stress testing a web application, the
server
+the sampler. For example, in stress testing a web application, the server
may return a successful "HTTP Response" code, but the page may have errors on
it or
may be missing sections. You could add assertions to check for certain HTML
tags,
common error strings, and so on. JMeter lets you create these assertions using
regular
@@ -365,9 +378,8 @@
<blockquote>
<p >
Logic
Controllers let you customize the logic that JMeter uses to
-decide when to send requests. Logic Controllers may have as child elements any
-of the following: Samplers (requests), Configuration Elements, and other Logic
-Controllers. Logic Controllers can change the order of requests coming from
their
+decide when to send requests.
+Logic Controllers can change the order of requests coming from their
child elements. They can modify the requests themselves, cause JMeter to
repeat
requests, etc.
@@ -564,13 +576,15 @@
</p>
<p >
- Listeners can
be added anywhere in the test. They will collect data only from elements at or
-below their level.
+
+Listeners can be added anywhere in the test, including directly under the test
plan.
+They will collect data only from elements at or below their level.
+
</p>
<p >
There are
several
<a href="component_reference.html#listeners">
- interesting
listeners
+ listeners
</a>
that come with JMeter.
@@ -594,13 +608,26 @@
making too many requests in a very short amount of time.
</p>
<p >
- The timer will
cause JMeter to delay a certain amount of time before each
+ The timer will
cause JMeter to delay a certain amount of time
+
<b >
+ before
+ </b>
+ each
request that a thread makes.
</p>
<p >
If you choose to add more than one timer to a Thread Group, JMeter takes the
sum of
-the timers and pauses for that amount of time before executing the samplers to
which they apply.
+the timers and pauses for that amount of time before executing the samplers to
which the timers apply.
+Timers can be added as children of samplers or controllers in order to
restrict the samplers to which they are applied.
+
+ </p>
+
<p >
+
+To provide a pause at a single place in a test plan, one can use the
+
<a
href="../usermanual/component_reference.html#Test_Action">Test Action</a>
+
Sampler.
+
</p>
</blockquote>
</td></tr>
@@ -671,6 +698,16 @@
<font size="-1"> Figure
1 -
Test Plan Showing Accessability of Configuration Elements
</font></td></tr></table></p>
+
<p><table border="1" bgcolor="#bbbb00" width="50%" cellspacing="0"
cellpadding="2">
+ <tr><td>
+The
+
<a
href="../usermanual/component_reference.html#User_Defined_Variables">User
Defined Variables</a>
+
Configuration element is different.
+It is processed at the start of a test, no matter where it is placed.
+For simplicity, it is suggested that the element is placed only at the start
of a Thread Group.
+
+ </td></tr>
+ </table></p>
</blockquote>
</td></tr>
<tr><td><br></td></tr>
@@ -731,10 +768,15 @@
</td></tr>
<tr><td>
<blockquote>
-
<ol >
+
<ol start="0">
<li >
+ Configuration
elements
+ </li>
+
+
+
<li >
Pre-Processors
</li>
@@ -885,7 +927,7 @@
<br >
</br>
-Properties are global to jmeter, and are used to define some of the defaults
JMeter uses.
+Properties are global to jmeter, and are mostly used to define some of the
defaults JMeter uses.
For example the property remote_hosts defines the servers that JMeter will try
to run remotely.
Properties can be referenced in test plans
- see
@@ -920,6 +962,38 @@
</p>
+
<p >
+
+Note that the values defined by the
+
<a
href="../usermanual/component_reference.html#User_Defined_Variables">User
Defined Variables</a>
+
configuration element
+are handled differently.
+Such variables are made available to the whole test plan at startup, and are
not updated.
+Other elements such as the
+
+
<a
href="../usermanual/component_reference.html#User_Parameters">User
Parameters</a>
+
Pre-Processor or
+
<a
href="../usermanual/component_reference.html#Regular_Expression_Extractor">Regular
Expression Extractor</a>
+
Post-Processor
+may be used to define the same variables, but these will not affect the global
values.
+For example if there is a global variable ABCD, its value will be visible to
all threads.
+However if a thread defines the variable ABCD in a runtime element such as a
User Parameters Pre-Processor,
+the new value will be seen by the thread, but only in the scope of the element.
+Local definitions of variables in a thread take precedence over the global
version of the variable,
+but the global copy is unaffected.
+
+ </p>
+
<p >
+
+Note that global variables cannot be updated during a test.
+The
+
<a href="functions.html#__setProperty">
+ setProperty
+ </a>
+
function can be used to define a JMeter property.
+These are global to the test plan, so can be used to pass information between
threads.
+
+ </p>
</blockquote>
</td></tr>
<tr><td><br></td></tr>
Modified: jakarta/jmeter/trunk/xdocs/usermanual/component_reference.xml
URL:
http://svn.apache.org/viewvc/jakarta/jmeter/trunk/xdocs/usermanual/component_reference.xml?rev=654472&r1=654471&r2=654472&view=diff
==============================================================================
--- jakarta/jmeter/trunk/xdocs/usermanual/component_reference.xml (original)
+++ jakarta/jmeter/trunk/xdocs/usermanual/component_reference.xml Thu May 8
03:59:30 2008
@@ -2502,13 +2502,25 @@
<component name="User Defined Variables" index="§-num;.4.13" width="690"
height="394" screenshot="user_defined_variables.png">
<description><p>The User Defined Variables lets you define variables for use
in other test elements, just as in the <complink name="Test Plan" />.
-The variables in User Defined Variables components will take precedence over
those defined closer to the tree root -- including those defined in the Test
Plan.</p>
+The variables in User Defined Variables components will take precedence over
those defined closer to the tree root -- including those defined in the Test
Plan.
+Note that all the UDV elements in a test plan - no matter where they are - are
processed at the start.
+</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>
+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 global variables, then other test elements
will see the local
+local value of the variable.
+The global value is not affected.
+</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 use variables that are defined in the same element.
-You can use variables defined in earlier UDVs or on the Test Plan.
+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>
@@ -3477,9 +3489,16 @@
could refer to it as ${SERVER}. 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>
<b>Note that the Test Plan cannot refer to variables it defines.</b>
If you need to construct other variables from the Test Plan variables,
-use a <complink name="User Defined Variables"/> or a <complink name="User
Parameters"/> test element.
+use a <complink name="User Defined Variables"/> test element.
</p>
<p>
Selecting Functional Testing instructs JMeter to save the additional sample
information
Modified: jakarta/jmeter/trunk/xdocs/usermanual/test_plan.xml
URL:
http://svn.apache.org/viewvc/jakarta/jmeter/trunk/xdocs/usermanual/test_plan.xml?rev=654472&r1=654471&r2=654472&view=diff
==============================================================================
--- jakarta/jmeter/trunk/xdocs/usermanual/test_plan.xml (original)
+++ jakarta/jmeter/trunk/xdocs/usermanual/test_plan.xml Thu May 8 03:59:30 2008
@@ -41,8 +41,11 @@
<p>You can also use the Configuration button on a listener to decide what
fields to save.</p>
<subsection name="§-num;.1 ThreadGroup" anchor="thread_group">
-<p>Thread group elements are the beginning points of any test plan. All
elements
-of a test plan must be under a thread group. As the name implies, the thread
group
+<p>Thread group elements are the beginning points of any test plan.
+All controllers and samplers must be under a thread group.
+Other elements, e.g. Listeners, may be placed directly under the test plan,
+in which case they will apply to all the thread groups.
+As the name implies, the thread group
element controls the number of threads JMeter will use to execute your test.
The
controls for a thread group allow you to:
<ul><li>Set the number of threads</li>
@@ -65,7 +68,7 @@
the first ones finish (unless one wants that to happen).
</p>
<p>
-Start with Ramp-up = number of threads and adjust as needed.
+Start with Ramp-up = number of threads and adjust up or down as needed.
</p>
<p>By default, the thread group is configured to loop once through its
elements.</p>
@@ -82,7 +85,10 @@
<subsection name="§-num;.2 Controllers" anchor="controllers">
-<p> JMeter has two types of Controllers: Samplers and Logical Controllers.</p>
+<p>
+JMeter has two types of Controllers: Samplers and Logical Controllers.
+These drive the processing of a test.
+</p>
<p>Samplers tell JMeter to send requests to a server. For
example, add an HTTP Request Sampler if you want JMeter
@@ -100,7 +106,12 @@
<subsection name="§-num;.2.1 Samplers" anchor="samplers">
-<p>Samplers tell JMeter to send requests to a server.
+<p>
+Samplers tell JMeter to send requests to a server and wait for a response.
+They are processed in the order they appear in the tree.
+Controllers can be used to modify the number of repetitions of a sampler.
+</p>
+<p>
JMeter samplers include:
<ul>
<li>FTP Request</li>
@@ -112,19 +123,19 @@
<li>WebService (SOAP) Request</li>
</ul>
Each sampler has several properties you can set.
-You can further customize a sampler by adding one or more Configuration
Elements to it.
-Note that JMeter sends requests in the order that the samplers appear in the
tree.</p>
+You can further customize a sampler by adding one or more Configuration
Elements to the Test Plan.
+</p>
<p>If you are going to send multiple requests of the same type (for example,
HTTP Request) to the same server, consider using a Defaults Configuration
Element. Each controller has one or more Defaults elements (see below). </p>
-<p>Remember to add a Listener to your Thread Group to view and/or store the
+<p>Remember to add a Listener to your test plan to view and/or store the
results of your requests to disk.</p>
<p>If you are interested in having JMeter perform basic validation on
the response of your request, add an <a href="#assertions">Assertion</a> to
-the Request controller. For example, in stress testing a web application, the
server
+the sampler. For example, in stress testing a web application, the server
may return a successful "HTTP Response" code, but the page may have errors on
it or
may be missing sections. You could add assertions to check for certain HTML
tags,
common error strings, and so on. JMeter lets you create these assertions using
regular
@@ -135,9 +146,8 @@
<subsection name="§-num;.2.2 Logic Controllers" anchor="logic_controller">
<p>Logic Controllers let you customize the logic that JMeter uses to
-decide when to send requests. Logic Controllers may have as child elements any
-of the following: Samplers (requests), Configuration Elements, and other Logic
-Controllers. Logic Controllers can change the order of requests coming from
their
+decide when to send requests.
+Logic Controllers can change the order of requests coming from their
child elements. They can modify the requests themselves, cause JMeter to
repeat
requests, etc.
</p>
@@ -231,10 +241,12 @@
<b>Note that all Listeners save the same data; the only difference is in the
way the data is presented on the screen.</b>
</p>
-<p>Listeners can be added anywhere in the test. They will collect data only
from elements at or
-below their level. </p>
+<p>
+Listeners can be added anywhere in the test, including directly under the test
plan.
+They will collect data only from elements at or below their level.
+</p>
-<p>There are several <a href="component_reference.html#listeners">interesting
listeners</a>
+<p>There are several <a href="component_reference.html#listeners">listeners</a>
that come with JMeter.</p>
</subsection>
@@ -245,12 +257,17 @@
your Thread Group. If you do not add a delay, JMeter could overwhelm your
server by
making too many requests in a very short amount of time.</p>
-<p>The timer will cause JMeter to delay a certain amount of time before each
+<p>The timer will cause JMeter to delay a certain amount of time <b>before</b>
each
request that a thread makes.</p>
<p>
If you choose to add more than one timer to a Thread Group, JMeter takes the
sum of
-the timers and pauses for that amount of time before executing the samplers to
which they apply.</p>
+the timers and pauses for that amount of time before executing the samplers to
which the timers apply.
+Timers can be added as children of samplers or controllers in order to
restrict the samplers to which they are applied.
+</p>
+<p>
+To provide a pause at a single place in a test plan, one can use the <complink
name="Test Action"/> Sampler.
+</p>
</subsection>
<subsection name="§-num;.5 Assertions" anchor="assertions">
@@ -290,6 +307,12 @@
<figure image="http-config/http-config-example.png">Figure 1 -
Test Plan Showing Accessability of Configuration Elements</figure>
+
+<note>
+The <complink name="User Defined Variables"/> Configuration element is
different.
+It is processed at the start of a test, no matter where it is placed.
+For simplicity, it is suggested that the element is placed only at the start
of a Thread Group.
+</note>
</subsection>
<subsection name="§-num;.7 Pre-Processor Elements" anchor="preprocessors">
@@ -307,7 +330,8 @@
</subsection>
<subsection name="§-num;.9 Execution order" anchor="executionorder">
-<ol>
+<ol start="0">
+<li>Configuration elements</li>
<li>Pre-Processors</li>
<li>Timers</li>
<li>Sampler</li>
@@ -363,7 +387,7 @@
<p>
JMeter <b>properties</b> are defined in jmeter.properties (see <a
href="get-started.html#configuring_jmeter">Gettting Started - Configuring
JMeter</a> for more details).
<br></br>
-Properties are global to jmeter, and are used to define some of the defaults
JMeter uses.
+Properties are global to jmeter, and are mostly used to define some of the
defaults JMeter uses.
For example the property remote_hosts defines the servers that JMeter will try
to run remotely.
Properties can be referenced in test plans
- see <a href="functions.html#__property">Functions - read a property</a> -
@@ -378,6 +402,24 @@
by the same thread.
For details of how to reference variables and functions, see <a
href="functions.html">Functions and Variables</a>
</p>
+<p>
+Note that the values defined by the <complink name="User Defined Variables"/>
configuration element
+are handled differently.
+Such variables are made available to the whole test plan at startup, and are
not updated.
+Other elements such as the
+<complink name="User Parameters"/> Pre-Processor or <complink name="Regular
Expression Extractor"/> Post-Processor
+may be used to define the same variables, but these will not affect the global
values.
+For example if there is a global variable ABCD, its value will be visible to
all threads.
+However if a thread defines the variable ABCD in a runtime element such as a
User Parameters Pre-Processor,
+the new value will be seen by the thread, but only in the scope of the element.
+Local definitions of variables in a thread take precedence over the global
version of the variable,
+but the global copy is unaffected.
+</p>
+<p>
+Note that global variables cannot be updated during a test.
+The <a href="functions.html#__setProperty">setProperty</a> function can be
used to define a JMeter property.
+These are global to the test plan, so can be used to pass information between
threads.
+</p>
</subsection>
</section>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
