Test Data Generator - Functions

The following functions are available to generate synthetic test data. When you parameterize your tests, you can assign these functions as variable values instead of using static hard-coded values.

For related functions, see also Test Data Generator - JavaScript Methods and Test Data Generator - Seed Lists.

Content:

• Terminology Used
  1. Example: Functions
  2. Example: Variables
  3. Advanced Example
• Text Functions
• Identifier Functions
• List Functions
• Date and Time Functions
• Numerical and Mathematical Functions
• Logical Functions
• Special Functions

Terminology Used

The parameter values for Test Data Generator functions are ECMAScript 6 expressions. An expression can be numbers, text, functions, functions, or a combination of these.

Functions: A Data Generation Function accepts zero or more arguments, and returns a value. For example, the random credit card function accepts "AMEX" as argument, and returns a valid random American Express number.

Variables: After you have declared a parameter x in your test, you can reference its value elsewhere using ${x} syntax. For example, you reference a parameter named celsius as ${celsius}.

Numbers: You can use numbers and familiar mathematical operators in parameters. A plus sign between two numeric values is interpreted as an addition. For example, you can use ${celsius} + 273.15 to calculate a numeric temperature in Kelvin.

Text: Use quotation marks to define a text string. You can use plus signs to join text, numbers, function return values, and variables into one string. For example, "4"+"2" results in the string "42", which is different from the number 42 and different from the addition 4+2=6. Joining pieces of text together is called string concatenation.

Dates and Times: Provide dates and times enclosed in quotes and in ISO 8601 (UTC) format, "YYYY-MM-DD HH:mm:ss.SSS". For example, "2019-12-01 14:55:03.123".

Logical functions: Comparisons and conditions support the Boolean values true and false.

Lists: You can define lists of strings using ["jelly","bread", "peanut butter"] syntax and, similarly, you define numeric lists as [1,2,3]. Lists are used together with List Functions.

Nesting: You can nest functions and variables into one another to chain them together. For example, variables are commonly arguments to functions.

Example: Function usage

To generate values such as "Kim.Smith@acme.com" for an email variable, you join (concatenate) generator functions and strings together. The following line concatenates a random first name function, a period, a random last name function, and the static string @acme.com into an email address:

randFromSeedlist("firstnames") + "." + randFromSeedlist("lastnames") + "@acme.com"

Example: Variable usage

If you already have variables that contain part of the data, you can concatenate multiple variables. In this example, you already have the variables firstName and lastName in your Data Entity. Next, you create an email variable and define it as concatenation of the ${firstName} value, a period, the ${lastName} value, and the string "@acme.com":

randFromSeedlist("firstnames")

randFromSeedlist("lastnames")

${firstName}+"."+${lastName}+"@acme.com"

Advanced Example

You can nest functions and variables as needed to fulfill complex requirements. For example, you want to generate email addresses in all lower case, from several different domains, such as kim.kumar@myorg.org and joe.smith@acme.com.

1. Concatenate the firstName variable, a period, and the lastName variable.
   ${firstName} + "." + ${lastName}
2. Use the lower() function on the variables to ensure that the names are in lower case.
   lower(${firstName}) + "." + lower(${lastName})
3. Create a string list to store your custom domain names:
   ["acme.com","myorg.org"]
4. Use the randFromList() function to pick a random domain name from this string list.
   randFromList(["acme.com","myorg.org"])
5. Concatenate the random name, an at-sign, and the random domain.

lower(${firstName}) + "." + lower(${lastName}) + "@" + randFromList(["acme.com","myorg.org"])

Text Functions

The following video shows how to generate random text or numbers, pick a random item from a fixed list, and even generate "lorem ipsum" filler text.

length(string)

Returns the number of characters in a string.

Parameters:

• string — a string expression.

Return value: number of characters in that string

Example: length("Contrafibularity")

Example result: 16

lorem(length)

Parameters:

• length — The number of characters to be extracted from the start of the "lorem ipsum" filler text.

Return value: A truncated example sentence.

Example: lorem(8)

Example result: "Lorem ip"

loremParagraphs(number)

Parameters:

• number — The number of "Lorem ipsum" filler text paragraphs to generate. A paragraph is defined as a random selection of 4 to 8 sentences.

Return value: One or more paragraphs of filler text.

Example: loremParagraphs(1)

Example result: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed sed cursus nunc, vitae suscipit dolor."

loremSentences(number)

Parameters:

• number — The number of "lorem ipsum" filler sentences to generate. A sentence is defined as a random selection of 4 to 16 words.

Return value: One or more sentences of filler text.

Example: loremSentences(2)

Example result: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed sed cursus nunc, vitae suscipit dolor."

loremWords(number)

• number — The number of "Lorem ipsum" filler text words to generate.

Return value: One or more words of filler text.

Example: loremWords(4)

Example result: "Lorem ipsum dolor sit"

lower(string)

Return a string in lower case.

Parameters:

• string — a string expression

Return value: A lower case string

Example: lower("HELLO")

Example result: hello

randText(minLen, maxLen)

Generate random alphanumeric text of a length between the min and max.

Parameters:

• minLen — minimum length of result
• maxLen — maximum length of result

Return value: a random string

Example: randText(3,50)

Example results: wdCAKqi86EhiYdAAVu

randChars(minLen,maxLen,chars)

Generate a random string of a given length using the provided characters.

Parameters:

• minLen — minimum length of result
• maxLen — maximum length of result
• chars — the set of characters to use.

Return value: a random string

Example: randChars(1,8,"ABCDEF1234567890")

Example results: 66DEF

regExp(pattern[,flags])

Generates a random string matching a standard regular expression.

Parameters:

• pattern — the regular expression pattern describing the string to be generated.
• flags — (optional) If the flag "i" is provided, the value is generated with random upper and lower case characters.

Return value: a random pattern string

upper(string)

Upper-cases a string.

Parameters:

• string — a string expression

Return value: the upper cased string

Example: upper("hello")

Example result: HELLO

wordcap(string)

Capitalizes a string.

Parameters:

• string — a string to capitalize

Return value: a capitalized string

Example: wordcap("hello folks")

Example result: Hello Folks

Identifier Functions

addLuhn(number)

Adds a Luhn checkdigit. The Luhn algorithm or Luhn formula, also known as the "modulus 10" or "mod 10" algorithm, is a simple checksum formula used to validate a variety of identification numbers, such as credit card numbers, IMEI numbers, National Provider Identifier numbers in US, and Canadian Social Insurance Numbers.

Parameters:

• number — a number of any length.

Return value: Card number with Luhn checkdigit

Example:

• addLuhn(1234556789)

randCreditCard(issuer)

Generates a credit card of a given length that is valid for a specific issuer with a checksum using the Luhn formula.

Parameters:

• issuer — the issuer of a credit card, or
• issuer_digits — the issuer of a credit card and the number of digits to generate, separated by an underscore.

Return value: An issuer's credit card number with Luhn checkdigit

Examples:

• randCreditCard("MASTERCARD")
• randCreditCard("VISA_16")
• randCreditCard("AMEX")

The following video shows how to generate fake credit card numbers with valid checksums for various providers.

customLuhn(number, index, length[, seedvalue])

Returns a random Luhn number based on a custom set of digits. For more information, see also the addLuhn() and randCreditCard() functions.

Parameters:

• number — A custom set of digits that stays the same in each generated number.
• index — The position in the number where the additional digits are inserted to generate a Luhn number.
• length — The target length of the Luhn number.
• seedvalue — An optional seed value to control uniqueness.

Return value: a random Luhn number

Example: You want to generate a Luhn number that starts with the five digits 12345 and ends with the five digits 56789. You want the Luhn number to be 16 digits long. The length of given prefix and postfix is 5+5=10 digits. So you want to generate the remaining random 6 digits in the middle. You call the function with the following parameters customLuhn(1234556789, 5, 6).

Example Result: This function call returns the random value "1234530628656789".

luhn(length)

Returns a random number of the given length, including a check digit in the end, using the Luhn algorithm.

Parameters:

• length — The length of the number to be returned including checksum digit

Return value: a number

Example: luhn(6)

Example result: 459818

guid(collapse)
uuidGenerator()

Generates a globally unique identifier (GUID).

Parameters:

• collapse — A Boolean that specifies whether you want a GUID with dashes (false) or without dashes (true).
  Default: uuidGenerator() is equal to guid(true).

Return value: a number

Example: guid(false)

Example result: 20f087d8-72f3-107e-36fb-4259eb2dd113

Example: uuidGenerator()

Example result: 20f087d872f3107e36fb4259eb2dd113

The following video shows how to generate globally unique identifiers.

usSsnNew([delimiter])

Returns a random valid SSN number issued by the US government with the scheme used from 2011 on. The authenticity of this generated SSN cannot be validated, because of its randomization scheme.
See also usSsn().

Parameters:

• Delimiter — Optional. The default group delimiter is "-".

Example: usSsnNew()
Example Result: "787-78-1984"

Example: usSsnNew("/")
Example Result: "773/68/7008"

usSsn([areaCode],[delimiter])

Returns a random valid SSN number issued by the US government with the scheme used before 2011.
See also usSsnNew().

Parameters:

• areaCode — Optional. If no areaCode is set or if the areaCode is set to undefined, a random area code is used.
  • Valid area codes are: AK, AL, AR, AS, AZ, CA, CM, CO, CT, DC, DE, FL, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MI, MN, MO, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, RI, SC, SD, TN, TX, UT, VA, VI, VT, WA, WI, WV, WY, or undefined.
• delimiter — Optional. The default group delimiter is "-". If you want to define a delimiter and also use a random areaCode, you must set the areaCode to undefined.

Example: To get an SSN from a random region region with default delimiter: usSsn()
Example Result: "267-23-0684"

Example: To get an SSN from the Alabama region with default delimiter: usSsn("AL")
Example Result: "417-25-6640"

Example: To get an SSN from a random region with underscore as delimiter: usSsn(undefined, "_")
Example Result: "417_25_1234"

Example: To get an SSN from the Ohio region with underscore as delimiter: usSsn("OH", "_")
Example Result: "278_76_0642"

brazilianCpf(fiscalRegion?: number | string)

Generates a Brazilian CPF (Cadastro de Pessoas Físicas) code.

Parameters:

• fiscalRegion Fiscal region — (Optional) The number code or two character code of the Brazilian fiscal region.

  • Valid fiscal region numbers: 0,1,2,3,4,5,6,7,8,9

  • Valid fiscal region codes: DF,GO,MS,MT,TO,AC,AM,AP,PA,RO,RR,CE,MA,PI,AL,PB,PE,RN,BA,SE,MG,ES,RJ,SP,PR,SC,RS

Example: brazilianCpf()
Example Result: "254.444.057-09"

Example: brazilianCpf(1)
Example Result: "130.144.181-37"

Example: brazilianCpf("SP")
Example Result: "196.695.448-40"

brazilianCnpj(branchIdentifier?: number | string)

Generates a Brazilian CNPJ (Cadastro Nacional de Pessoas Jurídicas) code.

Parameters:

• branchIdentifier — A number in the range 1-9999 or a string from "0001" to "9999".

Example: brazilianCnpj()
Example Result: "09.629.491/6260-16"

Example: brazilianCnpj(1)
Example Result: "99.338.251/0001-48"

Example: brazilianCnpj("1234")
Example Result: "76.348.888/1234-67"

elfProef(number, sign)

Tests if the number fulfills the Elf-Proef formula, or finds the next or previous Elf-Proef number, according to the Dutch bank account number validation method.

Parameters:

• number — A 9- or 10-digit-long number.
• sign — The arithmetic operator, either "+" to get the next number, or "-" to get the previous number in the sequence.

Return value: the next or previous Elf-Proef number

Example: elfProef("1234567890", "+")

Example result: 1234567903

italianTaxCode(firstName: string, surname: string, dobDate: string, isFemale: boolean, townCode: string)

Returns an Italian tax code based on personal data. You can use other functions to provide missing values.

Parameters:

• firstName — Provide a first name.

• surname — Provide a surname.

• dobDate — Provide a day of birth in theformat "YYYY-MM-DD" or "YYYY-MM-DD HH:mm:ss".

• isFemale — Specify false if male, true if female.

• townCode — Provide the code of the town of birth registry as 4 alphanumeric characters.

Example: italianTaxCode("Marco", "Rossi", "1988-02-20", false, "L736")

Example Result: "RSSMRC88B20L736G"

spanishDni()

Returns a random Spanish DNI (Documento Nacional de Identidad) code.

Example: spanishDni()

Example Result: "82775595K"

List Functions

The following video shows how to generate consistent address data where the random street, postal code, state, and city match plausibly, so you could look them up on a map service.

fixedDistribution(percentage, value, ...)

Returns a value from the arguments with a guaranteed probability. This function tries to distribute the values exactly according to the probability percentages. The arguments can be a mix of types or even functions or data parameters. See also percDistribution() and randDistribution().

Parameters:

• percentage — A value between 0.0 and 1.0, where 0.0 means never and 1.0 means always.

• value values — Each argument can be a string in quotation marks, a number, a boolean, a bigint, a function, or data parameter.

Examples:

fixedDistribution(0.5, "A", 0.3, "B", 0.2, "C")

fixedDistribution(0.95,randInt(1,10), 0.03,randInt(-100,-1), 0.02, randInt(1000,100000))

mid(string, startpos, length)

Returns a substring starting from the given position, up to the end of the string.

Parameters:

• string — the original string.
• startpos — starting position of the substring to return (first character is position 1). If the start position is past the end of the string, an empty string is returned.
• length — the required length of the returned string. If zero, then an empty string is returned. Optional.

Return value: a substring

Example: mid("ABCDEFGHIJK", 2)

Example result: BCDEFGHIJK

Example: mid("ABCDEFGHIJKL", 3, 4)

Example result: CDEF

percDistribution(percentage, value, ...)

Returns a random value from the arguments with a specific probability, this means, each occurrence is weighted by its distribution percentage. The arguments can be a mix of types or even functions or data parameters. See also fixedDistribution() and randDistribution().

Parameters:

• percentage — a value between 0.0 and 1.0, where 0.0 means never and 1.0 means always.

• value values — Each argument can be a string in quotation marks, a number, a boolean, a bigint, a function, or data parameter.

Examples:

percDistribution(0.5,"A", 0.3,"B", 0.2,"C")

percDistribution(0.95,randInt(1,10), 0.03,randInt(-100,-1), 0.02,randInt(1000,100000))

percval(list)

Returns a random value from a custom list of strings with the given probability. The values cannot be data parameters or functions. See also fixedDistribution(), percDistribution() and randDistribution().

Parameters:

• list — a custom list of string values prefixed with a probability percentage. Data parameters or functions are not accepted.

Example: percval("10%ten", "20%twenty", "70%seventy")

Example result: "seventy"

randDistribution(value, ...)

Returns a random value from the given arguments. The value arguments can be a mix of types. The probability of each value is equal, 1 divided by the number of arguments. See also percDistribution() and fixedDistribution().

Parameters:

• values — Each argument can be a string in quotation marks, a number, a boolean, a bigint, a function, or data parameter.

Examples:

randDistribution(true, false)

randDistribution(1, 2, 3, 4, 5)

randDistribution(randInt(1,10),randInt(-100,-1),randInt(1000,100000))

randFromCSV(filename, column)

Returns a random row from a column of an attached CSV file.

Parameters:

• filename — The name of an attached CSV file in quotation marks.
• column — Either the name of the column (parameter name) as string, or the index of the column, starting at 1.

Examples:

• randFromCSV("address.csv", 2) -> "Berlin"
• randFromCSV("address.csv", "city") -> "Madrid"

randFromList(list[, percnull])

Returns a random value from a string list that you provide.

Parameters:

• list — a list in the format ["a","b","c"]. By default, all values are equally probable.
  • Optionally, prefix strings with a percentage to control the probability of the value being returned, using the format ["95%a","4%b","1%c"].
• percnull — Optional. Percentage of null values to be returned over a large number of calls. For example, a percnull value of 50% for an "address line 2" value means that there is a 50-50 chance of the second address line being null.
  Default: 0, this means by default it returns a non-null value every time.

Examples:

• randFromList(["one", "two", "three"])
• randFromList(["one", "two", "three"], 50) -> returns a string or null with 50% probability

randFromSeedlist(seedlistname, column, percnull)
randlov(percnull, seedlistname)

Returns a random value or name from the specified seed list.

Parameters:

• seedlistname — the name of the seed list
• column — Which column of a multi-column list. Default is 1 for single-column lists. Optional.
• percnull — Percentage of null values expected to be returned over a large number of calls. Optional.
  Example: A percnull value of 50% for an "address line 2" value means that there is a 50-50 chance of the second address line being null.
  Default: 0, this means by default it returns a non-null value every time.

Return value: A random value from the given list included in BlazeMeter.

Examples: randFromSeedlist("streetnames")

Example result: Quarry Road

The following video shows how to get real looking people names and email addresses for a test:

randFromSeedListFiltered(seedlistname, regexp [, displayColumn] [, filterColumn])

Returns a random value from the specified seedlist column and lets you filter the possible values by a regular expression.

You can filter either the column that you return (displayColumn), or in multi-column lists, you can filter by one column (filterColumn) and return values from another (displayColumn). For example, you can filter addresses by the 'state' column and then return random values from the city column, to only display cities from a certain state.

Parameters:

• seedlistname — the name of the seedlist. The function supports multi- as well as single-column lists.
• regexp — A regular expression to filter the seedlist before returning a random value from it. Enclose the expression in slashes. Wildcards and regular expression syntax are supported. For example: /a|b|c/ selects only words that contain the letters a or b or c. /^x/ selects only words that start with x. /z$/ selects only words that end with z. /\d+/ selects only numeric values.
• displayColumn — (Optional) Which column of a multi-column list should be returned. If filterColumn is not provided, the filter expression is applied to this column.

  The default column is 1.

• filterColumn — (Optional) Use this argument if you want to apply the filter to a column other than the returned column. If filterColumn is provided, the filter expression is applied to the filterColumn. If filterColumn is not provided, the filter expression is applied to the displayColumn.

Return value: A random value from the given seedlist, filtered by a regular expression.

Examples: randFromSeedlistFiltered("usaddressbig-multicol", /NV|OH/, 3, 4)

Example results: Alamo, Alledonia, Adena, ..., Las Vegas, ...

Examples: randFromSeedlistFiltered("firstnames", /^J.*/)

Example result:Jack, John, Julia, Jane

seedlist(seedlistname)

The seedlist() function returns a list containing all values from a named seedlist.
Note: You can only use this function as a parameter in another function that accepts a list. It cannot be used stand-alone.

Parameters:

• seedlistname — the name of the seed list

Return value: A random value from the given list included in BlazeMeter.

Examples: randlov(0, seedlist("lastnames"))

Example result: "Thangawelu"

valueFromCSV(fileName, column, row)

Returns a specific row from a column of an attached CSV file.

Parameters:

• fileName — The name of an attached CSV file in quotation marks.
• column — Either the name of the column (a parameter name) as a string, or the index of the column, starting at 1.
• row — The row, by default, 1.

Examples:

• valueFromCSV("address.csv", 2,7) -> "Main Street"
• valueFromCSV("address.csv", "city",8) -> "Madrid"

valueFromList(index, list)

Returns a value from a list at the given index position. The first item has index 1. When the requested index is bigger than the number of items in the list, it rolls over to the beginning of the list, or in mathematical terms, the modulo of the list length is applied to the requested index.

Parameters:

• index — a number
• list — a comma separated list surrounded by square brackets, or a list returned by the seedlist() function.

Return value: a list item

Examples:

valueFromList(2, [1, 2, 3, 4, 5]) => 2

valueFromList(8, [1, 2, 3, 4, 5]) => 3 (index rolls over)

valueFromList(2, ["first", "second", "third"]) => "second"

valueFromList(4, ["first", "second", "third"]) => "first" (index rolls over)

valueFromSeedlist(seedlistname,row,column)

Returns the value at the given row and column of a seed list. When the requested row exceeds the number of rows, it rolls over to the beginning of the seed list (or in mathematical terms, the modulo of the seed list size is applied to the requested row).

Parameters:

• seedlistname — the name of the seed list
• row — the row of the multi-column seed list. The first row is 1, and so on.
• column — (Optional) the column of the multi-column seed list. Default: 1.

Return value: a specific list item

Examples:

• valueFromSeedlist("usaddress-multicol", 2, 1)
  Returns the first column of the second row of the multi-column seed list, "511 Beacon St".
• valueFromSeedlist("femalenames", 10)
  Returns the tenth name from a single-column seed list of names, "Bonnie".
• valueFromSeedlist("femalenames", sequenceGenerator())
  Returns the next value from a single-column seed list, "Amanda" -> "Ann" -> "Anna".
• After you define, for example, a variable addressindex as randInt(1,12288), you can now use this variable to get matching values from a multi-column seed list:
  • To get address line 1, use:
    valueFromSeedlist("usaddress-multicol",${addressindex},1)
  • To get the matching city, use:
    valueFromSeedlist("usaddress-multicol",${addressindex},2)
  • To get the matching state, use:
    valueFromSeedlist("usaddress-multicol",${addressindex},3)
  • To get the matching zip code, use:
    valueFromSeedlist("usaddress-multicol",${addressindex},4)

valueOfCSV(filename, columnName[, function])

Returns values from a named column of an attached CSV file, and when it reaches the end of the column, it either loops or it uses the provided function to extend the CSV file dynamically with generated test data.

Parameters:

• fileName — The name of an attached CSV file in quotation marks.
• columnName — The name of the column (a parameter name) as a string.
• function — A test data generator function with its required arguments. If no function is supplied, the function loops the column content again starting from row 1.

Examples:

• valueOfCSV("data.csv", "firstName", randText(3,10) )
  If the column "firstName" of the file "data.csv" has 3 rows and you generate 5 rows, you receive the following test data:

  John
  Peter
  Jill
  qfsdfsd
  rroiwopr

• valueOfCSV("data.csv", "firstName")
  If the column "firstName" of the file "data.csv" has 3 rows and you generate 5 rows, you receive the following test data:

  John
  Peter
  Jill
  John
  Peter

valueOfCSVByColumn(filename, columnIndex, function)

Returns values from a column of an attached CSV file, and when it reaches the end of the column, it uses the provided function to extend the CSV file dynamically with generated test data.

Parameters:

• fileName — The name of an attached CSV file in quotation marks.
• columnIndex — The index of the column, starting at 1.
• function — A test data generator function with its required arguments.

Examples:

• valueOfCSVByColumn("users.csv", 2, randText(3, 10))
  If the second column of users.csv contains 3 rows of last names, and you generate 5 rows, you receive the following test data:

Einstein
Goodall
Curie
sldfxh
aldjbvqml

Date and Time Functions

The following video shows how to generate relative dates such as today, tomorrow, yesterday, or a random date within the last three months.

addDays(date, days)

Adds a number of days to a date, or subtracts them, if it is a negative number.

Parameters:

• date — A date in ISO 8601 (UTC) format
• days — the number of days to add. Can be a positive or negative number.

Return value: The new date in ISO 8601 (UTC) format. By default, YYYY-MM-DD.

Examples:

addDays("2012-06-05",2) --> 2012-06-07

datetime( addDays("2012-06-05",2) , "MM/DD/yyyy") --> 06/07/2012

addMillisecs(timestamp, milliseconds)

Adds a number of milliseconds to a timestamp in ISO 8601 (UTC) format, or subtracts them, if it is a negative number.

Parameters:

• timestamp — A date string in ISO 8601 (UTC) format.
• milliseconds — The number of milliseconds to add. Can be a positive or negative number.

Return value: The new timestamp in the format "YYYY-MM-DD HH:mm:ss.SSS".

Examples:

addMillisecs("2016-11-23 03:36:20.000",136) --> 2016-11-23 03:36:20.136

datetime( addMillisecs("2016-11-23 03:36:20.000",136) , "MM/DD/yyyy HH:mm:ss.SSS") --> 11/23/2016 03:36:20.136

addMonths(date, months)

Adds a number of months to a date in ISO 8601 (UTC) format, or subtracts them, if it is a negative number.

Parameters:

• date — A date string in ISO 8601 (UTC) format.
• months — The number of months to add. Can be a positive or negative number.

Return value: a new date in ISO 8601 (UTC) format.

Examples:

addMonths("2020-05-22",3) --> 2020-08-22

datetime( addMonths("2020-05-22",3) , "MM/DD/yyyy") --> 08/22/2020

addRandDays(date, min, max)

Adds a random number of days between the min and max to the date. If max is less than min, the value returned is the date plus the min minus 1.

Parameters:

• date — a date string in ISO 8601 (UTC) format
• min — minimum number of days to add
• max — maximum number of days to add

Return value: a new date in format "YYYY-MM-DD".

Examples:

addRandDays("1977-04-13",3,10) --> 1977-04-22

datetime( addRandDays("1977-04-13",3,10) , "MM/DD/yyyy" ) --> 04/22/1977

addRandDays( parseDate("04/13/1977","MM/DD/yyyy"), 3, 10) --> 1977-04-22

addSecondsToDateTime(datetime, seconds)

Adds a number of seconds to a datetime value, or subtracts them if it is a negative number.

Parameters:

• datetime — a date time string in ISO 8601 (UTC) format
• seconds — number of seconds to add. Can be a positive or negative number.

Return value: a new datetime in "YYYY-MM-DD HH:mm:ss.SSS" format.

Examples:

addSecondsToDateTime("2008-07-22 00:00:00",1) --> 2008-07-22 00:00:01.000

datetime( addSecondsToDateTime("2008-07-22 00:00:00",1) , "MM/DD/yyyy HH:mm:ss") --> 07/22/2008 00:00:01

addSecondsToTime(time, seconds)

Adds a number of seconds to a time, or subtracts them if it is a negative number.

Parameters:

• time — a time string in ISO 8601 (UTC) format
• seconds — the number of seconds to add. Can be a positive or negative number.

Return value: the new time

Example: addSecondsToTime("01:02:00",1) --> 01:02:01

addYears(date, years)

Adds a number of years to a date, or subtracts them if it is a negative number.

Parameters:

• date — a date string in ISO 8601 (UTC) format
• years — the number of years to add. Can be a positive or negative number.

Return value: a new date in "YYYY-MM-DD” format.

Examples:

addYears("2008-07-15", 1) --> 2009-07-15

datetime( addYears("2008-07-15", 1), "MM/DD/yyyy") --> 07/15/2009

addYears( parseDate("07/15/2008", "MM/DD/yyyy"), 1) --> 2009-07-15

date(string [, format])
parseDate(string [, format])

Converts a date string from a custom format to the standard ISO 8601 (UTC) format. If no format is defined, the input is interpreted as standard ISO 8601.

Parameters:

• string — A custom date string
  Examples: "31/01/1999", "01-31-1999", or "310199".
• format — (Optional) The input date format.
  Examples: "DD/MM/YYYY", "MM-DD-YYYY", or "DDMMYY"
  Default: "YYYY-MM-DD HH:mm:ss.SSS"

Return value: The standardized datetime string

Examples:

parseDate("2018-05-18") -> "2018-05-18 00:00:00.000"

parseDate("2018-05-18 09:23:22.123") -> "2018-05-18 09:23:22.123"

parseDate("18/05/2018", "DD/MM/YYYY") -> "2018-12-26 00:00:00.000"

parseDate("18/05/2018 09-23-22", "DD/MM/YYYY HH-mm-ss") -> "2018-12-26 09:23:22.000"

datetime(string, format)

Converts a datetime string from the standard ISO 8601 (UTC) format to a custom format.

Parameters:

• string — An input string in standard ISO 8601 (UTC) format.
  YYYY-MM-DD HH:mm:ss.SSS or YYYY-MM-DD
• format — The target datetime format.

Return value: The custom datetime string

Examples:

datetime("2018-11-19") -> "2018-11-19 00:00:00.000"
datetime("2018-11-19 12:13:14.567") -> "2018-11-19 12:13:14.567"
datetime("2018-11-19 12:13:14.567", "DD/MM/YYYY") -> "19/11/2018"
datetime("2018-11-19 12:13:14.567", "HH:mm:ss") -> "12:13:14"
datetime("2018-11-19 12:13:14.567", "DD/MM/YYYY HH:mm:ss.SSS") -> "19/11/2018 12:13:14.567"

daysAfter(startdate, enddate)

Returns the difference in days between the end date and the start date.

Parameters:

• startdate — starting date in ISO 8601 (UTC) format
• enddate — ending date in ISO 8601 (UTC) format

Return value: The number of days between start and end.

Examples:

daysAfter( "2009-10-26","2009-10-31" ) --> 5

daysAfter( parseDate( "10/26/2009","MM/DD/yyyy"), parseDate("10/31/2009","MM/DD/yyyy") ) --> 5

dateOfBirth(minage, maxage, date)
dob(minage, maxage, date)

Returns a date of birth for someone who will be between a given minimum and maximum age on the specified date. Use this function together with now() to generate a birthdate of a person who is older or younger than a cut-off date on the day when the test runs.

Parameters:

• minage — minimum age
• maxage — maximum age
• date — A random age value between minage and maxage is subtracted from this date.

Return value: a date of birth in ”YYYY-MM-DD” format

Example: A birthdate of someone who was between 4 and 99 years old on December 8, 1901:
dateOfBirth(4,99,"1901-12-08") --> 1861-09-18

Example: A birthdate of someone who was between 18 and 60 years old today:
dateOfBirth(18, 60, now()) --> 1994-04-17

Example: A birthdate of someone who was between 20 and 100 years old on March 2, 1990, in month/day/year format:
datetime(dateOfBirth(20, 100, "1990-03-02"), "MM/DD/yyyy") --> 02/12/1947

dayOfWeek(date)
dow(date)

Returns the day of the week for the date specified.

Parameters:

• date — a date in ISO 8601 (UTC) format

Return value: a number representing a day of the week. Returns 1 for Sunday, 2 for Monday, 3 for Tuesday, 4 for Wednesday, 5 for Thursday, 6 for Friday, 7 for Saturday.

Example: dayOfWeek("1972-09-14") --> 5

lastDay(date)

Returns the last day of the month that the specified date is in.

Parameters:

• date — A date in ISO 8601 (UTC) format.

Return value: The date of the last day of the month in which the date resides.

Examples:

lastDay("2054-04-12") --> 2054-04-30, because the last day of April is the 30th

datetime( lastDay("2054-04-12") , "MM/DD/yyyy") --> 04/30/2054

randDate(min, max)

Returns a random date between the minimum and maximum values.

Parameters:

• min — minimum date in ISO 8601 (UTC) format
• max — maximum date in ISO 8601 (UTC) format

Return value: A random date in datetime format

Examples:

randDate("2009-01-01","2010-01-01") --> 2009-12-07 11:10:09.123

datetime( randDate("2009-01-01","2010-01-01") , "MM/DD/yyyy") --> 12/07/2009

randTime(min, max)

Returns a random time between a min and max.

Parameters:

• min — minimum time allowed in HH:mm:ss format
• max — maximum time allowed in HH:mm:ss format

Return value: A random time

Example: randTime("00:00:00","23:59:59") --> 12:34:01

secondsAfter(startdatetime, enddatetime)

Return the number of seconds between a start and end datetime or time.

Parameters:

• startdatetime — start time or datetime in ISO 8601 (UTC) format
• enddatetime — end time datetime in ISO 8601 (UTC) format

Return value: The number of seconds between those datetimes.

Example: secondsAfter("2008-10-26 01:30:56","2008-11-26 01:30:59") --> 2678403

time(datetime)

Returns the time portion of a datetime in ISO 8601 (UTC) format.

Parameters:

• datetime — a datetime in one of a number of formats.

Return value: the time part of the datetime.

Example: time("2008-02-26 12:23:22") -->12:23:22

now([offset])

Returns the current date and time in a given timezone.

Parameters:

• offset — (Optional) Named timezone ("Europe/Prague"), or a numeric hour and minute offset from UTC. The numeric offset can be positive or negative, for example, "+01:00" or "-02:00".
  Default: UTC

Return value: current date and time in UTC or the specified timezone

Example:

now() --> 2008-02-26 12:23:22.255

now("Europe/Prague") -->2008-02-26 14:23:22.255

now("+01:00") --> 2008-02-26 13:23:22.255

datetime( now() , "MM/DD/yyyy") --> 02/26/2008

Numerical and Mathematical Functions

abs(number)

Returns the absolute value of the argument.

Parameters:

• number — an integer or floating point number.

Return value: An absolute value

Example: abs(-23)

Example result: 23

add(number1, number2)

Adds two values together, or subtracts a negative value.

Parameters:

• Two expressions evaluating to integer or floating point numbers.

Return value: The sum of the two numbers.

Example: add(1,1)

Example result: 2

Example: add(10,-1)

Example result: 9

addRand(number, min, max)

Adds a random number between a specified minimum and maximum to a number. If max is less than min, the value returned is number plus min, minus 1.

Parameters:

• number — a long integer number
• min — minimum value for a random number
• max — maximum value for a random number

Return value: a new number

Example: addRand(1,1,5)

Example results: 3

convBase(number, base)

Converts the number to a different base.

Parameters:

• number — a decimal number
• base — the new base to convert to

Return value: a new number in the requested base

Example: convBase(999,16)

Example result: 3E7

divide(number1, number2)

Divides the first number by the second. The function expects integer or floating point numbers.

Parameters:

• number1 — dividend
• number2 — divisor

Return value: the quotient

Example: divide(6,3)

Example result: 2

exp(number, power)

Raises the specified number to a power.

Parameters:

• number — an integer or floating point number,
• power — an integer or floating point number.

Return value: the specified number raised to the power

Example: exp(10,2)

Example result: 100

mod(number1, number2)

Returns the modulo of two numbers. This is the remainder of the first number divided by the second number.

Parameters:

• number1 and number2 — numeric expressions

Return value: the remainder of number1 divided by number2

Example: mod(5,2)

Example result: 1

multiply(number1, number2)

Multiplies the two numbers.

Parameters:

• number1 and number2 — numeric expressions

Return value: value of number1 multiplied by number2

Example: multiply(2,3)

Example result: 6

randDigits(minlen, maxlen)

Returns a random string of digits of a length between minlen and maxlen.

Parameters:

• minlen — minimum length of the resulting string
• maxlen — maximum length of the resulting string

Return value: String of digits

Example: randDigits(3,10)

Example result: 2103

randInt(min, max[, width])
randRange(min, max[, width])

Returns a random integer within the of min and max values.

Parameters:

• min — minimum number generated
• max — maximum number generated
• width — (Optional) The value is zero-padded up to this width.

Return value: A random integer

Example: randRange(1,2),

Example result: 1

Example: randRange(100,1000,8),

Example result: 00000234

sequenceGenerator(number)

Generates a new sequential number for each iteration of the test. The number sequence begins with the number provided as an argument for this function. The number parameter is optional, the default start value is 1.

Example: sequenceGenerator(10) returns 10 for the first iteration, 11 for the second iteration, and so on.

Logical Functions

A Boolean expression consists of one of the following:

• An expression in the format <operand1> <operator> [<operand2>] that evaluates to true or false.
• The Boolean constants true or false (case sensitive).

Type of operands: An operand can be any string, Boolean, or numeric expression made of constants or variables.

Comparability of operands: All operators work with both numbers and strings. If the operands are strings, then a lexicographic comparison is made, for example, A is less than Z. If the operands are floating point numbers, then tests for equality are done within a fixed precision of 1.0e-10, because floating point numbers do not have a guaranteed accuracy.

Examples:

• ifCondition( ${age}>=18 , "adult" , "child")
  Returns either "adult" or "child", depending on the value of the variable ${age}.
• (${age}>=18) ? "adult" : "child"
  Returns either "adult" or "child", depending on the value of the variable ${age}.
  Note: This ternary operator is a syntax variant of the ifCondition() function.
• booleanCompare(200, 201, ">")
  Returns false.
• booleanCompare(a, c, ">")
  Returns true.

Special Functions

valueFromJson( url [, jsonpath [, index]] [, options] )

Returns a json object from the remote URL. Use this to get dynamic lists of custom values from a public endpoint, for example, custom items from a menu. Typically, you do not use the whole json object, but you provide an expression and an index to get a specific element from the json object.

Parameters:

• url — Defines the URL where the dynamic JSON data is publicly accessible for download.
• jsonpath — (Optional) Returns a specific array from the downloaded json object.
  For more information about JsonPath syntax, see https://goessner.net/articles/JsonPath/.
  Example: "$.store.book[0].title"
• index — (Optional) Defines a numeric index in the array. Use the index together with the JsonPath to return an array element. The array starts counting at one.
• options — (optional) Defines authentication information and headers, for example:

  {
      auth:    { user: string, pass: string },
      headers: { header_name: "header_value" }
  }

Examples

• valueFromJson("http://mydomain.net/jsondata.json")
  Returns an object that contains all downloaded json data, with no authentication.
• valueFromJson("http://www.domain.net/jsondata.json", {auth: {username: "john", password: "secret"}})
  Returns an object that contains all downloaded json data, using basic authentication.
• valueFromJson("http://www.domain.net/jsondata.json", {auth: {type: "digest", username: "john", password: "secret"}})
  Returns an object that contains all downloaded json data, using digest authentication.
• valueFromJson("http://mydomain.net/jsondata.json", "$.books[*].name")
  Evaluates the jsonPath expression and returns subset as an array, for example, ["War and Peace", "Invisible Man"].
• valueFromJson("http://mydomain.net/jsondata.json", "$.books[*].name", 1)
  Returns the array element found at the given JsonPath and index, for example, "War and Peace".

• valueFromJson("http://www.domain.net/jsondata.json", {headers: {"X-csrf-token": "123"}})
  Additionally includes a custom header.