feat: Utility function to launch and wait for server

.golangci.yaml

@@ -106,3 +106,7 @@ issues:
         - goconst
         - gomnd
         - govet
+    - path: example_test\.go
+      linters:
+        - gocritic
+        - errcheck

README.md

@@ -1,4 +1,4 @@
-![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/cerbos/cerbos-sdk-go?color=green&logo=github&sort=semver) [![Go Reference](https://pkg.go.dev/badge/github.com/cerbos/cerbos-sdk-go/client.svg)](https://pkg.go.dev/github.com/cerbos/cerbos-sdk-go)
+[![Go Reference](https://pkg.go.dev/badge/github.com/cerbos/cerbos-sdk-go/client.svg)](https://pkg.go.dev/github.com/cerbos/cerbos-sdk-go)
 
 # Cerbos Client SDK for Go
 

cerbos/grpc_admin_test.go

@@ -105,7 +105,7 @@ func TestAdminClient(t *testing.T) {
 	confFile := filepath.Join(tests.PathToTestDataDir(t, "configs"), "tcp_with_tls.yaml")
 	policyDir := tests.PathToTestDataDir(t, "policies")
 
-	s, err := launcher.Launch(&testutil.LaunchConf{
+	s, err := launcher.Launch(testutil.LaunchConf{
 		ConfFilePath: confFile,
 		AdditionalMounts: []string{
 			fmt.Sprintf("%s:/certs", certsDir),

cerbos/grpc_test.go

@@ -57,7 +57,7 @@ func TestGRPCClient(t *testing.T) {
 		tc := tc
 		t.Run(tc.name, func(t *testing.T) {
 			t.Run("tcp", func(t *testing.T) {
-				s, err := launcher.Launch(&testutil.LaunchConf{
+				s, err := launcher.Launch(testutil.LaunchConf{
 					ConfFilePath: tc.confFilePath,
 					PolicyDir:    policyDir,
 					AdditionalMounts: []string{
@@ -94,7 +94,7 @@ func TestGRPCClient(t *testing.T) {
 
 			t.Run("uds", func(t *testing.T) {
 				tempDir := t.TempDir()
-				s, err := launcher.Launch(&testutil.LaunchConf{
+				s, err := launcher.Launch(testutil.LaunchConf{
 					ConfFilePath: tc.confFilePath,
 					PolicyDir:    policyDir,
 					AdditionalMounts: []string{

testutil/example_test.go

@@ -0,0 +1,65 @@
+// Copyright 2021-2023 Zenauth Ltd.
+// SPDX-License-Identifier: Apache-2.0
+
+package testutil_test
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"time"
+
+	"github.com/cerbos/cerbos-sdk-go/cerbos"
+	"github.com/cerbos/cerbos-sdk-go/testutil"
+)
+
+func ExampleLaunchCerbosServer() {
+	// Configure Cerbos with the SQLite storage driver
+	conf := testutil.LaunchConf{
+		Cmd: []string{
+			"server",
+			"--set=storage.driver=sqlite3",
+			"--set=storage.sqlite3.dsn=:mem:?_fk=true",
+		},
+		Env: []string{
+			"CERBOS_LOG_LEVEL=error",
+		},
+	}
+
+	// Set timeout for launching the server
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+
+	s, err := testutil.LaunchCerbosServer(ctx, conf)
+	if err != nil {
+		log.Fatalf("Failed to launch Cerbos server: %v", err)
+	}
+
+	defer s.Stop()
+
+	c, err := cerbos.New(s.GRPCAddr(), cerbos.WithPlaintext())
+	if err != nil {
+		log.Fatalf("Failed to create Cerbos client: %v", err)
+	}
+
+	allowed, err := c.IsAllowed(context.TODO(),
+		cerbos.NewPrincipal("john").
+			WithRoles("employee", "manager").
+			WithAttr("department", "marketing").
+			WithAttr("geography", "GB"),
+		cerbos.NewResource("leave_request", "XX125").
+			WithAttributes(map[string]any{
+				"department": "marketing",
+				"geography":  "GB",
+				"owner":      "harry",
+				"status":     "DRAFT",
+			}),
+		"view",
+	)
+	if err != nil {
+		log.Fatalf("API request failed: %v", err)
+	}
+
+	fmt.Println(allowed)
+	// Output: false
+}

testutil/testutil.go

@@ -102,6 +102,7 @@ type LaunchConf struct {
 	PolicyDirMountPoint string
 	AdditionalMounts    []string
 	Cmd                 []string
+	Env                 []string
 }
 
 // NewCerbosServerLauncher creates a launcher for Cerbos containers.
@@ -125,12 +126,12 @@ func NewCerbosServerLauncherFromImage(repo, tag string) (*CerbosServerLauncher,
 	return &CerbosServerLauncher{pool: pool, repo: repo, tag: tag}, nil
 }
 
-func (csl *CerbosServerLauncher) Launch(conf *LaunchConf) (*CerbosServerInstance, error) {
+func (csl *CerbosServerLauncher) Launch(conf LaunchConf) (*CerbosServerInstance, error) {
 	options := &dockertest.RunOptions{
 		Repository: csl.repo,
 		Tag:        csl.tag,
 		Cmd:        conf.Cmd,
-		Env:        []string{"CERBOS_NO_TELEMETRY=1"},
+		Env:        append([]string{"CERBOS_NO_TELEMETRY=1"}, conf.Env...),
 	}
 
 	if conf.ConfFilePath != "" {
@@ -210,3 +211,18 @@ func envOrDefault(envVarName, defaultVal string) string {
 
 	return val
 }
+
+// LaunchCerbosServer is a utility method to start a Cerbos server and wait for it be ready.
+func LaunchCerbosServer(ctx context.Context, launchConf LaunchConf) (*CerbosServerInstance, error) {
+	launcher, err := NewCerbosServerLauncher()
+	if err != nil {
+		return nil, fmt.Errorf("failed to create launcher: %w", err)
+	}
+
+	server, err := launcher.Launch(launchConf)
+	if err != nil {
+		return nil, fmt.Errorf("failed to launch server: %w", err)
+	}
+
+	return server, server.WaitForReady(ctx)
+}