fake-gcs-server for Local Google Cloud Storage Tests

Why fake-gcs-server exists

fake-gcs-server addresses the gap between unit tests that mock a storage client and integration tests that need a server speaking the Google Cloud Storage API. The README presents it as an emulator that can run inside Go test suites or as a standalone binary and Docker image. That makes it relevant to engineers testing bucket creation, object upload, object listing, downloads, and other storage workflows without sending test data to Google Cloud Storage.

The primary audience includes Go developers who can import `github.com/fsouza/fake-gcs-server/fakestorage`, as well as teams running tests in Python, Java, Node.js, .NET, C++, Scala, `gcloud`, or `gsutil`. The repository includes example directories for those clients, although the README does not claim that every API feature is implemented. The project solves test isolation and local endpoint availability, not production storage durability, billing, access control, or global Google Cloud behavior.

How the emulator handles storage requests

The project is organized as a Go module with a `fakestorage` package, an internal implementation, a command entry point, and example clients. The standalone executable exposes an HTTP server that accepts Google Cloud Storage API requests. The README shows requests against `/storage/v1/b` for buckets and `/storage/v1/b/sample-bucket/o` for objects, so the server is designed to be addressed through the normal API surface rather than through a private testing protocol.

Data can be preloaded by mounting a directory at `/data`. The documented layout places bucket names directly under that directory, with object files beneath each bucket. In the example, `sample-bucket` contains `some_file.txt`. The emulator then reports the bucket and object through API listing requests. This is a concrete filesystem-to-API data flow, and it makes test fixtures easy to inspect.

The server defaults to HTTPS and listens on port `4443`. It can instead use HTTP, or it can start both protocols. Environment variables mirror server flags using the `FAKE_GCS_` prefix. Command line flags take precedence over environment variables, while invalid values prevent startup. These controls are useful for CI containers, local scripts, and tests that need a predictable endpoint.

Running a first Docker-based storage test

Start with Docker when the application is not written in Go or when the test process should talk to the emulator over the network. The following command starts the image in the background and maps the emulator port to the host. The container exposes port `4443`, matching the documented default.

docker run -d --name fake-gcs-server -p 4443:4443 fsouza/fake-gcs-server

After startup, query the bucket listing endpoint. The README uses HTTPS with `curl --insecure` because the emulator serves HTTPS by default and does not provide a certificate that the host should trust as a public Google certificate.

curl --insecure https://0.0.0.0:4443/storage/v1/b

The documented response includes a bucket named `sample-bucket`. For a fixture, mount a local directory at `/data`. The example tree contains `sample-bucket/some_file.txt`, and the container should expose both the bucket and object through the API.

docker run -d --name fake-gcs-server -p 4443:4443 -v ${PWD}/examples/data:/data fsouza/fake-gcs-server

The object listing command should return `some_file.txt` under `sample-bucket`. This is the first useful verification: it checks both the network endpoint and the fixture-to-API loading behavior.

Choosing HTTPS, HTTP, or both

Protocol selection is a practical compatibility decision. HTTPS is the default and is useful when the client expects a secure endpoint. HTTP is simpler for local scripts and avoids the need for `curl --insecure`. Pass `-scheme http` to the container while keeping the same port mapping.

docker run -d --name fake-gcs-server -p 4443:4443 -v ${PWD}/examples/data:/data fsouza/fake-gcs-server -scheme http

With this configuration, the README uses an HTTP request to the bucket endpoint.

curl http://0.0.0.0:4443/storage/v1/b

If a client and test harness need both protocols, use `-scheme both`. HTTPS uses `-port`, which defaults to `4443`, while HTTP uses `-port-http`, which defaults to `8000`. Both ports must be mapped when running Docker.

docker run -d --name fake-gcs-server -p 4443:4443 -p 8000:8000 -v ${PWD}/examples/data:/data fsouza/fake-gcs-server -scheme both

For configuration beyond these examples, the README says to inspect the server flags with `-help`. It also documents environment equivalents including `FAKE_GCS_PORT`, `FAKE_GCS_PORT_HTTP`, `FAKE_GCS_SCHEME`, `FAKE_GCS_BACKEND`, `FAKE_GCS_FILESYSTEM_ROOT`, `FAKE_GCS_PUBLIC_HOST`, and `FAKE_GCS_EXTERNAL_URL`.

Signed URLs and their documented caveats

fake-gcs-server supports signed URL workflows, but the implementation has explicit constraints. According to the README, it does not validate query parameters such as the signature and expiration. It also requires the client to replace `storage.googleapis.com` with a URL that points to the emulator. Finally, the server must be configured with `-public-host` to accept that local URL.

This means a test can exercise application code that generates or consumes signed URLs, but it cannot use the emulator to verify the complete security properties of Google-signed URLs. Signature validation is explicitly outside the emulator's behavior. A test that depends on expiration rejection, tampered signatures, or exact Google signing semantics needs a different verification strategy or a service-level test.

The relevant boundary is therefore clear: signed URL compatibility is useful for exercising plumbing, not evidence that the emulator enforces the same authentication rules as the hosted service.

Go library use and maintenance considerations

For Go projects, the library entry point is `github.com/fsouza/fake-gcs-server/fakestorage`. The README links to its Go documentation and describes using it from package test suites. The repository's `go.mod` identifies the module and records its Go and Google Cloud client dependencies, so consumers should inspect dependency changes when selecting a version.

The project is not archived. Its last push was on 2026-10-14, and recent releases include v1.56.1 on 2026-08-24, v1.56.0 on 2026-08-22, and v1.55.1 on 2026-07-19. These dates indicate recent repository activity, but they do not by themselves establish that every Google Cloud Storage API behavior is covered.

The repository is licensed under BSD-2-Clause. That is the declared project license, and the LICENSE file is the relevant source for its exact terms. Upgrade cost depends on the API surface used by the application. A version change may affect Go dependencies or emulator behavior, so teams should review release notes and run their own client-specific integration tests rather than treating a release number as compatibility proof.

Choosing fake-gcs-server versus the hosted service

The real alternative is Google Cloud Storage itself, used through its supported client libraries and service endpoints. That alternative can be used when a test requires the hosted service. fake-gcs-server instead offers a local endpoint that is convenient for deterministic tests and does not require a network call to the hosted service.

The choice depends on what the test is trying to establish. Use fake-gcs-server for fast integration tests that need bucket and object operations against a controlled local endpoint. Use the hosted service when the test must validate Google-specific service behavior that the emulator does not reproduce, especially signed URL validation or production operational characteristics. Some test suites may need both layers, with the emulator for ordinary flows and a small set of hosted tests for service-specific checks.

It is also the wrong tool when the application depends on authentication, IAM permissions, durable production data, or exact service semantics beyond the documented emulator behavior. The README does not promise complete Google Cloud Storage parity.

Editorial conclusion

Adopt fake-gcs-server when tests need a local Google Cloud Storage endpoint without calling the hosted service, especially for Go integration suites or multilingual Docker-based tests. Do not treat it as a general production storage system or as a complete replacement for Google Cloud Storage validation. Verify first that the required API behavior, signed URL handling, persistence model, and client configuration match the code paths used by your application.

Frequently asked questions

Official sources

1. fsouza/fake-gcs-server on GitHub
2. License: BSD-2-Clause
3. Project website
4. README
5. Releases