![RSpec Status](https://github.com/khamusa/rspec-graphql_matchers/actions/workflows/rspec.yml/badge.svg)

# 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 `valid_type` is a your type signature as a String: `"String!"`, `"Int!"`, `"[String]!"` (note the exclamation mark at the end, as required by the [GraphQL specifications](http://graphql.org/).

Please note that using references to type instances is deprecated and will be removed in a future release.

## Examples

Given a GraphQL object defined as

```ruby
class PostType < GraphQL::Schema::Object
  graphql_name "Post"
  description "A blog post"

  implements GraphQL::Types::Relay::Node

  field :id, ID, null: false
  field :comments, [String], null: false
  field :isPublished, Boolean, null: true
  field :published, Boolean, null: false, deprecation_reason: 'Use isPublished instead'

  field :subposts, PostType, null: true do
    argument :filter, String, required: false
    argument :id, ID, required: false
    argument :isPublished, Boolean, 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("ID!") }
  it { is_expected.to have_field(:comments).of_type("[String!]!") }
  it { is_expected.to have_field(:isPublished).of_type("Boolean") }

  # Check a field is deprecated
  it { is_expected.to have_field(:published).with_deprecation_reason }
  it { is_expected.to have_field(:published).with_deprecation_reason('Use isPublished instead') }
  it { is_expected.not_to have_field(:published).with_deprecation_reason('Wrong reason') }
  it { is_expected.not_to have_field(:isPublished).with_deprecation_reason }

  # The gem automatically converts field names to CamelCase, so this will
  # pass even though the field was defined as field :isPublished
  it { is_expected.to have_field(:is_published).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) 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) }

    # The gem automatically converts argument names to CamelCase, so this will
    # pass even though the argument was defined as :isPublished
    it { is_expected.to accept_argument(:is_published).of_type("Boolean") }
  end
end
```

### 4) Test an object's interface implementations:

```ruby
describe PostType do
  subject { described_class }

  it 'implements interface Node' do
    expect(subject).to implement('Node')
  end

  it { is_expected.not_to implement('OtherInterface') }
end
```

### 5) Using camelize: false on field names

By default the graphql gem camelizes field names. This gem deals with it transparently:

```ruby
class ObjectMessingWithCamelsAndSnakesType < GraphQL::Schema::Object
  graphql_name 'ObjectMessingWithCamelsAndSnakes'

  implements GraphQL::Types::Relay::Node

  field :me_gusta_los_camellos, ID, null: false

  # note the camelize: false
  field :prefiero_serpientes, ID, null: false, camelize: false
end
```

The following specs demonstrate the current behavior of the gem regarding fields:

```ruby
describe ObjectMessingWithCamelsAndSnakesType do
  subject { described_class }

  # For a field name that was automatically camelized, you can add expectations
  # against both versions and we handle it transparently:
  it { is_expected.to have_a_field(:meGustaLosCamellos) }
  it { is_expected.to have_a_field(:me_gusta_los_camellos) }

  # However, when using camelize: false, you have to use the exact case of the field definition:
  it { is_expected.to have_a_field(:prefiero_serpientes) }
  it { is_expected.not_to have_a_field(:prefieroSerpientes) } # Note we're using `not_to`
end
```

This behaviour is currently active only on field name matching. PRs are welcome to
reproduce it to arguments as well.

## TODO

-   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).