https://github.com/jonboulle/clockwork
a fake clock for golang
https://github.com/jonboulle/clockwork
Last synced: 4 months ago
JSON representation
a fake clock for golang
- Host: GitHub
- URL: https://github.com/jonboulle/clockwork
- Owner: jonboulle
- License: apache-2.0
- Created: 2014-09-09T18:24:00.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2025-01-02T13:06:52.000Z (6 months ago)
- Last Synced: 2025-03-06T18:52:44.710Z (4 months ago)
- Language: Go
- Size: 97.7 KB
- Stars: 683
- Watchers: 11
- Forks: 59
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-go - clockwork - A simple fake clock for golang. (Utilities / Utility/Miscellaneous)
- awesome-go-extra - clockwork - 09-09T18:24:00Z|2022-07-27T00:54:21Z| (Utilities / Fail injection)
- awesome-go - jonboulle/clockwork
- awesome-go - jonboulle/clockwork
README
# clockwork
[](https://github.com/avelino/awesome-go#utilities)
[](https://github.com/jonboulle/clockwork/actions?query=workflow%3ACI)
[](https://goreportcard.com/report/github.com/jonboulle/clockwork)
[](https://pkg.go.dev/mod/github.com/jonboulle/clockwork)
**A simple fake clock for Go.**
## Usage
Replace uses of the `time` package with the `clockwork.Clock` interface instead.
For example, instead of using `time.Sleep` directly:
```go
func myFunc() {
time.Sleep(3 * time.Second)
doSomething()
}
```
Inject a clock and use its `Sleep` method instead:
```go
func myFunc(clock clockwork.Clock) {
clock.Sleep(3 * time.Second)
doSomething()
}
```
Now you can easily test `myFunc` with a `FakeClock`:
```go
func TestMyFunc(t *testing.T) {
ctx := context.Background()
c := clockwork.NewFakeClock()
// Start our sleepy function
var wg sync.WaitGroup
wg.Add(1)
go func() {
myFunc(c)
wg.Done()
}()
// Ensure we wait until myFunc is waiting on the clock.
// Use a context to avoid blocking forever if something
// goes wrong.
ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()
c.BlockUntilContext(ctx, 1)
assertState()
// Advance the FakeClock forward in time
c.Advance(3 * time.Second)
// Wait until the function completes
wg.Wait()
assertState()
}
```
and in production builds, simply inject the real clock instead:
```go
myFunc(clockwork.NewRealClock())
```
See [example_test.go](example_test.go) for a full example.
# Credits
clockwork is inspired by @wickman's [threaded fake clock](https://gist.github.com/wickman/3840816), and the [Golang playground](https://blog.golang.org/playground#TOC_3.1.)
## License
Apache License, Version 2.0. Please see [License File](LICENSE) for more information.