Documentation
¶
Overview ¶
Package testsource answers the three questions every command that reads _test.go files in this repository used to answer for itself: whether a function name is a Go test entry point, which naming bucket that name falls in, and which files a scan of the tree may look at.
The three had drifted. Two generators counted test functions with rules that disagreed about a name whose first rune after "Test" is neither upper nor lower case, and the naming auditor skipped every name starting with the "TestMain" prefix, so every test named TestMain_Something was counted by the generators and invisible to the auditor. Go's own rule (testing.isTest) is what IsTestFunction implements, and it decides for all of them: the prefix "Test", the next rune not lower case, and exactly "TestMain" excluded as the framework entry point rather than a test.
The walk is here for the same reason. Four commands walked the same tree with two skip lists and two descents that skipped nothing, so "is testdata part of the corpus" had two answers and no recorded reason. SkipDir is that answer, written once: generated and vendored trees (node_modules, dist), a tool's own fixtures (testdata, whose Go files are inputs to a test rather than source this repository holds to its conventions) and every dot-directory.
One predicate deliberately stays where it is. cmd/godoc_tool asks which functions need a test-form doc comment, not which functions the testing package runs, so it keeps TestMain and the lower-case Test-prefixed helpers that IsTestFunction excludes; routing it through here would drop those findings from the documentation audit.
Discovery of the corpus itself is deliberately not here. cmd/gen_stats asks git for the tracked files so that its --check is a function of what is committed, and cmd/gen_testing_docs enumerates packages through go list because it describes packages; sharing the predicate is what those two needed, and sharing the input universe would break both.
Index ¶
Constants ¶
const ( Pattern3Part = "3-part" Pattern2Part = "2-part" PatternNoUnderscore = "no-underscore" PatternTestCov = "TestCov" )
The naming buckets ClassifyTestName sorts a test name into. The convention this repository holds tests to is TestThing_Scenario_Outcome, so a 3-part name is compliant, a 2-part one is tolerated, and the other two are the legacy shapes the naming auditor offers to rewrite.
const FileSuffix = "_test.go"
FileSuffix is what makes a Go file a test file.
Variables ¶
This section is empty.
Functions ¶
func ClassifyTestName ¶
ClassifyTestName returns the naming bucket name falls in. It classifies the name it is given and asks nothing about whether that name is a test, so a caller filters with IsTestFunction first.
func IsTestFunction ¶
IsTestFunction reports whether name is a Go test entry point, by the rule the testing package itself applies: the prefix "Test" followed by a rune that is not lower case, or by nothing at all. "TestMain" is excluded because it is the framework's entry point rather than a test; a longer name that merely starts with those letters, such as TestMain_Flags_Parse, is a test.
func SkipDir ¶
SkipDir reports whether a directory of this base name is left out of a walk that descends into it: a generated or vendored tree, a tool's own fixtures, or a dot directory. The relative names "." and ".." are exempt because they name a tree the caller is already in rather than one to descend into.
A walk root is exempt too, but that is WalkFiles' decision rather than this one: a scan pointed at a fixtures directory scans it, and only what lies below a root is judged by name.
func WalkFiles ¶
WalkFiles calls visit once for every file under each root that policy selects, in lexical order, entering no directory below a root that SkipDir names. A root is always entered, whatever it is called and whether it is a directory or a symlink to one, so a scan asked for one of those directories by name, or through a link, still runs.
It stops at the first error and returns it, whether the walk raised it (an absent root, a directory it may not read) or visit returned it. There is deliberately no best-effort mode: every caller but one is a gate, and a gate that skipped an unreadable directory would certify a tree it never read. A caller that wants to continue past a failure decides that for itself, by swallowing the error inside visit; what it must not do is discard the returned error, because the walk has already stopped by then and the corpus it collected is short with nothing to say so.
Source Files