cmd/hi: add integration test runner CLI tool (#2648)

* cmd/hi: add integration test runner CLI tool Add a new CLI tool 'hi' for running headscale integration tests with Docker automation. The tool replaces manual Docker command composition with an automated solution. Features: - Run integration tests in golang:1.24 containers - Docker context detection (supports colima and other contexts) - Test isolation with unique run IDs and isolated control_logs - Automatic Docker image pulling and container management - Comprehensive cleanup operations for containers, networks, images - Docker volume caching for Go modules - Verbose logging and detailed test artifact reporting - Support for PostgreSQL/SQLite selection and various test flags Usage: go run ./cmd/hi run TestPingAllByIP --verbose The tool uses creachadair/command and flax for CLI parsing and provides cleanup subcommands for Docker resource management. Updates flake.nix vendorHash for new Go dependencies. * ci: update integration tests to use hi CLI tool Replace manual Docker command composition in GitHub Actions workflow with the new hi CLI tool for running integration tests. Changes: - Replace complex docker run command with simple 'go run ./cmd/hi run' - Remove manual environment variable setup (handled by hi tool) - Update artifact paths for new timestamped log directory structure - Simplify command from 15+ lines to 3 lines - Maintain all existing functionality (postgres/sqlite, timeout, test patterns) The hi tool automatically handles Docker context detection, container management, volume mounting, and environment variable setup that was previously done manually in the workflow. * makefile: remove test integration Signed-off-by: Kristoffer Dalby <kristoffer@tailscale.com> --------- Signed-off-by: Kristoffer Dalby <kristoffer@tailscale.com>
2025-08-11 12:47:38 +00:00 · 2025-06-18 11:22:15 +02:00
parent d325211617
commit ea7376f522
10 changed files with 1166 additions and 77 deletions
--- a/cmd/hi/cleanup.go
+++ b/cmd/hi/cleanup.go
@@ -0,0 +1,144 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/filters"
+	"github.com/docker/docker/api/types/image"
+	"github.com/docker/docker/client"
+)
+
+// cleanupBeforeTest performs cleanup operations before running tests.
+func cleanupBeforeTest(ctx context.Context) error {
+	if err := killTestContainers(ctx); err != nil {
+		return fmt.Errorf("failed to kill test containers: %w", err)
+	}
+
+	if err := pruneDockerNetworks(ctx); err != nil {
+		return fmt.Errorf("failed to prune networks: %w", err)
+	}
+
+	return nil
+}
+
+// cleanupAfterTest removes the test container after completion.
+func cleanupAfterTest(ctx context.Context, cli *client.Client, containerID string) error {
+	return cli.ContainerRemove(ctx, containerID, container.RemoveOptions{
+		Force: true,
+	})
+}
+
+// killTestContainers terminates all running test containers.
+func killTestContainers(ctx context.Context) error {
+	cli, err := createDockerClient()
+	if err != nil {
+		return fmt.Errorf("failed to create Docker client: %w", err)
+	}
+	defer cli.Close()
+
+	containers, err := cli.ContainerList(ctx, container.ListOptions{
+		All: true,
+	})
+	if err != nil {
+		return fmt.Errorf("failed to list containers: %w", err)
+	}
+
+	killed := 0
+	for _, cont := range containers {
+		shouldKill := false
+		for _, name := range cont.Names {
+			if strings.Contains(name, "headscale-test-suite") ||
+				strings.Contains(name, "hs-") ||
+				strings.Contains(name, "ts-") {
+				shouldKill = true
+				break
+			}
+		}
+
+		if shouldKill {
+			if err := cli.ContainerKill(ctx, cont.ID, "KILL"); err == nil {
+				killed++
+			}
+		}
+	}
+
+	return nil
+}
+
+// pruneDockerNetworks removes unused Docker networks.
+func pruneDockerNetworks(ctx context.Context) error {
+	cli, err := createDockerClient()
+	if err != nil {
+		return fmt.Errorf("failed to create Docker client: %w", err)
+	}
+	defer cli.Close()
+
+	_, err = cli.NetworksPrune(ctx, filters.Args{})
+	if err != nil {
+		return fmt.Errorf("failed to prune networks: %w", err)
+	}
+
+	return nil
+}
+
+// cleanOldImages removes test-related and old dangling Docker images.
+func cleanOldImages(ctx context.Context) error {
+	cli, err := createDockerClient()
+	if err != nil {
+		return fmt.Errorf("failed to create Docker client: %w", err)
+	}
+	defer cli.Close()
+
+	images, err := cli.ImageList(ctx, image.ListOptions{
+		All: true,
+	})
+	if err != nil {
+		return fmt.Errorf("failed to list images: %w", err)
+	}
+
+	removed := 0
+	for _, img := range images {
+		shouldRemove := false
+		for _, tag := range img.RepoTags {
+			if strings.Contains(tag, "hs-") ||
+				strings.Contains(tag, "headscale-integration") ||
+				strings.Contains(tag, "tailscale") {
+				shouldRemove = true
+				break
+			}
+		}
+
+		if len(img.RepoTags) == 0 && time.Unix(img.Created, 0).Before(time.Now().Add(-7*24*time.Hour)) {
+			shouldRemove = true
+		}
+
+		if shouldRemove {
+			_, err := cli.ImageRemove(ctx, img.ID, image.RemoveOptions{
+				Force: true,
+			})
+			if err == nil {
+				removed++
+			}
+		}
+	}
+
+	return nil
+}
+
+// cleanCacheVolume removes the Docker volume used for Go module cache.
+func cleanCacheVolume(ctx context.Context) error {
+	cli, err := createDockerClient()
+	if err != nil {
+		return fmt.Errorf("failed to create Docker client: %w", err)
+	}
+	defer cli.Close()
+
+	volumeName := "hs-integration-go-cache"
+	_ = cli.VolumeRemove(ctx, volumeName, true)
+
+	return nil
+}
--- a/cmd/hi/docker.go
+++ b/cmd/hi/docker.go
@@ -0,0 +1,364 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/image"
+	"github.com/docker/docker/api/types/mount"
+	"github.com/docker/docker/client"
+)
+
+var (
+	ErrTestFailed              = errors.New("test failed")
+	ErrUnexpectedContainerWait = errors.New("unexpected end of container wait")
+	ErrNoDockerContext         = errors.New("no docker context found")
+)
+
+// runTestContainer executes integration tests in a Docker container.
+func runTestContainer(ctx context.Context, config *RunConfig) error {
+	cli, err := createDockerClient()
+	if err != nil {
+		return fmt.Errorf("failed to create Docker client: %w", err)
+	}
+	defer cli.Close()
+
+	runID := generateRunID()
+	containerName := "headscale-test-suite-" + runID
+	logsDir := filepath.Join(config.LogsDir, runID)
+
+	if config.Verbose {
+		log.Printf("Run ID: %s", runID)
+		log.Printf("Container name: %s", containerName)
+		log.Printf("Logs directory: %s", logsDir)
+	}
+
+	absLogsDir, err := filepath.Abs(logsDir)
+	if err != nil {
+		return fmt.Errorf("failed to get absolute path for logs directory: %w", err)
+	}
+
+	const dirPerm = 0o755
+	if err := os.MkdirAll(absLogsDir, dirPerm); err != nil {
+		return fmt.Errorf("failed to create logs directory: %w", err)
+	}
+
+	if config.CleanBefore {
+		if config.Verbose {
+			log.Printf("Running pre-test cleanup...")
+		}
+		if err := cleanupBeforeTest(ctx); err != nil && config.Verbose {
+			log.Printf("Warning: pre-test cleanup failed: %v", err)
+		}
+	}
+
+	goTestCmd := buildGoTestCommand(config)
+	if config.Verbose {
+		log.Printf("Command: %s", strings.Join(goTestCmd, " "))
+	}
+
+	imageName := "golang:" + config.GoVersion
+	if err := ensureImageAvailable(ctx, cli, imageName, config.Verbose); err != nil {
+		return fmt.Errorf("failed to ensure image availability: %w", err)
+	}
+
+	resp, err := createGoTestContainer(ctx, cli, config, containerName, absLogsDir, goTestCmd)
+	if err != nil {
+		return fmt.Errorf("failed to create container: %w", err)
+	}
+
+	if config.Verbose {
+		log.Printf("Created container: %s", resp.ID)
+	}
+
+	if err := cli.ContainerStart(ctx, resp.ID, container.StartOptions{}); err != nil {
+		return fmt.Errorf("failed to start container: %w", err)
+	}
+
+	log.Printf("Starting test: %s", config.TestPattern)
+
+	exitCode, err := streamAndWait(ctx, cli, resp.ID)
+
+	shouldCleanup := config.CleanAfter && (!config.KeepOnFailure || exitCode == 0)
+	if shouldCleanup {
+		if config.Verbose {
+			log.Printf("Running post-test cleanup...")
+		}
+		if cleanErr := cleanupAfterTest(ctx, cli, resp.ID); cleanErr != nil && config.Verbose {
+			log.Printf("Warning: post-test cleanup failed: %v", cleanErr)
+		}
+	}
+
+	if err != nil {
+		return fmt.Errorf("test execution failed: %w", err)
+	}
+
+	if exitCode != 0 {
+		return fmt.Errorf("%w: exit code %d", ErrTestFailed, exitCode)
+	}
+
+	log.Printf("Test completed successfully!")
+	listControlFiles(logsDir)
+
+	return nil
+}
+
+// buildGoTestCommand constructs the go test command arguments.
+func buildGoTestCommand(config *RunConfig) []string {
+	cmd := []string{"go", "test", "./..."}
+
+	if config.TestPattern != "" {
+		cmd = append(cmd, "-run", config.TestPattern)
+	}
+
+	if config.FailFast {
+		cmd = append(cmd, "-failfast")
+	}
+
+	cmd = append(cmd, "-timeout", config.Timeout.String())
+	cmd = append(cmd, "-v")
+
+	return cmd
+}
+
+// createGoTestContainer creates a Docker container configured for running integration tests.
+func createGoTestContainer(ctx context.Context, cli *client.Client, config *RunConfig, containerName, logsDir string, goTestCmd []string) (container.CreateResponse, error) {
+	pwd, err := os.Getwd()
+	if err != nil {
+		return container.CreateResponse{}, fmt.Errorf("failed to get working directory: %w", err)
+	}
+
+	projectRoot := findProjectRoot(pwd)
+
+	env := []string{
+		fmt.Sprintf("HEADSCALE_INTEGRATION_POSTGRES=%d", boolToInt(config.UsePostgres)),
+	}
+
+	containerConfig := &container.Config{
+		Image:      "golang:" + config.GoVersion,
+		Cmd:        goTestCmd,
+		Env:        env,
+		WorkingDir: projectRoot + "/integration",
+		Tty:        true,
+	}
+
+	hostConfig := &container.HostConfig{
+		AutoRemove: false, // We'll remove manually for better control
+		Binds: []string{
+			fmt.Sprintf("%s:%s", projectRoot, projectRoot),
+			"/var/run/docker.sock:/var/run/docker.sock",
+			logsDir + ":/tmp/control",
+		},
+		Mounts: []mount.Mount{
+			{
+				Type:   mount.TypeVolume,
+				Source: "hs-integration-go-cache",
+				Target: "/go",
+			},
+		},
+	}
+
+	return cli.ContainerCreate(ctx, containerConfig, hostConfig, nil, nil, containerName)
+}
+
+// streamAndWait streams container output and waits for completion.
+func streamAndWait(ctx context.Context, cli *client.Client, containerID string) (int, error) {
+	out, err := cli.ContainerLogs(ctx, containerID, container.LogsOptions{
+		ShowStdout: true,
+		ShowStderr: true,
+		Follow:     true,
+	})
+	if err != nil {
+		return -1, fmt.Errorf("failed to get container logs: %w", err)
+	}
+	defer out.Close()
+
+	go func() {
+		_, _ = io.Copy(os.Stdout, out)
+	}()
+
+	statusCh, errCh := cli.ContainerWait(ctx, containerID, container.WaitConditionNotRunning)
+	select {
+	case err := <-errCh:
+		if err != nil {
+			return -1, fmt.Errorf("error waiting for container: %w", err)
+		}
+	case status := <-statusCh:
+		return int(status.StatusCode), nil
+	}
+
+	return -1, ErrUnexpectedContainerWait
+}
+
+// generateRunID creates a unique timestamp-based run identifier.
+func generateRunID() string {
+	now := time.Now()
+	timestamp := now.Format("20060102-150405")
+	return timestamp
+}
+
+// findProjectRoot locates the project root by finding the directory containing go.mod.
+func findProjectRoot(startPath string) string {
+	current := startPath
+	for {
+		if _, err := os.Stat(filepath.Join(current, "go.mod")); err == nil {
+			return current
+		}
+		parent := filepath.Dir(current)
+		if parent == current {
+			return startPath
+		}
+		current = parent
+	}
+}
+
+// boolToInt converts a boolean to an integer for environment variables.
+func boolToInt(b bool) int {
+	if b {
+		return 1
+	}
+	return 0
+}
+
+// DockerContext represents Docker context information.
+type DockerContext struct {
+	Name      string                 `json:"Name"`
+	Metadata  map[string]interface{} `json:"Metadata"`
+	Endpoints map[string]interface{} `json:"Endpoints"`
+	Current   bool                   `json:"Current"`
+}
+
+// createDockerClient creates a Docker client with context detection.
+func createDockerClient() (*client.Client, error) {
+	contextInfo, err := getCurrentDockerContext()
+	if err != nil {
+		return client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
+	}
+
+	var clientOpts []client.Opt
+	clientOpts = append(clientOpts, client.WithAPIVersionNegotiation())
+
+	if contextInfo != nil {
+		if endpoints, ok := contextInfo.Endpoints["docker"]; ok {
+			if endpointMap, ok := endpoints.(map[string]interface{}); ok {
+				if host, ok := endpointMap["Host"].(string); ok {
+					if runConfig.Verbose {
+						log.Printf("Using Docker host from context '%s': %s", contextInfo.Name, host)
+					}
+					clientOpts = append(clientOpts, client.WithHost(host))
+				}
+			}
+		}
+	}
+
+	if len(clientOpts) == 1 {
+		clientOpts = append(clientOpts, client.FromEnv)
+	}
+
+	return client.NewClientWithOpts(clientOpts...)
+}
+
+// getCurrentDockerContext retrieves the current Docker context information.
+func getCurrentDockerContext() (*DockerContext, error) {
+	cmd := exec.Command("docker", "context", "inspect")
+	output, err := cmd.Output()
+	if err != nil {
+		return nil, fmt.Errorf("failed to get docker context: %w", err)
+	}
+
+	var contexts []DockerContext
+	if err := json.Unmarshal(output, &contexts); err != nil {
+		return nil, fmt.Errorf("failed to parse docker context: %w", err)
+	}
+
+	if len(contexts) > 0 {
+		return &contexts[0], nil
+	}
+
+	return nil, ErrNoDockerContext
+}
+
+// ensureImageAvailable pulls the specified Docker image to ensure it's available.
+func ensureImageAvailable(ctx context.Context, cli *client.Client, imageName string, verbose bool) error {
+	if verbose {
+		log.Printf("Pulling image %s...", imageName)
+	}
+
+	reader, err := cli.ImagePull(ctx, imageName, image.PullOptions{})
+	if err != nil {
+		return fmt.Errorf("failed to pull image %s: %w", imageName, err)
+	}
+	defer reader.Close()
+
+	if verbose {
+		_, err = io.Copy(os.Stdout, reader)
+		if err != nil {
+			return fmt.Errorf("failed to read pull output: %w", err)
+		}
+	} else {
+		_, err = io.Copy(io.Discard, reader)
+		if err != nil {
+			return fmt.Errorf("failed to read pull output: %w", err)
+		}
+		log.Printf("Image %s pulled successfully", imageName)
+	}
+
+	return nil
+}
+
+// listControlFiles displays the headscale test artifacts created in the control logs directory.
+func listControlFiles(logsDir string) {
+	entries, err := os.ReadDir(logsDir)
+	if err != nil {
+		log.Printf("Logs directory: %s", logsDir)
+		return
+	}
+
+	var logFiles []string
+	var tarFiles []string
+
+	for _, entry := range entries {
+		if entry.IsDir() {
+			continue
+		}
+
+		name := entry.Name()
+		// Only show headscale (hs-*) files
+		if !strings.HasPrefix(name, "hs-") {
+			continue
+		}
+
+		switch {
+		case strings.HasSuffix(name, ".stderr.log") || strings.HasSuffix(name, ".stdout.log"):
+			logFiles = append(logFiles, name)
+		case strings.HasSuffix(name, ".pprof.tar") || strings.HasSuffix(name, ".maps.tar") || strings.HasSuffix(name, ".db.tar"):
+			tarFiles = append(tarFiles, name)
+		}
+	}
+
+	log.Printf("Test artifacts saved to: %s", logsDir)
+
+	if len(logFiles) > 0 {
+		log.Printf("Headscale logs:")
+		for _, file := range logFiles {
+			log.Printf("  %s", file)
+		}
+	}
+
+	if len(tarFiles) > 0 {
+		log.Printf("Headscale archives:")
+		for _, file := range tarFiles {
+			log.Printf("  %s", file)
+		}
+	}
+}
--- a/cmd/hi/doctor.go
+++ b/cmd/hi/doctor.go
@@ -0,0 +1,353 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log"
+	"os/exec"
+	"strings"
+
+	"github.com/docker/docker/client"
+)
+
+var ErrSystemChecksFailed = errors.New("system checks failed")
+
+// DoctorResult represents the result of a single health check.
+type DoctorResult struct {
+	Name        string
+	Status      string // "PASS", "FAIL", "WARN"
+	Message     string
+	Suggestions []string
+}
+
+// runDoctorCheck performs comprehensive pre-flight checks for integration testing.
+func runDoctorCheck(ctx context.Context) error {
+	results := []DoctorResult{}
+
+	// Check 1: Docker binary availability
+	results = append(results, checkDockerBinary())
+
+	// Check 2: Docker daemon connectivity
+	dockerResult := checkDockerDaemon(ctx)
+	results = append(results, dockerResult)
+
+	// If Docker is available, run additional checks
+	if dockerResult.Status == "PASS" {
+		results = append(results, checkDockerContext(ctx))
+		results = append(results, checkDockerSocket(ctx))
+		results = append(results, checkGolangImage(ctx))
+	}
+
+	// Check 3: Go installation
+	results = append(results, checkGoInstallation())
+
+	// Check 4: Git repository
+	results = append(results, checkGitRepository())
+
+	// Check 5: Required files
+	results = append(results, checkRequiredFiles())
+
+	// Display results
+	displayDoctorResults(results)
+
+	// Return error if any critical checks failed
+	for _, result := range results {
+		if result.Status == "FAIL" {
+			return fmt.Errorf("%w - see details above", ErrSystemChecksFailed)
+		}
+	}
+
+	log.Printf("✅ All system checks passed - ready to run integration tests!")
+
+	return nil
+}
+
+// checkDockerBinary verifies Docker binary is available.
+func checkDockerBinary() DoctorResult {
+	_, err := exec.LookPath("docker")
+	if err != nil {
+		return DoctorResult{
+			Name:    "Docker Binary",
+			Status:  "FAIL",
+			Message: "Docker binary not found in PATH",
+			Suggestions: []string{
+				"Install Docker: https://docs.docker.com/get-docker/",
+				"For macOS: consider using colima or Docker Desktop",
+				"Ensure docker is in your PATH",
+			},
+		}
+	}
+
+	return DoctorResult{
+		Name:    "Docker Binary",
+		Status:  "PASS",
+		Message: "Docker binary found",
+	}
+}
+
+// checkDockerDaemon verifies Docker daemon is running and accessible.
+func checkDockerDaemon(ctx context.Context) DoctorResult {
+	cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
+	if err != nil {
+		return DoctorResult{
+			Name:    "Docker Daemon",
+			Status:  "FAIL",
+			Message: fmt.Sprintf("Cannot create Docker client: %v", err),
+			Suggestions: []string{
+				"Start Docker daemon/service",
+				"Check Docker Desktop is running (if using Docker Desktop)",
+				"For colima: run 'colima start'",
+				"Verify DOCKER_HOST environment variable if set",
+			},
+		}
+	}
+	defer cli.Close()
+
+	_, err = cli.Ping(ctx)
+	if err != nil {
+		return DoctorResult{
+			Name:    "Docker Daemon",
+			Status:  "FAIL",
+			Message: fmt.Sprintf("Cannot ping Docker daemon: %v", err),
+			Suggestions: []string{
+				"Ensure Docker daemon is running",
+				"Check Docker socket permissions",
+				"Try: docker info",
+			},
+		}
+	}
+
+	return DoctorResult{
+		Name:    "Docker Daemon",
+		Status:  "PASS",
+		Message: "Docker daemon is running and accessible",
+	}
+}
+
+// checkDockerContext verifies Docker context configuration.
+func checkDockerContext(_ context.Context) DoctorResult {
+	contextInfo, err := getCurrentDockerContext()
+	if err != nil {
+		return DoctorResult{
+			Name:    "Docker Context",
+			Status:  "WARN",
+			Message: "Could not detect Docker context, using default settings",
+			Suggestions: []string{
+				"Check: docker context ls",
+				"Consider setting up a specific context if needed",
+			},
+		}
+	}
+
+	if contextInfo == nil {
+		return DoctorResult{
+			Name:    "Docker Context",
+			Status:  "PASS",
+			Message: "Using default Docker context",
+		}
+	}
+
+	return DoctorResult{
+		Name:    "Docker Context",
+		Status:  "PASS",
+		Message: "Using Docker context: " + contextInfo.Name,
+	}
+}
+
+// checkDockerSocket verifies Docker socket accessibility.
+func checkDockerSocket(ctx context.Context) DoctorResult {
+	cli, err := createDockerClient()
+	if err != nil {
+		return DoctorResult{
+			Name:    "Docker Socket",
+			Status:  "FAIL",
+			Message: fmt.Sprintf("Cannot access Docker socket: %v", err),
+			Suggestions: []string{
+				"Check Docker socket permissions",
+				"Add user to docker group: sudo usermod -aG docker $USER",
+				"For colima: ensure socket is accessible",
+			},
+		}
+	}
+	defer cli.Close()
+
+	info, err := cli.Info(ctx)
+	if err != nil {
+		return DoctorResult{
+			Name:    "Docker Socket",
+			Status:  "FAIL",
+			Message: fmt.Sprintf("Cannot get Docker info: %v", err),
+			Suggestions: []string{
+				"Check Docker daemon status",
+				"Verify socket permissions",
+			},
+		}
+	}
+
+	return DoctorResult{
+		Name:    "Docker Socket",
+		Status:  "PASS",
+		Message: fmt.Sprintf("Docker socket accessible (Server: %s)", info.ServerVersion),
+	}
+}
+
+// checkGolangImage verifies we can access the golang Docker image.
+func checkGolangImage(ctx context.Context) DoctorResult {
+	cli, err := createDockerClient()
+	if err != nil {
+		return DoctorResult{
+			Name:    "Golang Image",
+			Status:  "FAIL",
+			Message: "Cannot create Docker client for image check",
+		}
+	}
+	defer cli.Close()
+
+	goVersion := detectGoVersion()
+	imageName := "golang:" + goVersion
+
+	// Check if we can pull the image
+	err = ensureImageAvailable(ctx, cli, imageName, false)
+	if err != nil {
+		return DoctorResult{
+			Name:    "Golang Image",
+			Status:  "FAIL",
+			Message: fmt.Sprintf("Cannot pull golang image %s: %v", imageName, err),
+			Suggestions: []string{
+				"Check internet connectivity",
+				"Verify Docker Hub access",
+				"Try: docker pull " + imageName,
+			},
+		}
+	}
+
+	return DoctorResult{
+		Name:    "Golang Image",
+		Status:  "PASS",
+		Message: fmt.Sprintf("Golang image %s is available", imageName),
+	}
+}
+
+// checkGoInstallation verifies Go is installed and working.
+func checkGoInstallation() DoctorResult {
+	_, err := exec.LookPath("go")
+	if err != nil {
+		return DoctorResult{
+			Name:    "Go Installation",
+			Status:  "FAIL",
+			Message: "Go binary not found in PATH",
+			Suggestions: []string{
+				"Install Go: https://golang.org/dl/",
+				"Ensure go is in your PATH",
+			},
+		}
+	}
+
+	cmd := exec.Command("go", "version")
+	output, err := cmd.Output()
+	if err != nil {
+		return DoctorResult{
+			Name:    "Go Installation",
+			Status:  "FAIL",
+			Message: fmt.Sprintf("Cannot get Go version: %v", err),
+		}
+	}
+
+	version := strings.TrimSpace(string(output))
+
+	return DoctorResult{
+		Name:    "Go Installation",
+		Status:  "PASS",
+		Message: version,
+	}
+}
+
+// checkGitRepository verifies we're in a git repository.
+func checkGitRepository() DoctorResult {
+	cmd := exec.Command("git", "rev-parse", "--git-dir")
+	err := cmd.Run()
+	if err != nil {
+		return DoctorResult{
+			Name:    "Git Repository",
+			Status:  "FAIL",
+			Message: "Not in a Git repository",
+			Suggestions: []string{
+				"Run from within the headscale git repository",
+				"Clone the repository: git clone https://github.com/juanfont/headscale.git",
+			},
+		}
+	}
+
+	return DoctorResult{
+		Name:    "Git Repository",
+		Status:  "PASS",
+		Message: "Running in Git repository",
+	}
+}
+
+// checkRequiredFiles verifies required files exist.
+func checkRequiredFiles() DoctorResult {
+	requiredFiles := []string{
+		"go.mod",
+		"integration/",
+		"cmd/hi/",
+	}
+
+	var missingFiles []string
+	for _, file := range requiredFiles {
+		cmd := exec.Command("test", "-e", file)
+		if err := cmd.Run(); err != nil {
+			missingFiles = append(missingFiles, file)
+		}
+	}
+
+	if len(missingFiles) > 0 {
+		return DoctorResult{
+			Name:    "Required Files",
+			Status:  "FAIL",
+			Message: "Missing required files: " + strings.Join(missingFiles, ", "),
+			Suggestions: []string{
+				"Ensure you're in the headscale project root directory",
+				"Check that integration/ directory exists",
+				"Verify this is a complete headscale repository",
+			},
+		}
+	}
+
+	return DoctorResult{
+		Name:    "Required Files",
+		Status:  "PASS",
+		Message: "All required files found",
+	}
+}
+
+// displayDoctorResults shows the results in a formatted way.
+func displayDoctorResults(results []DoctorResult) {
+	log.Printf("🔍 System Health Check Results")
+	log.Printf("================================")
+
+	for _, result := range results {
+		var icon string
+		switch result.Status {
+		case "PASS":
+			icon = "✅"
+		case "WARN":
+			icon = "⚠️"
+		case "FAIL":
+			icon = "❌"
+		default:
+			icon = "❓"
+		}
+
+		log.Printf("%s %s: %s", icon, result.Name, result.Message)
+
+		if len(result.Suggestions) > 0 {
+			for _, suggestion := range result.Suggestions {
+				log.Printf("   💡 %s", suggestion)
+			}
+		}
+	}
+
+	log.Printf("================================")
+}
--- a/cmd/hi/main.go
+++ b/cmd/hi/main.go
@@ -0,0 +1,93 @@
+package main
+
+import (
+	"context"
+	"os"
+
+	"github.com/creachadair/command"
+	"github.com/creachadair/flax"
+)
+
+var runConfig RunConfig
+
+func main() {
+	root := command.C{
+		Name: "hi",
+		Help: "Headscale Integration test runner",
+		Commands: []*command.C{
+			{
+				Name:     "run",
+				Help:     "Run integration tests",
+				Usage:    "run [test-pattern] [flags]",
+				SetFlags: command.Flags(flax.MustBind, &runConfig),
+				Run:      runIntegrationTest,
+			},
+			{
+				Name: "doctor",
+				Help: "Check system requirements for running integration tests",
+				Run: func(env *command.Env) error {
+					return runDoctorCheck(env.Context())
+				},
+			},
+			{
+				Name: "clean",
+				Help: "Clean Docker resources",
+				Commands: []*command.C{
+					{
+						Name: "networks",
+						Help: "Prune unused Docker networks",
+						Run: func(env *command.Env) error {
+							return pruneDockerNetworks(env.Context())
+						},
+					},
+					{
+						Name: "images",
+						Help: "Clean old test images",
+						Run: func(env *command.Env) error {
+							return cleanOldImages(env.Context())
+						},
+					},
+					{
+						Name: "containers",
+						Help: "Kill all test containers",
+						Run: func(env *command.Env) error {
+							return killTestContainers(env.Context())
+						},
+					},
+					{
+						Name: "cache",
+						Help: "Clean Go module cache volume",
+						Run: func(env *command.Env) error {
+							return cleanCacheVolume(env.Context())
+						},
+					},
+					{
+						Name: "all",
+						Help: "Run all cleanup operations",
+						Run: func(env *command.Env) error {
+							return cleanAll(env.Context())
+						},
+					},
+				},
+			},
+			command.HelpCommand(nil),
+		},
+	}
+
+	env := root.NewEnv(nil).MergeFlags(true)
+	command.RunOrFail(env, os.Args[1:])
+}
+
+func cleanAll(ctx context.Context) error {
+	if err := killTestContainers(ctx); err != nil {
+		return err
+	}
+	if err := pruneDockerNetworks(ctx); err != nil {
+		return err
+	}
+	if err := cleanOldImages(ctx); err != nil {
+		return err
+	}
+
+	return cleanCacheVolume(ctx)
+}
--- a/cmd/hi/run.go
+++ b/cmd/hi/run.go
@@ -0,0 +1,122 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/creachadair/command"
+)
+
+var ErrTestPatternRequired = errors.New("test pattern is required as first argument or use --test flag")
+
+type RunConfig struct {
+	TestPattern   string        `flag:"test,Test pattern to run"`
+	Timeout       time.Duration `flag:"timeout,default=120m,Test timeout"`
+	FailFast      bool          `flag:"failfast,default=true,Stop on first test failure"`
+	UsePostgres   bool          `flag:"postgres,default=false,Use PostgreSQL instead of SQLite"`
+	GoVersion     string        `flag:"go-version,Go version to use (auto-detected from go.mod)"`
+	CleanBefore   bool          `flag:"clean-before,default=true,Clean resources before test"`
+	CleanAfter    bool          `flag:"clean-after,default=true,Clean resources after test"`
+	KeepOnFailure bool          `flag:"keep-on-failure,default=false,Keep containers on test failure"`
+	LogsDir       string        `flag:"logs-dir,default=control_logs,Control logs directory"`
+	Verbose       bool          `flag:"verbose,default=false,Verbose output"`
+}
+
+// runIntegrationTest executes the integration test workflow.
+func runIntegrationTest(env *command.Env) error {
+	args := env.Args
+	if len(args) > 0 && runConfig.TestPattern == "" {
+		runConfig.TestPattern = args[0]
+	}
+
+	if runConfig.TestPattern == "" {
+		return ErrTestPatternRequired
+	}
+
+	if runConfig.GoVersion == "" {
+		runConfig.GoVersion = detectGoVersion()
+	}
+
+	// Run pre-flight checks
+	if runConfig.Verbose {
+		log.Printf("Running pre-flight system checks...")
+	}
+	if err := runDoctorCheck(env.Context()); err != nil {
+		return fmt.Errorf("pre-flight checks failed: %w", err)
+	}
+
+	if runConfig.Verbose {
+		log.Printf("Running test: %s", runConfig.TestPattern)
+		log.Printf("Go version: %s", runConfig.GoVersion)
+		log.Printf("Timeout: %s", runConfig.Timeout)
+		log.Printf("Use PostgreSQL: %t", runConfig.UsePostgres)
+	}
+
+	return runTestContainer(env.Context(), &runConfig)
+}
+
+// detectGoVersion reads the Go version from go.mod file.
+func detectGoVersion() string {
+	goModPath := filepath.Join("..", "..", "go.mod")
+
+	if _, err := os.Stat("go.mod"); err == nil {
+		goModPath = "go.mod"
+	} else if _, err := os.Stat("../../go.mod"); err == nil {
+		goModPath = "../../go.mod"
+	}
+
+	content, err := os.ReadFile(goModPath)
+	if err != nil {
+		return "1.24"
+	}
+
+	lines := splitLines(string(content))
+	for _, line := range lines {
+		if len(line) > 3 && line[:3] == "go " {
+			version := line[3:]
+			if idx := indexOf(version, " "); idx != -1 {
+				version = version[:idx]
+			}
+
+			return version
+		}
+	}
+
+	return "1.24"
+}
+
+// splitLines splits a string into lines without using strings.Split.
+func splitLines(s string) []string {
+	var lines []string
+	var current string
+
+	for _, char := range s {
+		if char == '\n' {
+			lines = append(lines, current)
+			current = ""
+		} else {
+			current += string(char)
+		}
+	}
+
+	if current != "" {
+		lines = append(lines, current)
+	}
+
+	return lines
+}
+
+// indexOf finds the first occurrence of substr in s.
+func indexOf(s, substr string) int {
+	for i := 0; i <= len(s)-len(substr); i++ {
+		if s[i:i+len(substr)] == substr {
+			return i
+		}
+	}
+
+	return -1
+}