diff --git a/README.md b/README.md index 4274d99..0abfb84 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,44 @@ # faket [![GoDoc][doc-img]][doc] [![Build Status][ci-img]][ci] [![Coverage][codecov-img]][codecov] -Are your test helpers correct -- test them with `faket`. +Are your test helpers correct -- be confident with faket. ## Introduction -Test helper functions play a crucial role in -encapsulating common validation patterns -and keeping your tests DRY (Don't Repeat Yourself). +Test helper functions taking a `testing.TB` are +helpful for encapsulating common validation patterns +and DRY'ing up tests (Don't Repeat Yourself). -These helpers often accept a `testing.TB` to report failures -but it can be tricky to test failure scenarios. - -As these helpers grow in complexity and become widely used, -verifying their behaviour becomes important-- +These helpers are not immune from bugs and +as they grow in complexity and become widely used. +Verifying their behaviour becomes important-- your tests' correctness depends upon them! -Failure handling by test helpers is particularly critical: - * Do they indicate all errors, or fail on required checks? +How do you test scenarios where the helper is expected to fail? +Using a real `testing.T` would fail the test, +when you want the opposite: +the test should fail if the helper passes unexpectedly +but pass if the helper fails with the expected failures! + +faket lets you validate correctness of your helpers +using a fake `testing.TB`, which provides insight +into the full behaviour of the test function: + + * Are all the expected errors reported? + * Did the helper `Fatal` the test? * Is the output formatted correctly - and does it include all relevant information? + with all the relevant information? -`faket` addresses these challenges by providing a fake `testing.TB` -so you can validate correctness of your test helpers -and ensure the reported messages are accurate and meaningful. +### Example -Let's take an example helper used to verify -if a string contains expected substrings in order: +Let's test a helper used to verify +a string contains expected substrings in order: ```go func StrContainsInOrder(t testing.TB, got string, contains ...string) ``` -`faket` can be used to test that the helper behaves as expected: +With faket, both successful and failure scenarios can be tested: ```go func TestStrContainsInOrder(t *testing.T) { t.Run("correct order", func(t *testing.T) { @@ -54,9 +60,8 @@ func TestStrContainsInOrder(t *testing.T) { * Fully-featured implementation of `testing.TB` including `Skip`, `Fatal`, and `Cleanup`. * Thoroughly tested against the real `testing.TB` - implementations to ensure correct behaviour - * E.g., ensuring skips within cleanups work the same way. - * Panic handling. + to ensure correct behaviour. + * Panic handling to allow validation of expected panics. ## Installation @@ -64,9 +69,10 @@ func TestStrContainsInOrder(t *testing.T) { faket is only supported and tested against the 2 most recent minor versions of Go. -## Development Status: Development +## Development Status: Alpha -This library is still in development, and is not API stable. +This library is ready for use **in tests**, +but it's _not_ API stable. [doc-img]: https://pkg.go.dev/badge/github.com/prashantv/zap [doc]: https://pkg.go.dev/github.com/prashantv/faket