README
¶
testclarity is a command-line tool for giving clarity to your go tests. Here's how to install it:
go install github.com/sreyardship/testclarity/cmd/testclarity@latest
All credits should go to https://github.com/sreyardship/testclarity from which this project is forked.
Why fork?
gotestdox is very focused on the "documentation" part of the equation. I.e. taking your test name and generate documenation out of those. We believe this should be taken a step further and into your daily development work. By constantly showing you the resulting documentation generated by your test names you are able to faster realize when you're design is badly designed. This is based on the assumption that the intent of the test informs the usefulness of it, which we believe is usually the case (no empherical research to back that up though).
For reference see:
What extra features are there then?
Today there's only one flag -v which makes testclarity verbose and prints the output of tests with filename and numbers. But features in line with the vision for this tooling will be integrated and developed going forward, in lieu of time.
Links
Gopher image by MariaLetta
Documentation
¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var DebugWriter io.Writer = os.Stderr
DebugWriter identifies the stream to which debug information should be printed, if desired. By default it is os.Stderr.
Functions ¶
func Main ¶
func Main() int
Main runs the command-line interface for gotestdox. The exit status for the binary is 0 if the tests passed, or 1 if the tests failed, or there was some error.
func Prettify ¶
Prettify takes a string input representing the name of a Go test, and attempts to turn it into a readable sentence, by replacing camel-case transitions and underscores with spaces.
input is expected to be a valid Go test name, as produced by 'go test -json'. For example, input might be the string:
TestFoo/has_well-formed_output
Here, the parent test is TestFoo, and this data is about a subtest whose name is 'has well-formed output'. Go's testing package replaces spaces in subtest names with underscores, and unprintable characters with the equivalent Go literal.
Prettify does its best to reverse this transformation, yielding (something close to) the original subtest name. For example:
Foo has well-formed output
Multiword function names ¶
Because Go function names are often in camel-case, there's an ambiguity in parsing a test name like this:
TestHandleInputClosesInputAfterReading
We can see that this is about a function named HandleInput, but Prettify has no way of knowing that. Without this information, it would produce:
Handle input closes input after reading
To give it a hint, we can add an underscore after the name of the function:
TestHandleInput_ClosesInputAfterReading
This will be interpreted as marking the end of a multiword function name:
HandleInput closes input after reading
Debugging ¶
If the GOTESTDOX_DEBUG environment variable is set, Prettify will output (copious) debug information to the DebugWriter stream, elaborating on its decisions.
Example ¶
input := "TestFoo/has_well-formed_output" fmt.Println(gotestdox.Prettify(input))
Output: Foo has well-formed output
Example (UnderscoreHint) ¶
input := "TestHandleInput_ClosesInputAfterReading" fmt.Println(gotestdox.Prettify(input))
Output: HandleInput closes input after reading
Types ¶
type Event ¶
type Event struct {
Action string
Package string
Test string
Sentence string
Output string
Elapsed float64
}
Event represents a Go test event as recorded by the 'go test -json' command. It does not attempt to unmarshal all the data, only those fields it needs to know about. It is based on the (unexported) 'event' struct used by Go's cmd/internal/test2json package.
func ParseJSON ¶
ParseJSON takes a string representing a single JSON test record as emitted by 'go test -json', and attempts to parse it into an Event, returning any parsing error encountered.
Example ¶
package main
import (
"fmt"
"log"
gotestdox "github.com/sreyardship/testclarity"
)
func main() {
input := `{"Action":"pass","Package":"demo","Test":"TestItWorks","Output":"test","Elapsed":0.2}`
event, err := gotestdox.ParseJSON(input)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%#v\n", event)
}
Output: gotestdox.Event{Action:"pass", Package:"demo", Test:"TestItWorks", Sentence:"", Output:"test", Elapsed:0.2}
func (Event) IsFinishedTest ¶
IsFinishedTest determines whether or not the test event represent that the test has finished (namely, a pass or fail event on a test). Events on non-tests (for example, examples) are ignored, and all events on tests other than pass or fail events (for example, run or pause events) are also ignored.
Example (False) ¶
package main
import (
"fmt"
gotestdox "github.com/sreyardship/testclarity"
)
func main() {
event := gotestdox.Event{
Action: "fail",
Test: "ExampleIsIrrelevant",
}
fmt.Println(event.IsFinishedTest())
}
Output: false
Example (True) ¶
package main
import (
"fmt"
gotestdox "github.com/sreyardship/testclarity"
)
func main() {
event := gotestdox.Event{
Action: "pass",
Test: "TestItWorks",
}
fmt.Println(event.IsFinishedTest())
}
Output: true
func (Event) IsPackageResult ¶
IsPackageResult determines whether or not the test event is a package pass or fail event. That is, whether it indicates the passing or failing of a package as a whole, rather than some individual test within the package.
func (Event) String ¶
String formats a test Event for display. The prettified test name will be prefixed by a ✔ if the test passed, or an x if it failed.
The sentence generated by Prettify from the name of the test will be shown, followed by the elapsed time in parentheses, to 2 decimal places.
Colour ¶
If the program is attached to an interactive terminal, as determined by github.com/mattn/go-isatty, and the NO_COLOR environment variable is not set, check marks will be shown in green and x's in red.
Example ¶
package main
import (
"fmt"
"github.com/fatih/color"
gotestdox "github.com/sreyardship/testclarity"
)
func main() {
event := gotestdox.Event{
Action: "pass",
Sentence: "It works",
}
color.NoColor = true
fmt.Println(event.String())
}
Output: ✔ It works (0.00s)
type TestDoxer ¶
TestDoxer holds the state and config associated with a particular invocation of 'go test'.
func NewTestDoxer ¶
func NewTestDoxer() *TestDoxer
NewTestDoxer returns a *TestDoxer configured with the default I/O streams: os.Stdin, os.Stdout, and os.Stderr.
func (*TestDoxer) ExecGoTest ¶
ExecGoTest runs the 'go test -json' command, with any extra args supplied by the user, and consumes its output. Any errors are reported to td's Stderr stream, including the full command line that was run. If all tests passed, td.OK will be true. If there was a test failure, or 'go test' returned some error, then td.OK will be false.
func (*TestDoxer) Filter ¶
Filter reads from td's Stdin stream, line by line, processing JSON records emitted by 'go test -json'.
For each Go package it sees records about, it will print the full name of the package to td.Stdout, followed by a line giving the pass/fail status and the prettified name of each test, sorted alphabetically. It can also print the output of the tests if the "printTestOutput" parameter is set to true.
If all tests passed, td.OK will be true at the end. If not, or if there was a parsing error, it will be false. Errors will be reported to td.Stderr.
Example ¶
package main
import (
"strings"
"github.com/fatih/color"
gotestdox "github.com/sreyardship/testclarity"
)
func main() {
input := `{"Action":"pass","Package":"demo","Test":"TestItWorks"}
{"Action":"pass","Package":"demo","Elapsed":0}`
td := gotestdox.NewTestDoxer()
td.Stdin = strings.NewReader(input)
color.NoColor = true
td.Filter(false)
}
Output: demo: ✔ It works (0.00s)
Source Files
Directories