JMeter __StringFromFile function reference: syntax, parameters, and practical examples for parameterizing test plans with dynamic values.
Also documented in context in the full Functions and Variables reference.
The StringFromFile function can be used to read strings from a text file. This is useful for running tests that require lots of variable data. For example when testing a banking application, 100s or 1000s of different account numbers might be required.
See also the CSV Data Set Config test element which may be easier to use. However, that does not currently support multiple input files.
Each time it is called it reads the next line from the file. All threads share the same instance, so different threads will get different lines. When the end of the file is reached, it will start reading again from the beginning, unless the maximum loop count has been reached. If there are multiple references to the function in a test script, each will open the file independently, even if the file names are the same. [If the value is to be used again elsewhere, use different variable names for each function call.]
If an error occurs opening or reading the file, then the function returns the string “**ERR**”
| Name | Required | Description |
|---|---|---|
| File Name | Yes | Path to the file name. (The path can be relative to the JMeter launch directory) If using optional sequence numbers, the path name should be suitable for passing to DecimalFormat. See below for examples. |
| Variable Name | No | A reference name - refName - for reusing the value created by this function. Stored values are of the form \${refName}. Defaults to “StringFromFile_”. |
| Start sequence number | No | Initial Sequence number (if omitted, the End sequence number is treated as a loop count) |
| End sequence number | No | Final sequence number (if omitted, sequence numbers can increase without limit) |
The file name parameter is resolved when the file is opened or re-opened.
The reference name parameter (if supplied) is resolved every time the function is executed.
Using sequence numbers:
When using the optional sequence numbers, the path name is used as the format string for java.text.DecimalFormat.
The current sequence number is passed in as the only parameter.
If the optional start number is not specified, the path name is used as is.
Useful formatting sequences are:
#
: insert the number, with no leading zeros or spaces
000
: insert the number packed out to three digits with leading zeros if necessary
Usage of format strings
Section titled “Usage of format strings”Here are a few format strings and the corresponding sequences they will generate.
pin#'.'dat
: Will generate the digits without leading zeros and treat the dot literally like
pin1.dat, …, pin9.dat, pin10.dat, …, pin9999.dat
pin000'.'dat
: Will generate leading zeros while keeping the dot. When the numbers start having more digits
then those three digits that this format suggests, the sequence will use more digits as can be seen in
pin001.dat, … pin099.dat, …, pin999.dat, …, pin9999.dat
pin'.'dat#
: Will append digits without leading zeros while keeping the dot and generate
pin.dat1, …, pin.dat9, …, pin.dat999
If more digits are required than there are formatting characters, the number will be expanded as necessary.
To prevent a formatting character from being interpreted,
enclose it in single quotes. Note that “.” is a formatting character,
and must be enclosed in single quotes
(though #. and 000. work as expected in locales where the decimal point is also “.”)
In other locales (e.g. fr), the decimal point is “,” - which means that “#.”
becomes “nnn,”.
See the documentation for DecimalFormat for full details.
If the path name does not contain any special formatting characters, the current sequence number will be appended to the name, otherwise the number will be inserted according to the formatting instructions.
If the start sequence number is omitted, and the end sequence number is specified,
the sequence number is interpreted as a loop count, and the file will be used at most “end” times.
In this case the filename is not formatted.
\${__StringFromFile(PIN#'.'DAT,,1,2)} - reads PIN1.DAT, PIN2.DAT
\${__StringFromFile(PIN.DAT,,,2)} - reads PIN.DAT twice
Note that the “.” in PIN.DAT above should not be quoted.
In this case the start number is omitted, so the file name is used exactly as is.