PR and Regression testing for Go snippets

.github/workflows/go-snippets-pr-check.yaml

@@ -0,0 +1,84 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: Go Snippets Build on PR and Schedule
+
+on:
+  # Run on pull requests targeting the main branch.
+  pull_request:
+    branches: [ "main" ]
+
+  # Run on a weekly schedule (every Sunday at 3:00 AM UTC).
+  schedule:
+    - cron: '0 3 * * 0'
+
+jobs:
+  # This job builds and runs the Go snippets.
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        # Fetch the entire history to compare branches in the PR.
+        fetch-depth: 0
+
+    - name: Set up Go
+      uses: actions/setup-go@v5
+      with:
+        go-version: '1.22'
+
+    - name: Cache Go modules
+      uses: actions/cache@v3
+      with:
+        path: ~/go/pkg/mod
+        key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+        restore-keys: |
+          ${{ runner.os }}-go-
+
+    # --- PR-Specific Checks ---
+    # These steps only run for pull request events.
+
+    - name: Find new, un-tested Go files (PR only)
+      if: github.event_name == 'pull_request'
+      run: |
+        echo "Checking for any new Go files that are not in the build script..."
+        ./tools/go-snippets/check_go_snippets.sh
+
+    - name: Get changed Go snippet files (PR only)
+      if: github.event_name == 'pull_request'
+      id: changed-files
+      run: |
+        # This command gets the list of changed .go files in the snippets directory
+        # between the PR's head and the base branch.
+        # The output is an escaped, space-separated string suitable for shell commands.
+        CHANGED_FILES=$(git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.head.sha }} -- 'examples/go/snippets/**/*.go' | xargs)
+        echo "changed_files=${CHANGED_FILES}" >> $GITHUB_OUTPUT
+        echo "Detected changes in: ${CHANGED_FILES}"
+
+    - name: Build changed Go snippets (PR only)
+      if: github.event_name == 'pull_request' && steps.changed-files.outputs.changed_files != ''
+      run: |
+        echo "Building only the changed Go files..."
+        ./tools/go-snippets/runner.sh build ${{ steps.changed-files.outputs.changed_files }}
+
+    # --- Scheduled Checks ---
+    # These steps only run on the weekly schedule.
+
+    - name: Build all Go snippets (Scheduled)
+      if: github.event_name == 'schedule'
+      run: |
+        echo "Running weekly build for all Go snippets..."
+        ./tools/go-snippets/runner.sh build

examples/go/go.mod

@@ -0,0 +1,46 @@
+module snippets
+
+go 1.25.1
+
+require (
+	google.golang.org/adk v0.2.0
+	google.golang.org/genai v1.35.0
+)
+
+require (
+	cloud.google.com/go v0.123.0 // indirect
+	cloud.google.com/go/auth v0.17.0 // indirect
+	cloud.google.com/go/compute/metadata v0.9.0 // indirect
+	github.com/a2aproject/a2a-go v0.3.0 // indirect
+	github.com/awalterschulze/gographviz v2.0.3+incompatible // indirect
+	github.com/felixge/httpsnoop v1.0.4 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/google/go-cmp v0.7.0 // indirect
+	github.com/google/jsonschema-go v0.3.0 // indirect
+	github.com/google/s2a-go v0.1.9 // indirect
+	github.com/google/safehtml v0.1.0 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/googleapis/enterprise-certificate-proxy v0.3.6 // indirect
+	github.com/googleapis/gax-go/v2 v2.15.0 // indirect
+	github.com/gorilla/mux v1.8.1 // indirect
+	github.com/gorilla/websocket v1.5.3 // indirect
+	github.com/mitchellh/mapstructure v1.5.0 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.63.0 // indirect
+	go.opentelemetry.io/otel v1.38.0 // indirect
+	go.opentelemetry.io/otel/metric v1.38.0 // indirect
+	go.opentelemetry.io/otel/sdk v1.38.0 // indirect
+	go.opentelemetry.io/otel/trace v1.38.0 // indirect
+	golang.org/x/crypto v0.45.0 // indirect
+	golang.org/x/net v0.47.0 // indirect
+	golang.org/x/sync v0.18.0 // indirect
+	golang.org/x/sys v0.38.0 // indirect
+	golang.org/x/text v0.31.0 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20251014184007-4626949a642f // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20251014184007-4626949a642f // indirect
+	google.golang.org/grpc v1.76.0 // indirect
+	google.golang.org/protobuf v1.36.10 // indirect
+	rsc.io/omap v1.2.0 // indirect
+	rsc.io/ordered v1.1.1 // indirect
+)

examples/go/go.sum

@@ -0,0 +1,93 @@
+cloud.google.com/go v0.123.0 h1:2NAUJwPR47q+E35uaJeYoNhuNEM9kM8SjgRgdeOJUSE=
+cloud.google.com/go v0.123.0/go.mod h1:xBoMV08QcqUGuPW65Qfm1o9Y4zKZBpGS+7bImXLTAZU=
+cloud.google.com/go/auth v0.17.0 h1:74yCm7hCj2rUyyAocqnFzsAYXgJhrG26XCFimrc/Kz4=
+cloud.google.com/go/auth v0.17.0/go.mod h1:6wv/t5/6rOPAX4fJiRjKkJCvswLwdet7G8+UGXt7nCQ=
+cloud.google.com/go/compute/metadata v0.9.0 h1:pDUj4QMoPejqq20dK0Pg2N4yG9zIkYGdBtwLoEkH9Zs=
+cloud.google.com/go/compute/metadata v0.9.0/go.mod h1:E0bWwX5wTnLPedCKqk3pJmVgCBSM6qQI1yTBdEb3C10=
+github.com/a2aproject/a2a-go v0.3.0 h1:mnfBEDJXShzEhXCmUbfZ9xo8sXfq2pCxemsY9uasvzg=
+github.com/a2aproject/a2a-go v0.3.0/go.mod h1:8C0O6lsfR7zWFEqVZz/+zWCoxe8gSWpknEpqm/Vgj3E=
+github.com/awalterschulze/gographviz v2.0.3+incompatible h1:9sVEXJBJLwGX7EQVhLm2elIKCm7P2YHFC8v6096G09E=
+github.com/awalterschulze/gographviz v2.0.3+incompatible/go.mod h1:GEV5wmg4YquNw7v1kkyoX9etIk8yVmXj+AkDHuuETHs=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
+github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/jsonschema-go v0.3.0 h1:6AH2TxVNtk3IlvkkhjrtbUc4S8AvO0Xii0DxIygDg+Q=
+github.com/google/jsonschema-go v0.3.0/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
+github.com/google/s2a-go v0.1.9 h1:LGD7gtMgezd8a/Xak7mEWL0PjoTQFvpRudN895yqKW0=
+github.com/google/s2a-go v0.1.9/go.mod h1:YA0Ei2ZQL3acow2O62kdp9UlnvMmU7kA6Eutn0dXayM=
+github.com/google/safehtml v0.1.0 h1:EwLKo8qawTKfsi0orxcQAZzu07cICaBeFMegAU9eaT8=
+github.com/google/safehtml v0.1.0/go.mod h1:L4KWwDsUJdECRAEpZoBn3O64bQaywRscowZjJAzjHnU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/googleapis/enterprise-certificate-proxy v0.3.6 h1:GW/XbdyBFQ8Qe+YAmFU9uHLo7OnF5tL52HFAgMmyrf4=
+github.com/googleapis/enterprise-certificate-proxy v0.3.6/go.mod h1:MkHOF77EYAE7qfSuSS9PU6g4Nt4e11cnsDUowfwewLA=
+github.com/googleapis/gax-go/v2 v2.15.0 h1:SyjDc1mGgZU5LncH8gimWo9lW1DtIfPibOG81vgd/bo=
+github.com/googleapis/gax-go/v2 v2.15.0/go.mod h1:zVVkkxAQHa1RQpg9z2AUCMnKhi0Qld9rcmyfL1OZhoc=
+github.com/gorilla/mux v1.8.1 h1:TuBL49tXwgrFYWhqrNgrUNEY92u81SPhu7sTdzQEiWY=
+github.com/gorilla/mux v1.8.1/go.mod h1:AKf9I4AEqPTmMytcMc0KkNouC66V3BtZ4qD5fmWSiMQ=
+github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
+github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
+github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.63.0 h1:RbKq8BG0FI8OiXhBfcRtqqHcZcka+gU3cskNuf05R18=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.63.0/go.mod h1:h06DGIukJOevXaj/xrNjhi/2098RZzcLTbc0jDAUbsg=
+go.opentelemetry.io/otel v1.38.0 h1:RkfdswUDRimDg0m2Az18RKOsnI8UDzppJAtj01/Ymk8=
+go.opentelemetry.io/otel v1.38.0/go.mod h1:zcmtmQ1+YmQM9wrNsTGV/q/uyusom3P8RxwExxkZhjM=
+go.opentelemetry.io/otel/metric v1.38.0 h1:Kl6lzIYGAh5M159u9NgiRkmoMKjvbsKtYRwgfrA6WpA=
+go.opentelemetry.io/otel/metric v1.38.0/go.mod h1:kB5n/QoRM8YwmUahxvI3bO34eVtQf2i4utNVLr9gEmI=
+go.opentelemetry.io/otel/sdk v1.38.0 h1:l48sr5YbNf2hpCUj/FoGhW9yDkl+Ma+LrVl8qaM5b+E=
+go.opentelemetry.io/otel/sdk v1.38.0/go.mod h1:ghmNdGlVemJI3+ZB5iDEuk4bWA3GkTpW+DOoZMYBVVg=
+go.opentelemetry.io/otel/sdk/metric v1.38.0 h1:aSH66iL0aZqo//xXzQLYozmWrXxyFkBJ6qT5wthqPoM=
+go.opentelemetry.io/otel/sdk/metric v1.38.0/go.mod h1:dg9PBnW9XdQ1Hd6ZnRz689CbtrUp0wMMs9iPcgT9EZA=
+go.opentelemetry.io/otel/trace v1.38.0 h1:Fxk5bKrDZJUH+AMyyIXGcFAPah0oRcT+LuNtJrmcNLE=
+go.opentelemetry.io/otel/trace v1.38.0/go.mod h1:j1P9ivuFsTceSWe1oY+EeW3sc+Pp42sO++GHkg4wwhs=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
+golang.org/x/crypto v0.45.0 h1:jMBrvKuj23MTlT0bQEOBcAE0mjg8mK9RXFhRH6nyF3Q=
+golang.org/x/crypto v0.45.0/go.mod h1:XTGrrkGJve7CYK7J8PEww4aY7gM3qMCElcJQ8n8JdX4=
+golang.org/x/net v0.47.0 h1:Mx+4dIFzqraBXUugkia1OOvlD6LemFo1ALMHjrXDOhY=
+golang.org/x/net v0.47.0/go.mod h1:/jNxtkgq5yWUGYkaZGqo27cfGZ1c5Nen03aYrrKpVRU=
+golang.org/x/sync v0.18.0 h1:kr88TuHDroi+UVf+0hZnirlk8o8T+4MrK6mr60WkH/I=
+golang.org/x/sync v0.18.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sys v0.38.0 h1:3yZWxaJjBmCWXqhN1qh02AkOnCQ1poK6oF+a7xWL6Gc=
+golang.org/x/sys v0.38.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.31.0 h1:aC8ghyu4JhP8VojJ2lEHBnochRno1sgL6nEi9WGFGMM=
+golang.org/x/text v0.31.0/go.mod h1:tKRAlv61yKIjGGHX/4tP1LTbc13YSec1pxVEWXzfoeM=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
+gonum.org/v1/gonum v0.16.0/go.mod h1:fef3am4MQ93R2HHpKnLk4/Tbh/s0+wqD5nfa6Pnwy4E=
+google.golang.org/adk v0.2.0 h1:X+iAZ2uiJMtOp8sbevcPtnVpTQmymaeN6qsVnBKmJ/s=
+google.golang.org/adk v0.2.0/go.mod h1:Nl15krF+mrvl/kCXOy+haxquJwSpLLbsKGScqCwkn60=
+google.golang.org/genai v1.35.0 h1:Jo6g25CzVqFzGrX5mhWyBgQqXAUzxcx5jeK7U74zv9c=
+google.golang.org/genai v1.35.0/go.mod h1:A3kkl0nyBjyFlNjgxIwKq70julKbIxpSxqKO5gw/gmk=
+google.golang.org/genproto/googleapis/api v0.0.0-20251014184007-4626949a642f h1:OiFuztEyBivVKDvguQJYWq1yDcfAHIID/FVrPR4oiI0=
+google.golang.org/genproto/googleapis/api v0.0.0-20251014184007-4626949a642f/go.mod h1:kprOiu9Tr0JYyD6DORrc4Hfyk3RFXqkQ3ctHEum3ZbM=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20251014184007-4626949a642f h1:1FTH6cpXFsENbPR5Bu8NQddPSaUUE6NA2XdZdDSAJK4=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20251014184007-4626949a642f/go.mod h1:7i2o+ce6H/6BluujYR+kqX3GKH+dChPTQU19wjRPiGk=
+google.golang.org/grpc v1.76.0 h1:UnVkv1+uMLYXoIz6o7chp59WfQUYA2ex/BXQ9rHZu7A=
+google.golang.org/grpc v1.76.0/go.mod h1:Ju12QI8M6iQJtbcsV+awF5a4hfJMLi4X0JLo94ULZ6c=
+google.golang.org/protobuf v1.36.10 h1:AYd7cD/uASjIL6Q9LiTjz8JLcrh/88q5UObnmY3aOOE=
+google.golang.org/protobuf v1.36.10/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+rsc.io/omap v1.2.0 h1:c1M8jchnHbzmJALzGLclfH3xDWXrPxSUHXzH5C+8Kdw=
+rsc.io/omap v1.2.0/go.mod h1:C8pkI0AWexHopQtZX+qiUeJGzvc8HkdgnsWK4/mAa00=
+rsc.io/ordered v1.1.1 h1:1kZM6RkTmceJgsFH/8DLQvkCVEYomVDJfBRLT595Uak=
+rsc.io/ordered v1.1.1/go.mod h1:evAi8739bWVBRG9aaufsjVc202+6okf8u2QeVL84BCM=

examples/go/snippets/sessions/session_management_example/session_management_example.go

@@ -37,22 +37,6 @@ func main() {
 	inMemoryService := session.InMemoryService()
 	fmt.Println("Initialized InMemoryService.")
 
-	// --8<-- [start:vertexai_service]
-	// 2. VertexAIService
-	// Before running, ensure your environment is authenticated:
-	// gcloud auth application-default login
-	// export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
-	// export GOOGLE_CLOUD_LOCATION="your-gcp-location"
-	modelName := "gemini-1.5-flash-001" // Replace with your desired model
-	vertexService, err := session.VertexAIService(ctx, modelName)
-	if err != nil {
-		log.Printf("Could not initialize VertexAIService (this is expected if the gcloud project is not set): %v", err)
-	} else {
-		fmt.Println("Successfully initialized VertexAIService.")
-	}
-	// --8<-- [end:vertexai_service]
-	_ = vertexService // Avoid unused variable error if initialization fails.
-
 	// --- Examining Session Properties ---
 	// We'll use the InMemoryService for this demonstration.
 	// --8<-- [start:examine_session]

tools/go-snippets/README.md

@@ -0,0 +1,80 @@
+# Go Snippets Tooling
+
+This directory contains the scripts and configuration for building, running, and testing the Go snippets located in `examples/go/`.
+
+## Overview
+
+The tooling is designed to ensure that all Go snippets are continuously validated and to provide a fast feedback loop for developers. It consists of a unified runner script, a configuration file to manage the list of snippets, and a suite of unit tests for the runner itself.
+
+## Key Components
+
+- **`runner.sh`**: The main script for building and running Go snippets.
+- **`files_to_test.txt`**: The configuration file that lists all Go snippets to be tested.
+- **`check_go_snippets.sh`**: A PR check script that ensures all `.go` files are registered in `files_to_test.txt`.
+- **`runner_test.sh`**: Unit tests for the `runner.sh` script.
+
+---
+
+## How to Use
+
+### Automatic Execution (CI/CD)
+
+The scripts are primarily designed to be run automatically by GitHub Actions.
+
+- **On Pull Requests:** When a pull request is opened, two workflows are triggered:
+    1.  **Go Snippets Build on PR and Schedule:** This workflow runs `check_go_snippets.sh` to ensure new files are registered. It then intelligently builds **only the `.go` files that were changed** in the PR.
+    2.  **Go Build and Test on PR:** This workflow runs a full build of **all** Go snippets and executes any unit tests (`go test ./...`) to ensure that a change has not broken any other part of the Go codebase.
+
+- **Scheduled Runs:** A full regression build of all Go snippets is run automatically every Sunday at 3:00 AM UTC to catch any potential issues.
+
+### Manual Execution
+
+You can also run the scripts locally to test your changes before pushing. All commands should be run from the **root of the repository**.
+
+#### Building All Snippets
+
+To run a full build of every Go snippet listed in `files_to_test.txt`:
+
+```bash
+./tools/go-snippets/runner.sh build
+```
+
+#### Building Specific Snippets
+
+To build one or more specific Go snippets (for example, if you are working on them and want a quick check):
+
+```bash
+./tools/go-snippets/runner.sh build examples/go/snippets/quickstart/main.go
+```
+
+#### Running the Unit Tests
+
+To run the unit tests for the `runner.sh` script itself:
+
+```bash
+./tools/go-snippets/runner_test.sh
+```
+
+---
+
+## Maintaining the Snippet List
+
+### Adding a New Snippet
+
+1.  Create your new `.go` file (e.g., `examples/go/snippets/my-new-snippet/main.go`).
+2.  Open `tools/go-snippets/files_to_test.txt`.
+3.  Add a new line with the path to your file, relative to the `examples/go/` directory.
+
+    ```
+    # In files_to_test.txt
+    snippets/my-new-snippet/main.go
+    ```
+
+4.  If your snippet is part of a package that requires multiple files to be built together, add them all to the same line:
+
+    ```
+    # In files_to_test.txt
+    snippets/my-multi-file-snippet/main.go snippets/my-multi-file-snippet/helpers.go
+    ```
+
+The `check_go_snippets.sh` script will automatically run on your PR and remind you if you've forgotten to add your new file to the list.

tools/go-snippets/check_go_snippets.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# This script ensures that every .go file within the Go snippets directory
+# is referenced in the files_to_test.txt file. This prevents new snippets
+# from being added without being included in the regression test suite.
+
+# --- Configuration ---
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+EXIT_CODE=0
+SNIPPETS_FILE="tools/go-snippets/files_to_test.txt"
+
+# --- Logic ---
+echo "Checking for Go files that are not registered in ${SNIPPETS_FILE}..."
+
+# Find all .go files in the snippets directory, excluding _test.go files.
+all_go_files=$(find examples/go -type f -name "*.go" ! -name "*_test.go" | sed 's|examples/go/||' | sort)
+
+# Extract all .go file paths from the snippets file, ignoring comments and arguments.
+referenced_files=$(grep -v '^\s*#' "${SNIPPETS_FILE}" | grep -o '[a-zA-Z0-9/._-]*\.go' | sort | uniq)
+
+# Compare the list of all .go files with the list of referenced files.
+unreferenced_files=$(comm -23 <(echo "${all_go_files}") <(echo "${referenced_files}"))
+
+if [[ -n "${unreferenced_files}" ]]; then
+  echo -e "${RED}Error: The following Go files were found but are not referenced in ${SNIPPETS_FILE}:${NC}"
+  # Indent the list of files for readability.
+  echo "${unreferenced_files}" | sed 's/^/  /'
+  echo
+  echo "Please add them to ${SNIPPETS_FILE} to include them in the regression tests."
+  EXIT_CODE=1
+else
+  echo "All Go files are correctly referenced in the snippets file."
+fi
+
+# Check for files in the list that don't exist on disk
+dangling_references=$(comm -23 <(echo "${referenced_files}") <(echo "${all_go_files}"))
+
+if [[ -n "${dangling_references}" ]]; then
+  echo -e "${RED}Error: The following files are referenced in ${SNIPPETS_FILE} but do not exist:${NC}"
+  echo "${dangling_references}" | sed 's/^/  /'
+  echo
+  echo "Please remove them from ${SNIPPETS_FILE}."
+  EXIT_CODE=1
+fi
+
+exit ${EXIT_CODE}