rspec-graphql_response 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67d1e0d86474c6b5f5e99c3d19e3d1645fe35819d5a47a4fd7007af9c9a5700e
-  data.tar.gz: d27339cca95c74fdb174fa0ca6a43116039b449e0b22ef6397ccd76e8eb472d1
+  metadata.gz: 352fd084b9379469d7b4f71c86cfe94ea90172047c61c1ea2d20dced4bc85026
+  data.tar.gz: 7eccaeb870a708fe43f2b0891a45d703b7d1fd64901efddd5323a27b6d87a77f
 SHA512:
-  metadata.gz: b427ec094b4a8e19865e3d610a14abb32625189f7ea190ca61dbcde61e8582abca4464980e2790bb2d30b8ecbb83912034f4a95bcc1cd8744410328a646ad755
-  data.tar.gz: d0864628a5e6beb9096fe8901f67dd6f75d824af26631e1b66ea97894bd30da4061f6ceb25ffc692461a1e54a50f7e7c56405f89cce6275e919d624c9dd29dc8
+  metadata.gz: 83ebc95cd8c33beb6f62df67c9eb7a6846f820ca7bbc2c8412aadd0b4ceb0098449c23aeaf599bcaf65db6ddd4f4d92d2029a46e5a83c2b463f26e826040156c
+  data.tar.gz: 876549c88363f4e330bdb01416940116bb7a997ee7f22d2864a0d8c7a55b9310df7198b135d4bc1d655b22adecfc02df09e89feb7e173f5febfd4f2a0bd73f9a

data/.github/workflows/test.yml

@@ -0,0 +1,14 @@
+name: Test rspec-graphql_response
+on:
+  push:
+    branches: [ $default-branch ]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        bundler-cache: true
+    - run: bin/rspec

data/.gitignore

@@ -9,3 +9,6 @@
 
 # rspec failure tracking
 .rspec_status
+
+# ignore the resulting .gem file from gem build
+rspec-graphql_response*.gem

data/.gituprc

@@ -0,0 +1,128 @@
+# Gitup: Git Update Dance Configuration
+# -------------------------------------
+# configuration for gitup can be set as a default for the current user
+# by adding a ~/.gituprc file with settings
+# 
+# current project or local directory settings can be added in ./.gituprc
+# 
+# the .gituprc file is a valid shell script, loaded every time gitup is
+# run. this means you can add logic, functions, and other calls to the
+# .gituprc file and it will be executed at runtime
+
+
+# GIT CONFIGURATION
+# -----------------
+# Manages the git branch update process for your project
+#
+# GITUP_SKIP_UPDATE:
+#   Whether or not a git update is performed prior to running
+#   the bundle install or db:migrate steps
+#
+#   Options:
+#     0: (default) do not skip the update
+#     1: skip the update
+#
+# GITUP_MERGE_COMMAND:
+#   How to update the local git branch, from the upstream branch.
+#
+#   Options:
+#     rebase:  (default) force a rebase of the upstream branch
+#     merge:   force a merge of the upstream branch
+#     <other>: your own command: `git <other> <remote>/<branch>`
+#
+# GITUP_REMOTE_NAME:
+#   The git remote name to pull from
+#
+#   Default:
+#     origin
+#
+# GITUP_BRANCH_NAME:
+#   The main remote branch name to pull, from which your current
+#   branch will be updated
+#
+#   Default:
+#     development
+#
+# GITUP_GIT_UPDATE_FN:
+#   The method called to update your git branch. Responsible
+#   for handling git pull, git merge or rebase, etc.
+#
+#   Params:
+#     $1: Merge Command
+#     $2: Remote Name
+#     $3: Branch Name 
+#
+#   Default:
+#     GITUP_GIT_UPDATE_FN=__gitup_git_update
+#
+GITUP_SKIP_UPDATE=0
+# GITUP_MERGE_COMMAND=rebase
+GITUP_REMOTE_NAME=origin
+GITUP_BRANCH_NAME=main
+GITUP_GIT_UPDATE_FN=__gitup_git_update
+
+# ADVANCED GIT CONFIGURATION
+# --------------------------
+# This .gituprs file is a full bash script. You can add logic
+# to determine how to update, based on your current branch, etc.
+#
+# Examples:
+#
+#   How to change merge command for specific branches
+#   
+# current git branch
+local branch_name=$(git symbolic-ref -q HEAD)
+
+# remove the `refs/heads/` structure from the name
+branch_name=${branch_name##refs/heads/}
+
+# merge if we're in 'development' branch
+if [[ $branch_name == $GITUP_BRANCH_NAME ]]; then
+  GITUP_MERGE_COMMAND=merge
+else
+  GITUP_MERGE_COMMAND=rebase
+fi
+
+# DEPENDENCY INSTALLATION
+# -----------------------
+# Manage the step installs dependencies, after updating git.
+# For example, run `bundle install` (default) and/or other 
+# commands to keep your project's dependencies up to date.
+#
+# GITUP_SKIP_INSTALL_DEPENDENCIES:
+#   Whether or not to skip the step that runs immediately after 
+#   the git-update completes
+#
+#   Options:
+#     0: (default) do not skip the after_update step
+#     1: skip the after_update step
+#
+# GITUP_INSTALL_DEPENDENCIES_FN:
+#   Function to run after gitup has completed the git update process
+#
+#   Default:
+#     GITUP_INSTALL_DEPENDENCIES_FN=__gitup_install_dependencies
+#
+GITUP_SKIP_INSTALL_DEPENDENCIES=0
+GITUP_INSTALL_DEPENDENCIES_FN=__gitup_install_dependencies
+
+# RUN MIGRATIONS
+# --------------
+# Manage the process of running schema and/or data migrations,
+# after your project's post-git-update function has run
+#
+# GITUP_SKIP_MIGRATIONS:
+#   Whether or not to skip the db:migration steps after the git update
+#
+#   Options:
+#     0: (default) do not skip the db:migration steps
+#     1: skip the db:migration steps
+#
+# GITUP_RUN_MIGRATIONS_FN:
+#   Function to run migrations. Occurs after git update and post-update steps
+#
+#   Default:
+#     GITUP_RUN_MIGRATIONS_FN=__gitup_migrations
+#
+GITUP_SKIP_MIGRATIONS=1
+# GITUP_RUN_MIGRATIONS_FN=__gitup_migrations

data/Gemfile.lock

@@ -2,7 +2,7 @@ PATH
   remote: .
   specs:
     rspec-graphql_response (0.1.0)
-      rspec
+      rspec (~> 3.10)
 
 GEM
   remote: https://rubygems.org/
@@ -39,9 +39,9 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 1.17)
   graphql (~> 1.12)
-  pry
-  pry-byebug
-  rake
+  pry (~> 0.14)
+  pry-byebug (~> 3.8)
+  rake (>= 12.0)
   rspec-graphql_response!
 
 BUNDLED WITH

data/README.md

@@ -3,6 +3,15 @@
 RSpec::GraphQLResponse provides a series of RSpec matchers, helper methods, and other configuration to help simplify
 the testing of responses from the `graphql-ruby` gem and the `<GraphQLSchemaName>.execute` method.
 
+## "Why Should I Use This?"
+
+There are a number of built-in helper methods and matchers that will allow you to skip the copy & paste work of executing
+a GraphQL Schema `.execute`. Additionally, there are custom matchers and other bits that will help simplify your work in
+validating common peices of a graphql response.
+
+Lastly, the work in this gem is geared toward customization for your own application's needs. Every API call used for building
+the pieces of this gem are available to you, directly, in the `API / Development` documentation, below.
+
 ## Installation
 
 Your app must have `graphql-ruby` and `rspec`. With that done, add this line to your application's Gemfile:
@@ -21,71 +30,55 @@ Or install it yourself as:
 
 ## Full Documentation
 
-The full documentation for RSpec::GraphQLResponse can be found in the `/docs`
-folder.
-
-Custom Matchers:
-* [have_errors matcher](/docs/have_errors.md) - validates errors, or lack of, on
-  the GraphQL response
-
-Helper Methods:
-* [operation](/docs/operation.md) - retrieves the results of a named operation
-  from the GraphQL response
+* [Release Notes](/RELEASE_NOTES.md)
+* [Upgrade Guide](/UPGRADE.md)
 
-Internal API / Development
+The full documentation for RSpec::GraphQLResponse can be found in the `/docs` folder.
 
-* [.add_matcher](/docs/add_matcher.md) - add a custom RSpec matcher to the
-  GraphQLResponse matchers
-* [.add_validator](/docs/add_validator.md) - add a custom validator to be used
-  by the custom matchers
+Configuration:
+* [RSpec::GraphQLResponse.configure](/docs/configuration.md)
+* [Spec Type :graphql](/docs/graphql_spec_type.md)
 
-## Configuration
+Custom Matchers:
+* [have_errors](/docs/have_errors.md) - validates errors, or lack of, on the GraphQL response
+* [have_operation](/docs/have_operation.md) - validates the presence of a specified graphql operation in the graphql response
 
-To get things rolling, add a configuration block to your `spec_helper.rb` (or other file that gets included in specs, as
-desired). Within this block, you'll need to provide the GraphQL Schema to use for query execution.
+Context / Describe Helper Methods:
+* [execute_graphql](/docs/execute_graphql.md) - executes a graphql call with the registered schema, query, variables and context
+* [graphql_query](/docs/execute_graphql.md) - the query to execute
+* [graphql_variables](/docs/execute_graphql.md) - a hash of variables the query expects
+* [graphql_context](/docs/execute_graphql.md) - the `context` of a query or mutation's resolver
 
-```ruby
-RSpec::GraphQLResponse.configure |config| do
+Spec Helper Methods:
+* [response](/docs/response.md) - the response, as JSON, of the executed graphql query
+* [operation](/docs/operation.md) - retrieves the results of a named operation from the GraphQL response
 
-  config.graphql_schema = MyGraphQLSchema
-
-end
-```
+API / Development
+* [.add_matcher](/docs/add_matcher.md) - add a custom RSpec matcher to the GraphQLResponse matchers
+* [.add_validator](/docs/add_validator.md) - add a custom validator to be used by the custom matchers
+* [.add_helper](/docs/add_helper.md) - add helper methods to your specs, made avialable in `it` or `describe` / `context` blocks
 
 ## Getting Started
 
-There are a number of built-in helper methods and matchers that will allow you to skip the copy & paste work of executing
-a GraphQL Schema `.execute`. These include:
-
-Spec types:
-
-* `type: :graphql`
-
-Helper methods:
-
-* `execute_graphql`
-* `response`
-* `operation`
+There are only a couple of bits you need to get started: 
 
-Matchers:
-
-* `have_errors`
-
-### The `:graphql` Spec Type
-
-To use these custom helpers and matchers, you need to specificy `type: :graphql` as part of your spec's description. For exmaple,
+* configuration of a GraphQL Schema in [`RSpec::GraphQLResponse.configure`](/docs/configuration.md)
+* the inclusion of [`type: :graphql`](/docs/graphql_spec_type.md) in your `RSpec.describe` call
 
 ```ruby
-RSpec.describe Some::Thing, type: :graphql do
-
-  # ... 
+RSpec::GraphQLResponse.configure do |config|
+  config.graphql_schema = MyGraphQLSchema
+end
 
+RSpec.describe My::Cool::Thing, type: :graphql do
+  # ...
 end
 ```
 
-With this `type` set, your specs will have access to all of the `RSpec::GraphQLResponse` code.
+Beyond these two basic needs, understanding the reason for this gem's existence can be useful in figuring out what the gem
+does, and what methods and options are available.
 
-### Helper Methods
+## How We Got Here
 
 Executing a GraphQL call from RSpec is not the most challening code to write:
 
@@ -121,16 +114,14 @@ in your specs.
 
 ```ruby
 RSpec.describe Some::Thing, type: :graphql do
-  let(:query) do
-    <<-GQL
-      query ListCharacters{
-        characters {
-          id
-          name
-        }
+  graphql_query <<-GQL
+    query ListCharacters{
+      characters {
+        id
+        name
       }
-    GQL
-  end
+    }
+  GQL
 
   it "executes the query" do
     response = execute_graphql.to_h
@@ -147,16 +138,14 @@ way. The reduce this, `RSpec::GraphQLResponse` provides a built-in `response` he
 
 ```ruby
 RSpec.describe Some::Thing, type: :graphql do
-  let(:query) do
-    <<-GQL
-      query {
-        characters {
-          id
-          name
-        }
+  graphql_query <<-GQL
+    query ListCharacters{
+      characters {
+        id
+        name
       }
-    GQL
-  end
+    }
+  GQL
 
   it "executes the query" do
     expect(response).to include(
@@ -176,16 +165,14 @@ nested hash checking, use the built-in `operation` method to retrieve the `chara
 
 ```ruby
 RSpec.describe Some::Thing, type: :graphql do
-  let(:query) do
-    <<-GQL
-      query {
-        characters {
-          id
-          name
-        }
+  graphql_query <<-GQL
+    query ListCharacters{
+      characters {
+        id
+        name
       }
-    GQL
-  end
+    }
+  GQL
 
   it "executes the query" do
     characters = operation(:characters)

data/RELEASE_NOTES.md

@@ -0,0 +1,39 @@
+# Release Notes
+
+Release notes for various versions of RSpec::GraphQLResponse
+
+See [the upgrade guide](/UPGRADE.md) for details on changes between versions and how to upgrade.
+
+## v0.2.0 - GraphQL Configuration DSL and Refactorings
+
+Misc changes and corrections, some new features, and generally trying to create a more robust
+and usable experience, right out of the box.
+
+### New Features
+
+* Significantly improved documentation
+* `have_operation` matcher
+* GraphQL configuration DSL
+  * `graphql_query`
+  * `graphql_variables`
+  * `graphql_context`
+* Describe/Context level RSpec helper methods via `.add_context_helper` DSL
+
+### Breaking Changes
+
+This release changes the graphql query, variables and context configuration away from `let` vars
+and into a proper DSL.
+
+### Bug Fixes
+
+Lots of misc bug fixes, including caching of values, ensuring things work in nested contexts, etc.
+
+## v0.1.0 - Initial Release
+
+Early beta work to get this out the door and begin adoption
+
+* `have_errors` matcher
+* `operation` helper
+* `response` helper
+* `execute_graphql` helper
+* DSL for adding custom matchers, validators, and helpers

data/UPGRADE.md

@@ -0,0 +1,37 @@
+# Upgrade Guide
+
+## v0.1.0 to v0.2.0
+
+There is a breaking change between v0.1.0 and v0.2.0 regarding the configuration of graphql queries, variables and context. 
+Previously, you defined these three items with `let` in rspec:
+
+```ruby
+let(:graphql_query) { ... }
+```
+
+In v0.2.0, this changes to a new DSL for each of these three items:
+
+```ruby
+RSpec.describe My::Stuff, type: :graphql do
+
+  graphql_query <<-GQL
+    query Characters($name: String) {
+      characters(name: $name) {
+        id
+        name
+      }
+    }
+  GQL
+
+  graphql_variables({
+    name: "Jam"
+  })
+
+  graphql_context({
+    some: "context here",
+    current_user: some_user
+  })
+
+  it " ... "
+end
+```

data/docs/add_helper.md

@@ -0,0 +1,95 @@
+# Adding Helper Methods with `.add_helper`
+
+Much of the value that RSpec::GraphQLResponse brings is in the form of helper methods. Some helpers
+will let you simplify a spec from a verbose set of structure parsing, like this:
+
+```ruby
+it "does stuff" do
+  characters = response["data"]["characters"]
+
+  expect(characters).to include(
+    ...
+  )
+end
+```
+
+Down into something a little more reasonable with the `operation` helper, like this:
+
+```ruby
+it "does stuff" do
+  expect(operation(:characters)).to include(
+    ...
+  )
+end
+```
+
+It's not a huge difference, but when you consider how well the `operation` method handles `nil` and 
+operation results that are not found, it's well worth the few lines of savings.
+
+There are many other helpers available for your test suites, as well. Be sure to check the full
+documentation list in the main readme.
+
+## Add a Spec Helper
+
+Most of the helpers that you'll want to add will be methods that are made available inside of
+your `it` (and related / similar) blocks, as shown above.
+
+To do this, you only need to call `RSpec::GraphQLResponse.add_helper(name, &helper_block)`. The `name` should
+be a symbol that represents the method name you wish to create. And the `&helper_block` is the actual
+method body, with any params you need.
+
+Within the helper body, you will have access to all available features of RSpec's `it` blocks, including
+other helper methods that come with RSpec::GraphQLResponse.
+
+A simple example can be found in the `operation` helper:
+
+```ruby
+RSpec::GraphQLResponse.add_helper :operation do |operation_name|
+  return nil unless response.is_a? Hash
+
+  response.dig("data", operation_name)
+end
+```
+
+In this example, the `response` helper is used, which guarantees the graphql has been executed and a response 
+is available, assuming there were no exceptions preventing that.
+
+## Add a Context Helper
+
+In addition to Spec level helpers, RSpec::GraphQLResponse allows you to add custom helpers at the context
+level. This means you can add configuration and other bits that can be called outside of an `it` block.
+The existing `graphql_query` and other DSL methods for configuring graphql calls are a great example of
+context level helpers.
+
+To create a context helper, call `RSpec::GraphQLResponse.add_context_helper(name, &helper_block)`. The params
+are the same as `.add_helper`, but the resulting method will be made available in `describe` and `context`
+blocks.
+
+```ruby
+RSpec::GraphQLResponse.add_context_helper :my_setting do |some_arg|
+  @my_setting = some_arg
+end
+```
+
+In this simple example, a method called `my_setting` is created, and it stores a value in the instance variable
+`@my_setting`. This takes advantage of RSpec's native ability to handle instance variables in describe and
+context blocks, allowing the variable to exist withing the hierarchy of objects for a given spec. 
+
+With that defined, it can be used within a spec:
+
+```ruby
+RSpec.describe Cool::Thing, type: :graphql do
+
+  my_setting "this is a cool setting!"
+
+
+  it "has the setting" do
+    setting = self.class.instance_variable_get(:@my_setting)
+
+    expect(setting).to eq("this is a cool setting!")
+  end
+end
+```
+
+You may want to provide a better way of retrieving the `@my_setting` var from the class, but this at least
+demonstrates the ability to retrieve it from the class created by the `describe` block.

data/docs/add_validator.md

@@ -6,5 +6,172 @@ organizing your matcher code.
 
 To solve this, RSpec::GraphQLResponse introduced validators - code that is
 called to manage the validation of a graphql response, and provide the failure
-messages. Validators allow your code to be well organized, and unit tested,
+messages. 
+
+
+## Clean Matchers with Validators
+
+Validators allow your code to be well organized, and unit tested,
 while providing a clean implementation of the matcher, as shown here:
+
+```ruby
+RSpec::GraphQLResponse.add_matcher :foo_bar do |expected_value)
+  match do |actual_value|
+    foo_bar = RSpec::GraphQLResponse.validator(:foo_bar)
+
+    @result = foo_bar.validate(actual_value, expected_value)
+  end
+
+  failure_message do |response|
+    @result.reason
+  end
+end
+```
+
+## Add a Validator with a Failure Message
+
+```ruby
+RSpec::GraphQLResponse.add_validator :foo_bar do
+  # a regular failure message named `:nil`
+  failure_message :nil, "Can't validate nil"
+
+  # a lambda failure message named `:not_foo`
+  # this lets you pass data to the message so it can
+  # be more expressive of the failure reason
+  failure_message :not_foo, -> (actual, expected) { "Expected it to #{actual}, but it did not. found #{expected}" }
+  
+  validate do |actual, expected|
+    # fail for one reason
+    next fail_validation(:nil) if actual.nil?
+
+    # fail for another reason, with data passed
+    # to the failure message
+    next fail_validation(:not_foo, actual, expected) unless actual == expected
+
+    # no failures found, so pass it!
+    pass_validation
+  end
+end
+```
+
+### Method: `failure_message(name, message)`
+
+The `failure_message` method allows a message to be registered with a specific name and a message associated with that name. 
+
+`failure_message name, message`
+
+The `name` should be symbol which represents a reason for failure.
+
+The `message` can either be a string containing the failure message, or a lambda (proc) that returns a string with the message.
+
+```ruby
+RSpec::GraphQLResponse.add_validator :some_validator do
+  failure_message :a_failure, "Failed because of a failure"
+
+  # ...
+end
+```
+
+Providing a lambda for the message allows the message to receive parameters and format the message using those parameters.
+
+```ruby
+RSpec::GraphQLResponse.add_validator :some_validator do
+  failure_message :wrong_value, ->(value) { "Failed because #{value} is not 'foo'" }
+
+  # ...
+end
+```
+
+The failure messages can be referenced in the validation methods by calling `fail_validation` (see below)
+
+### Method: `validate(&validation_block)`
+
+Provide a validation method to determine if the actual value meets expectations. This validation method is most commonly
+used with the `expect(something).to ...` RSpec matcher syntax.
+
+The `&validation_block` will receive the actual value to validate as well as any other parameters that may need to be defined.
+There are no limitations on the number of parameters or their names.
+
+```ruby
+RSpec::GraphQLResponse.add_validator :some_validator do
+  # ... failure_messages and other bits
+
+  validate do |actual, some_value|
+    # ... validation logic here
+
+    next fail_validation(:reason) if some_failure_criteria
+  end
+end
+```
+
+### Method: `validate_negated(&validation_block)`
+
+Provide a negated validation method to determine if the actual value meets expectations. This validation method is
+most commonly used with the negated expecation syntax, such as `expect(something).to_not ...`.
+
+The `&validation_block` will receive the actual value to validate as well as any other parameters that may need to be defined.
+There are no limitations on the number of parameters or their names.
+
+```ruby
+RSpec::GraphQLResponse.add_validator :some_validator do
+  # ... failure_messages and other bits
+
+  validate_negated do |actual, some_value|
+    # ... negated validation logic here
+
+    next fail_validation(:reason) unless some_failure_criteria
+  end
+end
+```
+
+Remember that `negated` validation should prove that the specified condition does _not_ exist. For example, when writing
+an expectation such as `expect(response).to_not have_errors`, the `validate_negated` method needs to verify that there are
+no errors in the response.
+
+```ruby
+validate_negated do |response|
+  errors = response.fetch("errors", [])
+
+  # check for the negation of have_errors, meaning check to 
+  # make sure there are no errors
+  next fail_validation(:found_errors) unless errors.count == 0
+end
+```
+
+### Validation Failure
+
+When the actual value does not reflect any expected value, a failure can be noted by calling `next failure_message(name, [values])`.
+
+The `name` is a symbol which has been registered using the `failure_message` method (see above). And `[values]` are an optional
+array of values that will be provided to the failure message if the registered message is a lambda (proc).
+
+```ruby
+vadliate do |actual|
+
+  # something went wrong, better fail!
+  next fail_validation(:bad_thing) if actual.bad_value
+end
+```
+
+**IMPORTANT NOTE**
+
+There can be only _one_ valid reason for failure at a time. Therefore, as soon as a failure condition is met, the `fail_validation`
+method should be invoked. Then to prevent the rest of the method from executing, the `validate` or `validate_negates` method should
+be halted immediately. Due to the syntax requirements of ruby lambdas and procs, this is done with the `next` keyword.
+
+So be sure to call `next failure_message ...` and not just `failure_message`!
+
+### Validation Success
+
+If all validation checks pass, the final call in the `validate` or `validate_negated` methods should be `pass_validation`
+
+```ruby
+validate do |actual|
+  # ... check for failed conditions
+
+  # everything passed!
+  pass_validation
+end
+```
+
+The `pass_validation` method takes in no parameters, as a valid result does not provide a reason.

data/docs/configuration.md

@@ -0,0 +1,12 @@
+# RSpec::GraphQLResponse Configuration
+
+To get things rolling, add a configuration block to your `spec_helper.rb` (or other file that gets included in specs, as
+desired). Within this block, you'll need to provide the GraphQL Schema to use for query execution.
+
+```ruby
+RSpec::GraphQLResponse.configure |config| do
+
+  config.graphql_schema = MyGraphQLSchema
+
+end
+```

data/docs/execute_graphql.md

@@ -0,0 +1,43 @@
+# Executing GraphQL with Helper Method `execute_graphql`
+
+Simplifies execution of a graphql query, using `context` / `describe` level helper
+methods for configuring the query.
+
+```ruby
+RSPec.describe Cool::Stuff, type: :graphql do
+  graphql_query <<-GQL
+    query SomeThing($name: String) {
+      characters(name: $name) {
+        id
+        name
+      }
+    }
+  GQL
+  
+  graphql_variables {
+    name: "Jam"
+  }
+
+  grapql_context {
+    current_user: "some user or whatever you need"
+  }
+
+  it "executes and does the thing with the vars and context" do
+    # ... expect things here
+  end
+end
+```
+
+## Available Configuration Methods
+
+### `graphql_query`
+
+A string - most commonly a ruby heredoc - for the graphql query to execute
+
+### `graphql_variables`
+
+A hash of keys and values that the query expects to use
+
+### `graphql_context`
+
+A hash of keys and values that are passed to a query or mutation, as `context`, in that query or mutation's resolver method.

data/docs/graphql_spec_type.md

@@ -0,0 +1,14 @@
+# Custom Spec Type, `type: :grapql`
+
+To use the custom helpers and matchers provide by RSpec::GraphQLResponse, you need to specificy `type: :graphql` as 
+part of your spec's description.
+
+```ruby
+RSpec.describe My::Cool::Thing, type: :graphql do
+
+  # ... all of RSpec::GraphQLResponse is now available!
+
+end
+```
+
+With this `type` set, your specs will have access to all of the `RSpec::GraphQLResponse` features.

data/docs/have_operation.md

@@ -0,0 +1,46 @@
+# Validate a response operation with `have_operation(name)`
+
+Check for the presence of an operation's results. Useful when you want to ensure an operation exists before
+retrieving the operation's results.
+
+## Validate an Operation is Present
+
+```ruby
+RSpec.describe My::Characters, type: :graphql do
+  graphql_query <<-GQL
+    query CharacterList {
+      characters {
+        id
+        name
+      }
+    }
+  GQL
+
+  it "has the characters" do
+
+    expect(response).to have_operation(:characters)
+
+  end
+end
+```
+
+## Validate an operation is NOT Present
+
+```ruby
+RSpec.describe My::Characters, type: :graphql do
+  graphql_query <<-GQL
+    query CharacterList {
+      characters {
+        id
+        name
+      }
+    }
+  GQL
+
+  it "does not have books" do
+
+    expect(response).to_not have_operation(:books)
+
+  end
+end
+```

data/docs/response.md

@@ -0,0 +1 @@
+# Check the GraphQL Response with Helper `response`

data/lib/rspec/graphql_response.rb

@@ -1,4 +1,4 @@
-require "RSpec"
+require "rspec"
 
 require_relative "graphql_response/version"
 require_relative "graphql_response/configuration"

data/lib/rspec/graphql_response/helpers.rb

@@ -1,9 +1,20 @@
 module RSpec
   module GraphQLResponse
-    def self.add_helper(name, &helper)
+    def self.add_context_helper(name, &helper)
+      self.add_helper(name, scope: :context, &helper)
+    end
+
+    def self.add_helper(name, scope: :spec, &helper)
       helper_module = Module.new do |mod|
         mod.define_method(name) do |*args|
-          @result ||= self.instance_exec(*args, &helper)
+          instance_var = "@#{name}".to_sym
+
+          if self.instance_variables.include? instance_var
+            return self.instance_variable_get(instance_var)
+          end
+
+          result = self.instance_exec(*args, &helper)
+          self.instance_variable_set(instance_var, result)
         end
       end
 
@@ -11,13 +22,27 @@ module RSpec
         config.after(:each) do
           helper_module.instance_variable_set(:@result, nil)
         end
-      end
 
-      self.include(helper_module)
+        module_method = if scope == :spec
+                          :include
+                        elsif scope == :context
+                          :extend
+                        else
+                          raise ArgumentError, "A helper method's scope must be either :spec or :describe"
+                        end
+
+        config.send(module_method, helper_module, type: :graphql)
+      end
     end
   end
 end
 
+# describe level helpers
+require_relative "helpers/graphql_query"
+require_relative "helpers/graphql_variables"
+require_relative "helpers/graphql_context"
+
+# spec level helpers
 require_relative "helpers/operation"
 require_relative "helpers/response"
 require_relative "helpers/execute_graphql"

data/lib/rspec/graphql_response/helpers/execute_graphql.rb

@@ -1,4 +1,12 @@
 RSpec::GraphQLResponse.add_helper :execute_graphql do
   config = RSpec::GraphQLResponse.configuration
-  config.graphql_schema.execute(query)
+
+  query = get_graphql_query if respond_to? :get_graphql_query
+  query_vars = get_graphql_variables if respond_to? :get_graphql_variables
+  query_context = get_graphql_context if respond_to? :get_graphql_context
+
+  config.graphql_schema.execute(query, {
+    variables: query_vars,
+    context: query_context
+  })
 end

data/lib/rspec/graphql_response/helpers/graphql_context.rb

@@ -0,0 +1,3 @@
+RSpec::GraphQLResponse.add_context_helper :graphql_context do |ctx|
+  self.define_method(:get_graphql_context) { ctx }
+end

data/lib/rspec/graphql_response/helpers/graphql_query.rb

@@ -0,0 +1,3 @@
+RSpec::GraphQLResponse.add_context_helper :graphql_query do |gql|
+  self.define_method(:get_graphql_query) { gql }
+end

data/lib/rspec/graphql_response/helpers/graphql_variables.rb

@@ -0,0 +1,3 @@
+RSpec::GraphQLResponse.add_context_helper :graphql_variables do |vars|
+  self.define_method(:get_graphql_variables) { vars }
+end

data/lib/rspec/graphql_response/matchers.rb

@@ -12,3 +12,4 @@ module RSpec
 end
 
 require_relative "matchers/have_errors"
+require_relative "matchers/have_operation"

data/lib/rspec/graphql_response/matchers/have_errors.rb

@@ -11,7 +11,7 @@ RSpec::GraphQLResponse.add_matcher :have_errors do |count = nil|
     @result.valid?
   end
 
-  failure_message do |response|
+  failure_message do |_|
     @result.reason
   end
 
@@ -27,7 +27,7 @@ RSpec::GraphQLResponse.add_matcher :have_errors do |count = nil|
     @result.valid?
   end
 
-  failure_message_when_negated do |response|
+  failure_message_when_negated do |_|
     @result.reason
   end
 

data/lib/rspec/graphql_response/matchers/have_operation.rb

@@ -0,0 +1,23 @@
+RSpec::GraphQLResponse.add_matcher :have_operation do |operation_name|
+  match do |response|
+    validator = RSpec::GraphQLResponse.validator(:have_operation)
+
+    @result = validator.validate(response, operation_name: operation_name)
+    @result.valid?
+  end
+
+  failure_message do |_|
+    @result.reason
+  end
+
+  match_when_negated do |response|
+    validator = RSpec::GraphQLResponse.validator(:have_operation)
+
+    @result = validator.validate_negated(response, operation_name: operation_name)
+    @result.valid?
+  end
+
+  failure_message_when_negated do |_|
+    @result.reason
+  end
+end

data/lib/rspec/graphql_response/validators.rb

@@ -11,6 +11,11 @@ module RSpec
       @validators[name] = validator_class
     end
 
+    def self.remove_validator(name)
+      @validators ||= {}
+      @validators.delete(:key)
+    end
+
     def self.validator(name)
       @validators[name].new
     end
@@ -18,3 +23,4 @@ module RSpec
 end
 
 require_relative "validators/have_errors"
+require_relative "validators/have_operation"

data/lib/rspec/graphql_response/validators/have_operation.rb

@@ -0,0 +1,24 @@
+RSpec::GraphQLResponse.add_validator :have_operation do
+  failure_message :nil, "Cannot evaluate operations on nil"
+  failure_message :not_found, ->(expected, actual) { "Expected to find operation result named #{expected}, but did not find it\n\t#{actual}" }
+
+  validate do |response, operation_name:|
+    next fail_validation(:nil) unless response.is_a? Hash
+
+    op = response.dig("data", operation_name.to_s)
+    next fail_validation(:not_found, operation_name, response) if op.nil?
+
+    pass_validation
+  end
+
+  failure_message :found, ->(expected, actual) { "Expected not to find operation result named #{expected}, but found it\n\t#{actual}" }
+
+  validate_negated do |response, operation_name:|
+    next fail_validation(:nil) unless response.is_a? Hash
+
+    op = response.dig("data", operation_name.to_s)
+    next fail_validation(:found, operation_name, response) unless op.nil?
+
+    pass_validation
+  end
+end

data/lib/rspec/graphql_response/version.rb

@@ -1,5 +1,5 @@
 module RSpec
   module GraphQLResponse
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rspec-graphql_response
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - River Lynn Bailey
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-02-24 00:00:00.000000000 Z
+date: 2021-03-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -102,34 +102,48 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/test.yml"
 - ".gitignore"
+- ".gituprc"
 - ".pryrc"
 - ".rspec"
 - ".ruby-version"
-- ".travis.yml"
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
 - README.md
+- RELEASE_NOTES.md
 - Rakefile
+- UPGRADE.md
 - bin/console
 - bin/rspec
 - bin/setup
+- docs/add_helper.md
 - docs/add_matcher.md
 - docs/add_validator.md
+- docs/configuration.md
+- docs/execute_graphql.md
+- docs/graphql_spec_type.md
 - docs/have_errors.md
+- docs/have_operation.md
 - docs/operation.md
+- docs/response.md
 - lib/rspec/graphql_response.rb
 - lib/rspec/graphql_response/configuration.rb
 - lib/rspec/graphql_response/helpers.rb
 - lib/rspec/graphql_response/helpers/execute_graphql.rb
+- lib/rspec/graphql_response/helpers/graphql_context.rb
+- lib/rspec/graphql_response/helpers/graphql_query.rb
+- lib/rspec/graphql_response/helpers/graphql_variables.rb
 - lib/rspec/graphql_response/helpers/operation.rb
 - lib/rspec/graphql_response/helpers/response.rb
 - lib/rspec/graphql_response/matchers.rb
 - lib/rspec/graphql_response/matchers/have_errors.rb
+- lib/rspec/graphql_response/matchers/have_operation.rb
 - lib/rspec/graphql_response/validators.rb
 - lib/rspec/graphql_response/validators/have_errors.rb
+- lib/rspec/graphql_response/validators/have_operation.rb
 - lib/rspec/graphql_response/validators/validation_base.rb
 - lib/rspec/graphql_response/validators/validation_result.rb
 - lib/rspec/graphql_response/validators/validation_runner.rb

data/.travis.yml

@@ -1,7 +0,0 @@
----
-sudo: false
-language: ruby
-cache: bundler
-rvm:
-  - 2.6.6
-before_install: gem install bundler -v 1.17.2