Date/Time Plugin

The plugin provides functionality to generate, modify and validate date/time.

Installation

Example 1. build.gradle
implementation(group: 'org.vividus', name: 'vividus-plugin-datetime', version: '0.3.0')

Properties

Required

There are no required properties for the plugin.

Optional

location.zone-id - Defines time zone which will be used. The default is set to a system default timezone. Time zone format

Expressions

The expression parameters marked with bold are mandatory.

generateDate

Generates the date using current date as a baseline.

 #{generateDate($period, $outputFormat)}

Let’s imagine the current date is 2020-11-23 and the time is 00:10:01. Here is a set of examples with the results and comments.

Table 1. Examples of the expressions generating dates
Expression Result Comment

#{generateDate(P)}

2020-11-23

Current date.

#{generateDate(P1DT2h)}

2020-11-24T02:10:01

Current date +1 day and +2 hours

#{generateDate(-P1D}

2020-11-23

Current date -1 day

#{generateDate(P1M)}

2020-12-23

Current date + 1 month

#{generateDate(-PT10M)}

2020-11-23T00:00:01

Current date time -10 mins

#{generateDate(P, yyyy-MM)}

2020-11

Current date with the custom output format

#{generateDate(P, MM/dd/yyyy)}

11/23/2020

Current date with a custom format

#{generateDate(P1D, yy-MM-dd)}

20-11-24

Current date +1 day with the custom output format

#{generateDate(P, yyyy-MM-dd’T’HH:mm:ssZ)}

2020-11-23’T'00:10:01+0300

Current date with the custom output format including time zone offset

formatDate

Formats the input date to another format. Additionally, time zone can be changed in the output result.

#{formatDate($inputDate, $outputFormat, $outputTimeZone)}

  • $inputDate - the date to be formatted, it should be presented in the ISO-8601 format

  • $outputFormat - the outut format based on the date/time format

  • $outputTimeZone - the time zone for the output result

Table 2. Examples of the expressions formatting dates
Expression Result

#{formatDate(2017-01-13T09:00:42.862Z, yyyy-MM-dd’T’HH:mm:ss.SSS)}

2017-01-13T09:00:42.862

#{formatDate(2017-01-13T09:00:42.862-05:00, yyyy-MM-dd’T’HH:mm:ss.SSS)}

2017-01-13T09:00:42.862

#{formatDate(2017-01-13T09:00:42.862-0500, yyyy-MM-dd’T’HH:mm:ss.SSS)}

Throw exception

#{formatDate(2017-01-13T09:00:42.862, yyyy-MM-dd’T’HH:mm:ss)}

2017-01-13T09:00:42

#{formatDate(2017-01-13T09:00:42.862Z, yyyy-MM-dd’T’HH:mm:ss)}

2017-01-13T09:00:42+0000

#{formatDate(2017-01-13T09:00:42.862Z, yyyy-MM-dd’T’HH:mm:ssZ)}

2017-01-13T09:00:42-05:00

#{formatDate(2017-01-13T09:00:42.862Z, yyyy-MM-dd)}

2017-01-13

#{formatDate(2017-01-13T09:00:42.862Z, yyyy-MM-dd’T’HH:mm:ss.SSSZ, -05:00)}

2017-01-13T04:00:42.862-0500

#{formatDate(2017-01-13T04:00:42.862-05:00, yyyy-MM-dd’T’HH:mm:ss.SSSZ, GMT)}

2017-01-13T09:00:42.862+0000

#{formatDate(2017-01-13T09:00:42.862Z, yyyy-MM-dd’T’HH:mm:ss.SSSZ, America/New_York)}

2017-01-13T04:00:42.862-0500

#{formatDate(2017:01:13T09:00:42.862Z, yyyy-MM-dd’T’HH:mm:ss.SSS)}

Error: invalid input data

#{formatDate(2017-01-13T09:00:42.862Z, BBByyyy-MM-dd’T’HH:mm:ss.SSS)}

Error: invalid output format

#{formatDate(2017-01-13T09:00:42.862Z, yyyy-MM-dd’T’HH:mm:ss.SSS, ABCD)}

Error: invalid output timezone

formatDateTo

Formats the input date to the desired format. The format of the input date should be provided in the second parameter.

#{formatDateTo($inputDate, $inputFormat, $outputFormat)}

  • $inputDate - the date to be formatted, it can be in any format but this format should be described in the second parameter

  • $inputFormat - the input date format based on the date/time format

  • $outputFormat - the output date format based on the date/time format

Since parameters of the expression comma-separated, meaningful commas (like, parts of the date format pattern) should be escaped using \.
Table 3. Examples of the expressions formatting dates with the custom input format
Expression Result

#{formatDateTo("2017-03-31T07:20:43.808Z", "yyyy-MM-dd’T’HH:mm:ss.SSSVV", EEE\, dd MMM yyyy HH:mm:ss ZZZZ)}

Fri, 31 Mar 2017 07:20:43 GMT

#{formatDateTo(Fri\, 31 Mar 2017 07:20:43 GMT, EEE\, dd MMM yyyy HH:mm:ss zzz, yyyy-MM-dd’T’HH:mm:ss)}

2017-03-31T07:20:43

shiftDate

Shifts the given input date for a given period in any direction (+/-).

#{shiftDate($inputDate, $inputFormat, $period)}

  • $inputDate - the date to be shifted, it can be in any format but this format should be described in the second parameter

  • $inputFormat - the input date format based on the date/time format

  • $period - the period by which the date will be shifted, it should be written in ISO-8601

Since parameters of the expression comma-separated, meaningful commas (like, parts of the date format pattern) should be escaped using \.
Table 4. Examples of the expressions shifting dates
Expression Result

#{shiftDate(2019-03-19 03:40:00, yyyy-MM-dd HH:mm:ss, -P1Y)}

2018-03-19 01:40:00

#{shiftDate(Wed\, 10 Apr 2019 07:20:43 GMT, EEE\, dd MMM yyyy HH:mm:ss zzz, P1MT2H)}

Fri, 10 May 2019 09:20:43 GMT

#{shiftDate("Wed\, 10 Apr\, 2019\, 07:20:43 GMT", "EEE\, dd MMM\, yyyy\, HH:mm:ss zzz", P1MT2H)}

"Fri, 10 May, 2019, 09:20:43 GMT"

diffDate

Calculates the difference between two dates with given formats and returns result as ISO-8601 period.

#{diffDate($inputDate1, $inputDate1Format, $inputDate2, $inputDate2Format)}

  • $inputDate1 - the first input date, it can be in any format but this format should be described in the second parameter

  • $inputDate1Format - the first input date format based on the date/time format

  • $inputDate2 - the second input date, it can be in any format but this format should be described in the second parameter

  • $inputDate2Format - the second input date format based on the date/time format

Since parameters of the expression comma-separated, meaningful commas (like, parts of the date format pattern) should be escaped using \.
Table 5. Examples of the expressions calculating dates difference
Expression Result

#{diffDate(2019-03-19 03:40:00, yyyy-MM-dd HH:mm:ss, 2019-03-19 03:40, yyyy-MM-dd HH:mm)}

PT0S

#{diffDate("Wed 10 Apr\, 2019\, 13:20:43 GMT", "EEE dd MMM\, yyyy\, HH:mm:ss zzz", "Wed 10 Apr\, 2019\, 09:20:43 America/New_York", "EEE dd MMM\, yyyy\, HH:mm:ss zzz")}

PT0S

#{diffDate(2019-03-19 03:40:00, yyyy-MM-dd HH:mm:ss, 3020-03-19 03:39:20, yyyy-MM-dd HH:mm:ss)}

PT8774591H59M20S

toEpochSecond

Converts the input date to the unix epoch time (the number of seconds from the epoch of 1970-01-01T00:00:00Z).

#{toEpochSecond($inputDate)}

  • $inputDate - the date to be formatted, it should be presented in the ISO-8601 format

Table 6. Examples of the expressions converting the input date to the unix epoch time
Expression Result

#{toEpochSecond(1993-04-16T00:00:00)}

734918400

#{toEpochSecond(2020-12-11T18:43:05+05:30)}

1607692385

Steps

Dates comparison

Info

Validates the difference between the current date and the date under test in seconds.

Wording

Then the date '$date' is $comparisonRule current for $seconds seconds

Parameters

  1. $date - the date in the ISO-8601 format

  2. $comparisonRule - Comparison Rule

  3. $seconds - the quantity of seconds between current and the date.

Usage

Example 2. Sample.story
Scenario: Validate the date is less than current for 10 seconds
Then the date '2020-06-16T15:25:29.516580Z' is less than current for 10 seconds

Dates comparison with custom date format

Info

Validates the difference between the current date and the date under test in seconds using custom date format.

Wording

Then the date '$date' in the format '$format' is $comparisonRule current for $seconds seconds

Parameters

  1. $date - the date to validate

  2. $format - the date in the date/time format

  3. $comparisonRule - Comparison Rule

  4. $seconds - the quantity of seconds between current and the date

Usage

Example 3. Sample.story
Scenario: Validate the date is greater than current for 10 seconds
Then the date '2020-06-25T00:19:58.890007Z' in the format 'uuuu-MM-dd'T'HH:mm:ss.nnnX' is > current for 10 seconds