DOCSEARCHbyAlgolia
Submit Docs

GripMock Documentation

website·Indexed 31 days ago

https://gripmock.org

Documentation for GripMock, a gRPC mocking tool. Includes guides on the Embedded SDK (v3.7.0+), Stub and History APIs, upstream modes like Capture mode (v3.9.0), and loading API definitions via gRPC Reflection (v3.8.5) or Buf Schema Registry (BSR v3.8.4). Covers installation for Go 1.26+, session management, and CI/CD integration with GitHub Actions.

Tokens
50.2K
Snippets
327
Records
397
Agent score
54%

What's inside GripMock

  1. Overview of GripMock gRPC Mock Server

    GripMock is a mock server for gRPC services. It allows developers to serve mock responses by pointing the server at .proto files or compiled .pb descriptors and defining the desired responses in YAML or JSON. It does not generate gRPC server code at runtime or spawn generated servers via cmd/exec; stubbing and transport are handled in-process.

  2. Overview of gRPC request input matching rules

    GripMock stubs select requests by matching fields in the data field of a gRPC request. Supported matching strategies include equals, contains, matches, glob, and anyOf. Matching expressions must be static; dynamic templates (e.g., {{ ... }}) are not allowed within these matchers.
    {
  "input": {
    "ignoreArrayOrder": false,
    "anyOf": [
      { "equals": { "field": "value" } }
    ],
    "equals|contains|matches|glob": {
      "field": "value"
    }
  }
}

  3. Overview of GripMock Embedded SDK

    The GripMock Embedded SDK allows you to run GripMock directly inside the Go test process, removing the need for external containers or binaries. This approach provides several advantages: no container startup latency, complete isolation between tests (one instance per test), type-safe stubs checked by the Go compiler, and the ability to use a debugger across the test and the mock without process boundaries. It supports unary and streaming patterns, headers, errors, delays, priority, and call history verification.

  4. Overview of gRPC-web support in GripMock

    GripMock supports unary and streaming gRPC-web calls using the same stubs as ConnectRPC and native gRPC. The gateway serves both gRPC-web and ConnectRPC on a single port (default :4769), using Content-Type negotiation to dispatch requests to the correct handler.

  5. Understand GripMock Upstream Modes

    Upstream modes define the runtime request resolution strategy when reflection sources are used. There are three primary modes, typically used in this progression:

    1. proxy: Acts as a pure reverse proxy to the upstream service.
    2. replay: Checks for local stubs first; if no matcher is found, it falls back to the upstream service.
    3. capture: Behaves like replay mode, but automatically records upstream responses for misses to create local stubs.

  6. Use Dynamic Templates in GripMock stubs

    GripMock allows stub responses to be dynamically generated using Go's text/template syntax. Templates are evaluated per request. They can access request data, headers, and use a variety of built-in functions to transform values. Note that templates render leaf values only; they cannot be used to add or remove array elements (use Response Templates for dynamic structure).

  7. Use Replay Mode for local-first mocking with upstream fallback

    Replay mode (replay) allows GripMock to act as a proxy that prioritizes local stubs. For every incoming request (unary, server-stream, client-stream, or bidirectional), GripMock follows this logic:

    1. Attempt to match the request against local stubs using full criteria (including input, headers, session, contains/matches, and options.times).
    2. If a match is found, the local response is returned.
    3. If the matcher returns NotFound, the request is forwarded to the configured upstream server.

    This mode is ideal for gradual migration where you have partial stubs and need the real upstream service to handle uncovered paths.

  8. Understand GripMock request matching logic

    GripMock uses a matcher to determine which stub responds to an incoming gRPC request. Matching is performed against two primary areas: the request body fields (input) and gRPC metadata/headers (headers).

    Matching follows a specific flow:

    1. Fast Path: Exact equals matches are evaluated first.
    2. Full Match: contains, matches, glob, and anyOf are evaluated.
    3. Ranking: If multiple stubs match, they are ordered by specificity, then by a score (calculated as rank plus priority × 10), and finally by the declared field count.

  9. Use GripMock in Proxy Mode

    Proxy mode (proxy) transforms GripMock into a pure reverse proxy. For all unary and streaming methods, requests are forwarded to the upstream server, and the response (including status, headers, and trailers) is returned directly from the upstream. Local stubs are ignored in this mode. This is ideal for baseline traffic inspection, immediate startup without stub preparation, or when only reverse-proxy behavior is required.

  10. Compare runtime architecture of bavix/gripmock and tokopedia/gripmock

    The bavix/gripmock implementation introduces several architectural optimizations over the original tokopedia/gripmock to improve performance and reduce dependencies:

    • Protobuf Handling: bavix/gripmock uses in-process handling with no code generation, whereas tokopedia/gripmock runs protoc at startup.
    • Server Process: bavix/gripmock is a single application; tokopedia/gripmock compiles and spawns a generated Go server.
    • Stub Lookup: bavix/gripmock performs lookups in-process, avoiding the internal gRPC-to-HTTP hop used by tokopedia/gripmock.
    • Image Dependencies: bavix/gripmock has no runtime dependencies in its image, while tokopedia/gripmock requires protobuf, protoc-gen-go, and protoc-gen-go-grpc.

  12. Stub the gRPC Health Check service

    GripMock allows stubbing the standard gRPC health service methods grpc.health.v1.Health/Check and grpc.health.v1.Health/Watch. This is used to simulate dependency health transitions (e.g., moving from NOT_SERVING to SERVING) to test client behavior.