GraphQL::Coverage

GraphQL::Coverage is a gem that calculates the coverage of GraphQL queries.

The motivation of this gem is to enforce the coverage of GraphQL queries in testing.

In our projects, we have a rule that the test cases must cover all GraphQL fields. However, it is difficult to enforce this rule because we have no tools to check the coverage of GraphQL fields.

You may think that we can check the coverage of GraphQL fields with ordinary coverage tools such as simplecov. However, it is not enough because GraphQL fields are often defined without method definition. For example:

# without `def id`
field :id, String, null: false

So I need to develop a tool that can check the coverage of GraphQL fields.

Install the gem and add to the application's Gemfile by executing:

$ bundle add graphql-coverage --require false --group test

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install graphql-coverage

This gem is not designed to be used in a production environment.

This gem is designed to be used in a test environment. Here is an example of using this gem with RSpec.

If your RSpec runs on a single process, add the following code to spec_helper.rb:

RSpec.configure do |config|
  config.before(:suite) do
    require 'graphql/coverage'
    # Pass a class that inherits `GraphQL::Schema`.
    GraphQL::Coverage.enable(YourSchema)
  end

  config.after(:suite) do
    GraphQL::Coverage.report!
    # You can also use `GraphQL::Coverage.report` if you just want to display the report without failure.
  end
end

You run RSpec on multiple processes in many cases. For example, you may use parallel_tests, test-queue, or CircleCI's parallelism. In such cases, you need to use GraphQL::Coverage in a different way to aggregate coverage results.

The following code is an example of using GraphQL::Coverage with CircleCI's parallelism on a Rails application.

# spec_helper.rb
RSpec.configure do |config|
  config.before(:suite) do
    # Pass a class that inherits `GraphQL::Schema`.
    GraphQL::Coverage.enable(YourSchema)
  end

  config.after(:suite) do
    # Instead of `GraphQL::Coverage.report!`, use `GraphQL::Coverage.dump` to dump the coverage result to a file.
    GraphQL::Coverage.dump(Rails.root.join("tmp/graphql-coverage-#{ENV['CIRCLE_NODE_INDEX']}.json"))
  end
end

After running RSpec, you can aggregate the coverage results and display the coverage with the following command:

# It displays the same report as `GraphQL::Coverage.report!`.
$ bundle exec graphql-coverage --require ./config/environment.rb tmp/graphql-coverage-*.json

You must specify --require (or -r) option to load the schema. If you use Rails, you can specify ./config/environment.rb as the argument of --require option.

You can also use --no-fail-on-uncovered option to display the coverage without failure.

You can specify ignored_fields option to ignore some fields.

# spec_helper.rb
RSpec.configure do |config|
  config.before(:suite) do
    GraphQL::Coverage.enable(YourSchema)
    GraphQL::Coverage.ignored_fields = [
      # GraphQL::Coverage does not complain about the coverage of `Article`'s `title` field.
      { type: 'Article', field: 'title' },
      # You can use `*` as a wildcard.
      { type: '*', field: 'id' },
    ]
  end
end

I recommend specifying the following configuration in most cases to ignore fields for Relay Connection.

GraphQL::Coverage.ignored_fields = [
  { type: '*', field: 'edges' },
  { type: '*', field: 'node' },
  { type: '*', field: 'cursor' },
]

After checking out the repo, run bin/setup to install dependencies. Then, run rake to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/pocke/graphql-coverage.