gbytes

gbytes: testing streaming buffers

gbytes provides *gbytes.Buffer, an in-memory io.Writer (and io.Reader/io.Closer) that captures everything written to it, plus the Say matcher for making ordered assertions against streaming data as it arrives. Pairs naturally with gomega:async (poll with Eventually) and gomega:gexec (a session's .Out/.Err are *gbytes.Buffers, and the session itself is a BufferProvider). Docs: https://onsi.github.io/gomega/#gbytes-testing-streaming-buffers.

import (
	. "github.com/onsi/gomega"
	"github.com/onsi/gomega/gbytes"
)

The buffer

gbytes.NewBuffer() returns an empty *gbytes.Buffer. Hand it to anything that wants an io.Writer and it accumulates the bytes:

buffer := gbytes.NewBuffer()
go client.AttachToDataStream(buffer) // client writes to buffer concurrently

• gbytes.BufferWithBytes(b []byte) — seed a buffer with already-captured bytes.
• buffer.Contents() []byte — all bytes ever written, regardless of cursor position. Use this for whole-buffer assertions (Expect(buffer.Contents()).To(ContainSubstring(...))).
• buffer.Close() / buffer.Closed() — mark a buffer done. Writes to a closed buffer error. A closed buffer tells Eventually to give up (see below).

The Say matcher

gbytes.Say(pattern, args...) takes a regular expression (optionally fmt.Sprintf-formatted with args) and matches against the buffer's unread portion:

Expect(buffer).To(gbytes.Say(`hello \w+`))

Say is cursor-based, not whole-buffer. Each buffer carries an opaque read cursor you cannot access. When Say matches, it fast-forwards the cursor to just past the match. The next Say only sees bytes after that point. This is what makes ordered assertions work — and the gotcha below.

The canonical streaming pattern: Eventually + Say

Streaming output arrives over time, so poll the buffer with Eventually (gomega:async). Each successful Say advances the cursor, so successive Says assert on successive output in order: