Change graphql_api helper name (#7)

Change the helper API to be `graphql_operation`. This more explicitly calls out that the Ruby heredoc can be more than just a query operation, but a mutation as well. Bumps the version to 0.4.0
testdouble · Mar 11, 2021 · 0ef7c7d · 0ef7c7d
1 parent 45f71dc
commit 0ef7c7d
Show file tree

Hide file tree

Showing 21 changed files with 85 additions and 71 deletions.
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rspec-graphql_response (0.3.0)
+    rspec-graphql_response (0.4.0)
       graphql (>= 1.0)
       rspec (>= 3.0)
 

diff --git a/README.md b/README.md
@@ -30,40 +30,45 @@ Or install it yourself as:
 
 ## Full Documentation
 
-* [Release Notes](/RELEASE_NOTES.md)
-* [Upgrade Guide](/UPGRADE.md)
+- [Release Notes](/RELEASE_NOTES.md)
+- [Upgrade Guide](/UPGRADE.md)
 
 The full documentation for RSpec::GraphQLResponse can be found in the `/docs` folder.
 
 Configuration:
-* [RSpec::GraphQLResponse.configure](/docs/configuration.md)
-* [Spec Type :graphql](/docs/graphql_spec_type.md)
+
+- [RSpec::GraphQLResponse.configure](/docs/configuration.md)
+- [Spec Type :graphql](/docs/graphql_spec_type.md)
 
 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
+
+- [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
 
 Context / Describe Helper Methods:
-* [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
+
+- [graphql_operation](/docs/execute_graphql.md) - the operation to execute (i.e query or mutation)
+- [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
 
 Spec Helper Methods:
-* [execute_graphql](/docs/execute_graphql.md) - executes a graphql call with the registered schema, query, variables and context
-* [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
+
+- [execute_graphql](/docs/execute_graphql.md) - executes a graphql call with the registered schema, query, variables and context
+- [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
 
 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
+
+- [.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 only a couple of bits you need to get started: 
+There are only a couple of bits you need to get started:
 
-* 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
+- 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::GraphQLResponse.configure do |config|
@@ -114,7 +119,7 @@ in your specs.
 
 ```ruby
 RSpec.describe Some::Thing, type: :graphql do
-  graphql_query <<-GQL
+  graphql_operation <<-GQL
     query ListCharacters{
       characters {
         id
@@ -138,7 +143,7 @@ way. The reduce this, `RSpec::GraphQLResponse` provides a built-in `response` he
 
 ```ruby
 RSpec.describe Some::Thing, type: :graphql do
-  graphql_query <<-GQL
+  graphql_operation <<-GQL
     query ListCharacters{
       characters {
         id
@@ -165,7 +170,7 @@ nested hash checking, use the built-in `operation` method to retrieve the `chara
 
 ```ruby
 RSpec.describe Some::Thing, type: :graphql do
-  graphql_query <<-GQL
+  graphql_operation <<-GQL
     query ListCharacters{
       characters {
         id
@@ -178,7 +183,7 @@ RSpec.describe Some::Thing, type: :graphql do
     characters = operation(:characters)
 
     expect(characters).to include(
-      # ... 
+      # ...
     )
   end
 end

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -4,20 +4,26 @@ 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.4.0 - Helper API change
+
+### Breaking Changes
+
+The helper `graphql_query` was renamed to `graphql_operation` to better communicate the use of the helper. Naming the helper with `_query` lead to an association that its use was meant for GraphQL query operations and could not also be used for a mutation.
+
 ## 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
+- 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
 
@@ -32,8 +38,8 @@ Lots of misc bug fixes, including caching of values, ensuring things work in nes
 
 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
+- `have_errors` matcher
+- `operation` helper
+- `response` helper
+- `execute_graphql` helper
+- DSL for adding custom matchers, validators, and helpers
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -1,8 +1,12 @@
 # Upgrade Guide
 
+## v0.3.0 to v0.4.0
+
+There is a breaking change between v0.3.0 and v0.4.0 where the helper `graphql_query` was renamed to `graphql_operation`. In order to migrate to v0.4.0 all references to `graphql_query` can be replaced with `graphql_operation`.
+
 ## 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. 
+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

diff --git a/docs/add_helper.md b/docs/add_helper.md
@@ -23,7 +23,7 @@ it "does stuff" do
 end
 ```
 
-It's not a huge difference, but when you consider how well the `operation` method handles `nil` and 
+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
@@ -51,15 +51,14 @@ RSpec::GraphQLResponse.add_helper :operation do |operation_name|
 end
 ```
 
-In this example, the `response` helper is used, which guarantees the graphql has been executed and a response 
+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.
+The existing `graphql_operation` 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`
@@ -73,7 +72,7 @@ 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. 
+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:
 

diff --git a/docs/execute_graphql.md b/docs/execute_graphql.md
@@ -8,15 +8,15 @@ RSPec.describe Cool::Stuff, type: :graphql do
   let(:user) { create(:graphql_user) }
   let(:search_name) { "Pet" }
 
-  graphql_query <<-GQL
+  graphql_operation <<-GQL
     query SomeThing($name: String) {
       characters(name: $name) {
         id
         name
       }
     }
   GQL
-  
+
   graphql_variables do
     {
       name: search_name
@@ -37,7 +37,7 @@ end
 
 ## Available Configuration Methods
 
-### `graphql_query`
+### `graphql_operation`
 
 A string - most commonly a ruby heredoc - for the graphql query to execute
 

diff --git a/docs/have_operation.md b/docs/have_operation.md
@@ -7,7 +7,7 @@ retrieving the operation's results.
 
 ```ruby
 RSpec.describe My::Characters, type: :graphql do
-  graphql_query <<-GQL
+  graphql_operation <<-GQL
     query CharacterList {
       characters {
         id
@@ -28,7 +28,7 @@ end
 
 ```ruby
 RSpec.describe My::Characters, type: :graphql do
-  graphql_query <<-GQL
+  graphql_operation <<-GQL
     query CharacterList {
       characters {
         id

diff --git a/lib/rspec/graphql_response/helpers.rb b/lib/rspec/graphql_response/helpers.rb
@@ -40,7 +40,7 @@ def self.add_helper(name, scope: :spec, &helper)
 end
 
 # describe level helpers
-require_relative "helpers/graphql_query"
+require_relative "helpers/graphql_operation"
 require_relative "helpers/graphql_variables"
 require_relative "helpers/graphql_context"
 

diff --git a/lib/rspec/graphql_response/helpers/execute_graphql.rb b/lib/rspec/graphql_response/helpers/execute_graphql.rb
@@ -1,17 +1,17 @@
 RSpec::GraphQLResponse.add_helper :execute_graphql do
   config = RSpec::GraphQLResponse.configuration
 
-  query = graphql_query if respond_to? :graphql_query
-  query = self.instance_eval(&graphql_query) if query.is_a? Proc
+  operation = graphql_operation if respond_to? :graphql_operation
+  operation = self.instance_eval(&graphql_operation) if operation.is_a? Proc
 
-  query_vars = graphql_variables if respond_to? :graphql_variables
-  query_vars = self.instance_eval(&graphql_variables) if query_vars.is_a? Proc
+  operation_vars = graphql_variables if respond_to? :graphql_variables
+  operation_vars = self.instance_eval(&graphql_variables) if operation_vars.is_a? Proc
 
-  query_context = graphql_context if respond_to? :graphql_context
-  query_context = self.instance_eval(&query_context) if query_context.is_a? Proc
+  operation_context = graphql_context if respond_to? :graphql_context
+  operation_context = self.instance_eval(&operation_context) if operation_context.is_a? Proc
 
-  config.graphql_schema.execute(query, {
-    variables: query_vars,
-    context: query_context
+  config.graphql_schema.execute(operation, {
+    variables: operation_vars,
+    context: operation_context
   })
 end
diff --git a/lib/rspec/graphql_response/helpers/graphql_operation.rb b/lib/rspec/graphql_response/helpers/graphql_operation.rb
@@ -0,0 +1,3 @@
+RSpec::GraphQLResponse.add_context_helper :graphql_operation do |gql|
+  self.define_method(:graphql_operation) { gql }
+end
diff --git a/lib/rspec/graphql_response/helpers/graphql_query.rb b/lib/rspec/graphql_response/helpers/graphql_query.rb
diff --git a/lib/rspec/graphql_response/version.rb b/lib/rspec/graphql_response/version.rb
@@ -1,5 +1,5 @@
 module RSpec
   module GraphQLResponse
-    VERSION = "0.3.0"
+    VERSION = "0.4.0"
   end
 end
diff --git a/spec/graphql_response/helpers/execute_graphql_spec.rb b/spec/graphql_response/helpers/execute_graphql_spec.rb
@@ -1,5 +1,5 @@
 RSpec.describe RSpec::GraphQLResponse, "helper#execute_graphql", type: :graphql do
-  graphql_query <<-GQL
+  graphql_operation <<-GQL
     query {
       characters {
         id,

diff --git a/spec/graphql_response/helpers/graphql_context_spec.rb b/spec/graphql_response/helpers/graphql_context_spec.rb
@@ -1,5 +1,5 @@
 RSpec.describe RSpec::GraphQLResponse, "graphql_variables helper", type: :graphql do
-  graphql_query <<-GQL
+  graphql_operation <<-GQL
     query CharacterList($name: String) {
       characters(name: $name) {
         id

diff --git a/spec/graphql_response/helpers/graphql_query_spec.rb b/spec/graphql_response/helpers/graphql_query_spec.rb
@@ -1,5 +1,5 @@
-RSpec.describe RSpec::GraphQLResponse, "graphql_query helper", type: :graphql do
-  graphql_query <<-GQL
+RSpec.describe RSpec::GraphQLResponse, "graphql_operation helper", type: :graphql do
+  graphql_operation <<-GQL
     query CharacterList {
       characters {
         id
@@ -35,7 +35,7 @@
   end
 
   context "proc as value" do
-    graphql_query do
+    graphql_operation do
       <<-GQL
         query CharacterList {
           characters {

diff --git a/spec/graphql_response/helpers/graphql_variables_spec.rb b/spec/graphql_response/helpers/graphql_variables_spec.rb
@@ -1,5 +1,5 @@
 RSpec.describe RSpec::GraphQLResponse, "graphql_variables helper", type: :graphql do
-  graphql_query <<-GQL
+  graphql_operation <<-GQL
     query CharacterList($name: String) {
       characters(name: $name) {
         id

diff --git a/spec/graphql_response/helpers/operation_spec.rb b/spec/graphql_response/helpers/operation_spec.rb
@@ -8,7 +8,7 @@
   end
 
   context "graphql response with data" do
-    graphql_query <<-GQL
+    graphql_operation <<-GQL
       query {
         characters {
           id,

diff --git a/spec/graphql_response/helpers/response_spec.rb b/spec/graphql_response/helpers/response_spec.rb
@@ -1,5 +1,5 @@
 RSpec.describe RSpec::GraphQLResponse, "helper#response", type: :graphql do
-  graphql_query <<-GQL
+  graphql_operation <<-GQL
     query {
       characters {
         id,

diff --git a/spec/graphql_response/matchers/have_operation_spec.rb b/spec/graphql_response/matchers/have_operation_spec.rb
@@ -1,5 +1,5 @@
 RSpec.describe RSpec::GraphQLResponse, "matcher#have_operation", type: :graphql do
-  graphql_query <<-GQL
+  graphql_operation <<-GQL
     query CharacterList {
       characters {
         id

diff --git a/spec/graphql_response/validators/have_operation_negated_spec.rb b/spec/graphql_response/validators/have_operation_negated_spec.rb
@@ -1,5 +1,5 @@
 RSpec.describe RSpec::GraphQLResponse, "#have_operation validator", type: :graphql do
-  graphql_query <<-GQL
+  graphql_operation <<-GQL
     query CharacterList {
       characters {
         id

diff --git a/spec/graphql_response/validators/have_operation_spec.rb b/spec/graphql_response/validators/have_operation_spec.rb
@@ -1,5 +1,5 @@
 RSpec.describe RSpec::GraphQLResponse, "#have_operation validator", type: :graphql do
-  graphql_query <<-GQL
+  graphql_operation <<-GQL
     query CharacterList {
       characters {
         id