{"id":37105237,"url":"https://github.com/torqio/grpcmock","last_synced_at":"2026-01-14T12:41:57.459Z","repository":{"id":198431509,"uuid":"484968448","full_name":"torqio/grpcmock","owner":"torqio","description":"Managed by Terraform","archived":false,"fork":false,"pushed_at":"2025-07-13T11:05:46.000Z","size":100,"stargazers_count":9,"open_issues_count":1,"forks_count":0,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-07-13T13:08:30.831Z","etag":null,"topics":["golang","grpc","grpcmock","mock","protobuf","testing"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/torqio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-04-24T08:24:33.000Z","updated_at":"2025-07-13T11:05:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"38c017a4-df3e-4080-9158-156c09b57e6f","html_url":"https://github.com/torqio/grpcmock","commit_stats":null,"previous_names":["torqio/grpcmock"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/torqio/grpcmock","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torqio%2Fgrpcmock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torqio%2Fgrpcmock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torqio%2Fgrpcmock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torqio%2Fgrpcmock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/torqio","download_url":"https://codeload.github.com/torqio/grpcmock/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torqio%2Fgrpcmock/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28420814,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T10:47:48.104Z","status":"ssl_error","status_checked_at":"2026-01-14T10:46:19.031Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","grpc","grpcmock","mock","protobuf","testing"],"created_at":"2026-01-14T12:41:56.818Z","updated_at":"2026-01-14T12:41:57.451Z","avatar_url":"https://github.com/torqio.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gRPCMock\n\ngRPCMock is a protobuf plugin that allows you to create implementation\nof a mock server for each RPC service defined in your protobuf file.\n\n## Usage\n### Generate plugin code\nFirst, install the plugin\n\n```bash\ngo install github.com/torqio/grpcmock/protoc-gen-grpcmock\n```\nMake sure you can execute `protoc-gen-grpcmock` (go binaries should be in the `PATH` environment variable)\nNext, add the plugin to your compilation tool.\n\nIf you use `protoc`:\n```bash\nprotoc -I/path/to/your/proto --go_out=paths=source_relative:/path/to/your/proto --go-grpc_out=paths=source_relative,require_unimplemented_servers=false:/path/to/your/proto --grpcmock_out=paths=source_relative:/path/to/your/proto /path/to/your/proto/test.proto \n```\n\nIf you use `buf`:\n\u003cpre\u003e\n\u003ccode class=\"yaml\"\u003e\nversion: v1\nplugins:\n  - plugin: buf.build/protocolbuffers/go\n    out: .\n    opt:\n      - paths=source_relative\n  - plugin: buf.build/grpc/go\n    out: .\n    opt:\n      - paths=source_relative\n      - require_unimplemented_servers=false\n  - \u003cb\u003eplugin: grpcmock\n    out: .\n    opt:\n      - paths=source_relative\u003c/b\u003e\n\u003c/code\u003e\n\u003c/pre\u003e\n\nNow, after the compilation you'll see `\u003cproto_file_name\u003e_grpcmock.pb.go` file for each protobuf file with gRPC.\u003cbr/\u003e\nEach file\n\n### Use the mock server\n#### Init server in tests\nFor the sake of the example, let's assume we have a protobuf file `svc.proto` with the following content:\n(you can find the file in the `tests` directory)\n```proto\nsyntax = \"proto3\";\npackage grpcmock.example;\noption go_package = \"github.com/torqio/grpcmock/tests\";\n\nservice ExampleService {\n  rpc ExampleMethod(ExampleMethodRequest) returns (ExampleMethodResponse);\n}\n\nmessage ExampleMethodRequest {\n  string req = 1;\n}\nmessage ExampleMethodResponse {\n  string res = 1;\n}\n```\nCompile the proto using `buf` \u003cbr/\u003e\nAfter the compilation, you'll see a new file `svc_grpcmock.pb.go`.\n\nIn your test file, first create a new mock server instance:\n```go\ntestServer := NewExampleServiceMockServerT(t)\n```\nThen, create a normal gRPC server and register the mock server as a handler (you can assign\nmiddlewares to the server as well):\n```go\nlis, err := net.Listen(\"tcp\", testSrvAddr)\nrequire.NoError(t, err)\nsrv := grpc.NewServer()\ngo func() {\n\t// Register the mock server as a handler\n    RegisterExampleServiceServer(srv, testServer) \n    // Start the server\n    require.NoError(t, srv.Serve(lis))\n}()\n```\n\u003cbr/\u003e\n\n#### Configure mock server return values\nNow, you can use the mock server to define the behavior of the server:\n```go\n// Define the default return value for an RPC\ntestServer.Configure().ExampleMethod().DefaultReturn(\u0026ExampleMethodResponse{Res: \"default-response\"}, nil)\n// Define the return value for an RPC with a specific request\ntestServer.Configure().ExampleMethod().On(mocker.Any(), \u0026ExampleMethodRequest{Req: \"some-request-that-should-be-matched\"}).Return(\u0026ExampleMethodResponse{Res: \"response-that-will-be-returned-if-request-matched\"}, nil)\n```\n\nAs you can see in the code block above, you have 2 main functions to define the behavior of the mock server:\n1. DefaultReturn - defines the default return value for an RPC. If the request doesn't match any of the defined\n   return values, the default return value will be returned.\n2. On+Return - defines the return value for an RPC with a specific request. If the RPC request matches the defined request,\n   the defined return value will be returned.\u003cbr/\u003eThe parameters given to the `On` function can implement [mocker.Matcher](pkg/mocker/mocker.go) (line #9) interface.\n   If the parameter doesn't implement the `Matcher` interface, the `eqMatcher` will be used by default.\u003cbr/\u003e\n   The `eqMatcher` is a matcher that checks if the request is equal to the given parameter using `reflect.DeepEqual` or by using `proto.Equal` in case the 2 compared objects are protobuf messages.\n\n#### Dynamic return values with DoAndReturn\nIn addition to static return values, gRPCMock supports dynamic return values using `DoAndReturn` and `DefaultDoAndReturn`:\n\n```go\n// Dynamic return value for a specific request\nvar counter int32\ntestServer.Configure().ExampleMethod().On(mocker.Any(), \u0026ExampleMethodRequest{Req: \"dynamic\"}).\n    DoAndReturn(func() (*ExampleMethodResponse, error) {\n        val := atomic.AddInt32(\u0026counter, 1)\n        return \u0026ExampleMethodResponse{Res: \"dynamic-response-\" + strconv.Itoa(int(val))}, nil\n    })\n\n// Dynamic default return value\ntestServer.Configure().ExampleMethod().DefaultDoAndReturn(func() (*ExampleMethodResponse, error) {\n    return \u0026ExampleMethodResponse{Res: \"default-dynamic-\" + time.Now().String()}, nil\n})\n\n// Dynamic streaming response\ntestServer.Configure().ExampleStreamResponse().On(\u0026ExampleMethodRequest{Req: \"stream-dynamic\"}, mocker.Any()).\n    DoAndReturn(func() ([]*ExampleMethodResponse, error) {\n        return []*ExampleMethodResponse{\n            {Res: \"stream-1-\" + time.Now().String()},\n            {Res: \"stream-2-\" + time.Now().String()},\n        }, nil\n    })\n\n// Dynamic error responses\ntestServer.Configure().ExampleMethod().On(mocker.Any(), \u0026ExampleMethodRequest{Req: \"error\"}).\n    DoAndReturn(func() (*ExampleMethodResponse, error) {\n        if time.Now().Second()%2 == 0 {\n            return nil, status.Error(codes.Internal, \"simulated error\")\n        }\n        return \u0026ExampleMethodResponse{Res: \"success\"}, nil\n    })\n```\n\n**Key benefits of DoAndReturn:**\n- **Dynamic responses**: Generate different responses each time the method is called\n- **Time-based logic**: Responses that depend on current time or other runtime conditions\n- **Stateful behavior**: Maintain state between calls using closures\n- **Error simulation**: Dynamically return different error conditions\n- **Backward compatibility**: All existing Return/DefaultReturn functionality continues to work\n\nThe DoAndReturn function is executed once per mock call and the result is cached to ensure consistent behavior within a single call.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftorqio%2Fgrpcmock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftorqio%2Fgrpcmock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftorqio%2Fgrpcmock/lists"}