Utility Keywords Guide
Utility Keywords Guide
dateUtilities · stringUtilities · performCalculations
Three helper methods turn a short expression into a value you can use in your test. Pass an expression, get a string back.
| Method | Use it for | Example |
|---|---|---|
| dateUtilities() | Dates and times | “{DATE}” |
| stringUtilities() | Text changes and comparisons | “{STRING[TOUPPER][hi][]}” |
| performCalculations() | Math | “{MATH[2+3]}” |
| Rule of thumb
Every expression must be wrapped in { }. If anything fails, you get an empty string “” back instead of a value — your test keeps running either way. |
Expression Syntax
All three methods follow the same shape:
| {KEYWORD[arg1][arg2][arg3]…} | |
| Piece | Meaning |
| { } | Wrapper — required around every expression |
| KEYWORD | DATE, STRING, MATH, or PERFORMCALCULATIONS (not case-sensitive) |
| [arg] | Each argument in its own brackets. Empty [] means “use default” |
Return values:
| Situation | You get |
|---|---|
| Success | The resolved value as a string |
| Failure | Empty string “” |
| Boolean result | “true” or “false” |
| Whole-number math result | Integer without decimals (5 not 5.0) |
| Fractional math result | Decimal value (2.5) |
dateUtilities()
For anything date- or time-related. Three ways to use it:
| Shape | Use when |
|---|---|
| {TOKEN} | You want a common value right now (today’s date, current time, etc.) |
| {DATE[base][offset][format]} | You want full control over date, shift, and output format |
| {DATE[OPERATION][input][params]} | You want a named operation: ADDDAYS, COMPARE, FORMATDATE, etc. |
Short tokens
No brackets needed. Just wrap in { }.
| Token | What you get | Example |
|---|---|---|
| {DATE} | Today’s date | 25.05.2026 |
| {TIME} | Current time | 14:30 |
| {DATETIME} | Current timestamp | 20260525143005 |
| {DAY} | Day of month | 25 |
| {MONTH} | Month number | 5 |
| {YEAR} | Two-digit year | 26 |
| {NDAY} | Day with leading zero | 05 |
| {NMONTH} | Month with leading zero | 05 |
| {NYEAR} | Numeric year | 26 |
| {LDATE} | Long date | Monday, May 25, 2026 |
| {LDAY} | Full weekday name | Monday |
| {LMONTH} | Full month name | May |
| {LYEAR} | Locale year | 26 |
| {ADAY} | Short weekday name | Mon |
| {AMONTH} | Short month name | May |
| {MONTHFIRST} | First day of this month | 01.05.2026 |
| {MONTHLAST} | Last day of this month | 31.05.2026 |
| {QUARTERFIRST} | First day of this quarter | 01.04.2026 |
| {TRIMESTERFIRST} | First day of this trimester (4-month block) | 01.05.2026 |
| {HYEARFIRST} | First day of this half-year | 01.01.2026 |
| {TIMEZONE} | System time zone | Asia/Kolkata |
| {CURRENTTIMEZONE} | Same as {TIMEZONE} | Asia/Kolkata |
Custom date — {DATE[base][offset][format]}
Three arguments, all optional. Leave any bracket empty for default.
| Argument | Description | Default |
|---|---|---|
| base | Starting date. Accepts dd.MM.yyyy, dd.MM.yyyy HH:mm, dd.MM.yyyy HH:mm:ss, yyyy-MM-dd, or yyyyMMddHHmmss. | Today (now) |
| offset | How much to shift the base. See offset units below. Combine multiple shifts. | No shift |
| format | Output format using Java date pattern (yyyy, MM, dd, HH, mm, ss, etc.) | dd.MM.yyyy |
Offset units — sign + number + unit. Combine as many as needed.
| Unit | Meaning | Example |
|---|---|---|
| d | Days | +7d |
| w | Workdays (skips weekends) | +5w |
| M | Months (capital M!) | -1M |
| y | Years | +1y |
| h | Hours (H also works) | +12h |
| m | Minutes (lowercase m!) | +30m |
| s | Seconds | -45s |
| fff | Milliseconds | +250fff |
| Watch out: M vs m
Capital M means months. Lowercase m means minutes. This is the most common offset mistake. |
Examples:
| // Tomorrow in ISO format
tg.dateUtilities(“{DATE[][+1d][yyyy-MM-dd]}”); // 2026-05-26
// 7 days from today, default format tg.dateUtilities(“{DATE[][+7d][]}”); // 01.06.2026
// One month before a specific date tg.dateUtilities(“{DATE[25.05.2026][-1M][yyyy-MM-dd]}”); // 2026-04-25
// 5 workdays from a specific datetime tg.dateUtilities(“{DATE[25.05.2026 09:00][+5w][EEE dd MMM yyyy]}”); // -> Mon 01 Jun 2026
// Combined: +1 year, -2 months, +10 days tg.dateUtilities(“{DATE[][+1y-2M+10d][dd/MM/yyyy]}”); |
Named operations
Shape is {DATE[OPERATION][input][params]}. The input and params depend on the operation.
| Operation | Input | Params | Returns |
|---|---|---|---|
| GETCURRENTDATE | Output format | Time zone | Current date |
| GETCURRENTTIME | Output format | Time zone | Current time |
| CURRENTTIMESTAMP | Output format | Time zone | Current timestamp |
| GETCURRENTTIMEZONE | — | Time zone | Resolved zone name |
| ADDDAYS | baseDate,days | Output format | Date + days |
| SUBTRACTDAYS | baseDate,days | Output format | Date − days |
| FORMATDATE | Date value | inputFmt,outputFmt | Re-formatted date |
| COMPARE | date1,date2 | Format | EQUAL/GREATER/LESSER |
| STRINGTODATE | Date string | inputFmt,outputFmt | Re-parsed date |
Examples:
| // Today in Tokyo, ISO format
tg.dateUtilities(“{DATE[GETCURRENTDATE][yyyy-MM-dd][Asia/Tokyo]}”);
// Current time with seconds tg.dateUtilities(“{DATE[GETCURRENTTIME][HH:mm:ss][]}”);
// Timestamp for a filename tg.dateUtilities(“{DATE[CURRENTTIMESTAMP][yyyyMMdd_HHmmss][]}”);
// Add 14 days tg.dateUtilities(“{DATE[ADDDAYS][25.05.2026,14][dd-MM-yyyy]}”); // 08-06-2026
// Subtract 10 days from today (empty base = today) tg.dateUtilities(“{DATE[SUBTRACTDAYS][,10][dd.MM.yyyy]}”);
// Convert dd.MM.yyyy to yyyy/MM/dd tg.dateUtilities(“{DATE[FORMATDATE][25.05.2026][dd.MM.yyyy,yyyy/MM/dd]}”); // -> 2026/05/25
// Compare two dates tg.dateUtilities(“{DATE[COMPARE][25.05.2026,01.01.2026][]}”); // GREATER
// Parse and reformat tg.dateUtilities(“{DATE[STRINGTODATE][2026-05-25][yyyy-MM-dd,dd MMM yyyy]}”); // -> 25 May 2026 |
| Time zones
For named operations, the time zone comes from the last comma-separated piece of params. Empty or unrecognised values silently fall back to the system default zone. |
stringUtilities()
For all text operations. Format is always:
| {STRING[OPERATION][input][params]} |
All operations
| Operation | What it does | Example |
|---|---|---|
| TOUPPER | Uppercase | {STRING[TOUPPER][hi][]} -> HI |
| TOLOWER | Lowercase | {STRING[TOLOWER][HI][]} -> hi |
| TRIM | Remove leading/trailing spaces | {STRING[TRIM][ hi ][]} -> hi |
| LENGTH | Length of string | {STRING[LENGTH][TestGrid][]} -> 8 |
| CHARAT | Character at index | {STRING[CHARAT][TestGrid][4]} -> G |
| SUBSTRING | Part from start to end | {STRING[SUBSTRING][TestGrid][0,4]} -> Test |
| INDEXOF | Position of substring, or -1 | {STRING[INDEXOF][TestGrid][Grid]} -> 4 |
| STARTSWITH | Check prefix (true/false) | {STRING[STARTSWITH][a.pdf][a]} -> true |
| ENDSWITH | Check suffix (true/false) | {STRING[ENDSWITH][a.pdf][.pdf]} -> true |
| MATCHES | Match regex (true/false) | {STRING[MATCHES][abc1][[a-z]+\d+]} -> true |
| REPLACE | Replace target with replacement | {STRING[REPLACE][hi a][a,b]} -> hi b |
| SPLIT | Split by delimiter, join with spaces | {STRING[SPLIT][a-b-c][-]} -> a b c |
| CONCAT | Join comma-separated values | {STRING[CONCAT][a,b,c][]} -> abc |
| COMPARE | Equal? (case-sensitive) | {STRING[COMPARE][a,a][]} -> true |
| COMPAREIGNORECASE | Equal? (ignore case) | {STRING[COMPAREIGNORECASE][a][A]} -> true |
| COMPARE accepts two formats
Either as one comma-separated input — {STRING[COMPARE][a,b][]} — or split across two brackets — {STRING[COMPARE][a][b]}. The comma form is checked first; use the two-bracket form if your text contains commas. |
performCalculations()
For math, comparisons, logical and bitwise operations. Use either keyword:
| {MATH[<expression>]}
{PERFORMCALCULATIONS[<expression>]} |
Operators
| Category | Operators | Notes |
|---|---|---|
| Arithmetic | + – * / % | Standard math |
| Comparison | < > <= >= | Returns true/false |
| Equality | == != | Returns true/false |
| Logical | && || ! | Returns true/false |
| Bitwise | & | ^ ~ | Works on integer value |
| Shift | << >> | Works on integer value |
Order of operations
From highest priority to lowest. Use parentheses to override.
| Order | Operators |
|---|---|
| 1 (highest) | ! ~ |
| 2 | * / % |
| 3 | + – |
| 4 | << >> |
| 5 | < > <= >= |
| 6 | == != |
| 7 | & ^ | |
| 8 | && |
| 9 (lowest) | || |
Examples
| // Arithmetic
tg.performCalculations(“{MATH[2 + 3 * 4]}”); // 14 tg.performCalculations(“{MATH[(7 + 3) * 2]}”); // 20 tg.performCalculations(“{MATH[10 / 4]}”); // 2.5 tg.performCalculations(“{MATH[10 % 3]}”); // 1
// Comparison tg.performCalculations(“{MATH[5 > 3]}”); // true tg.performCalculations(“{MATH[5 == 5]}”); // true tg.performCalculations(“{MATH[3 != 4]}”); // true
// Logical tg.performCalculations(“{MATH[1 && 0]}”); // false tg.performCalculations(“{MATH[1 || 0]}”); // true tg.performCalculations(“{MATH[!0]}”); // true tg.performCalculations(“{MATH[10 > 5 && 5 > 1]}”); // true
// Bitwise & shift tg.performCalculations(“{MATH[6 & 3]}”); // 2 tg.performCalculations(“{MATH[6 | 3]}”); // 7 tg.performCalculations(“{MATH[6 ^ 3]}”); // 5 tg.performCalculations(“{MATH[~5]}”); // -6 tg.performCalculations(“{MATH[1 << 4]}”); // 16 tg.performCalculations(“{MATH[64 >> 2]}”); // 16 |
Tips
- Always wrap in { } — even short tokens like {DATE}.
- Empty brackets [] mean “use the default”. {DATE[][+1d][]} is clearer than omitting brackets.
- For custom output formats, prefer the generic {DATE[base][offset][format]} form.
- In MATCHES regex, escape backslashes at the Java string level — use \\d+ for \d+.
- If your COMPARE text contains commas, use the two-bracket form {STRING[COMPARE][a][b]} instead of comma-separated.
- Both MATH and PERFORMCALCULATIONS work in the third method — use whichever reads better.
- Add parentheses generously in math expressions — they make the order of operations explicit.
- Use standard time zone names like Asia/Kolkata, Europe/London, UTC.