fftest

Documentation

Overview

Package fftest provides tools for testing flag sets.

Index

• Variables
• func Compare(t *testing.T, want, have *Vars)
• func DiffString(a, b string) string
• func UnindentString(s string, prefixes ...string) string
• func ValidateFlags(t *testing.T, fs ff.Flags, args []string)
• type Constructor
  • func NewNestedConstructor(delim string) Constructor
• type ParseTest
  • func (tc *ParseTest) Run(t *testing.T)
• type TestCases
  • func (tcs TestCases) Run(t *testing.T)
• type Vars

Examples

• UnindentString

Variables

var CoreConstructor = Constructor{
	Name: "ff.FlagSet",
	Make: func(def Vars) (ff.Flags, *Vars) {
		var v Vars
		fs := ff.NewFlagSet("fftest")
		fs.StringVar(&v.S, 's', "str", def.S, "string")
		fs.IntVar(&v.I, 'i', "int", def.I, "int")
		fs.Float64Var(&v.F, 'f', "flt", def.F, "float64")
		fs.BoolVarDefault(&v.A, 'a', "aflag", def.A, "bool a")
		fs.BoolVarDefault(&v.B, 'b', "bflag", def.B, "bool b")
		fs.BoolVarDefault(&v.C, 'c', "cflag", def.C, "bool c")
		fs.DurationVar(&v.D, 'd', "dur", def.D, "time.Duration")
		fs.AddFlag(ff.FlagConfig{ShortName: 'x', LongName: "xxx", Placeholder: "STR", Usage: "collection of strings (repeatable)", Value: ffval.NewList(&v.X)})
		return fs, &v
	},
}

CoreConstructor produces a standard flag set with both short and long names.

var DefaultConstructors = []Constructor{
	CoreConstructor,
	StdConstructor,
}

DefaultConstructors are used for test cases that don't specify constructors.

var StdConstructor = Constructor{
	Name: "flag.FlagSet",
	Make: func(def Vars) (ff.Flags, *Vars) {
		var v Vars
		fs := flag.NewFlagSet("fftest", flag.ContinueOnError)
		fs.StringVar(&v.S, "s", def.S, "string")
		fs.IntVar(&v.I, "i", def.I, "int")
		fs.Float64Var(&v.F, "f", def.F, "float64")
		fs.BoolVar(&v.A, "a", def.A, "bool a")
		fs.BoolVar(&v.B, "b", def.B, "bool b")
		fs.BoolVar(&v.C, "c", def.C, "bool c")
		fs.DurationVar(&v.D, "d", def.D, "time.Duration")
		fs.Var(ffval.NewList(&v.X), "x", "collection of strings (repeatable)")
		return ff.NewFlagSetFrom(fs.Name(), fs), &v
	},
}

StdConstructor produces a stdlib flag set adapter.

Functions

func Compare

func Compare(t *testing.T, want, have *Vars)

Compare one set of vars with another and t.Error on any difference.

func DiffString

func DiffString(a, b string) string

DiffString produces a git-like diff of two multi-line strings.

func UnindentString

func UnindentString(s string, prefixes ...string) string

UnindentString trims s of leading and trailing whitespace, and then trims each line in s of every prefix. If no prefixes are provided, each line is trimmed of all leading tab characters. This allows multi-line strings to be written in-line with other code, while remaining comparable.

Example

fs := ff.NewFlagSet("testcommand")
fs.String('f', "foo", "", "the foo parameter")
fs.IntLong("bar", 3, "the bar parameter")

want := fftest.UnindentString(`
		NAME
		  testcommand

		FLAGS
		  -f, --foo STRING   the foo parameter
		      --bar INT      the bar parameter (default: 3)
	`)

have := fftest.UnindentString(ffhelp.Flags(fs).String())

if want == have {
	fmt.Println("strings are identical")
} else {
	fmt.Println(fftest.DiffString(want, have))
}

Output:

strings are identical

func ValidateFlags

func ValidateFlags(t *testing.T, fs ff.Flags, args []string)

ValidateFlags checks the core invariants of a flag set and its flags. The provided flag set should contain at least two flags, and calling parse with the provided args should succeed.

Types

type Constructor

type Constructor struct {
	// Name of the constructor, used in test names.
	Name string

	// Make should return a flag set and vars structure, where each value in the
	// vars structure is updated by a corresponding flag in the flag set. The
	// default value for each flag should be taken from the def parameter.
	Make func(def Vars) (ff.Flags, *Vars)
}

Constructor produces a flag set, and a set of vars managed by that flag set.

func NewNestedConstructor

func NewNestedConstructor(delim string) Constructor

NewNestedConstructor returns a constructor where flags have specific hierarchical names delimited by the provided delim. This is useful for testing config file formats that allow nested configuration.

type ParseTest

type ParseTest struct {
	Name         string
	Constructors []Constructor
	Default      Vars
	ConfigFile   string
	Environment  map[string]string
	Args         []string
	Options      []ff.Option
	Want         Vars
}

ParseTest describes a parsing test scenario.

func (*ParseTest) Run

func (tc *ParseTest) Run(t *testing.T)

Run the test case.

type TestCases

type TestCases []ParseTest

TestCases are a collection of test cases that can be run as a group.

func (TestCases) Run

func (tcs TestCases) Run(t *testing.T)

Run the test cases in order.

type Vars

type Vars struct {
	S       string        // flag name `s`
	I       int           // flag name `i`
	F       float64       // flag name `f`
	A, B, C bool          // flag name `a`, `b`, `c`
	D       time.Duration // flag name `d`
	X       []string      // flag name `x`

	// ParseError should be assigned as the result of Parse in tests.
	ParseError error

	// If a test case expects an input to generate a parse error,
	// it can specify that error here. The Compare helper will
	// look for it using errors.Is.
	WantParseErrorIs error

	// If a test case expects an input to generate a parse error,
	// it can specify part of that error string here. The Compare
	// helper will look for it using strings.Contains.
	WantParseErrorString string

	// Args left over after a successful parse.
	Args []string
}

Vars are a common set of variables used for testing.