pytest-gcpsecretmanager

A pytest plugin that provides an in-memory fake for Google Cloud Secret Manager. No Docker, no emulator, no GCP credentials required.

Both SecretManagerServiceClient (sync) and SecretManagerServiceAsyncClient (async) are transparently patched for the duration of each test.

Installation

pip install pytest-gcpsecretmanager

The plugin requires Python 3.12+ and pytest 7.0+. It does not require google-cloud-secret-manager to be installed — if the SDK is absent, fake modules are injected so that from google.cloud.secretmanager import SecretManagerServiceClient still works in your code under test.

Quick start

import pytest
from google.cloud.secretmanager import SecretManagerServiceClient

@pytest.mark.secret("my-api-key", "s3cret")
def test_reads_secret(secret_manager):
    client = SecretManagerServiceClient()
    response = client.access_secret_version(
        name="projects/test-project/secrets/my-api-key/versions/latest"
    )
    assert response.payload.data == b"s3cret"

The secret_manager fixture activates patching and returns the underlying SecretStore. The @pytest.mark.secret marker pre-populates secrets before the test runs.

Fixtures

secret_manager

Function-scoped. Activates patching and returns a SecretStore instance. Any SecretManagerServiceClient or SecretManagerServiceAsyncClient instantiated during the test will use this in-memory store.

def test_programmatic_setup(secret_manager):
    secret_manager.set_secret("db-password", "hunter2")
    secret_manager.set_secret("binary-key", b"\x00\x01\x02")

    client = SecretManagerServiceClient()
    resp = client.access_secret_version(
        name="projects/test-project/secrets/db-password/versions/latest"
    )
    assert resp.payload.data == b"hunter2"

The store also supports multiple versions:

def test_versioned_secrets(secret_manager):
    secret_manager.set_secret_sequence("rotating-key", ["v1", "v2", "v3"])

    client = SecretManagerServiceClient()
    resp = client.access_secret_version(
        name="projects/test-project/secrets/rotating-key/versions/2"
    )
    assert resp.payload.data == b"v2"

secret_manager_client

Returns a FakeSecretManagerServiceClient instance backed by the current test's store.

def test_with_client(secret_manager_client):
    secret_manager_client.create_secret(
        parent="projects/test-project", secret_id="new-secret"
    )
    secret_manager_client.add_secret_version(
        parent="projects/test-project/secrets/new-secret",
        payload={"data": b"payload"},
    )
    resp = secret_manager_client.access_secret_version(
        name="projects/test-project/secrets/new-secret/versions/1"
    )
    assert resp.payload.data == b"payload"

secret_manager_async_client

Returns a FakeSecretManagerServiceAsyncClient — same API, but all methods are async.

async def test_async_client(secret_manager_async_client):
    await secret_manager_async_client.create_secret(
        parent="projects/test-project", secret_id="async-secret"
    )
    await secret_manager_async_client.add_secret_version(
        parent="projects/test-project/secrets/async-secret",
        payload={"data": b"hello"},
    )
    resp = await secret_manager_async_client.access_secret_version(
        name="projects/test-project/secrets/async-secret/versions/1"
    )
    assert resp.payload.data == b"hello"

secret_failure_injector

Returns the active _FailureInjector for programmatic failure injection (see Failure injection below).

Markers

@pytest.mark.secret(secret_id, value, *, project=None)

Pre-populate a secret before the test runs. The default project is "test-project".

# Single version
@pytest.mark.secret("api-key", "my-key")
def test_single(secret_manager): ...

# Multiple versions (pass a list)
@pytest.mark.secret("rotating", ["v1", "v2", "v3"])
def test_versions(secret_manager): ...

# Custom project
@pytest.mark.secret("api-key", "my-key", project="my-project")
def test_custom_project(secret_manager): ...

# Stack multiple markers
@pytest.mark.secret("key-a", "value-a")
@pytest.mark.secret("key-b", "value-b")
def test_multiple(secret_manager): ...

@pytest.mark.secret_failure(method, exception, *, transient=False, count=1)

Inject a failure into a specific client method.

from pytest_gcpsecretmanager import NotFound

# Permanent failure — every call raises
@pytest.mark.secret_failure("access_secret_version", NotFound("gone"))
def test_not_found(secret_manager):
    client = SecretManagerServiceClient()
    with pytest.raises(NotFound):
        client.access_secret_version(name="projects/p/secrets/s/versions/1")

# Transient failure — fails `count` times, then succeeds
@pytest.mark.secret_failure(
    "access_secret_version", NotFound("retry me"), transient=True, count=2
)
@pytest.mark.secret("key", "val")
def test_transient(secret_manager):
    client = SecretManagerServiceClient()
    for _ in range(2):
        with pytest.raises(NotFound):
            client.access_secret_version(
                name="projects/test-project/secrets/key/versions/latest"
            )
    # Third call succeeds
    resp = client.access_secret_version(
        name="projects/test-project/secrets/key/versions/latest"
    )
    assert resp.payload.data == b"val"

Failure injection

In addition to the marker, you can inject failures programmatically via the secret_failure_injector fixture:

from pytest_gcpsecretmanager import PermissionDenied

def test_programmatic_failure(secret_manager, secret_failure_injector):
    secret_failure_injector.add_permanent_failure(
        "create_secret", PermissionDenied("nope")
    )
    client = SecretManagerServiceClient()
    with pytest.raises(PermissionDenied):
        client.create_secret(parent="projects/test-project", secret_id="x")

Available exception types: NotFound, AlreadyExists, PermissionDenied, FailedPrecondition, InvalidArgument, ResourceExhausted, DeadlineExceeded.

Supported API methods

Both sync and async clients support:

How patching works

When the secret_manager fixture is active:

1. If google-cloud-secret-manager is installed, the real client classes are patched via unittest.mock.patch across all known import paths (google.cloud.secretmanager, google.cloud.secretmanager_v1, etc.).
2. If the SDK is not installed, fake modules are injected into sys.modules so that from google.cloud.secretmanager import SecretManagerServiceClient resolves to the fake client.

This means your application code doesn't need any special imports or conditional logic — the fake is transparent.

Response types

Responses use lightweight dataclasses that mirror the GCP protobuf shapes:

• AccessSecretVersionResponse — has .name and .payload (a SecretPayload with .data bytes and .data_crc32c)
• Secret — has .name, .replication, .create_time, .labels
• SecretVersion — has .name, .create_time, .state

License

MIT