ci: Add snapshot tests for changes in the API

CONTRIBUTING.md

@@ -142,6 +142,17 @@ gcloud auth login --update-adc
 make run-api-server
 ```
 
+#### API E2E Snapshots
+
+If you have made any changes to the API, please update the API query snapshots with
+
+```shell
+gcloud auth login --update-adc
+make update-api-snapshots
+```
+
+and check the git diff to see if the API result changes are expected.
+
 ### Making commits
 
 Please follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for commit messages. This helps us to automate processes like changelog generation and ensures a clear and consistent commit history.

Makefile

@@ -47,6 +47,12 @@ api-server-tests:
 	test -f $(HOME)/.config/gcloud/application_default_credentials.json || (echo "GCP Application Default Credentials not set, try 'gcloud auth login --update-adc'"; exit 1)
 	cd gcp/api && docker build -f Dockerfile.esp -t osv/esp:latest .
 	cd gcp/api && ./run_tests.sh $(HOME)/.config/gcloud/application_default_credentials.json
+	cd gcp/api && ./run_tests_e2e.sh $(HOME)/.config/gcloud/application_default_credentials.json
+
+update-api-snapshots:
+	test -f $(HOME)/.config/gcloud/application_default_credentials.json || (echo "GCP Application Default Credentials not set, try 'gcloud auth login --update-adc'"; exit 1)
+	cd gcp/api && docker build -f Dockerfile.esp -t osv/esp:latest .
+	cd gcp/api && UPDATE_SNAPS=true ./run_tests_e2e.sh $(HOME)/.config/gcloud/application_default_credentials.json
 
 lint:
 	GOTOOLCHAIN=go1.25.5 $(run-cmd) tools/lint_and_format.sh

deployment/terraform/environments/oss-vdb/unmanaged.md

@@ -42,6 +42,7 @@ Not everything here needs to be managed by Terraform, this is just for reference
   - `esp-test`
   - `osv-user` (unused?)
   - `terraform-plan`
+  - `api-e2e-tester`
   - `worker` (unused?)
 - A number of IAM permissions
 - `osv-vulnerabilities GCS bucket health` Monitoring Alert Policy

gcp/api/cloudbuild.yaml

@@ -41,7 +41,16 @@ steps:
   args: ['bash', '-ex', 'run_tests.sh', '/workspace/dummy.json']
   waitFor: ['init', 'sync']
 
+- name: 'gcr.io/oss-vdb/ci'
+  id: 'api-snapshot-tests'
+  dir: gcp/api
+  args: ['bash', '-ex', 'run_tests_e2e.sh', '/workspace/dummy.json']
+  # Don't run at the same time as api-tests
+  waitFor: ['init', 'sync', 'api-tests']
+
 timeout: 7200s
+serviceAccount: 'projects/oss-vdb/serviceAccounts/api-e2e-tester@oss-vdb.iam.gserviceaccount.com'
 options:
+  logging: CLOUD_LOGGING_ONLY
   env:
     - CLOUDBUILD=1

gcp/api/run_apitester.py

@@ -0,0 +1,72 @@
+# 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.
+"""Run E2E golang cassette API tests."""
+
+import os
+import sys
+import subprocess
+import time
+import test_server
+
+_PORT = 8080
+
+
+def main():
+  if len(sys.argv) < 2:
+    print(f'Usage: {sys.argv[0]} path/to/credential.json')
+    sys.exit(1)
+
+  credential_path = sys.argv[1]
+
+  # Ensure Docker image is pulled
+  subprocess.run(
+      ['docker', 'pull', 'gcr.io/endpoints-release/endpoints-runtime:2'],
+      check=True)
+
+  print("Starting test server...")
+  server = test_server.start(credential_path, port=_PORT)
+
+  # Wait for server to start up
+  time.sleep(10)
+
+  try:
+    # Determine API URL
+    if os.getenv('CLOUDBUILD'):
+      host = test_server.get_cloudbuild_esp_host()
+    else:
+      host = 'localhost'
+
+    api_base_url = f"{host}:{_PORT}"
+    print(f"Running Go tests against {api_base_url}")
+
+    env = os.environ.copy()
+    env['OSV_API_BASE_URL'] = api_base_url
+
+    # Go tests path
+    # Assuming this script is in gcp/api/
+    go_test_dir = os.path.abspath(
+        os.path.join(os.path.dirname(__file__), '../../tools/apitester'))
+
+    cmd = ['go', 'test', './...']
+    print(f"Executing: {' '.join(cmd)} in {go_test_dir}")
+
+    subprocess.run(cmd, cwd=go_test_dir, env=env, check=True)
+
+  finally:
+    print("Stopping test server...")
+    server.stop()
+
+
+if __name__ == '__main__':
+  main()

gcp/api/run_tests_e2e.sh

@@ -0,0 +1,31 @@
+#!/bin/bash -x
+# 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.
+
+if [ $# -lt 1 ]; then
+  echo "Usage: $0 /path/to/credential.json"
+  exit 1
+fi
+
+export GOOGLE_CLOUD_PROJECT=oss-vdb-test OSV_VULNERABILITIES_BUCKET=osv-test-vulnerabilities
+
+# Try to start docker if not running (mostly for CI)
+service docker start || true
+
+set -e
+
+if [ -z "$CLOUDBUILD" ]; then
+  poetry sync
+fi
+poetry run python run_apitester.py "$1"

tools/apitester/README.md

@@ -46,4 +46,5 @@ Before the test suite is actually run, the cassettes will be "cleaned" so that
 - the `response` is property is not present, to reduce the size of each cassette
 
 By default, requests are made against the local instance of the API, but you can
-use the `OSV_API_BASE_URL` to point it against other instances.
+use the `OSV_API_BASE_URL` to point it against other instances. 
+E.g. `OSV_API_BASE_URL=api.test.osv.dev go test ./...`