Show HN: A tool that renders your tests as readable documentation

I came up with this idea because I was trying to encourage people to think about how they name their tests. One useful technique is to make the test name a complete (but brief) sentence describing the required behaviour.

This is helpful when the test fails, because you see the name printed out as part of the failure message. But it's also a good thinking tool as you're writing the test, because you have to start by deciding exactly what the behaviour under test should be.

As some guy named Sam Altman said, "If it takes more than a sentence to explain what you're doing, that's almost always a sign that it's too complicated." This is a good guide for programmers too, because the amount of behaviour that can be concisely described in a sentence is also about the right amount for a software component or function.

Hence a program that parses your (Go) test names, eliminating camel case and underscores and so forth, and prints them out as readable English sentences. For example, if the test name is 'TestFooReturnsErrorForInvalidInput', the program will print:

  Foo returns error for invalid input

(preceded by a tick or a cross to show the current test status)

To try it out, run:

  go install github.com/bitfield/gotestdox/cmd/gotestdox@latest

Then run 'gotestdox' in some Go project or package (the default target is the current package, but it can also take any arguments that 'go test' takes, such as a package list like './...').

The original implementation of this simple but useful idea was 'agiledox', written by Chris Stevenson for JUnit. It has been ported to various other languages and test frameworks, but not (as far as I know) to Go, until now.

I wrote an article explaining in more depth why I think test names should be written as sentences, and how 'gotestdox' can help with that: https://bitfieldconsulting.com/golang/test-names