gbytes

Documentation

Overview

Package gbytes provides a buffer that supports incrementally detecting input.

You use gbytes.Buffer with the gbytes.Say matcher. When Say finds a match, it fastforwards the buffer's read cursor to the end of that match.

Subsequent matches against the buffer will only operate against data that appears *after* the read cursor.

The read cursor is an opaque implementation detail that you cannot access. You should use the Say matcher to sift through the buffer. You can always access the entire buffer's contents with Contents().

Index

• Variables
• func Say(expected string, args ...interface{}) *sayMatcher
• func TimeoutCloser(c io.Closer, timeout time.Duration) io.Closer
• func TimeoutReader(r io.Reader, timeout time.Duration) io.Reader
• func TimeoutWriter(w io.Writer, timeout time.Duration) io.Writer
• type Buffer
  • func BufferReader(reader io.Reader) *Buffer
  • func BufferWithBytes(bytes []byte) *Buffer
  • func NewBuffer() *Buffer
  • func (b *Buffer) CancelDetects()
  • func (b *Buffer) Clear() error
  • func (b *Buffer) Close() error
  • func (b *Buffer) Closed() bool
  • func (b *Buffer) Contents() []byte
  • func (b *Buffer) Detect(desired string, args ...interface{}) chan bool
  • func (b *Buffer) Read(d []byte) (int, error)
  • func (b *Buffer) Write(p []byte) (n int, err error)
• type BufferProvider

Variables

var ErrTimeout = errors.New("timeout occurred")

ErrTimeout is returned by TimeoutCloser, TimeoutReader, and TimeoutWriter when the underlying Closer/Reader/Writer does not return within the specified timeout

Functions

func Say

func Say(expected string, args ...interface{}) *sayMatcher

Say is a Gomega matcher that operates on gbytes.Buffers:

Expect(buffer).Should(Say("something"))

will succeed if the unread portion of the buffer matches the regular expression "something".

When Say succeeds, it fast forwards the gbytes.Buffer's read cursor to just after the successful match. Thus, subsequent calls to Say will only match against the unread portion of the buffer

Say pairs very well with Eventually. To assert that a buffer eventually receives data matching "[123]-star" within 3 seconds you can:

Eventually(buffer, 3).Should(Say("[123]-star"))

Ditto with consistently. To assert that a buffer does not receive data matching "never-see-this" for 1 second you can:

Consistently(buffer, 1).ShouldNot(Say("never-see-this"))

In addition to bytes.Buffers, Say can operate on objects that implement the gbytes.BufferProvider interface. In such cases, Say simply operates on the *gbytes.Buffer returned by Buffer()

If the buffer is closed, the Say matcher will tell Eventually to abort.

func TimeoutCloser

func TimeoutCloser(c io.Closer, timeout time.Duration) io.Closer

TimeoutCloser returns an io.Closer that wraps the passed-in io.Closer. If the underlying Closer fails to close within the allotted timeout ErrTimeout is returned.

func TimeoutReader

func TimeoutReader(r io.Reader, timeout time.Duration) io.Reader

TimeoutReader returns an io.Reader that wraps the passed-in io.Reader. If the underlying Reader fails to read within the allotted timeout ErrTimeout is returned.

func TimeoutWriter

func TimeoutWriter(w io.Writer, timeout time.Duration) io.Writer

TimeoutWriter returns an io.Writer that wraps the passed-in io.Writer. If the underlying Writer fails to write within the allotted timeout ErrTimeout is returned.

Types

type Buffer

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

gbytes.Buffer implements an io.Writer and can be used with the gbytes.Say matcher.

You should only use a gbytes.Buffer in test code. It stores all writes in an in-memory buffer - behavior that is inappropriate for production code!

func BufferReader

func BufferReader(reader io.Reader) *Buffer

BufferReader returns a new gbytes.Buffer that wraps a reader. The reader's contents are read into the Buffer via io.Copy

func BufferWithBytes

func BufferWithBytes(bytes []byte) *Buffer

BufferWithBytes returns a new gbytes.Buffer seeded with the passed in bytes

func NewBuffer

func NewBuffer() *Buffer

NewBuffer returns a new gbytes.Buffer

func (*Buffer) CancelDetects

func (b *Buffer) CancelDetects()

CancelDetects cancels any pending detects and cleans up their goroutines. You should always call this when you're done with a set of Detect channels.

func (*Buffer) Clear

func (b *Buffer) Clear() error

Clear clears out the buffer's contents

func (*Buffer) Close

func (b *Buffer) Close() error

Close signifies that the buffer will no longer be written to

func (*Buffer) Closed

func (b *Buffer) Closed() bool

Closed returns true if the buffer has been closed

func (*Buffer) Contents

func (b *Buffer) Contents() []byte

Contents returns all data ever written to the buffer.

func (*Buffer) Detect

func (b *Buffer) Detect(desired string, args ...interface{}) chan bool

Detect takes a regular expression and returns a channel.

The channel will receive true the first time data matching the regular expression is written to the buffer. The channel is subsequently closed and the buffer's read-cursor is fast-forwarded to just after the matching region.

You typically don't need to use Detect and should use the ghttp.Say matcher instead. Detect is useful, however, in cases where your code must be branch and handle different outputs written to the buffer.

For example, consider a buffer hooked up to the stdout of a client library. You may (or may not, depending on state outside of your control) need to authenticate the client library.

You could do something like:

select { case <-buffer.Detect("You are not logged in"):

//log in

case <-buffer.Detect("Success"):

//carry on

case <-time.After(time.Second):

	//welp
}

buffer.CancelDetects()

You should always call CancelDetects after using Detect. This will close any channels that have not detected and clean up the goroutines that were spawned to support them.

Finally, you can pass detect a format string followed by variadic arguments. This will construct the regexp using fmt.Sprintf.

func (*Buffer) Read

func (b *Buffer) Read(d []byte) (int, error)

Read implements the io.Reader interface. It advances the cursor as it reads.

func (*Buffer) Write

func (b *Buffer) Write(p []byte) (n int, err error)

Write implements the io.Writer interface

type BufferProvider

type BufferProvider interface {
	Buffer() *Buffer
}

Objects satisfying the BufferProvider can be used with the Say matcher.