rspec-graphql_response 0.1.0 → 0.4.1

data/docs/response.md

@@ -0,0 +1 @@
+# The GraphQL Response, via Helper `response`

data/docs/response_data.md

@@ -0,0 +1,146 @@
+# Using the `response_data` Helper
+
+The `response_data` helper will dig through a graphql response, through
+the outer hash, into the response data for an operation, and through any
+and all layers of hash and array. 
+
+## Syntax
+
+```ruby
+response_data *[dig_pattern]
+```
+
+Data returned via this helper will assume a `"data" => ` key at the root of
+the `response` object. This root does not need to be specified in the list
+of attributes for the `dig_pattern`.
+
+### Params
+
+* `*[dig_pattern]` - an array of attributes (`:symbol`, `"string"`, or `key: :value` pair) that describes
+the data structure to dig through, and the final data set to retrieve from the graphql response.
+
+#### dig_pattern
+
+Each attribute added to the `dig_pattern` represents an attribute at the given level of the
+data structure, in numeric order from left to right. The first attribute provides will dig into
+that attribute at the first level of data (just below the `"data" =>` key). The second attribute
+will dig through data just below that first level, etc. etc. etc.
+
+For example, with a data structure as shown below, in "Basic Use", you could specifiy these
+attributes for the dig pattern:
+
+* :characters
+* :name
+
+Like this:
+
+```ruby
+response_data :characters, :name
+```
+
+This dig pattern will find the `"characters"` key just below `"data"`, then iterate through
+the array of characters and retrieve the `"name"` of each character.
+
+For more details and options for the dig pattern, see the examples below.
+
+## Basic Use
+
+A `response` data structure may look something like the following.
+
+```ruby
+{
+  "data" => {
+    "characters" => [
+      { "id" => "1", "name" => "Jam" },
+      { "id" => "2", "name" => "Redemption" },
+      { "id" => "3", "name" => "Pet" }
+    ]
+  }
+}
+```
+
+The `response_data` helper will dig through to give you simplified
+results that are easier to verify.
+
+For example, if only the names of the characters need to be checked:
+
+```ruby
+response_data :characters, :name
+
+# => ["Jam", "Redemption", "Pet"]
+```
+
+Or perhaps only the name for 2nd character is needed:
+
+```ruby
+response_data {characters: [1]}, :name
+
+# => "Redemption"
+```
+
+## List Every Item in an Array
+
+Many responses from a graphql call will include an array of data somewhere
+in the data structure. If you need to return all of the items in an array,
+you only need to specify that array's key:
+
+```ruby
+it "has characters" do
+  characters = response_data(:characters)
+
+  expect(character).to include(
+    { id: 1, name: "Jam" },
+    # ...
+  )
+end
+```
+
+## Dig a Field From Every Item in an Array
+
+When validation only needs to occur on a specific field for items found in
+an array, there are two options.
+
+1. Specify a list of fields as already shown
+2. change the array's key to a hash and provide a `:symbol` wrapped in an array as the value
+
+The first option was already shown in the Basic Use section above. 
+
+```ruby
+response_data :characters, :name
+
+# => ["Jam", "Redemption", "Pet"]
+```
+
+For the second option, the code would look like this:
+
+```ruby
+response_data characters: [:name]
+
+# => ["Jam", "Redemption", "Pet"]
+```
+
+Both of these options are functionaly the same. The primary difference will be
+how you wish to express the data structure in your code. Changing the list of
+attributes to a hash with an array wrapping the value will provide a better
+indication that an array is expected at that point in the data structure.
+
+## Dig Out an Item By Index, From an Array
+
+There may be times when only a single piece of a returned array needs to be
+validated. To handle this, switch the key of the array to a hash, as in the
+previous example. Rather than specifying a child node's key in the value, though,
+specify the index of the item you wish to extract.
+
+```ruby
+response_data characters: [1]
+```
+
+This will return the character at index 1, from the array of characters.
+
+## Handling Nil
+
+If there is no data the key supplied, the helper will return `nil`
+
+```ruby
+response_data(:something_that_does_not_exist) #=> nil
+```

data/lib/rspec/graphql_response.rb

@@ -1,5 +1,6 @@
-require "RSpec"
+require "rspec"
 
+require_relative "graphql_response/dig_dug/dig_dug"
 require_relative "graphql_response/version"
 require_relative "graphql_response/configuration"
 require_relative "graphql_response/validators"

data/lib/rspec/graphql_response/dig_dug/dig_dug.rb

@@ -0,0 +1,83 @@
+module RSpec
+  module GraphQLResponse
+    class DigDug
+      attr_reader :dig_pattern
+
+      def initialize(*dig_pattern)
+        @dig_pattern = parse_dig_pattern(*dig_pattern)
+      end
+
+      def dig(data)
+        dig_data(data, dig_pattern)
+      end
+
+      private
+
+      def dig_data(data, patterns)
+        return data if patterns.nil?
+        return data if patterns.empty?
+
+        node = patterns[0]
+        node_key = node[:key]
+        node_key = node_key.to_s if node_key.is_a? Symbol
+        node_value = node[:value]
+
+        if node[:type] == :symbol
+          result = dig_symbol(data, node_key)
+        elsif node[:type] == :array
+          if data.is_a? Hash
+            child_data = data[node_key]
+            result = dig_symbol(child_data, node_value)
+          elsif data.is_a? Array
+            result = data.map { |value|
+              child_data = value[node_key]
+              dig_symbol(child_data, node_value)
+            }.compact
+          else
+            result = data
+          end
+        end
+
+        dig_data(result, patterns.drop(1))
+      end
+
+      def parse_dig_pattern(*pattern)
+        pattern_config = pattern.map do |pattern_item|
+          if pattern_item.is_a? Symbol 
+            {
+              type: :symbol,
+              key: pattern_item
+            }
+          elsif pattern_item.is_a? Hash
+            pattern_item.map do |key, value|
+              {
+                type: :array,
+                key: key,
+                value: value[0]
+              }
+            end
+          end
+        end
+
+        pattern_config.flatten
+      end
+
+      def dig_symbol(data, key)
+        key = key.to_s if key.is_a? Symbol
+        return data[key] if data.is_a? Hash
+
+        if data.is_a? Array
+          if key.is_a? Numeric
+            mapped_data = data[key]
+          else
+            mapped_data = data.map { |value| value[key] }.flatten
+          end
+
+          return mapped_data
+        end
+
+        return data
+      end
+    end
+  end
+end

data/lib/rspec/graphql_response/helpers.rb

@@ -1,23 +1,51 @@
 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)
+        mod.define_method(name) do |*args, &block|
+          instance_var = "@#{name}".to_sym
+
+          if self.instance_variables.include? instance_var
+            return self.instance_variable_get(instance_var)
+          end
+
+          args << block
+          result = self.instance_exec(*args, &helper)
+          self.instance_variable_set(instance_var, result)
         end
       end
 
       RSpec.configure do |config|
         config.after(:each) do
-          helper_module.instance_variable_set(:@result, nil)
+          instance_var = "@#{name}".to_sym
+          helper_module.instance_variable_set(instance_var, 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_context"
+require_relative "helpers/graphql_operation"
+require_relative "helpers/graphql_variables"
+
+# spec level helpers
+require_relative "helpers/execute_graphql"
 require_relative "helpers/operation"
 require_relative "helpers/response"
-require_relative "helpers/execute_graphql"
+require_relative "helpers/response_data"

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

@@ -1,4 +1,17 @@
 RSpec::GraphQLResponse.add_helper :execute_graphql do
   config = RSpec::GraphQLResponse.configuration
-  config.graphql_schema.execute(query)
+
+  operation = graphql_operation if respond_to? :graphql_operation
+  operation = self.instance_eval(&graphql_operation) if operation.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
+  
+  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(operation, {
+    variables: operation_vars,
+    context: operation_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(:graphql_context) { ctx }
+end

data/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

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(:graphql_variables) { vars }
+end

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

@@ -1,4 +1,5 @@
 RSpec::GraphQLResponse.add_helper :operation do |name|
+  warn 'WARNING: operation has been deprecated in favor of response_data. This helper will be removed in v0.5'
   return nil unless response.is_a? Hash
 
   response.dig("data", name.to_s)

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

@@ -0,0 +1,13 @@
+RSpec::GraphQLResponse.add_helper :response_data do |*fields|
+  next nil unless response.is_a? Hash
+
+  response_data = response["data"]
+  next nil if response_data.nil?
+  next nil if response_data.empty?
+
+  fields = fields.compact
+  next response_data if fields.empty?
+
+  dig_dug = RSpec::GraphQLResponse::DigDug.new(*fields)
+  dig_dug.dig(response_data)
+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