gexec

gexec: testing external processes

gexec compiles Go binaries, starts them as subprocesses, sends them signals, and exposes their stdout/stderr as gbytes.Buffers so you can assert on streaming output and exit codes. Import it normally (Gomega is dot-imported):

import (
	. "github.com/onsi/gomega"
	. "github.com/onsi/ginkgo/v2"
	"github.com/onsi/gomega/gexec"
)

Docs: https://onsi.github.io/gomega/#gexec-testing-external-processes.

Compiling binaries

gexec.Build(packagePath, ...args) runs go build and returns the path to a temp binary.

var pathToCLI string

BeforeSuite(func() {
	var err error
	pathToCLI, err = gexec.Build("github.com/spacely/sprockets")
	Expect(err).NotTo(HaveOccurred())
})

AfterSuite(func() {
	gexec.CleanupBuildArtifacts()
})

• gexec.BuildWithEnvironment(packagePath, env []string, ...args) — set env vars for the build (e.g. GOOS/GOARCH for cross-compilation).
• gexec.BuildIn(gopath, packagePath, ...args) — build with a custom GOPATH (e.g. against vendored deps).

Always defer/AfterSuite gexec.CleanupBuildArtifacts(). It deletes the temp binaries; skipping it leaks files into your temp dir across runs.

Starting a process

gexec.Start(cmd, outWriter, errWriter) calls cmd.Start() and returns a *gexec.Session that wraps and monitors the process, forwarding stdout/stderr to the writers you pass.

command := exec.Command(pathToCLI, "-api=127.0.0.1:8899")
session, err := gexec.Start(command, GinkgoWriter, GinkgoWriter)
Expect(err).NotTo(HaveOccurred())

Pass GinkgoWriter for both writers. Output is then silent on passing tests but printed on failure (and always under ginkgo -v) — invaluable for debugging.

Asserting on exit

The gexec.Exit() matcher is pollable and only works on a *Session — pair it with Eventually (→ gomega:async):

Eventually(session).Should(gexec.Exit())   // exited, any code
Eventually(session).Should(gexec.Exit(0))  // exited with code 0