Documentation
¶
Overview ¶
Package clock provides a simulated time for Gost-DOM.
Index ¶
- type Clock
- func (c *Clock) AddMicrotask(task TaskCallback)
- func (c *Clock) AddSafeMicrotask(task SafeTaskCallback)
- func (c *Clock) AddSafeTask(task SafeTaskCallback, delay time.Duration) TaskHandle
- func (c *Clock) Advance(d time.Duration) error
- func (c *Clock) Cancel(handle TaskHandle)
- func (c *Clock) RunAll() error
- func (c *Clock) SetInterval(task SafeTaskCallback, delay time.Duration) TaskHandle
- func (c *Clock) SetTimeout(task TaskCallback, delay time.Duration) TaskHandle
- func (c *Clock) Tick() error
- type NewClockOption
- type SafeTaskCallback
- type TaskCallback
- type TaskHandle
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Clock ¶
type Clock struct {
Time time.Time
// Sets the number of times a task is allowed to run without seeing a
// reduction in task list size. I.e., the task list doesn't need to be
// emptied after the specified no of tasks executed, but the smallest
// observed size of the queue must have decreased. The counter is reset
// every time a new minimum of remaining number of tasks is noticed
MaxLoopWithoutDecrement int
// contains filtered or unexported fields
}
Clock simulates passing of time, as well as potential future tasks. Simulated Time can be advanced using Clock.Advance or Clock.RunAll. The zero value for Clock represents Unix time 0, and will not panic.
Advance and RunAll will return an error if any of the executed tasks return an error; Advance and RunAll panics if the task list isn't reducing.
Advancing the clock panics if the task queue isn't decreasing, i.e, tasks are adding new tasks. This will happen if a JavaScript call to setInterval isn't cleared before calling [RunAll], or a setInterval callback that continuously adds a new immediate callback, or a microtasks creating a new microtask.
This is designed to panic rather than return an error, as an error represents an error generated by the code being tested. You may choose to ignore it, or even assert on it's precense when testing error conditions. But a task list that doesn't decrease is an error in the test itself, that the developer should be notified of; which is why the design is a panic.
The behaviour is configurable by the MaxLoopWithoutDecrement value.
func New ¶
func New(options ...NewClockOption) *Clock
Creates a new clock. If the options don't set a specific time, the clock is initialised with the current system time as the initial simulated wall clock time.
If tests depend on an actual time, e.g., verifying a local time displaed in the user interface, then test code should pass a concrete starting time; letting the test execution be independent of the running environment.
The option should only be left out if the test only needs to verify behaviour due to passing of time. E.g., testing throttling/debouncing/timeouts.
func (*Clock) AddMicrotask ¶
func (c *Clock) AddMicrotask(task TaskCallback)
AddMicrotask adds a task to the "microtask queue".
This shouldn't be called from Go code. Microtasks are a property of JavaScript execution and should really be carried out by the javascript engine.
func (*Clock) AddSafeMicrotask ¶
func (c *Clock) AddSafeMicrotask(task SafeTaskCallback)
AddSafeMicrotask is a version of AddMicrotask, where the caller can guarantee the task doesn't generate an error.
func (*Clock) AddSafeTask ¶
func (c *Clock) AddSafeTask(task SafeTaskCallback, delay time.Duration) TaskHandle
Schedules a task to run at a specified time in the future. Panics if the time is in the past.
func (*Clock) Advance ¶
Advances the clock by the specified amount of time. Any new tasks being registered while running will be executed; if they are scheduled _before_ the timeout. When returning, the clock time will be the current time + the duration.
Returns an error if any of the added tasks generate an error. Panics if the task list doesn't decrease in size. See Clock documentation for more info.
func (*Clock) Cancel ¶
func (c *Clock) Cancel(handle TaskHandle)
Cancel removes the task that have been added using Clock.SetTimeout or Clock.SetInterval. This corresponds to either clearTimeout or clearInterval in the browser, which by specification can be used interchangably; but shouldn't for clarity.
func (*Clock) RunAll ¶
Keeps running as long as there are tasks in the task queue. New tasks appended while running will also run. When returning, the current time will be the time of the last executed task.
Returns an error if any of the added tasks generate an error. Panics if the task list doesn't decrease in size. See Clock documentation for more info.
func (*Clock) SetInterval ¶
func (c *Clock) SetInterval(task SafeTaskCallback, delay time.Duration) TaskHandle
SetInterval corresponds to the browser's [setInterval] function. Panics if the delay is negative.
func (*Clock) SetTimeout ¶
func (c *Clock) SetTimeout(task TaskCallback, delay time.Duration) TaskHandle
SetInterval corresponds to the browser's [setTimeout] function. Panics if the delay is negative.
type NewClockOption ¶
type NewClockOption func(*Clock)
NewClockOption are used to initialize a new Clock
func OfIsoString ¶
func OfIsoString(iso string) NewClockOption
Initializes the clock's simulated time based on an RFC3339 time string. Panics if the string is not valid.
This is intended for the use case where the time is a constant in a test case, and as such will either fail or succeed consistently. For variable input, the caller should parse the time and use OfTime instead.
type SafeTaskCallback ¶
type SafeTaskCallback func()
A SafeTaskCallback is the callback that registered for a [futureTask] that can't generate an err.r
type TaskCallback ¶
type TaskCallback func() error
A TaskCallback is the callback registered for a [futureTask].
type TaskHandle ¶
type TaskHandle uint32
Source Files