14. Functions

JMeter functions are special values that can populate fields of any Sampler or other configuration element in a test tree. A function looks like this:


Where "__functionName" matches the name of an existing built-in or user-defined function.

Parentheses surround the parameters sent to the function. The actual parameters vary from function to function. Functions that require no parameters can leave off the parentheses. The function itself is wrapped in ${}.

14.1 What can functions do

There are two kinds of functions: user-defined static values, and built-in functions.

User-defined static values allows the user to define variables to be replaced with their static value when a test tree is compiled and submitted to be run. This replacement happens once at the beginning of the test run. This could be used to replace the DOMAIN field of all HTTP requests, for example - making it a simple matter to change a test to target a different server with the same test.

This type of replacement is possible without functions, but was less convenient and less intuitive. It required users to create default config elements that would fill in blank values of Samplers. User-defined functions allows one to replace only part of any given value, not just filling in blank values.

With built-in functions users can compute new values at run-time based on previous response data, which thread the function is in, the time, and many other sources. These values are generated fresh for every request throughout the course of the test.

14.2 Where can functions be used?

A user-defined function can be written into any field of any test component. Some fields do not allow random strings because they are expecting numbers, and thus will not accept a function. However, most fields will allow functions.

Built-in functions can be written into any field of non-controller test components. This includes Samplers, Timers, Listeners, Modifiers, Assertions, and Config Elements.

14.3 Writing the function string

User-defined functions take the form: ${varName} . In the TestPlan tree element, a two-column table of user-defined values is kept, matching up variable names with static values. Referencing the variable in a test element is done by bracketing the variable name with '${' and '}'.

Built-in functions are written in the same manner, but by convention, the names of built-in parameters begin with "__" to avoid conflict with user value names * . Some functions take arguments to configure them, and these go in parentheses, comma-delimited. If the function takes no arguments, the parentheses can be left out. A further complication for argument values that themselves contain commas is that the value should be encoded the way HTTP parameters are encoded. JMeter provides a tool to help you construct function calls for various built-in functions, which you can then copy-paste. If your argument values do not contain commas, encoding is not required.

* If you define a user-defined static variable with the same name as a built-in function, your static variable will override the built-in function.

14.4 The Function Helper Dialog

The Function Helper dialog is available from JMeter's Tools menu.

Function Helper Dialog

Using the Function Helper, you can select a function from the pull down, and assign values for its arguments. The left column in the table provides a brief description of the argument, and the right column is where you write in the value for that argument. Different functions take different arguments.

Once you have done this, click the "generate" button, and the appropriate string is generated for you to copy-paste into your test plan wherever you like.

Copyright © 1999-2001, Apache Software Foundation