Skip to content

robot.libraries.DateTime

A library for handling date and time values.

DateTime is a Robot Framework standard library that supports creating and converting date and time values (e.g. Get Current Date, Convert Time), as well as doing simple calculations with them (e.g. Subtract Time From Date, Add Time To Time). It supports dates and times in various formats, and can also be used by other libraries programmatically.

== Table of contents ==

%TOC%

= Terminology =

In the context of this library, date and time generally have the following meanings:

  • date: An entity with both date and time components but without any time zone information. For example, 2014-06-11 10:07:42.
  • time: A time interval. For example, 1 hour 20 minutes or 01:20:00.

This terminology differs from what Python's standard [http://docs.python.org/library/datetime.html|datetime] module uses. Basically its [http://docs.python.org/library/datetime.html#datetime-objects|datetime] and [http://docs.python.org/library/datetime.html#timedelta-objects|timedelta] objects match date and time as defined by this library.

= Date formats =

Dates can be given to and received from keywords in timestamp, custom timestamp, Python datetime and epoch time formats. These formats are discussed thoroughly in subsequent sections.

Input format is determined automatically based on the given date except when using custom timestamps, in which case it needs to be given using date_format argument. Default result format is timestamp, but it can be overridden using result_format argument.

== Timestamp ==

If a date is given as a string, it is always considered to be a timestamp. If no custom formatting is given using date_format argument, the timestamp is expected to be in [http://en.wikipedia.org/wiki/ISO_8601|ISO 8601] like format YYYY-MM-DD hh:mm:ss.mil, where any non-digit character can be used as a separator or separators can be omitted altogether. Additionally, only the date part is mandatory, all possibly missing time components are considered to be zeros.

Dates can also be returned in the same YYYY-MM-DD hh:mm:ss.mil format by using timestamp value with result_format argument. This is also the default format that keywords returning dates use. Milliseconds can be excluded using exclude_millis as explained in Millisecond handling section.

Examples: | ${date1} = | Convert Date | 2014-06-11 10:07:42.000 | | ${date2} = | Convert Date | 20140611 100742 | result_format=timestamp | | Should Be Equal | ${date1} | ${date2} | | ${date} = | Convert Date | 20140612 12:57 | exclude_millis=yes | | Should Be Equal | ${date} | 2014-06-12 12:57:00 |

== Custom timestamp ==

It is possible to use custom timestamps in both input and output. The custom format is same as accepted by Python's [http://docs.python.org/library/datetime.html#strftime-strptime-behavior| datetime.strptime] function. For example, the default timestamp discussed in the previous section would match %Y-%m-%d %H:%M:%S.%f.

When using a custom timestamp in input, it must be specified using date_format argument. The actual input value must be a string that matches the specified format exactly. When using a custom timestamp in output, it must be given using result_format argument.

Examples: | ${date} = | Convert Date | 28.05.2014 12:05 | date_format=%d.%m.%Y %H:%M | | Should Be Equal | ${date} | 2014-05-28 12:05:00.000 | | ${date} = | Convert Date | ${date} | result_format=%d.%m.%Y | | Should Be Equal | ${date} | 28.05.2014 |

== Python datetime ==

Python's standard [https://docs.python.org/library/datetime.html#datetime.datetime|datetime] objects can be used both in input and output. In input, they are recognized automatically, and in output it is possible to get them by using the datetime value with the result_format argument.

One nice benefit with datetime objects is that they have different time components available as attributes that can be easily accessed using the extended variable syntax.

Examples: | ${datetime} = | Convert Date | 2014-06-11 10:07:42.123 | datetime | | Should Be Equal As Integers | ${datetime.year} | 2014 | | Should Be Equal As Integers | ${datetime.month} | 6 | | Should Be Equal As Integers | ${datetime.day} | 11 | | Should Be Equal As Integers | ${datetime.hour} | 10 | | Should Be Equal As Integers | ${datetime.minute} | 7 | | Should Be Equal As Integers | ${datetime.second} | 42 | | Should Be Equal As Integers | ${datetime.microsecond} | 123000 |

== Python date ==

Python's standard [https://docs.python.org/library/datetime.html#datetime.date|date] objects are automatically recognized in input starting from Robot Framework 7.0. They are not supported in output, but datetime objects can be converted to date objects if needed:

| ${datetime} = | Convert Date | 2023-12-18 11:10:42 | datetime | | Log | ${datetime.date()} | # The time part is ignored. |

== Epoch time ==

Epoch time is the time in seconds since the [http://en.wikipedia.org/wiki/Unix_time|UNIX epoch] i.e. 00:00:00.000 (UTC) January 1, 1970. To give a date as an epoch time, it must be given as a number (integer or float), not as a string. To return a date as an epoch time, it is possible to use epoch value with result_format argument. Epoch times are returned as floating point numbers.

Notice that epoch times are independent on time zones and thus same around the world at a certain time. For example, epoch times returned by Get Current Date are not affected by the time_zone argument. What local time a certain epoch time matches then depends on the time zone.

Following examples demonstrate using epoch times. They are tested in Finland, and due to the reasons explained above they would fail on other time zones.

| ${date} = | Convert Date | ${1000000000} | | Should Be Equal | ${date} | 2001-09-09 04:46:40.000 | | ${date} = | Convert Date | 2014-06-12 13:27:59.279 | epoch | | Should Be Equal | ${date} | ${1402568879.279} |

== Earliest supported date ==

The earliest date that is supported depends on the date format and to some extent on the platform:

  • Timestamps support year 1900 and above.
  • Python datetime objects support year 1 and above.
  • Epoch time supports 1970 and above on Windows.
  • On other platforms epoch time supports 1900 and above or even earlier.

= Time formats =

Similarly as dates, times can be given to and received from keywords in various different formats. Supported formats are number, time string (verbose and compact), timer string and Python timedelta.

Input format for time is always determined automatically based on the input. Result format is number by default, but it can be customised using result_format argument.

== Number ==

Time given as a number is interpreted to be seconds. It can be given either as an integer or a float, or it can be a string that can be converted to a number.

To return a time as a number, result_format argument must have value number, which is also the default. Returned number is always a float.

Examples: | ${time} = | Convert Time | 3.14 | | Should Be Equal | ${time} | ${3.14} | | ${time} = | Convert Time | ${time} | result_format=number | | Should Be Equal | ${time} | ${3.14} |

== Time string ==

Time strings are strings in format like 1 minute 42 seconds or 1min 42s. The basic idea of this format is having first a number and then a text specifying what time that number represents. Numbers can be either integers or floating point numbers, the whole format is case and space insensitive, and it is possible to add a minus prefix to specify negative times. The available time specifiers are:

  • weeks, week, w (new in RF 7.1)
  • days, day, d
  • hours, hour, h
  • minutes, minute, mins, min, m
  • seconds, second, secs, sec, s
  • milliseconds, millisecond, millis, ms
  • microseconds, microsecond, us, μs (new in RF 6.0)
  • nanoseconds, nanosecond, ns (new in RF 6.0)

When returning a time string, it is possible to select between verbose and compact representations using result_format argument. The verbose format uses long specifiers week, day, hour, minute, second and millisecond, and adds s at the end when needed. The compact format uses shorter specifiers w, d, h, min, s and ms, and even drops the space between the number and the specifier.

Examples: | ${time} = | Convert Time | 1 minute 42 seconds | | Should Be Equal | ${time} | ${102} | | ${time} = | Convert Time | 4200 | verbose | | Should Be Equal | ${time} | 1 hour 10 minutes | | ${time} = | Convert Time | - 1.5 hours | compact | | Should Be Equal | ${time} | - 1h 30min |

== Timer string ==

Timer string is a string given in timer like format hh:mm:ss.mil. In this format both hour and millisecond parts are optional, leading and trailing zeros can be left out when they are not meaningful, and negative times can be represented by adding a minus prefix.

To return a time as timer string, result_format argument must be given value timer. Timer strings are by default returned in full hh:mm:ss.mil format, but milliseconds can be excluded using exclude_millis as explained in Millisecond handling section.

Examples: | ${time} = | Convert Time | 01:42 | | Should Be Equal | ${time} | ${102} | | ${time} = | Convert Time | 01:10:00.123 | | Should Be Equal | ${time} | ${4200.123} | | ${time} = | Convert Time | 102 | timer | | Should Be Equal | ${time} | 00:01:42.000 | | ${time} = | Convert Time | -101.567 | timer | exclude_millis=yes | | Should Be Equal | ${time} | -00:01:42 |

== Python timedelta ==

Python's standard [http://docs.python.org/library/datetime.html#datetime.timedelta|timedelta] objects are also supported both in input and in output. In input they are recognized automatically, and in output it is possible to receive them by giving timedelta value to result_format argument.

Examples: | ${timedelta} = | Convert Time | 01:10:02.123 | timedelta | | Should Be Equal | ${timedelta.total_seconds()} | ${4202.123} |

= Millisecond handling =

This library handles dates and times internally using the precision of the given input. With timestamp, time string, and timer string result formats seconds are, however, rounded to millisecond accuracy. Milliseconds may also be included even if there would be none.

All keywords returning dates or times have an option to leave milliseconds out by giving a true value to exclude_millis argument. If the argument is given as a string, it is considered true unless it is empty or case-insensitively equal to false, none or no. Other argument types are tested using same [http://docs.python.org/library/stdtypes.html#truth|rules as in Python].

When milliseconds are excluded, seconds in returned dates and times are rounded to the nearest full second. With timestamp and timer string result formats, milliseconds will also be removed from the returned string altogether.

Examples: | ${date} = | Convert Date | 2014-06-11 10:07:42 | | Should Be Equal | ${date} | 2014-06-11 10:07:42.000 | | ${date} = | Convert Date | 2014-06-11 10:07:42.500 | exclude_millis=yes | | Should Be Equal | ${date} | 2014-06-11 10:07:43 | | ${dt} = | Convert Date | 2014-06-11 10:07:42.500 | datetime | exclude_millis=yes | | Should Be Equal | ${dt.second} | ${43} | | Should Be Equal | ${dt.microsecond} | ${0} | | ${time} = | Convert Time | 102 | timer | exclude_millis=false | | Should Be Equal | ${time} | 00:01:42.000 | | | ${time} = | Convert Time | 102.567 | timer | exclude_millis=true | | Should Be Equal | ${time} | 00:01:43 | |

= Programmatic usage =

In addition to be used as normal library, this library is intended to provide a stable API for other libraries to use if they want to support same date and time formats as this library. All the provided keywords are available as functions that can be easily imported:

from robot.libraries.DateTime import convert_time
def example_keyword(timeout):
seconds = convert_time(timeout)
# ...

Additionally, helper classes Date and Time can be used directly:

from robot.libraries.DateTime import Date, Time
def example_keyword(date, interval):
date = Date(date).convert('datetime')
interval = Time(interval).convert('number')
# ...

get_current_date 

1
2
3
4
5
6
get_current_date(
    time_zone="local",
    increment=0,
    result_format="timestamp",
    exclude_millis=False,
)

Returns current local or UTC time with an optional increment.

  • time_zone: Get the current time on this time zone. Currently only local (default) and UTC are supported. Has no effect if date is returned as an epoch time.
  • increment: Optional time increment to add to the returned date in one of the supported time formats. Can be negative.
  • result_format: Format of the returned date (see date formats).
  • exclude_millis: When set to any true value, rounds and drops milliseconds as explained in millisecond handling.

Examples: | ${date} = | Get Current Date | | Should Be Equal | ${date} | 2014-06-12 20:00:58.946 | | ${date} = | Get Current Date | UTC | | Should Be Equal | ${date} | 2014-06-12 17:00:58.946 | | ${date} = | Get Current Date | increment=02:30:00 | | Should Be Equal | ${date} | 2014-06-12 22:30:58.946 | | ${date} = | Get Current Date | UTC | - 5 hours | | Should Be Equal | ${date} | 2014-06-12 12:00:58.946 | | ${date} = | Get Current Date | result_format=datetime | | Should Be Equal | ${date.year} | ${2014} | | Should Be Equal | ${date.month} | ${6} |

Source code in src/robot/libraries/DateTime.py 
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
def get_current_date(time_zone='local', increment=0, result_format='timestamp',
                     exclude_millis=False):
    """Returns current local or UTC time with an optional increment.

    Arguments:
    - ``time_zone:``      Get the current time on this time zone. Currently only
                          ``local`` (default) and ``UTC`` are supported.
                          Has no effect if date is returned as an `epoch time`.
    - ``increment:``      Optional time increment to add to the returned date in
                          one of the supported `time formats`. Can be negative.
    - ``result_format:``  Format of the returned date (see `date formats`).
    - ``exclude_millis:`` When set to any true value, rounds and drops
                          milliseconds as explained in `millisecond handling`.

    Examples:
    | ${date} =       | Get Current Date |
    | Should Be Equal | ${date}          | 2014-06-12 20:00:58.946 |
    | ${date} =       | Get Current Date | UTC                     |
    | Should Be Equal | ${date}          | 2014-06-12 17:00:58.946 |
    | ${date} =       | Get Current Date | increment=02:30:00      |
    | Should Be Equal | ${date}          | 2014-06-12 22:30:58.946 |
    | ${date} =       | Get Current Date | UTC                     | - 5 hours |
    | Should Be Equal | ${date}          | 2014-06-12 12:00:58.946 |
    | ${date} =       | Get Current Date | result_format=datetime  |
    | Should Be Equal | ${date.year}     | ${2014}                 |
    | Should Be Equal | ${date.month}    | ${6}                    |
    """
    if time_zone.upper() == 'LOCAL' or result_format.upper() == 'EPOCH':
        dt = datetime.datetime.now()
    elif time_zone.upper() == 'UTC':
        if sys.version_info >= (3, 12):
            # `utcnow()` was deprecated in Python 3.12. We only support "naive"
            # datetime objects and thus need to remove timezone information here.
            dt = datetime.datetime.now(datetime.UTC).replace(tzinfo=None)
        else:
            dt = datetime.datetime.utcnow()
    else:
        raise ValueError(f"Unsupported timezone '{time_zone}'.")
    date = Date(dt) + Time(increment)
    return date.convert(result_format, millis=not exclude_millis)

convert_date 

1
2
3
4
5
6
convert_date(
    date,
    result_format="timestamp",
    exclude_millis=False,
    date_format=None,
)

Converts between supported date formats.

Arguments: - date: Date in one of the supported date formats. - result_format: Format of the returned date. - exclude_millis: When set to any true value, rounds and drops milliseconds as explained in millisecond handling. - date_format: Specifies possible custom timestamp format.

Examples: | ${date} = | Convert Date | 20140528 12:05:03.111 | | Should Be Equal | ${date} | 2014-05-28 12:05:03.111 | | ${date} = | Convert Date | ${date} | epoch | | Should Be Equal | ${date} | ${1401267903.111} | | ${date} = | Convert Date | 5.28.2014 12:05 | exclude_millis=yes | date_format=%m.%d.%Y %H:%M | | Should Be Equal | ${date} | 2014-05-28 12:05:00 |

Source code in src/robot/libraries/DateTime.py 
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
def convert_date(date, result_format='timestamp', exclude_millis=False,
                 date_format=None):
    """Converts between supported `date formats`.

    Arguments:
    - ``date:``           Date in one of the supported `date formats`.
    - ``result_format:``  Format of the returned date.
    - ``exclude_millis:`` When set to any true value, rounds and drops
                          milliseconds as explained in `millisecond handling`.
    - ``date_format:``    Specifies possible `custom timestamp` format.

    Examples:
    | ${date} =       | Convert Date | 20140528 12:05:03.111   |
    | Should Be Equal | ${date}      | 2014-05-28 12:05:03.111 |
    | ${date} =       | Convert Date | ${date}                 | epoch |
    | Should Be Equal | ${date}      | ${1401267903.111}       |
    | ${date} =       | Convert Date | 5.28.2014 12:05         | exclude_millis=yes | date_format=%m.%d.%Y %H:%M |
    | Should Be Equal | ${date}      | 2014-05-28 12:05:00     |
    """
    return Date(date, date_format).convert(result_format, millis=not exclude_millis)

convert_time 

1
2
3
convert_time(
    time, result_format="number", exclude_millis=False
)

Converts between supported time formats.

Arguments: - time: Time in one of the supported time formats. - result_format: Format of the returned time. - exclude_millis: When set to any true value, rounds and drops milliseconds as explained in millisecond handling.

Examples: | ${time} = | Convert Time | 10 seconds | | Should Be Equal | ${time} | ${10} | | ${time} = | Convert Time | 1:00:01 | verbose | | Should Be Equal | ${time} | 1 hour 1 second | | ${time} = | Convert Time | ${3661.5} | timer | exclude_milles=yes | | Should Be Equal | ${time} | 01:01:02 |

Source code in src/robot/libraries/DateTime.py 
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
def convert_time(time, result_format='number', exclude_millis=False):
    """Converts between supported `time formats`.

    Arguments:
    - ``time:``           Time in one of the supported `time formats`.
    - ``result_format:``  Format of the returned time.
    - ``exclude_millis:`` When set to any true value, rounds and drops
                          milliseconds as explained in `millisecond handling`.

    Examples:
    | ${time} =       | Convert Time  | 10 seconds        |
    | Should Be Equal | ${time}       | ${10}             |
    | ${time} =       | Convert Time  | 1:00:01           | verbose |
    | Should Be Equal | ${time}       | 1 hour 1 second   |
    | ${time} =       | Convert Time  | ${3661.5} | timer | exclude_milles=yes |
    | Should Be Equal | ${time}       | 01:01:02          |
    """
    return Time(time).convert(result_format, millis=not exclude_millis)

subtract_date_from_date 

1
2
3
4
5
6
7
8
subtract_date_from_date(
    date1,
    date2,
    result_format="number",
    exclude_millis=False,
    date1_format=None,
    date2_format=None,
)

Subtracts date from another date and returns time between.

  • date1: Date to subtract another date from in one of the supported date formats.
  • date2: Date that is subtracted in one of the supported date formats.
  • result_format: Format of the returned time (see time formats).
  • exclude_millis: When set to any true value, rounds and drops milliseconds as explained in millisecond handling.
  • date1_format: Possible custom timestamp format of date1.
  • date2_format: Possible custom timestamp format of date2.

Examples: | ${time} = | Subtract Date From Date | 2014-05-28 12:05:52 | 2014-05-28 12:05:10 | | Should Be Equal | ${time} | ${42} | | ${time} = | Subtract Date From Date | 2014-05-28 12:05:52 | 2014-05-27 12:05:10 | verbose | | Should Be Equal | ${time} | 1 day 42 seconds |

Source code in src/robot/libraries/DateTime.py 
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
def subtract_date_from_date(date1, date2, result_format='number',
                            exclude_millis=False, date1_format=None,
                            date2_format=None):
    """Subtracts date from another date and returns time between.

    Arguments:
    - ``date1:``          Date to subtract another date from in one of the
                          supported `date formats`.
    - ``date2:``          Date that is subtracted in one of the supported
                          `date formats`.
    - ``result_format:``  Format of the returned time (see `time formats`).
    - ``exclude_millis:`` When set to any true value, rounds and drops
                          milliseconds as explained in `millisecond handling`.
    - ``date1_format:``   Possible `custom timestamp` format of ``date1``.
    - ``date2_format:``   Possible `custom timestamp` format of ``date2``.

     Examples:
    | ${time} =       | Subtract Date From Date | 2014-05-28 12:05:52     | 2014-05-28 12:05:10 |
    | Should Be Equal | ${time}                 | ${42}                   |
    | ${time} =       | Subtract Date From Date | 2014-05-28 12:05:52     | 2014-05-27 12:05:10 | verbose |
    | Should Be Equal | ${time}                 | 1 day 42 seconds        |
    """
    time = Date(date1, date1_format) - Date(date2, date2_format)
    return time.convert(result_format, millis=not exclude_millis)

add_time_to_date 

1
2
3
4
5
6
7
add_time_to_date(
    date,
    time,
    result_format="timestamp",
    exclude_millis=False,
    date_format=None,
)

Adds time to date and returns the resulting date.

  • date: Date to add time to in one of the supported date formats.
  • time: Time that is added in one of the supported time formats.
  • result_format: Format of the returned date.
  • exclude_millis: When set to any true value, rounds and drops milliseconds as explained in millisecond handling.
  • date_format: Possible custom timestamp format of date.

Examples: | ${date} = | Add Time To Date | 2014-05-28 12:05:03.111 | 7 days | | Should Be Equal | ${date} | 2014-06-04 12:05:03.111 | | | ${date} = | Add Time To Date | 2014-05-28 12:05:03.111 | 01:02:03:004 | | Should Be Equal | ${date} | 2014-05-28 13:07:06.115 |

Source code in src/robot/libraries/DateTime.py 
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
def add_time_to_date(date, time, result_format='timestamp',
                     exclude_millis=False, date_format=None):
    """Adds time to date and returns the resulting date.

    Arguments:
    - ``date:``           Date to add time to in one of the supported
                          `date formats`.
    - ``time:``           Time that is added in one of the supported
                          `time formats`.
    - ``result_format:``  Format of the returned date.
    - ``exclude_millis:`` When set to any true value, rounds and drops
                          milliseconds as explained in `millisecond handling`.
    - ``date_format:``    Possible `custom timestamp` format of ``date``.

    Examples:
    | ${date} =       | Add Time To Date | 2014-05-28 12:05:03.111 | 7 days       |
    | Should Be Equal | ${date}          | 2014-06-04 12:05:03.111 |              |
    | ${date} =       | Add Time To Date | 2014-05-28 12:05:03.111 | 01:02:03:004 |
    | Should Be Equal | ${date}          | 2014-05-28 13:07:06.115 |
    """
    date = Date(date, date_format) + Time(time)
    return date.convert(result_format, millis=not exclude_millis)

subtract_time_from_date 

1
2
3
4
5
6
7
subtract_time_from_date(
    date,
    time,
    result_format="timestamp",
    exclude_millis=False,
    date_format=None,
)

Subtracts time from date and returns the resulting date.

  • date: Date to subtract time from in one of the supported date formats.
  • time: Time that is subtracted in one of the supported time formats.
  • result_format: Format of the returned date.
  • exclude_millis: When set to any true value, rounds and drops milliseconds as explained in millisecond handling.
  • date_format: Possible custom timestamp format of date.

Examples: | ${date} = | Subtract Time From Date | 2014-06-04 12:05:03.111 | 7 days | | Should Be Equal | ${date} | 2014-05-28 12:05:03.111 | | ${date} = | Subtract Time From Date | 2014-05-28 13:07:06.115 | 01:02:03:004 | | Should Be Equal | ${date} | 2014-05-28 12:05:03.111 |

Source code in src/robot/libraries/DateTime.py 
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
def subtract_time_from_date(date, time, result_format='timestamp',
                            exclude_millis=False, date_format=None):
    """Subtracts time from date and returns the resulting date.

    Arguments:
    - ``date:``           Date to subtract time from in one of the supported
                          `date formats`.
    - ``time:``           Time that is subtracted in one of the supported
                         `time formats`.
    - ``result_format:``  Format of the returned date.
    - ``exclude_millis:`` When set to any true value, rounds and drops
                          milliseconds as explained in `millisecond handling`.
    - ``date_format:``    Possible `custom timestamp` format of ``date``.

    Examples:
    | ${date} =       | Subtract Time From Date | 2014-06-04 12:05:03.111 | 7 days |
    | Should Be Equal | ${date}                 | 2014-05-28 12:05:03.111 |
    | ${date} =       | Subtract Time From Date | 2014-05-28 13:07:06.115 | 01:02:03:004 |
    | Should Be Equal | ${date}                 | 2014-05-28 12:05:03.111 |
    """
    date = Date(date, date_format) - Time(time)
    return date.convert(result_format, millis=not exclude_millis)

add_time_to_time 

1
2
3
4
5
6
add_time_to_time(
    time1,
    time2,
    result_format="number",
    exclude_millis=False,
)

Adds time to another time and returns the resulting time.

Arguments: - time1: First time in one of the supported time formats. - time2: Second time in one of the supported time formats. - result_format: Format of the returned time. - exclude_millis: When set to any true value, rounds and drops milliseconds as explained in millisecond handling.

Examples: | ${time} = | Add Time To Time | 1 minute | 42 | | Should Be Equal | ${time} | ${102} | | ${time} = | Add Time To Time | 3 hours 5 minutes | 01:02:03 | timer | exclude_millis=yes | | Should Be Equal | ${time} | 04:07:03 |

Source code in src/robot/libraries/DateTime.py 
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
def add_time_to_time(time1, time2, result_format='number',
                     exclude_millis=False):
    """Adds time to another time and returns the resulting time.

    Arguments:
    - ``time1:``          First time in one of the supported `time formats`.
    - ``time2:``          Second time in one of the supported `time formats`.
    - ``result_format:``  Format of the returned time.
    - ``exclude_millis:`` When set to any true value, rounds and drops
                          milliseconds as explained in `millisecond handling`.

    Examples:
    | ${time} =       | Add Time To Time | 1 minute          | 42       |
    | Should Be Equal | ${time}          | ${102}            |
    | ${time} =       | Add Time To Time | 3 hours 5 minutes | 01:02:03 | timer | exclude_millis=yes |
    | Should Be Equal | ${time}          | 04:07:03          |
    """
    time = Time(time1) + Time(time2)
    return time.convert(result_format, millis=not exclude_millis)

subtract_time_from_time 

1
2
3
4
5
6
subtract_time_from_time(
    time1,
    time2,
    result_format="number",
    exclude_millis=False,
)

Subtracts time from another time and returns the resulting time.

  • time1: Time to subtract another time from in one of the supported time formats.
  • time2: Time to subtract in one of the supported time formats.
  • result_format: Format of the returned time.
  • exclude_millis: When set to any true value, rounds and drops milliseconds as explained in millisecond handling.

Examples: | ${time} = | Subtract Time From Time | 00:02:30 | 100 | | Should Be Equal | ${time} | ${50} | | ${time} = | Subtract Time From Time | ${time} | 1 minute | compact | | Should Be Equal | ${time} | - 10s |

Source code in src/robot/libraries/DateTime.py 
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
def subtract_time_from_time(time1, time2, result_format='number',
                            exclude_millis=False):
    """Subtracts time from another time and returns the resulting time.

    Arguments:
    - ``time1:``          Time to subtract another time from in one of
                          the supported `time formats`.
    - ``time2:``          Time to subtract in one of the supported `time formats`.
    - ``result_format:``  Format of the returned time.
    - ``exclude_millis:`` When set to any true value, rounds and drops
                          milliseconds as explained in `millisecond handling`.

    Examples:
    | ${time} =       | Subtract Time From Time | 00:02:30 | 100      |
    | Should Be Equal | ${time}                 | ${50}    |
    | ${time} =       | Subtract Time From Time | ${time}  | 1 minute | compact |
    | Should Be Equal | ${time}                 | - 10s    |
    """
    time = Time(time1) - Time(time2)
    return time.convert(result_format, millis=not exclude_millis)