Integration tests

Local GCP integration tests for agents

Agent-written integration tests are safer when they run against disposable localhost services first. LocalCloud gives those tests BigQuery, Pub/Sub, Cloud Storage, Firestore, Spanner, Bigtable, and more in one container.

Read docs Check compatibility SDK examples

Agent prompt CTAs

Configure this repo

Have an agent wire an existing project to LocalCloud safely.

Set up this repository to use LocalCloud for local GCP development. First read https://local.cloud/ai/agents.md, then inspect this repo, identify the GCP services and SDK language, configure emulator environment variables, and run the narrowest integration test against localhost. Do not use real GCP credentials or production endpoints.

Start LocalCloud

Give an agent one URL and have it start the local GCP sandbox.

Fetch https://local.cloud/ai/agents.md and follow the instructions to start LocalCloud on my machine. Verify Docker, start or reuse the localcloud container, export emulator environment variables, and run one local GCP SDK/API smoke check. Do not ask for or use real GCP credentials.

Troubleshoot routing

Diagnose why SDKs or Terraform are still reaching real GCP.

Troubleshoot my LocalCloud setup. Read https://local.cloud/ai/agents.md, check whether Docker and the localcloud container are healthy, verify emulator environment variables are set in this shell/test runner, and identify any SDK or Terraform configuration that could still call real Google Cloud.

Fact

Use real SDK clients; avoid mocks for service behavior.

Fact

Seed fixtures locally for repeatable runs.

Fact

Unset emulator env vars before production validation.

Test design

Exercise behavior that can actually break

Use LocalCloud for SDK routing, serialization, resource naming, query syntax, event flow, and setup/teardown behavior. Keep pure unit tests for business logic.

State control

Reset or seed local state deliberately

Agents should create the minimum data they need or load seed fixtures. Avoid depending on a previous local run.

Copy-ready setup

Commands and prompts

Use these snippets as starting points, then keep the checks scoped to localhost until you intentionally validate against real Google Cloud.

Local test wrapper

set -euo pipefail
eval "$(localcloud env)"
export GOOGLE_CLOUD_PROJECT=local-gcp-project
./scripts/integration-test.sh

Limitations

Use the sandbox deliberately

Permitted workflows use local endpoint values and should stop rather than fall back to real Google Cloud or real credentials. The Public Preview License permits individuals and organizations, including for-profit companies, to use LocalCloud for non-production internal development, testing, CI, evaluation, and pilots.
LocalCloud emulates bounded local development workflows. Validate application behavior against real Google Cloud before production deployment.
Before production deployment, unset LocalCloud emulator environment variables and validate behavior against real Google Cloud.

Next routes

Keep the agent on the supported path

SDK examples — Language-specific SDK routing examples.
Seed data — Repeatable fixture loading.
Compatibility matrix — Check current support boundaries before relying on a local-only test.
Service catalog — Review every LocalCloud service, endpoint, and limitation.
SDK examples — Use standard Google Cloud SDKs pointed at localhost.
Seed data — Load deterministic fixtures for repeatable agent and CI runs.