Using proxymock with GCP Services

A local mock can keep development moving when a Google Cloud API is unavailable or expensive to call repeatedly. The useful boundary is specific: record an application workflow, then use its captured responses to test the caller. A recording does not turn your laptop into an implementation of Google Cloud.

This guide uses a Cloud Storage object-listing workflow as the example. Your application still makes its normal supported API calls, but matching dependency calls can be answered by proxymock after recording. Keep the example read-only until you have verified the capture and matching behavior.

What to test with a GCP mock

Use captured responses to check parsing, application decisions, and handling of known errors. For example, test how the application handles an empty object list or an unavailable dependency. A mock only returns the behavior you configured or recorded; it does not discover missing error cases for you.

Keep separate tests for IAM permissions, OAuth token acquisition and refresh, and the actual behavior of Google Cloud services. A captured Cloud Storage listing does not implement object persistence. A captured Pub/Sub exchange does not establish acknowledgement deadlines, redelivery, or delivery guarantees. The service virtualization guide describes why a test substitute still needs explicit coverage limits.

Record the application calling Google Cloud

Follow the proxymock installation instructions and configure its API key. Run the application with test credentials and a test Google Cloud project. Capturing a workflow still calls the real API and can consume its quota.

For an application started with python app.py, use:

proxymock record --out ./gcp-recording -- python app.py

Substitute your own startup command, exercise the Cloud Storage listing through your application, and stop the recording. Use the language configuration guide to configure the SDK’s proxy and certificate handling. SDKs may use HTTP or gRPC, so confirm the protocol and client configuration rather than assuming an HTTP environment variable is sufficient.

Inspect the result:

proxymock web --in ./gcp-recording

Open the printed local address and confirm that the expected Google Cloud request and response were recorded. Check the bucket or resource path, query parameters, and response body. Do not proceed on the assumption that a successful application request necessarily passed through the recorder.

Use the recorded response locally

Start the same application with the recording as mock input:

proxymock mock --in ./gcp-recording --no-passthrough -- python app.py

Run the same object-listing path and verify a mock match. The --no-passthrough flag blocks unmatched calls routed through the mock proxy from being forwarded to Google Cloud. It does not intercept connections that bypass the proxy; use network isolation as well when the whole test must be offline.

If a request does not match, inspect the changed fields before adjusting the fixture. New resource names, generated IDs, and authorization values can differ between runs. Keep meaningful checks on the operation and its input. The traffic replay tutorial explains how to inspect a failing run and distinguish an application regression from a setup problem.

Authentication, quotas, and state remain separate concerns

Google’s Application Default Credentials documentation explains how client libraries find credentials. A mock response does not verify those credentials or enforce Google Cloud IAM. Your application may also fetch or refresh a token before calling the target API, so identify those calls when deciding what must be captured or stubbed.

Review access tokens, service-account details, project identifiers, and customer data before sharing recorded traffic. Use redacted fixtures where appropriate and keep a real integration check for authorization behavior.

Error and delay fixtures can exercise retry budgets and fallback code. They do not reproduce a project’s live quota accounting, billing, or regional availability. Similarly, repeated reads from a recorded fixture do not establish the effects of a preceding write. Test stateful workflows against a suitable emulator or disposable real resources when that behavior matters.

Refresh the recording when the workflow changes

Keep each recording tied to a named workflow and capture date. Re-record when the client changes its requests or a real integration test exposes stale assumptions. Start with the local recording guide and expand one application path at a time.