tqtesting

Documentation

Overview

Package tqtesting can be used in unit tests to simulate task queue calls produced by tq.Dispatcher.

Index

• type SimulationParams
• type Task
• type TaskList
  • func (l TaskList) Len() int
  • func (l TaskList) Less(i, j int) bool
  • func (l TaskList) Payloads() (out []proto.Message)
  • func (l TaskList) Swap(i, j int)
• type Testable
  • func GetTestable(ctx context.Context, d *tq.Dispatcher) Testable

Types

type SimulationParams

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
}

SimulationParams are passed to RunSimulation.

type Task

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

Task represents a scheduled tq Task.

type TaskList

type TaskList []Task

TaskList is a sortable list of Task structs.

func (TaskList) Len

func (l TaskList) Len() int

func (TaskList) Less

func (l TaskList) Less(i, j int) bool

func (TaskList) Payloads

func (l TaskList) Payloads() (out []proto.Message)

Payloads collects payloads of each task into a slice.

Useful when writing asserts in tests.

func (TaskList) Swap

func (l TaskList) Swap(i, j int)

type Testable

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)
}

Testable can be used from unit tests that posts TQ tasks.

It assumes Dispatcher is in complete control of all Task Queue tasks, e.g. if some handlers add task queue tasks directly, they are going to be clobbered by Testable's PopTasks.

func GetTestable

func GetTestable(ctx context.Context, d *tq.Dispatcher) Testable

GetTestable returns an interface for TQ intended to be used only from tests.

Panics if used with production Task Queue implementation.