queryhistory

Documentation

Overview

Package queryhistory provides tools for verifying that a SQL statement history conforms to a set of expectations.

For example...

expectations := Expect("delete1", "insert1").
    Then(func(sequence ExpectationSequence) ExpectationSequence {
        c1 := sequence.Then(Eventually("insert2")).
                       Then(Eventually("update1"))
        c2 := sequence.Then(Eventually("insert3")).
                       Then(Eventually("update2"))
        c1.Then(c2.Eventually())
        return c2
    }).
    Then(Immediately("delete2")

...creates a sequence of expectations, such that:

• "delete1" is expected first,
• "insert1" immediately follows "delete1",
• "insert2" and "insert3" eventually follow "insert1", in any order,
• "update1" eventually follows "insert2"
• "update2" eventually follows "insert3"
• "update2" eventually follows "update1"
• "delete2" immediately follows "update2"

To verify a sequence of expectations, construct a verifier...

verifier := NewVerifier(expectations)

...and make successive calls with actual queries:

result := verifier.AcceptQuery("insert1")

If the verifier accepts a query, it modifies its internal state in order to verify sequenced expectations (e.g. that "q2" eventually follows "q1").

Index

• func MatchQueries(pattern, query string) (bool, error)
• type Expectation
• type ExpectationSequence
  • func ExpectNone() ExpectationSequence
• type ExpectationSequenceVisitor
• type ExpectationSequencer
  • func Expect(head string, tail ...string) ExpectationSequencer
• type ExpectationSequencerFn
  • func Eventually(head string, tail ...string) ExpectationSequencerFn
  • func Immediately(head string, tail ...string) ExpectationSequencerFn
• type History
  • func (h History) At(index int) (string, error)
  • func (h History) String() string
• type Result
• type SequencedExpectation
  • func Query(query string) SequencedExpectation
• type SequencedExpectationSet
• type Verifier
  • func NewVerifier(sequence ExpectationSequence) *Verifier
  • func (v *Verifier) AcceptQuery(query string) *Result
  • func (v *Verifier) History() History
  • func (v *Verifier) Pending() []Expectation
• type VisitControl

Functions

func MatchQueries

func MatchQueries(pattern, query string) (bool, error)

Types

type Expectation

type Expectation interface {
	ExpectQuery(string)
	MatchQuery(string) (bool, error)
	Query() string
	String() string
}

Expectation represents an expectation about the contents of a query.

type ExpectationSequence

type ExpectationSequence interface {
	Count() int
	// Head returns the head of the sequence. A sequence may only have one
	// head.
	Head() SequencedExpectation
	// Visit every expectation in the sequence, in any order.
	Visit(ExpectationSequenceVisitor)
}

ExpectationSequence represents a temporal ordering of expectations.

func ExpectNone

func ExpectNone() ExpectationSequence

ExpectNone generates an empty sequence of expectations.

type ExpectationSequenceVisitor

type ExpectationSequenceVisitor func(SequencedExpectation) VisitControl

type ExpectationSequencer

type ExpectationSequencer interface {
	ExpectationSequence
	// Return the current SequencedExpectation.
	Current() SequencedExpectation
	// Eventually returns an ExpectationSequencerFn that can be used to compose
	// this ExpectationSequencer with another.
	//
	// For example...
	//	sequencer1.Then(sequencer2.Eventually())
	//
	// Produces an ExpectationSequence that starts with sequence1, and is
	// eventually followed by the head of sequence2.
	Eventually() ExpectationSequencerFn
	// Immediately returns an ExpectationSequencerFn that can be used to
	// compose this ExpectationSequencer with another.
	//
	// For example...
	//	sequencer1.Then(sequencer2.Immediately())
	//
	// Produces an ExpectationSequence that starts with sequence1, and is
	// immediately followed by the head of sequence2.
	Immediately() ExpectationSequencerFn
	// Then passes this ExpectationSequencer to ExpectationSequencerFn,
	// and returns the resulting ExpectationSequencer.
	Then(ExpectationSequencerFn) ExpectationSequencer
}

ExpectationSequencer is a convenient way to compose ExpectationSequences.

func Expect

func Expect(head string, tail ...string) ExpectationSequencer

Expect generates a sequence of expectations, where each query after the head query immediately follows the preceding query.

type ExpectationSequencerFn

type ExpectationSequencerFn func(ExpectationSequencer) ExpectationSequencer

func Eventually

func Eventually(head string, tail ...string) ExpectationSequencerFn

Eventually generates an ExpectationSequencerFn which can be used to append a new sequence of expectations onto an existing sequence.

Expect("foo", "bar").Then(Eventually("hello", "world")

Generates a sequence of expectations such that:

• "foo" is expected first
• "bar" immediately follows "foo"
• "hello" eventually follows "bar"
• "world" eventually follows "hello"

func Immediately

func Immediately(head string, tail ...string) ExpectationSequencerFn

Immediately generates an ExpectationSequencerFn which can be used to append a new sequence of expectations onto an existing sequence.

Expect("foo", "bar").Then(Immediately("hello", "world")

Generates a sequence of expectations such that:

• "foo" is expected first
• "bar" immediately follows "foo"
• "hello" immediately follows "bar"
• "world" immediately follows "hello"

type History

type History []string

History represents an actual sequence of SQL statements.

func (History) At

func (h History) At(index int) (string, error)

At returns the query in the history at the given index. Returns an error if the index is out-of-bounds.

func (History) String

func (h History) String() string

type Result

type Result struct {
	Accepted    bool
	Error       error
	Expectation Expectation
	Index       int
	Matched     bool
	Message     string
}

type SequencedExpectation

type SequencedExpectation interface {
	Expectation

	// EventuallyAfter returns the SequencedExpectationSet containing
	// SequencedExpectations which this SequencedExpectation eventually
	// follows.
	EventuallyAfter() SequencedExpectationSet
	// EventuallyBefore returns the SequencedExpectationSet contains
	// SequencedExpectations eventually follow this SequencedExpectation.
	EventuallyBefore() SequencedExpectationSet
	// ExpectImmediatelyAfter sets the SequencedExpectation which this
	// SequencedExpectation immediately follows. It also sets the inverse
	// relationship on the provided expectation.
	ExpectImmediatelyAfter(SequencedExpectation)
	// ExpectImmediatelyBefore sets the SequencedExpectation which immediately
	// follow this SequencedExpectation. It also sets the inverse relationship
	// on the provided expectation.
	ExpectImmediatelyBefore(SequencedExpectation)
	// ExpectEventuallyAfter adds a SequencedExpectation to the
	// SequencedExpectationSet which this SequencedExpectation eventually
	// follows. It also sets the inverse relationship on the provided
	// expectation.
	ExpectEventuallyAfter(SequencedExpectation)
	// ExpectEventuallyAfter adds a SequencedExpectation to the
	// SequencedExpectationSet which eventually follows this
	// SequencedExpectation. It also sets the inverse relationship on the
	// provided expectation.
	ExpectEventuallyBefore(SequencedExpectation)
	// ImmediatelyAfter returns the SequencedExpectation which this
	// SequencedExpectation immediately follows.
	ImmediatelyAfter() SequencedExpectation
	// ImmediatelyBefore returns the SequencedExpectation which immediately
	// follows this SequencedExpectation.
	ImmediatelyBefore() SequencedExpectation
}

SequencedExpectation is an Expectation situated in an ExpectationSequence. In other words, it is an Expectation with temporal relationships to other Expectations.

func Query

func Query(query string) SequencedExpectation

Query generates a single-member expectation sequence.

type SequencedExpectationSet

type SequencedExpectationSet interface {
	Add(SequencedExpectation)
	Contains(SequencedExpectation) bool
	Slice() []SequencedExpectation
}

SequencedExpectationSet provides a set-like interface over a Golang map of SequencedExpectations.

type Verifier

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

Verifier verifies that an actual history of queries matches an expected sequence of queries.

func NewVerifier

func NewVerifier(sequence ExpectationSequence) *Verifier

func (*Verifier) AcceptQuery

func (v *Verifier) AcceptQuery(query string) *Result

AcceptQuery verifies that the provided query is valid according to the internal ExpectationSequence and the internal History of preceding queries. Returns a *Result indicating whether the query was accepted and, if not, diagnostic details indicating why not.

func (*Verifier) History

func (v *Verifier) History() History

History returns the internal History of accepted queries.

func (*Verifier) Pending

func (v *Verifier) Pending() []Expectation

Pending returns a list of Expectations that have not yet fully matched an accepted query.

type VisitControl

type VisitControl int

const (
	VisitContinue VisitControl = iota
	VisitTerminate
)