chore: add README to clock testing #13583
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
This stack of pull requests is managed by Graphite. Learn more about stacking. Join @spikecurtis and the rest of your teammates on |
johnstcn
approved these changes
Jun 17, 2024
clock/README.md
Outdated
| * [github.com/aspenmesh/tock](https://github.com/aspenmesh/tock) | ||
|
|
||
| Quartz shares the high level design of a `Clock` interface that closely resembles the functions in | ||
| the `time` standard library, and a "real" clock passes thru to the standard libary in production, |
There was a problem hiding this comment.
Suggested change
| the `time` standard library, and a "real" clock passes thru to the standard libary in production, | |
| the `time` standard library, and a "real" clock passes through to the standard library in production, |
There was a problem hiding this comment.
clock/README.md
Outdated
Comment on lines
9
to
10
| Writing good unit tests for components and functions that use the `time` package is difficult, and | ||
| several open source libraries exist. In building Quartz, we took some inspiration from |
There was a problem hiding this comment.
Suggested change
| Writing good unit tests for components and functions that use the `time` package is difficult, and | |
| several open source libraries exist. In building Quartz, we took some inspiration from | |
| Writing good unit tests for components and functions that use the `time` package is difficult, even though | |
| several open source libraries exist. In building Quartz, we took some inspiration from |
clock/README.md
Outdated
Comment on lines
103
to
106
| (As an aside, we still support a traditional standard library-style `Ticker`, if you want to keep | ||
| your code as close as possible to the standard library, or if you need to use the channel in a | ||
| larger `select` block, but in that case you'll have to find some other mechanism to sync tick | ||
| processing to your test code.) |
There was a problem hiding this comment.
Run-on sentence, consider breaking up.
| Our high level goal is to write unit tests that | ||
|
|
||
| 1. execute quickly | ||
| 2. don't flake |
There was a problem hiding this comment.
suggestion: avoid colloquialism
Suggested change
| 2. don't flake | |
| 2. execute reliably |
There was a problem hiding this comment.
While arguably "jargon", I think flaky is more precise. It refers to tests that succeed or fail due to uncontrolled randomness.
A test might not be reliable for other reasons, such as not actually testing or asserting the thing it purports to.
| For several reasons, this is a tall order when it comes to code that depends on time, and we found | ||
| the existing libraries insufficient for our goals. | ||
|
|
||
| For tests to execute quickly without flakes, we want to focus on _determinism_: the test should run |
There was a problem hiding this comment.
Suggested change
| For tests to execute quickly without flakes, we want to focus on _determinism_: the test should run | |
| For tests to execute quickly and reliably, we want to focus on _determinism_: the test should run |
e4294f1 to
ba76a30
Compare
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adds README with some draft content explaining why the library exists. Will be most relevant when we spin out into a standalone library.