1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106  \index{Functions} \index{Parameter!Function} You can calculate specific values without to enter the results yourself using \bxname{functions}. There are specific functions that work out-of-the-box, and additional functions can be added as well. \subsubsection{Syntax for functions} \index{Functions!Syntax} The sign used to introduce a function is the question mark: \bxshell{?} (without quotes). After the sign, you must enter the name of the function followed by the arguments the function requires, e.g.: \verb+?add(arg1,arg2)+ The arguments are separated by commas and are placed within round brackets. \subsubsection{Pre-defined functions} The following functions are available directly in the \ite{}: \textbf{Mathematical functions}\\ The following functions give their results as decimal numbers, e.g. 1.0, 1.2 etc. \begin{description} \item [add]{Adds 0 or more numbers to 0, e.g.: \bxshell{?add(1,2)}.} \item [sub]{Subtracts the second number from the first: \bxshell{?sub(3,2)}. \\This function only accepts two numbers.} \item [mult]{Multiplies 0 or more numbers by 1 e.g.: \bxshell{?mult(2,4)}.} \item [div]{Divides the first number by the second: \bxshell{?div(2,1)}. \\This function only accepts two numbers.} \item [trunc]{Takes two arguments, the decimal to be truncated and the precision (as an integer) to truncate the decimal to. Use \bxshell{0} to cut off the number to no decimal places (i.e. to receive a plain integer), and use \bxshell{1} to cut off the decimal to one decimal place etc: \bxshell{?trunc(2.396,0)} gives \bxshell{2} and \bxshell{?trunc(2.789,1) gives \bxshell{2.7}}.} \item [round]{Takes two arguments, the decimal to be rounded and the precision (as an integer) to round to. This function uses \bxname{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.: \bxshell{?round(2.56,1)} gives \bxshell{2.6}. If the final number after rounding is 4 or less, there is no incrementation, eg. \bxshell{?round(2.43,1)} gives \bxshell{2.4}. } \bxwarn{It is currently only possible to use numbers formatted with the decimal mark \bxname{period} or \bxname{fullstop} (\bxshell{.}). Thousands separators may not be used. For example, \bxshell{1.5} is accepted, but \bxshell{1,5} is not. \bxshell{1000} can be entered but \bxshell{1,000} cannot. Entering \bxshell{1.000} is equivalent to entering \bxshell{1}.} \end{description} \bxtipp{Use single quotes around negative numbers, e.g. '-0.5'.} \textbf{Date functions}\\ \begin{description} \item [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: \bxshell{?now()}.} \item [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. \bxshell{?formatDate(?now(), dd-MM-yyyy)}. The formats that can used here are the formats from the SimpleDateFormat class in Java.} \item [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 \bxshell{?parseDate(2011.06.25,yyyy.MM.dd)}. This function should be used when reading and working with dates shown in the \gdaut{}. } \item [modifyDate]{This function can add days (d), months (M), and years (y) 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. \bxshell{?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.} \end{description} \bxtipp{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.} \textbf{Test functions}\\ \begin{description} \item [getNodeAttribute]{Reads the value on the node (e.g. \gdcase{}, \gdstep{}) on which this function is resolved, and uses this as the data for the \gdstep{}. It has two possible arguments, \bxname{name} reads the name of the node, and \bxname{comment} reads the comment on the node. If the comment is empty, the value used is \bxname{null}. If you have overwritten either the name or the comment at this place of reuse, then these new details are used.} \item [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.} \end{description} \textbf{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 \bxname{Customer}: \tablehead{\hline\textbf{CUSTOMER\_TYPE}&\textbf{CUSTOMER\_NAME}\\\hline} \begin{supertabular}{|p{6.0cm}p{6.0cm}|} \hline NormalUser & Bob Normal\\ \hline SuperUser & Alice Super\\ \hline SupportUser & John Support \\ \hline \end{supertabular} To select a customer name using the customer type, you should enter: \begin{quote} \textbf{?getCentralTestDataSetValue\\ (Customer,CUSTOMER\_TYPE,SuperUser,CUSTOMER\_NAME)} \end{quote} This will look in the central data set called \bxname{Customer}, locate the value \bxname{SuperUser} in the \bxname{CUSTOMER\_TYPE} column, and use that line to choose the cell in the \bxname{CUSTOMER\_NAME} column -- Alice Super. \textbf{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. \begin{description} \item [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 \bxname{org.apache.commons.lang.math.RandomUtils}} \item [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 \bxname{string}, the part(s) of the string to replace are defined by the \bxname{regular expression}, and the string to replace it with is given as the \bxname{replacement}. This function is from \bxname{java.util.regex}.} \item [uuid()]{This function generates a universal unique identifier. The function is from \bxname{java.util.UUID}.} \item [base64Encode(string)]{This function encodes a string to base 64. The function is from \bxname{org.apache.commons.codec.binary.Base64}.} \item [base64Decode(string)]{This function decodes a string from base 64. The function is from \bxname{org.apache.commons.codec.binary.Base64}.} \end{description} \subsubsection{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:\\ \bxshell{?add(?sub(2,1),1)}\\ Results in \bxshell{1.0 + 1}, i.e. \bxshell{1.0}\\ \subsubsection{Useful examples for functions} Especially when it comes to the date functions, it is often necessary to use multiple functions embedded within each other. \begin{description} \item [?formatDate(?now(), dd' MMMM 'yyyy)]{e.g. 29 February 2012} \item [?formatDate(?now(), dd' MMM 'yyyy)]{e.g. 29 Feb 2012} \item [?formatDate(?now(), dd-MMM-yyyy)]{e.g. 29-Feb-2012} \item [?formatDate(?now(), dd.MM.yyyy)]{e.g. 29.02.2012} \item [?formatDate(?now(), dd/MM/yyyy)]{e.g. 29/02/2012} \end{description} A more complex example involving embedded functions is e.g.: \begin{quote} \textbf{?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. \end{quote} \subsubsection{Adding your own functions} You can also add your own functions using an extension point. This is described in the Extension Manual.