Date and Time (%TIME) Macro

Applies to ReadyAPI 3.52, last modified on April 18, 2024

The Date and Time macro is used to insert date and time values into the strings generated by a data source using the Custom String data generator.

The macro is an analog of the Date and Time data generator.


The macro has the following syntax:

%TIME(MinDate, MaxDate, Format, GenerationMode, IncrementDay, IncrementHour, IncrementMinute, IncrementSecond)


MinDate and MaxDate

Strings that specify the earliest and latest possible generated dates.

MinDate must be an earlier date/time value than MaxDate.
MinDate and MaxDate must have the following date format:

"7/19/15 10:11:12 AM GMT"


A string that specifies the format of the generated date/time value.

ReadyAPI uses the SimpleDateFormat class to parse the date. This class considers all letter characters (from a to z and from A to Z) as part of the format pattern. You can use any other symbols (except symbols that are prohibited to use in macros) to be used in the pattern. To specify letters that are not part of the format pattern, quote them using single quotes. To specify the single quote (') symbol, double it.

Usually, specifying the same letter several times changes the format to a longer version. For example:

  • M – Inserts the month number (1, 12).

  • MM – Inserts the month number with the leading zero (01, 12).

  • MMM – Inserts the short name of the month (Jan, Dec).

  • MMMM – Inserts the long name of the month (January, December).

The format string is case-sensitive. Note that some symbols have different meanings in different cases. For example, D specifies the day of the year (from 1 to 366), while d specifies the day of the month (from 1 to 31). So, if you want to specify a date in the format 1990-12-31, you should use the YYYY-MM-dd string.

The following list shows the most used representations of the letters. For the full description, see the class documentation.

Symbol Description Examples
y or Y Represents a year. 15
M Represents a month. 1
w The number of a week in a year. 33
W The number of a week in a month. 3
D The number of a day in a year. 221
d The number of a day in a month. 8
E The name of a day of the week. Tue
a Inserts the AM or PM marker. PM
H The hour of the day in the 24-hour period. Midnight is shown as 0. 0
k The hour of the day in the 24-hour period. Midnight is shown as 24. 24
K The hour of the day in the 12-hour period. Midnight and noon are shown as 0. 10
h The hour of the day in the 12-hour period. Midnight and noon are shown as 12. 11
m Minutes in an hour. 32
s Seconds in a minute. 12

The default value of the parameter is M/d/yyyy KK:mm:ss a.


Specifies the functioning mode for the generator:

  • True – In this case, ReadyAPI uses the sequential generation mode. The macro uses MinDate as the first generated value and increases it using values of the IncrementValues parameter to get the next generated values.

  • False – In this case, ReadyAPI uses the Random generation mode. For each generated custom string, the macro produces an arbitrary date and time value within the MinDate to MaxDate range.

The parameter is case-insensitive.

IncrementDay, IncrementHour, IncrementMinute, IncrementSecond

These parameters are used only if the Sequential mode is selected (see above). It specifies the number of days, hours, minutes and seconds to be added to the previously generated value to get a new value.

These parameters are used only with the sequential generation mode, but you have to specify the parameter even if you use the Random generation mode.

The default parameter values are 1.


The following examples demonstrate how to use the Date and Time macro:

  • %TIME("7/12/2014 00:00:00 AM GMT","10/20/2014 00:00:00 AM GMT","MMM d, yyyy h:mm a", True, 1,1,10,0)

    Example: Date and Time macro in Data Generator

    Click the image to enlarge it.

    Generates date and time values starting from midnight, July 12, 2014, and increasing each value by one day, one hour and ten minutes. The values have a brief month name and the AM/PM time format:

    Jul 13, 2014 5:10 AM
    Jul 14, 2014 6:20 AM
    Jul 15, 2014 7:30 AM
  • %TIME("7/12/2014 00:00:00 AM GMT","7/12/2015 00:00:00 AM GMT","dd.MM.YY kk:mm:ss", false, 0, 0, 0, 0)

    Generates random date/time values in the range from July 12, 2014, to July 12, 2015. The generated values have the format adopted in Germany and some other European countries:

    08.12.14 12:53:51
    09.02.15 17:03:00
    17.08.14 10:11:17
  • %TIME("7/12/2014 00:00:00 AM GMT","10/20/2014 00:00:00 AM GMT","dd-MMM-yy", false, 0, 0, 0, 0)

    Generates random dates in the range from July 12, 2014, to October 20, 2014. Generated values include only dates (no time):

  • %TIME("01/10/15 03:05:30 AM GMT","14/10/15 14:05:00 AM GMT","HH:mm:ss", TRUE, 0, 0, 10, 0)

    Generates time values starting from 03:05:30 and increasing the value by 10 minutes. The generated values include only time (no date):



For more information on adding macros to custom strings, see About Custom String Generator.

For more information on general rules used for specifying macro parameters, see Custom String Generator Rules.

See Also

Date and Time Generator
Custom String Generator
Macro Reference

Highlight search results