Przejdź do treści
Biblioteka skilli
Programowanie · Testowanie

gbytes

/gbytes

Pomaga testować strumieniowe bufory io w Go z gbytes: NewBuffer, dopasowanie Say z kursorem odczytu, wzorzec Eventually(buffer).Should(Say(...)), Contents, buffer.Detect i TimeoutReader, Writer i Closer.

Repozytorium
gomega ↗
Licencja
MIT
Ostatnia zmiana repozytorium
09.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 09.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Pomaga testować strumieniowe bufory io w Go z gbytes: NewBuffer, dopasowanie Say z kursorem odczytu, wzorzec Eventually(buffer).Should(Say(...)), Contents, buffer.Detect i TimeoutReader, Writer i Closer.

Oryginalny opis (EN)

Testing streaming io buffers with gbytes — gbytes.NewBuffer() (an io.Writer also returned by gexec sessions), the Say(regexp) matcher that forward-scans from a moving read cursor, the canonical Eventually(buffer).Should(Say(...)) streaming pattern, sequential cursor-advancing Say calls, Contents(), BufferWithBytes/BufferReader, buffer.Detect for branching, and TimeoutReader/Writer/Closer for testing blocking io.Reader/Writer/Closer. Use when asserting on streaming or incremental output (process stdout/stderr, API streams, io.Readers) rather than a complete value.

Jak działa

  1. The buffer
  2. The Say matcher
  3. The canonical streaming pattern: Eventually + Say
  4. Handling branches
  5. Testing io.Reader/io.Writer/io.Closer
  6. Gotchas
Sekcje z nagłówków SKILL.md, w oryginale · 107 linii, 641 słów
Podgląd SKILL.md
---
name: gbytes
description: Testing streaming io buffers with gbytes — gbytes.NewBuffer() (an io.Writer also returned by gexec sessions), the Say(regexp) matcher that forward-scans from a moving read cursor, the canonical Eventually(buffer).Should(Say(...)) streaming pattern, sequential cursor-advancing Say calls, Contents(), BufferWithBytes/BufferReader, buffer.Detect for branching, and TimeoutReader/Writer/Closer for testing blocking io.Reader/Writer/Closer. Use when asserting on streaming or incremental output (process stdout/stderr, API streams, io.Readers) rather than a complete value.
---

# 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.Buffer`s, and the session itself is a `BufferProvider`). Docs: <https://onsi.github.io/gomega/#gbytes-testing-streaming-buffers>.

```go
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:

```go
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:

```go
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 `Say`s assert on successive output in order:

```go
Eventually(buffer).Should(gbytes.Say(`Attached as client \d+`))

client.ReticulateSplines()
Eventually(buffer).Should(gbytes.Say(`reticulating splines`))

client.EncabulateRetros(7)
Eventually(buffer).Should(gbytes.Say(`encabulating 7 retros`))
```

Because the cursor only moves forward, this counts repeats correctly — these two assertions pass only if `reticulating splines` appears **twice**:

```go
client.ReticulateSplines()
Eventually(buffer).Should(gbytes.Say(`reticulating splines`))
client.ReticulateSplines()
Eventually(buffer).Should(gbytes.Say(`reticulating splines`))
```

And consequently this (counterintuitively) passes — the first `Say` consumed the match:

```go
Eventually(buffer).Should(gbytes.Say(`reticulating splines`))
Consistently(buffer).ShouldNot(gbytes.Say(`reticulating splines`))
```

`Say` works on a `*gbytes.Buffer` or any `BufferProvider` (anything with a `Buffer() *gbytes.Buffer` method, e.g. a `gexec.Session`), so `Eventually(session).Should(gbytes.Say(...))` works directly.

## Handling branches

When the test must react to *whichever* output arrives, use `buffer.Detect(regexp, args...)`, which returns a channel that fires once on match (and fast-forwards the cursor). Always `CancelDetects()` to clean up the spawned goroutines:

```go
client.Authorize()
select {
case <-buffer.Detect("You are not logged in"):
	client.Login()
case <-buffer.Detect("Success"):
	// carry on
case <-time.After(time.Second):
	Fail("timed out waiting for output")
}
buffer.CancelDetects()
```

## Testing `io.Reader`/`io.Writer`/`io.Closer`

These interfaces are expected to block, so calling `Read`/`Write`/`Close` directly in a test risks hanging forever. Wrap them with timeouts; the wrappers return `gbytes.ErrTimeout` if the operation doesn't complete in time:

```go
p := make([]byte, 5)
_, err := gbytes.TimeoutReader(reader, time.Second).Read(p)
Expect(err).NotTo(HaveOccurred())
```

`gbytes.TimeoutReader`, `gbytes.TimeoutWriter`, and `gbytes.TimeoutCloser` each wrap the matching interface. To use `Say` against an `io.Reader`, wrap it with `gbytes.BufferReader(reader)` — it launches an `io.Copy` goroutine into a fresh buffer (closed when the copy completes). Because the copy is async you **must** use `Eventually`:

```go
Eventually(gbytes.BufferReader(reader)).Should(gbytes.Say("abcde"))
```

## Gotchas

- **Say takes a regexp — escape metacharacters.** `(`, `)`, `.`, `[`, `+`, `?`, `\d`, etc. are regex syntax. To match a literal `splines (v2)` write `gbytes.Say(`splines \(v2\)`)`. The pattern is compiled with `regexp.MustCompile`, so a bad pattern panics.
- **The cursor only moves forward.** You cannot re-match output an earlier `Say` already consumed. If you need to assert on the whole buffer, use `buffer.Contents()` with a string matcher (`gomega:matchers`) instead of `Say`.
- **Pair `Say` with `Eventually` for live streams; use plain `Expect` only on an already-complete buffer.** A bare `Expect(buffer).To(Say(...))` checks the buffer once, right now — it will flake if the data hasn't arrived yet.
- **A closed buffer aborts `Eventually` early.** Once `Close()` is called, a pending `Say` can never succeed on new data, so the matcher signals `Eventually`/`Consistently` to stop polling and fail immediately rather than wait out the timeout.

Wersje

W bazie nie ma innych skilli o nazwie gbytes.

Migawka bazy z 13.11.2026 · wersja paczki 44b8e8157059 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95gexec
    Testuje zewnętrzne procesy w Go przez gexec: buduje binarki, uruchamia je, wysyła sygnały i sprawdza wyjście.
  • 100overview
    Wyjaśnia zasady pisania asercji w bibliotece Gomega dla Go i wskazuje, którego skilla gomega użyć dalej.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.