testkit

type Action interface {
	// Caption returns the caption that should be used for this action in the
	// test report.
	Caption() string

	// Location returns the location within the code that the action was
	// constructed.
	Location() location.Location

	// ConfigurePredicate updates o with any options required by the action.
	//
	// It is called before Do() when the action is used with Test.Expect().
	ConfigurePredicate(o *PredicateOptions)

	// Do performs the action within the context of a specific test.
	Do(ctx context.Context, s ActionScope) error
}

type ActionScope struct {
	// App is the application being tested.
	App configkit.RichApplication

	// VirtualClock is the time that the Test uses as the engine time for the
	// NEXT Action.
	VirtualClock *time.Time

	// Engine is the engine used to handled messages.
	Engine *engine.Engine

	// Executor is the command executor returned by the Test's CommandExecutor()
	// method.
	Executor *engine.CommandExecutor

	// Recorder is the event recorder returned by the Test's EventRecorder()
	// method.
	Recorder *engine.EventRecorder

	// OperationOptions is the set of options that should be used with calling
	// Engine.Dispatch() or Engine.Tick().
	OperationOptions []engine.OperationOption
}

type Expectation interface {
	// Caption returns the caption that should be used for this action in the
	// test report.
	Caption() string

	// Predicate returns a new predicate that checks that this expectation is
	// satisfied.
	//
	// The predicate must be closed by calling Done() once the action it tests
	// is completed.
	Predicate(s PredicateScope) (Predicate, error)
}

type Predicate interface {
	fact.Observer

	// Ok returns true if the expectation tested by this predicate has been met.
	//
	// The return value may change as the predicate is notified of additional
	// facts. It must return a consistent value once Done() has been called.
	Ok() bool

	// Done finalizes the predicate.
	//
	// The behavior of the predicate is undefined if it is notified of any
	// additional facts after Done() has been called, or if Done() is called
	// more than once.
	Done()

	// Report returns a report describing whether or not the expectation
	// was met.
	//
	// treeOk is true if the entire "tree" of expectations is considered to have
	// passed. This may not be the same value as returned from Ok() when this
	// expectation is used as a child of a composite expectation.
	//
	// The behavior of Report() is undefined if Done() has not been called.
	Report(treeOk bool) *Report
}

type PredicateOptions struct {
	// MatchDispatchCycleStartedFacts controls whether predicates that look for
	// specific messages should consider messages from DispatchCycleStarted
	// facts.
	//
	// If it is false, the predicate must only match against messages produced
	// by handlers.
	MatchDispatchCycleStartedFacts bool
}

type PredicateScope struct {
	// App is the application being tested.
	App configkit.RichApplication

	// Options contains values that dictate how the predicate should behave.
	// The options are provided by the Test and the Action being performed.
	Options PredicateOptions
}

type Report struct {
	// TreeOk is true if the "tree" that the expectation belongs to passed.
	TreeOk bool

	// Ok is true if this expectation passed.
	Ok bool

	// Criteria is a brief description of the expectation's requirement to pass.
	Criteria string

	// Outcome is a brief description of the outcome of the expectation.
	Outcome string

	// Explanation is a brief description of what actually happened during the
	// test as it relates to this expectation.
	Explanation string

	// Sections contains arbitrary "sections" that are added to the report by
	// the expectation.
	Sections []*ReportSection

	// SubReports contains the reports of any child expectations.
	SubReports []*Report
}

type ReportSection struct {
	Title   string
	Content strings.Builder
}

type SatisfyT struct {
	// Options contains the set of options that change the behavior of the
	// predicate function.
	//
	// They are not necessarily applicable to every predicate.
	Options PredicateOptions

	// Facts is an ordered slice of the facts that occurred.
	Facts []fact.Fact
	// contains filtered or unexported fields
}

type Test struct {
	// contains filtered or unexported fields
}

type TestOption interface {
	// contains filtered or unexported methods
}

type TestingT interface {
	Failed() bool
	Log(args ...interface{})
	Logf(f string, args ...interface{})
	Fatal(args ...interface{})
	FailNow()
	Helper()
}

type TimeAdjustment interface {
	// Description returns a human-readable string that describes how the clock
	// will be advanced.
	//
	// It should complete the sentence "The clock is being advanced...". For
	// example, "by 10 seconds".
	Description() string

	// Step returns the time that the virtual clock should be set to as a result
	// of the adjustment.
	//
	// t is the virtual clock's current time.
	Step(t time.Time) time.Time
}