The easiest way to begin using JMeter is to first download the latest production release and install it. The release contains all of the files you need to build and run most types of tests, e.g. Web (HTTP/HTTPS), FTP, JDBC, LDAP, Java, and JUnit.

If you want to perform JDBC testing, then you will, of course, need the appropriate JDBC driver from your vendor. JMeter does not come with any JDBC drivers.

JMeter includes the JMS API jar, but does not include a JMS client implementation. If you want to run JMS tests, you will need to download the appropriate jars from the JMS provider.

See the JMeter Classpath section for details on installing additional jars.

Next, start JMeter and go through the Building a Test Plan section of the User Guide to familiarize yourself with JMeter basics (for example, adding and removing elements).

Finally, go through the appropriate section on how to build a specific type of Test Plan. For example, if you are interested in testing a Web application, then see the section Building a Web Test Plan . The other specific Test Plan sections are:

• Advanced Web Test Plan
• JDBC
• FTP
• JMS Point-to-Point
• JMS Topic
• LDAP
• LDAP Extended
• WebServices (SOAP)

Once you are comfortable with building and running JMeter Test Plans, you can look into the various configuration elements (timers, listeners, assertions, and others) which give you more control over your Test Plans.

JMeter requires your computing environment meets some minimum requirements.

2.1.1 Java Version

JMeter requires a fully compliant JVM 1.5 or higher. Because JMeter uses only standard Java APIs, please do not file bug reports if your JRE fails to run JMeter because of JRE implementation issues.

2.1.2 Operating Systems

JMeter is a 100% Java application and should run correctly on any system that has a compliant Java implementation. Operating systems tested with JMeter can be view on this page on JMeter wiki. Even if your OS is not listed on the wiki page, JMeter should run on it provided that the JVM is compliant.

If you plan on doing JMeter development, then you will need one or more optional packages listed below.

2.2.1 Java Compiler

If you want to build the JMeter source or develop JMeter plugins, then you will need a fully compliant JDK 1.5 or higher.

2.2.2 SAX XML Parser

JMeter comes with Apache's Xerces XML parser . You have the option of telling JMeter to use a different XML parser. To do so, include the classes for the third-party parser in JMeter's classpath , and update the jmeter.properties file with the full classname of the parser implementation.

2.2.3 Email Support

JMeter has extensive Email capabilities. It can send email based on test results, and has a POP3(S)/IMAP(S) sampler. It also has an SMTP sampler.

2.2.4 SSL Encryption

To test a web server using SSL encryption (HTTPS), JMeter requires that an implementation of SSL be provided, as is the case with Sun Java 1.4 and above. If your version of Java does not include SSL support, then it is possible to add an external implementation. Include the necessary encryption packages in JMeter's classpath . Also, update system.properties to register the SSL Provider. JMeter HTTP defaults to protocol level TLS. This can be changed by editting the JMeter property "https.default.protocol" in jmeter.properties or user.properties. The JMeter HTTP samplers are configured to accept all certificates, whether trusted or not, regardless of validity periods etc. This is to allow the maximum flexibility in testing servers. If the server requires a client certificate, this can be provided. There is also the SSL Manager , for greater control of certificates. The JMeter proxy server (see below) supports recording HTTPS (SSL) in versions after 2.3.4 The SMTP sampler can optionally use a local trust store or trust all certificates.

2.2.5 JDBC Driver

You will need to add your database vendor's JDBC driver to the classpath if you want to do JDBC testing. Make sure the file is a jar file, not a zip.

2.2.6 JMS client

JMeter now includes the JMS API from Apache Geronimo, so you just need to add the appropriate JMS Client implementation jar(s) from the JMS provider. Please refer to their documentation for details. There may also be some information on the JMeter Wiki .

2.2.7 Libraries for ActiveMQ JMS

At the time of writing, the current version of ActiveMQ is 5.3.2. You will need to add the jar activemq-all-5.3.2.jar to your classpath, e.g. by storing it in the lib/ directory. Alternatively, add the jar activemq-core-5.3.2.jar to the classpath; this requires the javax/management/j2ee classes which can be found in the Apache Geronimo jar geronimo-j2ee-management_1.0_spec-1.0.jar. The other required jars (such as commons-logging) are already included with JMeter. See http://activemq.apache.org/initial-configuration.html for details.

See the JMeter Classpath section for more details on installing additional jars.

We recommend that most users run the latest release .

To install a release build, simply unzip the zip/tar file into the directory where you want JMeter to be installed. Provided that you have a JRE/JDK correctly installed and the JAVA_HOME environment variable set, there is nothing more for you to do.

Note: there can be problems (especially with client-server mode) if the directory path contains any spaces.

The installation directory structure should look something like this (for version 2.7):

apache-jmeter-2.7
apache-jmeter-2.7/bin
apache-jmeter-2.7/docs
apache-jmeter-2.7/extras
apache-jmeter-2.7/lib/
apache-jmeter-2.7/lib/ext
apache-jmeter-2.7/lib/junit
apache-jmeter-2.7/printable_docs

You can rename the parent directory (i.e. apache-jmeter-2.7) if you want, but do not change any of the sub-directory names.

To run JMeter, run the jmeter.bat (for Windows) or jmeter (for Unix) file. These files are found in the bin directory. After a short pause, the JMeter GUI should appear.

There are some additional scripts in the bin directory that you may find useful. Windows script files (the .CMD files require Win2K or later):

• jmeter.bat - run JMeter (in GUI mode by default)
• jmeter-n.cmd - drop a JMX file on this to run a non-GUI test
• jmeter-n-r.cmd - drop a JMX file on this to run a non-GUI test remotely
• jmeter-t.cmd - drop a JMX file on this to load it in GUI mode
• jmeter-server.bat - start JMeter in server mode
• mirror-server.cmd - runs the JMeter Mirror Server in non-GUI mode
• shutdown.cmd - Run the Shutdown client to stop a non-GUI instance gracefully
• stoptest.cmd - Run the Shutdown client to stop a non-GUI instance abruptly

Note: the special name LAST can be used with jmeter-n.cmd, jmeter-t.cmd and jmeter-n-r.cmd and means the last test plan that was run interactively.

The environment variable JVM_ARGS can be used to override JVM settings in the jmeter.bat script. For example:

set JVM_ARGS="-Xms1024m -Xmx1024m -Dpropname=propvalue"
jmeter -t test.jmx ...

Un*x script files; should work on most Linux/Unix systems:

• jmeter - run JMeter (in GUI mode by default). Defines some JVM settings which may not work for all JVMs.
• jmeter-server - start JMeter in server mode (calls jmeter script with appropriate parameters)
• jmeter.sh - very basic JMeter script with no JVM options specified.
• mirror-server.sh - runs the JMeter Mirror Server in non-GUI mode
• shutdown.sh - Run the Shutdown client to stop a non-GUI instance gracefully
• stoptest.sh - Run the Shutdown client to stop a non-GUI instance abruptly

It may be necessary to edit the jmeter shell script if some of the JVM options are not supported by the JVM you are using. The JVM_ARGS environment variable can be used to override or set additional JVM options, for example:

JVM_ARGS="-Xms1024m -Xmx1024m" jmeter -t test.jmx [etc.]

will override the HEAP settings in the script.

2.4.1 JMeter's Classpath

JMeter automatically finds classes from jars in the following directories: JMETER_HOME/lib - used for utility jars JMETER_HOME/lib/ext - used for JMeter components and add-ons If you have developed new JMeter components, then you should jar them and copy the jar into JMeter's lib/ext directory. JMeter will automatically find JMeter components in any jars found here. Support jars (libraries etc) should be placed in the lib directory. If you don't want to put JMeter extension jars in the lib/ext directory, then define the property search_paths in jmeter.properties. Do not use lib/ext for utility jars; it is only intended for JMeter components. Other jars (such as JDBC, JMS implementations and any other support libaries needed by the JMeter code) should be placed in the lib directory - not the lib/ext directory Note: JMeter will only find .jar files, not .zip. You can also install utility Jar files in $JAVA_HOME/jre/lib/ext, or (since 2.1.1) you can set the property user.classpath in jmeter.properties Note that setting the CLASSPATH environment variable will have no effect. This is because JMeter is started with "java -jar", and the java command silently ignores the CLASSPATH variable, and the -classpath/-cp options when -jar is used. [This occurs with all Java programs, not just JMeter.]

2.4.2 Using a Proxy Server

If you are testing from behind a firewall/proxy server, you may need to provide JMeter with the firewall/proxy server hostname and port number. To do so, run the jmeter.bat/jmeter file from a command line with the following parameters: -H [proxy server hostname or ip address] -P [proxy server port] -N [nonproxy hosts] (e.g. *.apache.org|localhost) -u [username for proxy authentication - if required] -a [password for proxy authentication - if required] Example : jmeter -H my.proxy.server -P 8000 -u username -a password -N localhost Alternatively, you can use --proxyHost, --proxyPort, --username, and --password JMeter also has its own in-built HTTP Proxy Server , which can be used for recording HTTP or HTTPS browser sessions. This is not to be confused with the proxy settings described above, which are used when JMeter makes HTTP or HTTPS requests itself.

2.4.3 Non-GUI Mode (Command Line mode)

For non-interactive testing, you may choose to run JMeter without the GUI. To do so, use the following command options -n This specifies JMeter is to run in non-gui mode -t [name of JMX file that contains the Test Plan]. -l [name of JTL file to log sample results to]. -j [name of JMeter run log file]. -r Run the test in the servers specified by the JMeter property "remote_hosts" -R [list of remote servers] Run the test in the specified remote servers The script also lets you specify the optional firewall/proxy server information: -H [proxy server hostname or ip address] -P [proxy server port] Example : jmeter -n -t my_test.jmx -l log.jtl -H my.proxy.server -P 8000 If the property jmeterengine.stopfail.system.exit is set to true (default is false), then JMeter will invoke System.exit(1) if it cannot stop all threads. Normally this is not necessary.

2.4.4 Server Mode

For distributed testing , run JMeter in server mode on the remote node(s), and then control the server(s) from the GUI. You can also use non-GUI mode to run remote tests. To start the server(s), run jmeter-server/jmeter-server.bat on each server host. The script also lets you specify the optional firewall/proxy server information: -H [proxy server hostname or ip address] -P [proxy server port] Example : jmeter-server -H my.proxy.server -P 8000 If you want the server to exit after a single test has been run, then define the JMeter property server.exitaftertest=true. To run the test from the client in non-GUI mode, use the following command: jmeter -n -t testplan.jmx -r [-Gprop=val] [-Gglobal.properties] [-Z] where: -G is used to define JMeter properties to be set in the servers -X means exit the servers at the end of the test -Rserver1,server2 - can be used instead of -r to provide a list of servers to start Overrides remote_hosts, but does not define the property. If the property jmeterengine.remote.system.exit is set to true (default is false), then JMeter will invoke System.exit(0) after stopping RMI at the end of a test. Normally this is not necessary.

2.4.5 Overriding Properties Via The Command Line

Java system properties, JMeter properties, and logging properties can be overriden directly on the command line (instead of modifying jmeter.properties). To do so, use the following options: -D[prop_name]=[value] - defines a java system property value. -J[prop name]=[value] - defines a local JMeter property. -G[prop name]=[value] - defines a JMeter property to be sent to all remote servers. -G[propertyfile] - defines a file containing JMeter properties to be sent to all remote servers. -L[category]=[priority] - overrides a logging setting, setting a particular category to the given priority level. The -L flag can also be used without the category name to set the root logging level. Examples : jmeter -Duser.dir=/home/mstover/jmeter_stuff \ -Jremote_hosts=127.0.0.1 -Ljmeter.engine=DEBUG jmeter -LDEBUG N.B. The command line properties are processed early in startup, but after the logging system has been set up. Attempts to use the -J flag to update log_level or log_file properties will have no effect.

2.4.6 Logging and error messages

JMeter does not generally use pop-up dialog boxes for errors, as these would interfere with running tests. Nor does it report any error for a mis-spelt variable or function; instead the reference is just used as is. See Functions and Variables for more information . If JMeter detects an error during a test, a message will be written to the log file. The log file name is defined in the jmeter.properties file (or using the -j option, see below). It defaults to jmeter.log , and will be found in the directory from which JMeter was launched. Since JMeter 2.6, menu Options > Log Viewer displays the log file in a bottom pane on main JMeter window. Since JMeter 2.7 (GUI mode), the number of error/fatal messages logged in the log file is displayed at top-right. Error/fatal counter JMeter versions after 2.2 added a new command-line option, -j jmeterlogfile. This is processed after the initial properties file is read, and before any further properties are processed. It therefore allows the default of jmeter.log to be overridden. The jmeter scripts that take a test plan name as a parameter (e.g. jmeter-n.cmd) have been updated to define the log file using the test plan name, e.g. for the test plan Test27.jmx the log file is set to Test27.log. When running on Windows, the file may appear as just jmeter unless you have set Windows to show file extensions. [Which you should do anyway, to make it easier to detect viruses and other nasties that pretend to be text files...] As well as recording errors, the jmeter.log file records some information about the test run. For example: 10/17/2003 12:19:20 PM INFO - jmeter.JMeter: Version 1.9.20031002 10/17/2003 12:19:45 PM INFO - jmeter.gui.action.Load: Loading file: c:\mytestfiles\BSH.jmx 10/17/2003 12:19:52 PM INFO - jmeter.engine.StandardJMeterEngine: Running the test! 10/17/2003 12:19:52 PM INFO - jmeter.engine.StandardJMeterEngine: Starting 1 threads for group BSH. Ramp up = 1. 10/17/2003 12:19:52 PM INFO - jmeter.engine.StandardJMeterEngine: Continue on error 10/17/2003 12:19:52 PM INFO - jmeter.threads.JMeterThread: Thread BSH1-1 started 10/17/2003 12:19:52 PM INFO - jmeter.threads.JMeterThread: Thread BSH1-1 is done 10/17/2003 12:19:52 PM INFO - jmeter.engine.StandardJMeterEngine: Test has ended The log file can be helpful in determining the cause of an error, as JMeter does not interrupt a test to display an error dialogue.

2.4.7 Full list of command-line options

Invoking JMeter as "jmeter -?" will print a list of all the command-line options. These are shown below. -h, --help print usage information and exit -v, --version print the version information and exit -p, --propfile {argument} the jmeter property file to use -q, --addprop {argument} additional property file(s) -t, --testfile {argument} the jmeter test(.jmx) file to run -j, --jmeterlogfile {argument} the jmeter log file -l, --logfile {argument} the file to log samples to -n, --nongui run JMeter in nongui mode -s, --server run the JMeter server -H, --proxyHost {argument} Set a proxy server for JMeter to use -P, --proxyPort {argument} Set proxy server port for JMeter to use -u, --username {argument} Set username for proxy server that JMeter is to use -a, --password {argument} Set password for proxy server that JMeter is to use -J, --jmeterproperty {argument}={value} Define additional JMeter properties -G, --globalproperty (argument)[=(value)] Define Global properties (sent to servers) e.g. -Gport=123 or -Gglobal.properties -D, --systemproperty {argument}={value} Define additional System properties -S, --systemPropertyFile {filename} a property file to be added as System properties -L, --loglevel {argument}={value} Define loglevel: [category=]level e.g. jorphan=INFO or jmeter.util=DEBUG -r, --runremote (non-GUI only) Start remote servers (as defined by the jmeter property remote_hosts) -R, --remotestart server1,... (non-GUI only) Start these remote servers (overrides remote_hosts) -d, --homedir {argument} the jmeter home directory to use -X, --remoteexit Exit the remote servers at end of test (non-GUI) Note: the JMeter log file name is formatted as a SimpleDateFormat (applied to the current date) if it contains paired single-quotes, .e.g. 'jmeter_'yyyyMMddHHmmss'.log' If the special name LAST is used for the -t, -j or -l flags, then JMeter takes that to mean the last test plan that was run in interactive mode.

2.4.8 non-GUI shutdown

Prior to version 2.5.1, JMeter invoked System.exit() when a non-GUI test completed. This caused problems for applications that invoke JMeter directly, so JMeter no longer invokes System.exit() for a normal test completion. [Some fatal errors may still invoke System.exit()] JMeter will exit all the non-daemon threads it starts, but it is possible that some non-daemon threads may still remain; these will prevent the JVM from exitting. To detect this situation, JMeter starts a new daemon thread just before it exits. This daemon thread waits a short while; if it returns from the wait, then clearly the JVM has not been able to exit, and the thread prints a message to say why. The property jmeter.exit.check.pause can be used to override the default pause of 2000ms (2secs). If set to 0, then JMeter does not start the daemon thread.

If you wish to modify the properties with which JMeter runs you need to either modify the jmeter.properties in the /bin directory or create your own copy of the jmeter.properties and specify it in the command line.

Note: since 2.2, you can define additional JMeter properties in the file defined by the JMeter property user.properties which has the default value user.properties . The file will be automatically loaded if it is found in the current directory or if it is found in the JMeter bin directory. Similarly, system.properties is used to update system properties.

Parameters

Attribute	Description	Required
ssl.provider	You can specify the class for your SSL implementation if you don't want to use the built-in Java implementation.	No
xml.parser	You can specify an implementation as your XML parser. The default value is: org.apache.xerces.parsers.SAXParser	No
remote_hosts	Comma-delimited list of remote JMeter hosts (or host:port if required). If you are running JMeter in a distributed environment, list the machines where you have JMeter remote servers running. This will allow you to control those servers from this machine's GUI	No
not_in_menu	A list of components you do not want to see in JMeter's menus. As JMeter has more and more components added, you may wish to customize your JMeter to show only those components you are interested in. You may list their classname or their class label (the string that appears in JMeter's UI) here, and they will no longer appear in the menus.	No
search_paths	List of paths (separated by ;) that JMeter will search for JMeter add-on classes; for example additional samplers. This is in addition to any jars found in the lib/ext directory.	No
user.classpath	List of paths that JMeter will search for utility classes. This is in addition to any jars found in the lib directory.	No
user.properties	Name of file containing additional JMeter properties. These are added after the initial property file, but before the -q and -J options are processed.	No
system.properties	Name of file containing additional system properties. These are added before the -S and -D options are processed.	No

The command line options and properties files are processed in the following order:

• -p propfile
• jmeter.properties (or the file from the -p option) is then loaded
• -j logfile
• Logging is initialised
• user.properties is loaded
• system.properties is loaded
• all other command-line options are processed

See also the comments in the jmeter.properties, user.properties and system.properties files for further information on other settings you can change.