![Build Status](https://travis-ci.org/khamusa/rspec-graphql_matchers.svg?branch=master) # Rspec::GraphqlMatchers Convenient rspec matchers for testing your [graphql-ruby](https://github.com/rmosolgo/graphql-ruby) API/Schema. ## Installation ``` gem 'rspec-graphql_matchers' ``` ## Usage The matchers currently supported are: - `expect(a_graphql_object).to have_a_field(field_name).of_type(valid_type)` - `expect(a_graphql_object).to implement(interface_name, ...)` - `expect(a_mutation_type).to have_a_return_field(field_name).returning(valid_type)` - `expect(a_mutation_type).to have_an_input_field(field_name).of_type(valid_type)` - `expect(a_field).to be_of_type(valid_type)` - `expect(an_input).to accept_argument(argument_name).of_type(valid_type)` Where a valid type for the expectation is either: - A reference to the actual type you expect; - [Recommended] A String representation of a type: `"String!"`, `"Int!"`, `"[String]!"` (note the exclamation mark at the end, as required by the [GraphQL specs](http://graphql.org/). For objects defined with the legacy `#define` api, testing `:property`, `:hash_key` and _metadata_ is also possible by chaining `.with_property`, `.with_hash_key` and `.with_metadata`. For example: - `expect(a_graphql_object).to have_a_field(field_name).with_property(property_name).with_metadata(metadata_hash)` - `expect(a_graphql_object).to have_a_field(field_name).with_hash_key(hash_key)` ## Examples Given a GraphQL object defined as ```ruby class PostType < GraphQL::Schema::Object graphql_name "Post" description "A blog post" implements GraphQL::Relay::Node.interface field :id, ID, null: false field :comments, [String], null: false field :isPublished, Boolean, null: true field :subposts, PostType, null: true do argument :filter, types.String, required: false argument :id, types.ID, required: false end end ``` ### 1) Test your type defines the correct fields: ```ruby describe PostType do subject { described_class } it { is_expected.to have_field(:id).of_type(!types.ID) } it { is_expected.to have_field(:comments).of_type("[String!]!") } it { is_expected.to have_field(:isPublished).of_type("Boolean") } end ``` ### 2) Test a specific field type with `be_of_type` matcher: ```ruby describe PostType do describe 'id' do subject { PostType.fields['id'] } it { is_expected.to be_of_type('ID!') } it { is_expected.not_to be_of_type('Float!') } end describe 'subposts' do subject { PostType.fields['subposts'] } it { is_expected.to be_of_type('Post') } end end ``` ### 3) For objects defined using the legacy `#define` api, you can also use `with_property`, `with_hash_key` and `with_metadata`: ```ruby PostTypeWithDefineApi = GraphQL::ObjectType.define do name "DefinedPost" interfaces [GraphQL::Relay::Node.interface] field :id, !types.ID, property: :post_id field :comments, !types[types.String], hash_key: :post_comments field :isPublished, admin_only: true end describe PostTypeWithDefineApi do it { is_expected.to have_a_field(:id).of_type('ID!').with_property(:post_id) } it { is_expected.to have_a_field(:comments).with_hash_key(:post_comments) } it { is_expected.to have_a_field(:isPublished).with_metadata(admin_only: true) } end ``` ### 4) Test the arguments accepted by a field with `accept_argument` matcher: ```ruby describe PostType do describe 'subposts' do subject { PostType.fields['subposts'] } it 'accepts a filter and an id argument, of types String and ID' do expect(subject).to accept_argument(:filter).of_type('String') expect(subject).to accept_argument(:id).of_type('ID') end it { is_expected.not_to accept_argument(:weirdo) } end end ``` ### 5) Test an object's interface implementations: ```ruby describe PostType do subject { described_class } it 'implements interface Node' do expect(subject).to implement('Node') end # Accepts arguments as an array and type objects directly it { is_expected.to implement(GraphQL::Relay::Node.interface) } it { is_expected.not_to implement('OtherInterface') } end ``` ## TODO - Support GraphQL 1.9.x; - Check the method used for resolving a field; - New matchers! ## Contributing - Send Bug reports, suggestions or any general question through the [Issue tracker](https://github.com/khamusa/rspec-graphql_matchers/issues). Think of another matcher that could be useful? This is the place to ask, or... - Pull requests are welcome through the usual procedure: fork the project, commit your changes and open the [PR](https://github.com/khamusa/rspec-graphql_matchers/pulls). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. ## License The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).