graphql-response_validator 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 59a6ee689aecc77afc491f97738976e94f41176120eb57ce4378cd94f921241d
+  data.tar.gz: 35021c4ccc45801799003f40c26af09267d70783e6bbdb9e088aac18f2945078
+SHA512:
+  metadata.gz: de6caf3beae2a38edeeba7f76d290d48399b875ffa11594a6451b427969c98a685f1e9f2d4236f6143fe226276571d7865212d2b4650f99b6c639694b04e847a
+  data.tar.gz: 31143dca640e94861279b3406a348b2eb62624546028280aeed7648bfc6d59a7d7bea28582c6a25632e2a11160148b538b930a435469cb72a0b5a2fc183c0248

data/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - gemfile: Gemfile
+            ruby: 3.3
+    steps:
+    - run: echo BUNDLE_GEMFILE=${{ matrix.gemfile }} > $GITHUB_ENV
+    - uses: actions/checkout@v4
+    - name: Setup Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Run tests
+      run: |
+        gem install bundler -v 2.4.22
+        bundle install --jobs 4 --retry 3
+        bundle exec rake test

data/.gitignore

@@ -0,0 +1,39 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+.envrc
+.byebug_history
+.ruby-version
+.rvmrc
+.DS_Store
+
+Gemfile.lock
+secrets.json
+example/*/*.graphql
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+gem 'pry'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Greg MacWilliam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,92 @@
+# GraphQL response validator
+
+Testing GraphQL queries using fixture responses runs the risk of false-positive tests when a query changes without its static response getting updated. This gem provides a simple utility for validating response fixtures against the shape of a query to assure that they match.
+
+```shell
+gem "graphql-response_validator"
+```
+
+## Usage
+
+Build a test query and its response data into a `GraphQL::ResponseValidator`, then assert that the fixture is correct for the query as part of your test:
+
+```ruby
+def test_my_stuff
+  request = %|{ widget { id title } }|
+  response = {
+    "data" => {
+      "widget" => { 
+        "id" => "1", 
+        "name" => "My widget", # << wrong, should be `title`
+      },
+    },
+  }
+  
+  # check that the query is valid...
+  query = GraphQL::Query.new(MySchema, query: request)
+  assert query.static_errors.none?, query.static_errors.map(&:message).join("\n")
+
+  # check that the response is valid...
+  fixture = GraphQL::ResponseValidator.new(query, response)
+  assert fixture.valid?, fixture.errors.map(&:message).join("\n")
+  # Results in: "Expected data to provide field `widget.title`"
+end
+```
+
+### Abstract selections
+
+Abstract selections must include a type identity so that the validator knows what selection path(s) to follow. This can be done by including a `__typename` in abstract selection scopes:
+
+```ruby
+def test_my_stuff
+  request = %|{ 
+    node(id: 1) { 
+      ... on Product { title }
+      ... on Order { totalCost }
+      __typename 
+    }
+  }|
+  response = {
+    "data" => {
+      "node" => { 
+        "title" => "Ethereal wishing well", 
+        "__typename" => "Product",
+      },
+    },
+  }
+  
+  query = GraphQL::Query.new(MySchema, query: request)
+  fixture = GraphQL::ResponseValidator.new(query, response)
+
+  assert fixture.valid?, fixture.errors.first&.message
+end
+```
+
+Alternatively, you can use a system `__typename__` hint that exists only in response data, and this can be pruned from the response data after validating it:
+
+```ruby
+def test_my_stuff
+  request = %|{ 
+    node(id: 1) { 
+      ... on Product { title }
+      ... on Order { totalCost }
+    }
+  }|
+  response = {
+    "data" => {
+      "node" => { 
+        "totalCost" => 23, 
+        "__typename__" => "Order",
+      },
+    },
+  }
+  
+  query = GraphQL::Query.new(MySchema, query: request)
+  fixture = GraphQL::ResponseValidator.new(query, response)
+
+  assert fixture.valid?, fixture.errors.first&.message
+
+  expected_result = { "data" => { "node" => { "totalCost" => 23 } } }
+  assert_equal expected_result, fixture.prune!.to_h
+end
+```

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t, args|
+  puts args
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task :default => :test

data/graphql-response_validator.gemspec

@@ -0,0 +1,34 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "graphql/response_validator/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "graphql-response_validator"
+  spec.version       = GraphQL::ResponseValidator::VERSION
+  spec.authors       = ["Greg MacWilliam"]
+  spec.summary       = "Validate that GraphQL response fixtures match their test queries."
+  spec.description   = "Validate that GraphQL response fixtures match their test queries."
+  spec.homepage      = "https://github.com/gmac/graphql-response_validator"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata    = {
+    "homepage_uri" => "https://github.com/gmac/graphql-response_validator",
+    "changelog_uri" => "https://github.com/gmac/graphql-response_validator/releases",
+    "source_code_uri" => "https://github.com/gmac/graphql-response_validator",
+    "bug_tracker_uri" => "https://github.com/gmac/graphql-response_validator/issues",
+  }
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^test/})
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency "graphql", ">= 2.0.0"
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 12.0"
+  spec.add_development_dependency "minitest", "~> 5.12"
+end

data/lib/graphql/response_validator/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module GraphQL
+  class ResponseValidator
+    VERSION = "0.0.1"
+  end
+end

data/lib/graphql/response_validator.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "graphql"
+
+module GraphQL
+  class ResponseValidator
+    ValidationError = Struct.new(:message, :path)
+
+    SYSTEM_TYPENAME = "__typename__"
+    SCALAR_VALIDATORS = {
+      "Boolean" => -> (data) { data.is_a?(TrueClass) || data.is_a?(FalseClass) },
+      "Float" => -> (data) { data.is_a?(Numeric) },
+      "ID" => -> (data) { data.is_a?(String) || data.is_a?(Integer) },
+      "Int" => -> (data) { data.is_a?(Integer) },
+      "JSON" => -> (data) { data.is_a?(Hash) },
+      "String" => -> (data) { data.is_a?(String) },
+    }.freeze
+  
+    attr_reader :errors
+  
+    def initialize(
+      query,
+      data,
+      scalar_validators: SCALAR_VALIDATORS,
+      system_typename: SYSTEM_TYPENAME
+    )
+      @query = query
+      @data = data
+      @errors = []
+      @valid = nil
+      @scalar_validators = scalar_validators
+      @system_typename = system_typename
+      @system_typenames = Set.new
+    end
+  
+    def valid?
+      return @valid unless @valid.nil?
+    
+      op = @query.selected_operation
+      parent_type = @query.root_type_for_operation(op.operation_type)
+      validate_selections(parent_type, op, @data["data"])
+      @valid = @errors.none?
+    end
+  
+    def prune!
+      valid?
+      @system_typenames.each { _1.delete(@system_typename) }
+      self
+    end
+  
+    def to_h
+      @data
+    end
+  
+    private
+  
+    def validate_selections(parent_type, parent_node, data_part, path = [])
+      if parent_type.non_null?
+        if !data_part.nil?
+          return validate_selections(parent_type.of_type, parent_node, data_part, path)
+        else
+          @errors << ValidationError.new("Expected non-null selection to provide value", path.dup)
+          return false
+        end
+    
+      elsif data_part.nil?
+        # nullable node with a null value is okay
+        return true
+    
+      elsif parent_type.list?
+        if data_part.is_a?(Array)
+          return data_part.all? { |item| validate_selections(parent_type.of_type, parent_node, item, path) }
+        else
+          @errors << ValidationError.new("Expected list selection to provide Array", path.dup)
+          return false
+        end
+        
+      elsif parent_type.kind.leaf?
+        return validate_leaf(parent_type, data_part, path)
+    
+      elsif !data_part.is_a?(Hash)
+        @errors << ValidationError.new("Expected composite selection to provide Hash", path.dup)
+        return false
+      end
+    
+      parent_node.selections.all? do |node|
+        case node
+        when GraphQL::Language::Nodes::Field
+          begin
+            path << (node.alias || node.name)
+            unless data_part.key?(path.last)
+              @errors << ValidationError.new("Expected data to provide field", path.dup)
+              next false
+            end
+            
+            next_value = data_part[path.last]
+            next_type = if node.name == "__typename"
+              annotation_type = @query.get_type(data_part[path.last])
+              unless annotation_type && @query.possible_types(parent_type).include?(annotation_type)
+                @errors << ValidationError.new("Expected selection to provide a possible type name of `#{parent_type.graphql_name}`", path.dup)
+                next false
+              end
+
+              @query.get_type("String")
+            else
+              @query.get_field(parent_type, node.name)&.type
+            end
+
+            unless next_type
+              @errors << ValidationError.new("Invalid selection of `#{parent_type.graphql_name}.#{node.name}`", path.dup)
+              next false
+            end
+
+            validate_selections(next_type, node, next_value, path)
+          ensure
+            path.pop
+          end
+      
+        when GraphQL::Language::Nodes::InlineFragment
+          resolved_type = resolved_type(parent_type, data_part, path)
+          next false if resolved_type.nil?
+
+          fragment_type = node.type.nil? ? parent_type : @query.get_type(node.type.name)
+          next true unless @query.possible_types(fragment_type).include?(resolved_type)
+      
+          validate_selections(fragment_type, node, data_part, path)
+      
+        when GraphQL::Language::Nodes::FragmentSpread
+          resolved_type = resolved_type(parent_type, data_part, path)
+          next false if resolved_type.nil?
+
+          fragment_def = @query.fragments[node.name]
+          fragment_type = @query.get_type(fragment_def.type.name)
+          next true unless @query.possible_types(fragment_type).include?(resolved_type)
+      
+          validate_selections(fragment_type, fragment_def, data_part, path)
+        end
+      end
+    end
+  
+    def validate_leaf(parent_type, value, path)
+      valid = if parent_type.kind.enum?
+        parent_type.values.key?(value)
+      elsif parent_type.kind.scalar?
+        validator = @scalar_validators[parent_type.graphql_name]
+        validator.nil? || validator.call(value)
+      end
+    
+      @errors << ValidationError.new("Expected a valid `#{parent_type.graphql_name}` value", path.dup) unless valid
+      valid
+    end
+  
+    def resolved_type(parent_type, data_part, path)
+      return parent_type unless parent_type.kind.abstract?
+    
+      typename = data_part["__typename"] || data_part[@system_typename]
+      if typename.nil?
+        @errors << ValidationError.new("Abstract position expects `__typename` or system typename hint", path.dup)
+        return nil
+      end
+    
+      @system_typenames.add(data_part) if data_part.key?(@system_typename)
+      annotated_type = @query.get_type(typename)
+
+      if annotated_type.nil?
+        @errors << ValidationError.new("Abstract typename `#{typename}` is not a valid type", path.dup)
+        nil
+      elsif !@query.possible_types(parent_type).include?(annotated_type)
+        @errors << ValidationError.new("Abstract type `#{parent_type.graphql_name}` cannot be `#{typename}`", path.dup)
+        nil
+      else
+        annotated_type
+      end
+    end
+  end
+end
+
+require_relative "./response_validator/version"

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: graphql-response_validator
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Greg MacWilliam
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-03-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: graphql
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.12'
+description: Validate that GraphQL response fixtures match their test queries.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- graphql-response_validator.gemspec
+- lib/graphql/response_validator.rb
+- lib/graphql/response_validator/version.rb
+homepage: https://github.com/gmac/graphql-response_validator
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/gmac/graphql-response_validator
+  changelog_uri: https://github.com/gmac/graphql-response_validator/releases
+  source_code_uri: https://github.com/gmac/graphql-response_validator
+  bug_tracker_uri: https://github.com/gmac/graphql-response_validator/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.15
+signing_key:
+specification_version: 4
+summary: Validate that GraphQL response fixtures match their test queries.
+test_files: []