tqtesting

type SimulationParams struct {
	Deadline           time.Time                     // default is "don't stop on deadline"
	ShouldStopBefore   func(t Task) bool             // returns true if simulation should stop
	ShouldStopAfter    func(t Task) bool             // returns true if simulation should stop
	UnknownTaskHandler func(t *taskqueue.Task) error // handles unrecognized tasks
}

type Task struct {
	Task    *taskqueue.Task // original task queue task
	Payload proto.Message   // deserialized payload or nil if unrecognized
}

type TaskList []Task

type Testable interface {
	// CreateQueues creates all push queues used by registered tasks.
	CreateQueues()

	// GetScheduledTasks fetches all scheduled tasks.
	//
	// Returned tasks are sorted by ETA (earliest first) and Name.
	GetScheduledTasks() TaskList

	// ExecuteTask executes a handler for the given task in a derivative of a
	// given context.
	//
	// Returns whatever the handle returns or a general error if the task can't
	// be dispatched.
	ExecuteTask(ctx context.Context, task Task, hdr *taskqueue.RequestHeaders) error

	// RunSimulation simulates task queue service by running enqueued tasks.
	//
	// It looks at all pending tasks, picks the one with smallest ETA, moves the
	// test clock and executes the task, looks at all pending tasks again, picks
	// the one with smallest ETA, and so on ...
	//
	// Panics if there's no test clock in the context. Assumes complete control
	// of the task queue service (e.g if something is popping or resetting tasks
	// in parallel, bad things will happen).
	//
	// If it encounters an unrecognized task, calls params.UnknownTaskHandler to
	// handle it. Unrecognized tasks are still returned in 'executed' and
	// 'pending' sets, except they don't have 'Payload' set.
	//
	// It stops whenever any of the following happens:
	//   * The queue of pending tasks is empty.
	//   * ETA of the next task is past deadline (set via SimulationParams).
	//   * ShouldStopBefore(...) returns true for the next to-be-executed task.
	//   * ShouldStopAfter(...) returns true for the just-executed task.
	//   * A task returns an error. The bad task will be last in 'executed' list.
	//
	// Returns:
	//   executed: executed tasks, in order of their execution.
	//   pending: tasks to be executed (when hitting a deadline or an error).
	//   err: an error produced by the failed task (when exiting on an error).
	RunSimulation(ctx context.Context, params *SimulationParams) (executed, pending TaskList, err error)
}