3.14.6. Using functions as data for Test Cases
Prev | 3.14. Working with test data | Next

### 3.14.6. Using functions as data for Test Cases

You can calculate specific values without entering the results yourself using functions. There are specific functions that work out-of-the-box, and additional functions can be added as well.

#### 3.14.6.1. Syntax for functions

The sign used to introduce a function is the question mark: ? (without quotes).

After the sign, you must enter the name of the function followed by the arguments the function requires, e.g.:

`?add(arg1,arg2)`

The arguments are separated by commas and are placed within round brackets.

#### 3.14.6.2. Pre-defined functions

The following functions are available directly in the ITE:

Mathematical functions
The following functions give their results as decimal numbers, e.g. 1.0, 1.2 etc.

add

  Adds 0 or more numbers to 0, e.g.: ?add(1,2).

sub

  Subtracts the second number from the first: ?sub(3,2).
  This function only accepts two numbers.

mult

  Multiplies 0 or more numbers by 1 e.g.: ?mult(2,4).

div

  Divides the first number by the second: ?div(2,1).
  This function only accepts two numbers.

trunc

  Takes two arguments, the decimal to be truncated and the precision (as an integer) to truncate the decimal to. Use 0 to cut off the number to no decimal places (i.e. to receive a plain integer), and use 1 to cut off the decimal to one decimal place etc: ?trunc(2.396,0) gives 2 and ?trunc(2.789,1) gives 2.7.

round

  Takes two arguments, the decimal to be rounded and the precision (as an integer) to round to. This function uses half-up rounding to round the number so that if the final decimal place after rounding is 5 or higher, the final number will be incremented by 1 e.g.: ?round(2.56,1) gives 2.6. If the final number after rounding is 4 or less, there is no incrementation, eg. ?round(2.43,1) gives 2.4.

  | It is currently only possible to use numbers formatted with the decimal mark period or fullstop (.). Thousands separators may not be used. For example, 1.5 is accepted, but 1,5 is not. 1000 can be entered but 1,000 cannot. Entering 1.000 is equivalent to entering 1. You can use the formatNumber function to convert a number to an integer or to change the amount of decimal points a number has.

formatNumber

  Takes two arguments, the decimal to be formatted and the amount of decimal places the formatted number should contain. The numbers or decimal places will not be rounded when using this function. ?formatNumber(15.43,0) gives 15. ?formatNumber(15.4,3) gives 15.4, no zeros will be appended. ?formatNumber(15.4356,2) gives 15.43.

| Use single quotes around negative numbers, e.g. ’-0.5’.

Date functions

now

  Saves the current date in an internal format that can be used as a basis for the formatDate and modifyDate functions. This function takes no arguments: ?now().

formatDate

  Puts a date into a specific format. The date to be formatted is entered as the first argument, followed by the format string e.g. ?formatDate(?now(), dd-MM-yyyy). The formats that can used here are the formats from the SimpleDateFormat class in Java.

parseDate

  Reads a value that is a date and parses it into an internal format based on the format string given (i.e. how the date should be understood). The first argument is the date, and the second is the format string ?parseDate(2011.06.25,yyyy.MM.dd). This function should be used when reading and working with dates shown in the AUT.

modifyDate

  This function can add days (d), months (M), years (y), hours (h), minutes (i), seconds (s) and milliseconds (j) to a given date. The date must first be parsed (i.e. using parseDate) so that the correct internal format is used. This function takes two arguments: the first is the date to modify, and the second is the modification to perform, e.g. ?modifyDate(?now(),1d). Additions are entered as positive integers (but without a plus sign, e.g. 1d, 1M, 1y) and subtractions are entered as negative integers, e.g. -1d, -1M, -1y, -1i.

| If you want to use the result of a date function as a part of your test data (i.e. to enter or check), then you will most likely need to use formatDate on any date modifications you have performed.

Test functions

getNodeAttribute

  Reads the value on the node (e.g. Test Case, Test Step) on which this function is resolved, and uses this as the data for the Test Step. It has four possible arguments, name reads the name of the node, comment reads the comment on the node, description reads the raw (non-rendered) description on the node, and task.id reads the task ID on the node. If the content is empty, the value used is null. If you have overwritten either the name or the comment at this place of reuse, then these new details are used.

getCentralTestDataSetValue

  Use this function to access a value saved in a central data set. This lets you combine values that you have defined centrally with values that you use locally, or lets you combine values from different central data sets in your test. It locates a single cell in a specific central data set based on a value in a column that you define as a key, and a column in which to search for the required value. It requires four arguments: the name of the central data set to search in, the name of the column which you wish to use as a ”key” (you can name the column KEY if you require), the value in the key column (to specify the line), and the column in which the required data cell is located.

Example of the getCentralTestDataSetValue function
The function to retrieve data from a central data set can be exemplified using this example central data set, which is named Customer:

CUSTOMER_TYPE | CUSTOMER_NAME
--- | ---
NormalUser | Bob Normal
SuperUser | Alice Super
SupportUser | John Support

To select a customer name using the customer type, you should enter:

> ?getCentralTestDataSetValue
> (Customer,CUSTOMER_TYPE,SuperUser,CUSTOMER_NAME)

This will look in the central data set called Customer, locate the value SuperUser in the CUSTOMER_TYPE column, and use that line to choose the cell in the CUSTOMER_NAME column – Alice Super.

If you use this function, then it is possible to try to jump to the referenced data set using the Jump to Central Test Data Set command in the Properties or Data Set View (Section 5.5.2, “The Properties View”, Section 5.5.3, “The Data Sets View”).

Wrapped functions from other libraries
You can also use the following functions in your tests. For full documentation on them, please refer to the respective library.

randomInt(exclusive maximum value)

  Use this function to generate a random integer up to but not including the value you specify. The function is from org.apache.commons.lang.math.RandomUtils

replaceAll(string,regular expression,replacement)

  Use this function to replace all of the parts of a string you specify with something else. The string to perform the replacement on is entered as the string, the part(s) of the string to replace are defined by the regular expression, and the string to replace it with is given as the replacement. This function is from java.util.regex.

uuid()

  This function generates a universal unique identifier. The function is from java.util.UUID.

base64Encode(string)

  This function encodes a string to base 64. The function is from org.apache.commons.codec.binary.Base64.

base64Decode(string)

  This function decodes a string from base 64. The function is from org.apache.commons.codec.binary.Base64.

urlEncode(string)

  This function encodes (using UTF-8) a string for further usage within URLs.

urlDecode(string)

  This function decodes (using UTF-8) a string from a URL.

#### 3.14.6.3. Embedding functions in other functions

Functions can be added as arguments to other functions. If, for example, you want to use the result of a subtraction as the first argument of your addition, you could write it like this:

?add(?sub(2,1),1)

Results in 1.0 + 1, i.e. 2.0

#### 3.14.6.4. Useful examples for functions

Especially when it comes to the date functions, it is often necessary to use multiple functions embedded within each other.

?formatDate(?now(), dd’ MMMM ’yyyy)

  e.g. 29 February 2012

?formatDate(?now(), dd’ MMM ’yyyy)

  e.g. 29 Feb 2012

?formatDate(?now(), dd-MMM-yyyy)

  e.g. 29-Feb-2012

?formatDate(?now(), dd.MM.yyyy)

  e.g. 29.02.2012

?formatDate(?now(), dd/MM/yyyy)

  e.g. 29/02/2012

A more complex example involving embedded functions is e.g.:

> ?formatDate(?modifyDate(?parseDate
> (22.2.2012, dd.MM.yyyy),-1d),dd.MM.yy)
> This function will parse the date 22.2.2012 into an internal format, subtract one day and then format it as a dd.MM.yy, in this case: 21.2.12.

#### 3.14.6.5. Adding your own functions

You can also add your own functions using an extension point. This is described in the Developer Manual.