taskgraphtest

type BindingMatcher interface {
	// ID should return the id of the binding to be checked.
	ID() tg.ID

	// Match should return an error if the binding does not match, and nil otherwise.
	Match(got tg.Binding) error
}

type Suite struct {
	// Graph defines the Graph to be tested. Should not be set in conjunction with Task. The Graph or
	// Task to be tested is preferentially read from each Test, falling back to the Suite (if used).
	Graph tg.Graph

	// Task provides a convenient approach for testing individual tasks; the given Task is turned into
	// a single-node Graph. Should not be set in conjunction with Graph. The Graph or Task to be
	// tested is preferentially read from each Test, falling back to the Suite (if used).
	//
	// For compatibility with helpers which accept and return TaskSets, this field is a TaskSet, but
	// the set is expected to contain a single element.
	Task tg.TaskSet

	// Tests defines the individual tests to be run.
	Tests []Test

	// How long the task/graph should be allowed to run in each test. If unset, defaults to 10 seconds
	Timeout time.Duration
}

type Test struct {
	// Description is passed to testing.T.Run when this test is part of a suite; it may be omited if
	// the test is used in isolation.
	Description string

	// Graph defines the Graph to be tested. Should not be set in conjunction with Task. The Graph or
	// Task to be tested is preferentially read from the Test, falling back to the Suite (if used).
	Graph tg.Graph

	// Task provides a convenient approach for testing individual tasks; the given Task is turned into
	// a single-node Graph. Should not be set in conjunction with Graph. The Graph or Task to be
	// tested is preferentially read from the Test, falling back to the Suite (if used).
	//
	// For compatibility with helpers which accept and return TaskSets, this field is a TaskSet, but
	// the set is expected to contain a single element.
	Task tg.TaskSet

	// Inputs defines the inputs passed to the graph for the test.
	Inputs []tg.Binding

	// WantError defines the expected error returned from the Graph's execution (note that the test
	// will always fail if Graph setup/configuration fails). Compared using errors.Is.
	WantError error

	// WantBindings defines the expected set of bindings to be available once the graph/task is run.
	// Note that unless CheckExcessBindings is set, this field need not contain every single binding
	// produced by a graph (and in general it is advisable that it doesn't to avoid fragile tests).
	WantBindings []BindingMatcher

	// WantPendingBindings defines a set of IDs which should not have been bound by the graph. This
	// is typically only used for testing the framework itself (asserting that IDs are unbound when
	// errors occur)
	WantPendingBindings []tg.ID

	// CheckExcessBindings, if true, causes the graph result to be checked for the presence of
	// bindings not in WantBindings. This option should be used sparingly, as it can lead to fragile
	// tests. Note that this will not play nicely with virtual bindings such as those generated
	// by tg.Presence().
	CheckExcessBindings bool

	// WantInputBindings defines matchers on input bindings (i.e. those in Inputs) which are checked
	// after the graph is run. This can be used to check for side effects on inputs.
	WantInputBindings []BindingMatcher

	// How long the task/graph should be allowed to run. If unset, defaults to 10 seconds
	Timeout time.Duration
}