https://github.com/jonboulle/clockwork

a fake clock for golang
https://github.com/jonboulle/clockwork

Last synced: about 2 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 (over 10 years ago)
• Default Branch: master
• Last Pushed: 2024-10-17T23:20:27.000Z (2 months ago)
• Last Synced: 2024-10-25T08:34:00.672Z (about 2 months ago)
• Language: Go
• Size: 88.9 KB
• Stars: 662
• Watchers: 11
• Forks: 58
• 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)

README

        
# clockwork

[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go#utilities)

[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/jonboulle/clockwork/ci.yaml?style=flat-square)](https://github.com/jonboulle/clockwork/actions?query=workflow%3ACI)

[![Go Report Card](https://goreportcard.com/badge/github.com/jonboulle/clockwork?style=flat-square)](https://goreportcard.com/report/github.com/jonboulle/clockwork)

![Go Version](https://img.shields.io/badge/go%20version-%3E=1.15-61CFDD.svg?style=flat-square)

[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](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.