{"id":14991362,"url":"https://github.com/bigcommerce/gruf-rspec","last_synced_at":"2025-10-05T02:42:17.816Z","repository":{"id":33555800,"uuid":"157288925","full_name":"bigcommerce/gruf-rspec","owner":"bigcommerce","description":"RSpec helper suite for gruf","archived":false,"fork":false,"pushed_at":"2024-05-06T15:37:45.000Z","size":74,"stargazers_count":23,"open_issues_count":2,"forks_count":6,"subscribers_count":57,"default_branch":"main","last_synced_at":"2025-03-24T12:56:19.436Z","etag":null,"topics":["gruf","rspec","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bigcommerce.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-12T22:58:31.000Z","updated_at":"2024-05-07T00:59:40.000Z","dependencies_parsed_at":"2024-05-01T09:24:31.093Z","dependency_job_id":"04986b23-c133-4a0b-aac4-4a76a872ecd8","html_url":"https://github.com/bigcommerce/gruf-rspec","commit_stats":{"total_commits":54,"total_committers":4,"mean_commits":13.5,"dds":0.09259259259259256,"last_synced_commit":"d50fcd4978b77a62a714495058c4f7c0b0e4a07d"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigcommerce%2Fgruf-rspec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigcommerce%2Fgruf-rspec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigcommerce%2Fgruf-rspec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigcommerce%2Fgruf-rspec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bigcommerce","download_url":"https://codeload.github.com/bigcommerce/gruf-rspec/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247773721,"owners_count":20993639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["gruf","rspec","ruby"],"created_at":"2024-09-24T14:27:32.665Z","updated_at":"2025-10-05T02:42:12.783Z","avatar_url":"https://github.com/bigcommerce.png","language":"Ruby","readme":"# gruf-rspec\n\n[![CircleCI](https://circleci.com/gh/bigcommerce/gruf-rspec/tree/main.svg?style=svg)](https://circleci.com/gh/bigcommerce/gruf-rspec/tree/main) [![Gem Version](https://badge.fury.io/rb/gruf-rspec.svg)](https://badge.fury.io/rb/gruf-rspec) [![Documentation](https://inch-ci.org/github/bigcommerce/gruf-rspec.svg?branch=main)](https://inch-ci.org/github/bigcommerce/gruf-rspec?branch=main) [![Maintainability](https://api.codeclimate.com/v1/badges/db2d134a7148dde045b7/maintainability)](https://codeclimate.com/github/bigcommerce/gruf-rspec/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/db2d134a7148dde045b7/test_coverage)](https://codeclimate.com/github/bigcommerce/gruf-rspec/test_coverage)\n\nAssistance helpers and custom type for easy testing [Gruf](https://github.com/bigcommerce/gruf) controllers with\n[RSpec](https://github.com/rspec/rspec).\n\n## Installation\n\n```ruby\ngem 'gruf-rspec'\n```\n\nNote that this gem requires at least Ruby 3.0+, Gruf 2.5.1+, and RSpec 3.8+.\n\n## Usage\n\n* Add a test for a Gruf controller in `spec/rpc`\n* Run the `run_rpc` method with three args: The gRPC method name, the request object\nand the active_call_options. The third argument is optional.\n* Validate the response\n\n## Example\n\nLet's assume you have a gruf controller named `ThingController` that is bound to the gRPC\nservice `Rpc::Things::Service`. That has a method `GetThing`:\n\n```ruby\nclass ThingController \u003c Gruf::Controllers::Base\n  bind ::Rpc::Things::Service\n\n  def get_thing\n    Rpc::GetThingResponse.new(id: request.message.id)\n  end\nend\n```\n\nTo test it, you'd create `spec/rpc/thing_controller_spec.rb`:\n\n```ruby\ndescribe ThingController do\n  describe '#get_thing' do\n    let(:request_proto) { Rpc::GetThingRequest.new(id: rand(1..100)) }\n    let(:metadata) {\n      { 'user_id' =\u003e 'axj42i' }\n    }\n\n    subject { run_rpc(:GetThing, request_proto, active_call_options: { metadata: metadata }) }\n\n    it 'returns the thing' do\n      expect(subject).to be_a_successful_rpc\n      expect(subject.id).to eq request_proto.id\n    end\n  end\nend\n```\n\nAlternatively, you can pass a block:\n\n```ruby\nit 'returns the thing' do\n  run_rpc(:GetThing, request_proto) do |resp|\n    expect(resp).to be_a_successful_rpc\n    expect(resp.id).to eq request_proto.id\n  end\nend\n```\n\n### Accessing the Bound Service\n\nNote that you can also access the bound gRPC service class:\n\n```ruby\nit 'binds the service correctly' do\n  expect(grpc_bound_service).to eq Rpc::Things::Service\nend\n```\n\n### Matching Errors\n\nYou can match against errors as well:\n\n```ruby\ndescribe 'testing an error' do\n  let(:request_proto) { Rpc::GetThingRequest.new(id: rand(1..100)) }\n\n  subject { run_rpc(:GetThing, request_proto) }\n\n  it 'fails with the appropriate error' do\n    expect { subject }.to raise_rpc_error(GRPC::InvalidArgument)\n  end\nend\n```\n\nOr further, even check your serialized error that is passed in metadata:\n\n```ruby\nit 'fails with the appropriate error code' do\n  expect { subject }.to raise_rpc_error(GRPC::InvalidArgument).with_serialized { |err|\n    expect(err).to be_a(MyCustomErrorClass)\n    expect(err.error_code).to eq 'invalid_request'\n\n    fe = err.field_errors.first\n    expect(fe.field_name).to eq 'name'\n    expect(fe.error_code).to eq 'invalid_name'\n    expect(fe.error_message).to eq 'That name is already taken!'\n  }\nend\n```\n\nNote that when using `with_serialized`, you _must_ pass the block with `{ }`, not using\n`do` and `end`.\n\n### RSpec Controller Matcher Configuration\n\nBy default, the type matcher for Gruf controllers matches in `/spec/rpc`. You can customize this by configuring it\nin the `Gruf::Rspec` configuration block like so:\n\n```ruby\nGruf::Rspec.configure do |c|\n  c.rpc_spec_path = '/spec/rpc_controllers'\nend\n```\n\nAlternatively, you can pass configuration of the path via ENV. For example, where\n`RPC_SPEC_PATH=\"/spec/rpc_controllers\"` is set in a `.env` file:\n\n```bash\nbundle exec dotenv rspec\n```\n\nOr, add `require: false` to the gemspec for the `gruf-rspec` gem, and then explicitly require it after setting the ENV\nvar:\n\n```ruby\nDotenv.load # assuming the .env file has the RPC_SPEC_PATH var set\n# or:\nENV['RPC_SPEC_PATH'] = '/spec/rpc_controllers'\nrequire 'gruf/rspec'\n```\n\n## License\n\nCopyright (c) 2018-present, BigCommerce Pty. Ltd. All rights reserved\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated\ndocumentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the\nrights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit\npersons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the\nSoftware.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE\nWARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\nCOPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR\nOTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigcommerce%2Fgruf-rspec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbigcommerce%2Fgruf-rspec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigcommerce%2Fgruf-rspec/lists"}