OpenParable
Skip to content
← Back to skills

Gexec

Testing & Quality
gexec

Gexec is an Agent Skill for testing & quality published in the onsi/gomega repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Testing external processes with gexec — compile binaries with Build/BuildWithEnvironment/BuildIn and CleanupBuildArtifacts, start them with Start returning a *Session, await exit with the Exit matcher (Eventually(session).Should(Exit(0))), Wait/ExitCode, signal via Kill/Terminate/Interrupt/Signal and package-level KillAndWait/TerminateAndWait, and assert on session.Out/Err which are gbytes buffers (Say, Contents). Use when building, running, signaling, or asserting on subprocesses in Go tests.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/onsi/gomega/blob/HEAD/plugins/gomega/skills/gexec/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/gexec, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

session.ExitCode() returns the raw code, or -1 if the process hasn't exited yet.

session.Wait([timeout]) blocks until exit (failing if it doesn't exit within the default Eventually timeout) and returns the session for chaining:

session.Wait(5 * time.Second)

Don't Wait on the wrapped exec.Cmd yourself — gexec already calls Wait to monitor the process. session.Wait is just Eventually under the hood.

Sending signals

session.Kill()         // SIGKILL
session.Interrupt()    // SIGINT
session.Terminate()    // SIGTERM
session.Signal(sig)    // arbitrary os.Signal

Each returns the session, so chain with Wait: session.Terminate().Wait(). Signaling an already-exited process is a no-op.

Signaling every started session

Package-level helpers signal all sessions gexec has started, in any context — ideal for cleanup:

gexec.Kill()              // SIGKILL to all
gexec.Terminate()         // SIGTERM to all
gexec.Interrupt()         // SIGINT to all
gexec.Signal(sig)         // os.Signal to all
gexec.KillAndWait()       // signal all, then wait
gexec.TerminateAndWait(2 * time.Second)  // per-process timeout

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

These are global. Calling them in an AfterEach will also signal processes started in BeforeSuite. Good practice is to ensure all processes are killed before the suite ends.

Asserting on output

session.Out and session.Err are gbytes.Buffers connected to stdout/stderr, so use the gbytes.Say matcher for ordered streaming assertions (→ gomega:gbytes). The session itself is a BufferProvider for Out:

Eventually(session.Out).Should(gbytes.Say("hello [A-Za-z], nice to meet you"))
Eventually(session.Err).Should(gbytes.Say("oops!"))
Eventually(session).Should(gbytes.Say("hello"))  // shorthand for session.Out

To grab the whole output after exit, Wait() returns the session, so .Out.Contents() gives a []byte (→ gomega:matchers):

Expect(session.Wait().Out.Contents()).To(ContainSubstring("finished successfully"))

End-to-end

var pathToCLI string

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

var _ = AfterSuite(func() {
	gexec.CleanupBuildArtifacts()
})

var _ = It("greets and exits cleanly", func() {
	command := exec.Command(pathToCLI, "--name=George")
	session, err := gexec.Start(command, GinkgoWriter, GinkgoWriter)
	Expect(err).NotTo(HaveOccurred())

	Eventually(session).Should(gbytes.Say("hello George"))
	Eventually(session).Should(gexec.Exit(0))
	Expect(session.Out.Contents()).To(ContainSubstring("done"))
})