TimeControl

TimeControl sets the time returned by the framework-provided MockTime interface, and controls all time symbols and CAS time constraints that use the now keyword. Developers must inject the MockTime interface into their application to replace the system clock, ensuring stability of time-dependent tests.

Basic Usage

Given current time is "2026-01-27T10:00:00"

This instruction will:

Set the MockTime interface return time to 2026-01-27T10:00:00
All time symbols (e.g., @time("now"), @date("now")) and CAS time constraints (e.g., &sameTime("now")) that use now will be based on this time

Why Control Time?

Without TimeControl, tests depend on the system clock, producing different results at different times:

# ❌ Without TimeControl: only passes at specific times
Then create todo(201) response, with table:
  | createdAt                        |
  | &sameTime("2026-02-12T10:00:00") |

# ✅ With TimeControl: passes regardless of when executed
Given current time is "2026-02-01T10:00:00"
Then create todo(201) response, with table:
  | createdAt                        |
  | &sameTime("2026-02-01T10:00:00") |

Supported Time Formats

Format	Example
Date only	`2025-12-25` (defaults to 00:00:00)
ISO without timezone	`2025-11-04T08:00:00` (uses system timezone)
ISO with timezone	`2025-12-25T14:30:00+08:00`
ISO UTC	`2025-12-25T06:30:00Z`
Time symbol	`@time("2025-12-25T14:30:00")` (see TIME-System)

Scope of Effect

The time set by TimeControl affects all expressions that use the now keyword:

Time Symbols

Symbol	Description
`@time("now")`	Returns the current MockTime
`@time("now+1d")`	Relative calculation based on current MockTime
`@date("now")`	Returns the current MockTime date
`@localtime("now")`	Returns the current MockTime time (time only)

CAS Time Constraints

Constraint	Description
`&sameTime("now")`	Validates value equals the current MockTime
`&before("now")`	Validates value is before the current MockTime
`&after("now")`	Validates value is after the current MockTime

Time symbols and CAS time constraints can be used in DataTable fields of any instruction.

Error Handling

Runtime

Error	Description
Missing time parameter	Time expression is empty
Unable to parse	Time format doesn't match supported formats

Complete Example

Feature: Todo Time Control

  Background:
    Given current time is "2026-01-27T10:00:00"
    Given prepare a user, with table:
      | >Alice.id | name  | email             | status |
      | <userId   | Alice | alice@example.com | ACTIVE |

  Example: Create then advance time and update
    # 1. Create todo (createdAt = 2026-01-27T10:00:00)
    When (UID="$Alice.id") create todo, call table:
      | >todo1.id | title    |
      | <todoId   | Buy milk |
    Then create todo(201) response, with table:
      | todoId    | createdAt                        |
      | $todo1.id | &sameTime("2026-01-27T10:00:00") |

    # 2. Advance time by 1 day
    Given current time is "@time("now+1d")"

    # 3. Update todo (updatedAt = 2026-01-28T10:00:00)
    When (UID="$Alice.id") update todo, call table:
      | P:todoId  | title        |
      | $todo1.id | Buy soy milk |
    Then update todo(200) response, with table:
      | todoId    | updatedAt                        |
      | $todo1.id | &sameTime("2026-01-28T10:00:00") |

TimeControl

On this page