Documentation
¶
Overview ¶
Package testverbhelp is the per-tool check of the verb-help rule (the CLI style's rule (b), #4505; pkg/nsprint/verbflag is the one seam that implements it): `<tool> <verb> -h` and `--help` print that verb's help on stdout and exit 0, with nothing on stderr, no file written and no dial. The check opens no socket: it is a unit-tier check.
Each tool's test names its verbs and, for each, the flags that would point the verb at a place: a path flag gets {dir}/..., a store address gets {addr}. They are given BEFORE -h, so the parser has taken them when it meets -h, and the check then holds that nothing was created under {dir}. {addr} is RefusedAddr, a loopback port nothing listens on: the check owns no socket, and a verb that dials before it answers -h meets a refusal and fails the exit or stderr clause. How long help takes is a performance check, not a unit one: it is held only under -tags perf (budget_perf.go), and the perf job runs it through each tool's perf-only TestEveryVerbsHelpIsWithinTheBudget.
Index ¶
- Constants
- func Check(t *testing.T, run Run, cases []Case)
- func Complete(t *testing.T, cases []Case, seen []captured)
- func Completeness(run Run, c Case, dir string) (tool string, gaps []string)
- func Gaps(help, refusal string) []string
- func HelpVerb(t *testing.T, run Run, tool string, verbs ...string)
- func Judge(key string, gaps, ledgered []string) []string
- func Ledger(text string) (map[string][]string, error)
- func LedgerPath() string
- func One(t *testing.T, run Run, c Case, spelling string)
- func Problems(run Run, c Case, spelling, dir string) []string
- func RefusalProblems(run Run, c Case, dir string) []string
- type Case
- type Run
Constants ¶
const ( GapUsage = "usage" GapDescription = "description" GapExample = "example" GapExitCodes = "exit-codes" // GapFlagPrefix is followed by a flag's name: the flag has no description. GapFlagPrefix = "flag-undescribed:" // GapMissingPrefix is followed by a flag's name: the refusal names it, -h does not print it. GapMissingPrefix = "flag-missing:" )
Gap names, as the ledger spells them.
const RefusedAddr = "127.0.0.1:1"
RefusedAddr is what {addr} becomes: loopback port 1, where nothing listens, so a dial is refused at once and the check needs no listener of its own.
const UnknownFlag = "--no-such-flag-breadcrumb"
UnknownFlag is a flag no verb defines. Every verb that is handed it refuses.
Variables ¶
This section is empty.
Functions ¶
func Completeness ¶
Completeness runs one case with -h, and with an unknown flag to read the set's flags, and returns the verb's tool and gaps.
func Gaps ¶
Gaps is what the help text lacks of the rule, in the ledger's spelling, sorted. refusal is the stderr of the verb handed UnknownFlag ("" when not known); the flags it lists are the set's.
func HelpVerb ¶
HelpVerb checks `<tool> help <verb>` for a tool whose help verb takes one: the same help `<verb> -h` prints, on stdout, at exit 0, nothing on stderr.
func Judge ¶
Judge compares one verb's gaps with its ledger row (nil: none), and returns the problems: a gap not in the ledger, a ledger part already fixed.
func Ledger ¶
Ledger is the ledger's rows: "<tool> <verb>" to its gaps. A malformed line is an error.
func LedgerPath ¶
func LedgerPath() string
LedgerPath is the shrink-only ledger, found from this source file.
func Problems ¶
Problems runs one case with one spelling of help, with {dir} as dir, and returns every way it broke the rule; none is a pass.
func RefusalProblems ¶
RefusalProblems runs one case with UnknownFlag and returns every way the refusal broke the rule: a tool or verb never fails silently, and every refusal carries a breadcrumb to the fix. It is the runtime half of internal/ci's remedy and no-ok-on-failure rules, run through the same seam every verb parses its flags with:
- the exit is not 0: an invocation the verb cannot parse did not succeed;
- something is said on stderr, and it names the flag or the usage, or a remedy in the house form (oneline.HasRemedy): never silent, and a breadcrumb to the fix;
- no line on stdout closes with OK: the last word of a failed run is never OK;
- nothing is written under {dir} and nothing dials: the refusal comes before the work.
Source Files