Merge pull request ghostunnel#678 from ghostunnel/claude/setup-go-integration-tests-1FT6X

Update AGENTS.md with Go toolchain setup and integration test instructions

Author: csstaub

CONTRIBUTING.md

@@ -7,28 +7,55 @@ When submitting code, please make efforts to follow existing conventions and
 style in order to keep the code as readable as possible. Please also make sure
 all tests pass by running `mage test:all`, and format your code with `go fmt`.
 
+## Go Toolchain Setup
+
+This project requires the Go version specified in `go.mod`. If the default `go`
+on PATH is older, builds will fail with a version mismatch error.
+
+**Claude Code (cloud environment):** Multiple Go versions are installed
+side-by-side under `/usr/local/`. The default `/usr/local/go/` may be older
+than what this project requires. Check for a matching version (e.g.
+`/usr/local/go<VERSION>/bin/go`) and prepend it to your PATH:
+
+```bash
+# Find available Go versions
+ls /usr/local/go*/bin/go
+
+# Use the version that matches go.mod (check with: grep '^go ' go.mod)
+export PATH="/usr/local/go<VERSION>/bin:$PATH"
+go version
+```
+
+Mage is available as a Go tool dependency (no separate install needed):
+
+```bash
+go tool mage -l   # list all targets
+```
+
 ## Build & Test Commands
 
-This project uses [mage](https://magefile.org) as the build system (defined in `magefile.go`):
+This project uses [mage](https://magefile.org) as the build system (defined in `magefile.go`).
+Invoke it via `go tool mage` (not a standalone `mage` binary):
 
 ```bash
-mage go:build              # Build binary
-mage go:lint               # Run golangci-lint (config: .golangci.yml)
-mage test:all              # Unit + integration tests with merged coverage
-mage test:unit             # Go unit tests only
-mage test:integration      # Python integration tests only
-mage test:docker           # Full suite in Docker (includes PKCS#11/SoftHSM)
-mage test:keys             # Generate test certificates in test-keys/
-mage docker:build          # Build Docker images
-mage -l                    # List all available targets
+go tool mage go:build              # Build binary
+go tool mage go:lint               # Run golangci-lint (config: .golangci.yml)
+go tool mage test:all              # Unit + integration tests with merged coverage
+go tool mage test:unit             # Go unit tests only
+go tool mage test:integration      # Python integration tests only
+go tool mage test:docker           # Full suite in Docker (includes PKCS#11/SoftHSM)
+go tool mage test:keys             # Generate test certificates in test-keys/
+go tool mage docker:build          # Build Docker images
+go tool mage -l                    # List all available targets
 ```
 
 ### Running a Single Test
 
 ```bash
-go test -v -run TestName ./...       # Single Go unit test
-go test -v ./auth/...                # All tests in a package
-cd tests && python3 test-name.py     # Single integration test
+go test -v -run TestName ./...                   # Single Go unit test
+go test -v ./auth/...                            # All tests in a package
+go tool mage test:single test-server-pem-rsa     # Single integration test (via mage)
+cd tests && python3 test-server-pem-rsa.py       # Single integration test (directly)
 ```
 
 ### Linting
@@ -52,14 +79,30 @@ run checks on a live instance. If you are adding new features or changing
 existing behavior, please add/update the integration tests in the `tests/`
 directory accordingly. The tests use the `tests/common.py` helper module.
 
-Integration tests run in parallel by default (up to `NumCPU`, capped at 16 by default).
-Set `GHOSTUNNEL_TEST_PARALLEL` to control the number of concurrent tests (may exceed the default cap):
+### Prerequisites
+
+1. **Go** at the version specified in `go.mod` on PATH (see "Go Toolchain Setup" above).
+2. **Python 3** with packages used by the test harness (typically already available).
+3. **Test certificates** must be generated before the first run:
+
+```bash
+go tool mage test:keys        # generates certs in test-keys/
+```
+
+### Running Integration Tests
 
 ```bash
-GHOSTUNNEL_TEST_PARALLEL=4 mage test:integration
+go tool mage test:integration                              # all integration tests
+go tool mage test:single test-server-pem-rsa               # single test by name
+GHOSTUNNEL_TEST_PARALLEL=4 go tool mage test:integration   # control parallelism
 ```
 
-Test certificates are generated in `test-keys/` via `mage test:keys`.
+Integration tests run in parallel by default (up to `NumCPU`, capped at 16).
+Set `GHOSTUNNEL_TEST_PARALLEL` to control the number of concurrent tests (may exceed the default cap).
+
+The integration test runner first builds a coverage-instrumented test binary
+(`go test -c`), then runs each `tests/test-*.py` script against that binary.
+Each Python test starts a ghostunnel process, exercises it, and verifies behavior.
 
 ## Architecture Overview
 

README.md

@@ -64,7 +64,7 @@ started is to use a package like [cloudflare/cfssl](https://github.com/cloudflar
 For testing and development purposes, you can generate test certificates using:
 
     # Generate test certificates and keys
-    mage test:keys
+    go tool mage test:keys
 
 This will create a `test-keys` directory with all the necessary certificates and keys
 for testing. **Note: These are test certificates only and should NOT be used in production.**
@@ -78,16 +78,17 @@ built directly via Github Actions on the latest available images. If you need
 compatibility for specific OS versions we recommend building yourself.
 
 Ghostunnel uses the [mage][mage] build system, a make/rake-like build tool using
-Go. You can build Ghostunnel with the [mage][mage] commands shown below.
+Go. Mage is available as a Go tool dependency (no separate install needed). You
+can build Ghostunnel with the commands shown below.
 
     # Compile binary
-    mage go:build
+    go tool mage go:build
 
     # Build containers
-    mage docker:build
+    go tool mage docker:build
 
-You can also run `mage -l` to view all build targets and add `-v` to mage commands
-to get more verbose output.
+You can also run `go tool mage -l` to view all build targets and add `-v` to
+mage commands to get more verbose output.
 
 [rel]: https://github.com/ghostunnel/ghostunnel/releases
 [hub]: https://hub.docker.com/r/ghostunnel/ghostunnel
@@ -101,11 +102,11 @@ suite requires Python 3.
 To run tests:
 
     # Option 1: run unit & integration tests locally
-    mage test:all
+    go tool mage test:all
 
     # Option 2: run unit & integration tests in a Docker container
     # This also runs PKCS#11 integration tests using SoftHSM in the container
-    mage test:docker
+    go tool mage test:docker
 
     # Open coverage information in browser
     go tool cover -html coverage/all.profile
@@ -153,7 +154,7 @@ information. In this example, we assume that the CN of the client cert we want
 to accept connections from is `client`.
 
 **Note:** Before running the examples below, make sure you have generated the test
-certificates by running `mage test:keys` (see the [Getting Started](#getting-started)
+certificates by running `go tool mage test:keys` (see the [Getting Started](#getting-started)
 section above).
 
 Start a backend server: