Test a CLI
In this tutorial, we will write Go tests that run cloudctl the way a user does: with a command line, input to read, and somewhere to write. Along the way, deploy will learn to ask for confirmation before it deploys. We continue in the cloudctl directory from Configure a CLI from a file and the environment, with cloudctl.yaml still in place.
Each test starts from a command line and checks what cloudctl gives back, running the app inside the test with no binary to build. About testing CONGA programs compares this with running the built binary.
The command we will build
Section titled “The command we will build”By the end, three tests pass:
$ go test -v=== RUN TestDeploy--- PASS: TestDeploy (0.00s)=== RUN TestDeployCanceled--- PASS: TestDeployCanceled (0.00s)=== RUN TestDeployNeedsImage--- PASS: TestDeployNeedsImage (0.00s)PASSok cloudctl 0.006sLet a test build the same app
Section titled “Let a test build the same app”A test needs the same app that main runs, with the same name, prefix, and config settings. Move the builder calls out of main into a function, and replace main:
main and the tests both build the app here.func newApp() *conga.App[CLI] { return conga.New[CLI](). Name("cloudctl"). Description("Manage services in the cloud"). Version("0.1.0"). EnvPrefix("CLOUDCTL"). RegisterDecoder(".yaml", yaml.Decode). ConfigOptions(conga.ConfigPaths("."))}
func main() { app := newApp()
if err := app.Run(); err != nil { app.Exit(err) }}Build the program, and check that it behaves as before:
go build$ ./cloudctl deploy webdeploying web (nginx:1.27) to eu-west-1 with 3 replicasRun the app in a test
Section titled “Run the app in a test”Create main_test.go with a test that deploys web and checks what it prints:
package main
import ( "bytes" "testing")
func TestDeploy(t *testing.T) { var stdoutBuffer bytes.Buffer
app := newApp().The command line for this run, in place of the real one. Args([]string{"deploy", "web", "--image", "nginx:1.27"}).The app's standard output for this run. Stdout(&stdoutBuffer)
if err := app.RunContext(t.Context()); err != nil { t.Fatalf("run failed: %v", err) }
want := "deploying web (nginx:1.27) to us-east-1 with 2 replicas\n" if got := stdoutBuffer.String(); got != want { t.Errorf("output = %q, want %q", got, want) }}The test gives the app its own command line and an output buffer, runs it, and compares what landed in the buffer. It gives only --image, so it expects the defaults, us-east-1 and 2 replicas. Run it, and list the test as it runs. It fails:
$ go test -v=== RUN TestDeploydeploying web (nginx:1.27) to eu-west-1 with 3 replicas main_test.go:21: output = "", want "deploying web (nginx:1.27) to us-east-1 with 2 replicas\n"--- FAIL: TestDeploy (0.00s)FAILexit status 1FAIL cloudctl 0.006sNotice that the buffer is empty, and the deployment line appears in go test’s own output instead. deploy prints with fmt.Printf, which always writes to os.Stdout, the process’s standard output. Stdout(&stdoutBuffer) sets a separate stream, the app’s standard output, and fmt.Printf never writes to it.
Write through the session
Section titled “Write through the session”The session that CONGA passes to Run has the app’s streams. session.Stdout() is the app’s standard output, session.Stderr() its standard error, and session.Stdin() its standard input. A normal run sets them to the process’s own streams, so the user sees no difference. A test that calls Stdout(&stdoutBuffer) points session.Stdout() at the buffer.
Make both commands write through the session:
func (d *DeployCmd) Run(ctx context.Context, session *conga.Session) error { root := session.Root[CLI]() fmt.Fprintf(session.Stdout(), "deploying %s (%s) to %s with %d replicas\n", d.Service.Get(), d.Image.Get(), root.Region.Get(), d.Replicas.Get())
return nil}
// ...
func (s *StatusCmd) Run(ctx context.Context, session *conga.Session) error { root := session.Root[CLI]() fmt.Fprintf(session.Stdout(), "all services healthy in %s\n", root.Region.Get())
return nil}Run the test again:
$ go test--- FAIL: TestDeploy (0.00s) main_test.go:21: output = "deploying web (nginx:1.27) to eu-west-1 with 3 replicas\n", want "deploying web (nginx:1.27) to us-east-1 with 2 replicas\n"FAILexit status 1FAIL cloudctl 0.005sThe line reached the buffer this time, but with eu-west-1 and 3 replicas. Notice that those came from cloudctl.yaml. The test ran the whole app, and go test runs in the package directory, so the app found the file there, as it does when we run ./cloudctl. It would read CLOUDCTL_REGION and the other variables from the shell in the same way.
Give each test a clean start, with no config file and none of the app’s variables set:
func isolate(t *testing.T) { t.Helper()
Runs the test in a new, empty directory. t.Chdir(t.TempDir())Empties the variable for this test, and restores it afterwards. t.Setenv("CLOUDCTL_REGION", "") t.Setenv("CLOUDCTL_IMAGE", "") t.Setenv("CLOUDCTL_REPLICAS", "")}
func TestDeploy(t *testing.T) { isolate(t)
var stdoutBuffer bytes.Buffer // ...}CONGA treats an empty variable as unset. Run the test with a region set in the shell, to check that it no longer reaches the app:
$ CLOUDCTL_REGION=ap-south-1 go testPASSok cloudctl 0.008sAsk before deploying
Section titled “Ask before deploying”A deployment is worth a second thought. Let’s make deploy ask first, unless the user passes --yes. Add errors to the imports, a Yes flag, and the question to Run:
import ( "context" "errors" "fmt"
"github.com/conga-sh/conga" "github.com/conga-sh/conga/decoder/yaml")
// ...
type DeployCmd struct { Service conga.RequiredArg[string] `help:"Service to deploy"` Image conga.RequiredFlag[string] `help:"Container image to run"` Replicas conga.OptionalFlag[int] `default:"2" help:"Number of copies to run"` Yes conga.OptionalFlag[bool] `help:"Deploy without asking" short:"y"`}
func (d *DeployCmd) Run(ctx context.Context, session *conga.Session) error { root := session.Root[CLI]()
if !d.Yes.Get() {The question goes to standard error, so standard output holds only the result. fmt.Fprintf(session.Stderr(), "deploy %s to %s? [y/N] ", d.Service.Get(), root.Region.Get())
var answer stringReads the answer from the app's standard input. if _, err := fmt.Fscanln(session.Stdin(), &answer); err != nil || answer != "y" { return errors.New("deployment canceled") } }
fmt.Fprintf(session.Stdout(), "deploying %s (%s) to %s with %d replicas\n", d.Service.Get(), d.Image.Get(), root.Region.Get(), d.Replicas.Get())
return nil}Build the program, run a deployment, and answer y:
go build$ ./cloudctl deploy webdeploy web to eu-west-1? [y/N] ydeploying web (nginx:1.27) to eu-west-1 with 3 replicasRun it again, and answer n:
$ ./cloudctl deploy webdeploy web to eu-west-1? [y/N] nError:cloudctl: error: deployment canceledError$ echo $?1With -y, it deploys without asking:
$ ./cloudctl deploy web -ydeploying web (nginx:1.27) to eu-west-1 with 3 replicasBecause the question goes to standard error, it still reaches the terminal when we send the output to a file, and the file holds only the result:
$ echo y | ./cloudctl deploy web > deploy.logdeploy web to eu-west-1? [y/N]$ cat deploy.logdeploying web (nginx:1.27) to eu-west-1 with 3 replicasTest the question
Section titled “Test the question”A test can’t type at a prompt, so it gives the app its input instead. Replace main_test.go:
package main
import ( "bytes" "strings" "testing")
func isolate(t *testing.T) { t.Helper()
t.Chdir(t.TempDir()) t.Setenv("CLOUDCTL_REGION", "") t.Setenv("CLOUDCTL_IMAGE", "") t.Setenv("CLOUDCTL_REPLICAS", "") t.Setenv("CLOUDCTL_YES", "")}
func TestDeploy(t *testing.T) { isolate(t)
var stdoutBuffer, stderrBuffer bytes.Buffer
app := newApp(). Args([]string{"deploy", "web", "--image", "nginx:1.27"}).What session.Stdin() reads, as if the user typed y. Stdin(strings.NewReader("y\n")). Stdout(&stdoutBuffer).Where session.Stderr() writes. Stderr(&stderrBuffer)
if err := app.RunContext(t.Context()); err != nil { t.Fatalf("run failed: %v", err) }
want := "deploying web (nginx:1.27) to us-east-1 with 2 replicas\n" if got := stdoutBuffer.String(); got != want { t.Errorf("output = %q, want %q", got, want) }
wantPrompt := "deploy web to us-east-1? [y/N] " if got := stderrBuffer.String(); got != wantPrompt { t.Errorf("prompt = %q, want %q", got, wantPrompt) }}
func TestDeployCanceled(t *testing.T) { isolate(t)
var stdoutBuffer bytes.Buffer
app := newApp(). Args([]string{"deploy", "web", "--image", "nginx:1.27"}). Stdin(strings.NewReader("n\n")). Stdout(&stdoutBuffer). Stderr(new(bytes.Buffer))
err := app.RunContext(t.Context()) if err == nil || err.Error() != "deployment canceled" { t.Fatalf("err = %v, want deployment canceled", err) }
if stdoutBuffer.Len() > 0 { t.Errorf("output = %q, want none", stdoutBuffer.String()) }}isolate now also empties CLOUDCTL_YES, the variable the new --yes flag reads. TestDeploy answers y and checks each stream, the result on standard output and the question on standard error. TestDeployCanceled answers n and checks that nothing was deployed.
$ go test -v=== RUN TestDeploy--- PASS: TestDeploy (0.00s)=== RUN TestDeployCanceled--- PASS: TestDeployCanceled (0.00s)PASSok cloudctl 0.004sTest a usage error
Section titled “Test a usage error”Last, check that leaving out --image fails as a usage error. Add conga to the imports, and a third test:
import ( "bytes" "strings" "testing"
"github.com/conga-sh/conga")
// ...
func TestDeployNeedsImage(t *testing.T) { isolate(t)
var stderrBuffer bytes.Buffer
app := newApp(). Args([]string{"deploy", "web"}). Stderr(&stderrBuffer)
err := app.RunContext(t.Context())True for a mistake on the command line, the kind that exits with status 2. if !conga.IsUsageError(err) { t.Fatalf("err = %v, want a usage error", err) }
if stderrBuffer.Len() > 0 { t.Errorf("stderr = %q, want empty", stderrBuffer.String()) }}$ go test -v=== RUN TestDeploy--- PASS: TestDeploy (0.00s)=== RUN TestDeployCanceled--- PASS: TestDeployCanceled (0.00s)=== RUN TestDeployNeedsImage--- PASS: TestDeployNeedsImage (0.00s)PASSok cloudctl 0.006sNotice that the test checks standard error is empty. RunContext returns the error and prints nothing. In main, app.Exit prints the message and picks the exit status. The canceled deployment exited with status 1, because the command line was fine. The missing --image exits with status 2, because the command line was wrong.
Where to go next
Section titled “Where to go next”We now have a cloudctl whose commands read and write through the session, and tests that run it with their own command line and streams.
- About testing CONGA programs: end-to-end tests with the built binary or inside the test, and where unit tests fit.
- How to test a command: table-driven tests, and checking the exit status that
Exitpicks. - Add shell completion to a CLI: the next tutorial, which makes the shell complete
cloudctl’s commands, flags, and values.