Test Clocks Test helper

A test clock enables deterministic control over objects in testmode. With a test clock, you can create objects at a frozen time in the past or future, and advance to a specific future time to observe webhooks and state changes. After the clock advances, you can either validate the current state of your scenario (and test your assumptions), change the current state of your scenario (and test more complex scenarios), or keep advancing forward in time.

Was this section helpful? Yes No

Create a test clock

POST / v1 / test_helpers / test_clocks

Retrieve a test clock

GET / v1 / test_helpers / test_clocks /:id

List all test clocks

GET / v1 / test_helpers / test_clocks

Delete a test clock

DELETE / v1 / test_helpers / test_clocks /:id

Advance a test clock

POST / v1 / test_helpers / test_clocks /:id / advance

The Test Clock object Test helper

Attributes

• id string Unique identifier for the object.
• object string, value is "test_helpers.test_clock" String representing the object’s type. Objects of the same type share the same value.
• created timestamp Time at which the object was created. Measured in seconds since the Unix epoch.
• deletes _ after timestamp Time at which this clock is scheduled to auto delete.
• frozen _ time timestamp Time at which all objects belonging to this clock are frozen.
• livemode boolean If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.
• name nullable string The custom name supplied at creation.
• status enum The status of the Test Clock. Possible enum values advancing In the process of advancing time for the test clock objects. internal_failure Failed to advance time. Future requests to advance time will fail. ready All test clock objects have advanced to the frozen_time.
• status _ details object Details on the current state of the Test Clock.

The Test Clock object

{ "id": "clock_1Mr3I22eZvKYlo2Ck0rgMqd7", "object": "test_helpers.test_clock", "created": 1680112806, "deletes_after": 1680717606, "frozen_time": 1577836800, "livemode": false, "name": null, "status": "ready"}

Create a test clock Test helper

POST / v1 / test_helpers / test_clocks

Creates a new test clock that can be attached to new customers and quotes.

Parameters

• frozen _ time timestamp Required The initial frozen time for this test clock.
• name string The name for this test clock. The maximum length is 300 characters.

More parameters

• customer string

Returns

The newly created TestClock object is returned upon success. Otherwise, this call raises an error.

Response

{ "id": "clock_1Mr3I22eZvKYlo2Ck0rgMqd7", "object": "test_helpers.test_clock", "created": 1680112806, "deletes_after": 1680717606, "frozen_time": 1577836800, "livemode": false, "name": null, "status": "ready"}