schema-test 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 260d4172bc31999c0e327e3ac45428d042b7977bbad68c5b5d77e9eadba6765d
-  data.tar.gz: ff9ff5f54b598950d61b955750473007bd66afafeaa0d81cbb937a877c460c36
+  metadata.gz: 63c3ad67322093fabc506bf99f0f8677eb24b929d7f17bb569656d1951bc6e71
+  data.tar.gz: 3ef25c82500f915aeab5b522514778742a5235e4ae9289b1178f07be4faf998d
 SHA512:
-  metadata.gz: 6592e1e7f3b5d0f6ddb2fdfe5099d87de1e2674d3abb5e7a3e3268537ff86ff0bccdf933c4fdf563e581c54b5ec11025db9b16fa05477cf3c24783813e7667a2
-  data.tar.gz: 9d295a52695e323afe73236219694d4e51ea14754e323464f48328bf9421362626bc522ac286211e91a207858b6de25573272949c4e1917f9ae68e24b024f561
+  metadata.gz: 4a3cc4befe4ecd6fec9f948ed6c9048306948a530b815a1dab4c2d127d4557b1a0e6d62ae61bd7ffcf4e7ea622a27fc3151ad4c0209a6cd8d1d15abe7a470586
+  data.tar.gz: f2dd3828fc7ce1ae14df985408d08e64444bd4efd406b71275daa49889c21caf7d78703f2490cfe8b4e6f1f1d3f9bb737f5d6c1cf54e6524ef1cd831a953a6f4

data/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "bundler"
+    directory: "/"
+    schedule:
+      interval: "weekly"

data/.github/workflows/tests.yml

@@ -19,15 +19,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['2.6', '2.7', '3.0']
+        ruby-version: ['3.1', '3.2', '3.3']
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Set up Ruby
-    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
-    # change this to (see https://github.com/ruby/setup-ruby#versioning):
-    # uses: ruby/setup-ruby@v1
-      uses: ruby/setup-ruby@473e4d8fe5dd94ee328fdfca9f8c9c7afc9dae5e
+      uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby-version }}
         bundler-cache: true # runs 'bundle install' and caches installed gems automatically

data/Gemfile.lock

@@ -1,40 +1,39 @@
 PATH
   remote: .
   specs:
-    schema-test (0.1.0)
+    schema-test (0.2.0)
       json
       json_schemer
 
 GEM
   remote: https://rubygems.org/
   specs:
+    bigdecimal (3.1.8)
     byebug (11.1.3)
-    diff-lcs (1.4.4)
-    ecma-re-validator (0.3.0)
-      regexp_parser (~> 2.0)
+    diff-lcs (1.5.1)
     hana (1.3.7)
-    json (2.5.1)
-    json_schemer (0.2.18)
-      ecma-re-validator (~> 0.3)
+    json (2.7.2)
+    json_schemer (2.3.0)
+      bigdecimal
       hana (~> 1.3)
       regexp_parser (~> 2.0)
-      uri_template (~> 0.7)
-    rake (10.5.0)
-    regexp_parser (2.1.1)
-    rspec (3.10.0)
-      rspec-core (~> 3.10.0)
-      rspec-expectations (~> 3.10.0)
-      rspec-mocks (~> 3.10.0)
-    rspec-core (3.10.1)
-      rspec-support (~> 3.10.0)
-    rspec-expectations (3.10.1)
+      simpleidn (~> 0.2)
+    rake (13.2.1)
+    regexp_parser (2.9.2)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.0)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-mocks (3.10.2)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.10.0)
-    rspec-support (3.10.2)
-    uri_template (0.7.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    simpleidn (0.2.3)
 
 PLATFORMS
   ruby
@@ -42,9 +41,9 @@ PLATFORMS
 DEPENDENCIES
   bundler (~> 2)
   byebug
-  rake (~> 10.0)
+  rake (~> 13.0)
   rspec (~> 3.0)
   schema-test!
 
 BUNDLED WITH
-   2.1.4
+   2.5.9

data/README.md

@@ -129,6 +129,7 @@ require 'schema_test/minitest'
 SchemaTest.configure do |config|
   config.domain = 'mydomain.com'
   config.definition_paths << Rails.root.join('test', 'schema_definitions')
+  config.disable_rubocop = true # optional, set to true if using rubocop to disable it in the generated code
 end
 SchemaTest.load!
 ```
@@ -190,6 +191,64 @@ end
 ```
 Keeping the full schema directly in the tests means that it is **impossible** for us to accidentally impact any API endpoints with a distant schema change without also producing some change in the test files for those endpoints. That is the main benefit that this library tries to acheive.
 
+### Compiled mode
+
+As an alternative to inlining expanded schemas into your test files, you can use **compiled mode**. In this mode, all schema definitions are compiled to standalone JSON Schema files on disk, and test assertions validate against those files directly. No test file rewriting happens.
+
+To enable it, update your `test_helper.rb`:
+
+``` ruby
+require 'schema_test/minitest'
+SchemaTest.configure do |config|
+  config.domain = 'mydomain.com'
+  config.definition_paths << Rails.root.join('test', 'schema_definitions')
+  config.compiled = true
+end
+SchemaTest.compile!
+```
+
+This will create a `compiled` directory inside your schema definitions directory containing one JSON file per definition. The compiled files mirror the layout of your original definition files, so a definition declared in `api/v3/film.rb` is compiled to `compiled/api/v3/film.json`:
+
+```
+test/schema_definitions/
+├── api/
+│   └── v3/
+│       ├── film.rb
+│       └── user.rb
+└── compiled/
+    └── api/
+        └── v3/
+            ├── film.json
+            ├── user.v1.json
+            └── user.v2.json
+```
+
+Versioned definitions are named `<name>.v<version>.json`; unversioned ones are simply `<name>.json`. Definitions without a known source location are written to the root of the `compiled` directory.
+
+Your test assertions stay the same — `assert_valid_json_for_schema` will load the pre-compiled JSON schema file and validate against it:
+
+``` ruby
+test 'JSON returned matches schema' do
+  json = JSON.parse(response.body)
+  assert_valid_json_for_schema(json, :user, version: 1)
+end
+```
+
+You can commit the compiled JSON files to your repository so that the schemas used in tests are visible in diffs, or add `compiled/` to your `.gitignore` and regenerate them as part of your test setup.
+
+#### Schema fingerprints
+
+In compiled mode the test files no longer contain the expanded schema, so a schema change wouldn't otherwise show up as a diff in the tests themselves. To keep that feedback, each assertion records a `fingerprint:` argument — a SHA-256 of the compiled schema:
+
+``` ruby
+test 'JSON returned matches schema' do
+  json = JSON.parse(response.body)
+  assert_valid_json_for_schema(json, :user, version: 1, fingerprint: '9f2c…')
+end
+```
+
+You don't write the fingerprint by hand. When you run the tests locally, the assertion compares the fingerprint argument against the compiled schema and, if it is missing or stale, rewrites it in place. The resulting diff points at exactly which API endpoints changed. In CI (when `ENV['CI']` is set) a mismatched or missing fingerprint fails the test instead of rewriting it, so out-of-date assertions can't be merged.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/schema_test/collapser.rb

@@ -0,0 +1,58 @@
+module SchemaTest
+  class Collapser
+    def initialize(contents)
+      @lines = contents.split("\n")
+    end
+
+    def output
+      result = []
+      i = 0
+      while i < @lines.length
+        line = @lines[i]
+
+        # Skip rubocop:disable line immediately before an EXPANDED block
+        if line.match?(/#{DISABLE_RUBOCOP_COMMENT}/) &&
+            i + 1 < @lines.length && @lines[i + 1].match?(/#{OPENING_COMMENT}/)
+          i += 1
+          next
+        end
+
+        if line =~ /\A(\s*)(\w+)\(\s*#{OPENING_COMMENT}/
+          indent = $1
+          method_name = $2
+
+          # Next line is the json variable
+          json_var = @lines[i + 1].strip.sub(/,\z/, '')
+
+          # Gather remaining content lines until closing marker
+          content_lines = []
+          j = i + 2
+          while j < @lines.length && !@lines[j].match?(/#{CLOSING_COMMENT}/)
+            content_lines << @lines[j]
+            j += 1
+          end
+          end_index = j
+
+          # Extract name and version from the content
+          joined = content_lines.map(&:strip).join(' ')
+          name = joined.match(/:(\w+),/)[1]
+          version_match = joined.match(/:version\s*=>\s*([^,}]+)/)
+          version = version_match[1].strip
+
+          result << "#{indent}#{method_name}(#{json_var}, :#{name}, version: #{version})"
+
+          # Skip rubocop:enable line immediately after END EXPANDED
+          i = end_index + 1
+          if i < @lines.length && @lines[i].match?(/#{ENABLE_RUBOCOP_COMMENT}/)
+            i += 1
+          end
+        else
+          result << line
+          i += 1
+        end
+      end
+
+      result.join("\n") + "\n"
+    end
+  end
+end

data/lib/schema_test/collection.rb

@@ -2,9 +2,12 @@ require 'schema_test/property'
 
 module SchemaTest
   class Collection < SchemaTest::Property::Object
-    def initialize(name, of_name, version: nil, description: nil)
+    attr_reader :location
+
+    def initialize(name, of_name, location: nil, version: nil, description: nil)
       super(name, version: version, description: description)
       @item_type = lookup_object(of_name, version)
+      @location = location
       SchemaTest::Definition.register(self)
     end
 

data/lib/schema_test/configuration.rb

@@ -9,9 +9,19 @@ module SchemaTest
     # files in as many subdirectories are you like.
     attr_accessor :definition_paths
 
+    # Set to true in order to disable running rubocop on the expanded schemas,
+    # as the Ruby PP output does not conform to rubocop's standards.
+    attr_accessor :disable_rubocop
+
+    # Set to true to use pre-compiled JSON schema files for validation
+    # instead of inlining expanded schemas into test files.
+    attr_accessor :compiled
+
     def initialize
       @domain = 'example.com'
       @definition_paths = []
+      @disable_rubocop = false
+      @compiled = false
     end
   end
 end

data/lib/schema_test/definition.rb

@@ -16,28 +16,22 @@ module SchemaTest
       (@definitions || {}).dig(name, version)
     end
 
+    def self.all
+      (@definitions || {}).values.flat_map(&:values)
+    end
+
     def self.find!(name, version)
       found = find(name, version)
-      raise "Could not find schema for #{name.inspect} (version: #{version.inspect})" unless found
+      raise SchemaTest::Error, "Could not find schema for #{name.inspect} (version: #{version.inspect})" unless found
       found
     end
 
-    def initialize(*args)
-      super
-      self.class.register(self)
-    end
-
-    def type(name, version=nil)
-      lookup_object(name, version || @version)
-    end
+    attr_reader :location
 
-    def optional(object)
-      object.optional!
-    end
-
-    def as_structure(_=nil)
-      hashes, others = @properties.values.map(&:as_structure).partition { |x| x.is_a?(Hash) }
-      others + [hashes.inject(&:merge)].compact
+    def initialize(name, location: nil, **attributes)
+      super(name, **attributes)
+      self.class.register(self)
+      @location = location
     end
 
     def as_json_schema(domain: SchemaTest.configuration.domain)
@@ -48,12 +42,5 @@ module SchemaTest
         'title' => name.to_s
       }.merge(super(false))
     end
-
-    def based_on(name, version: self.version)
-      other_version = self.class.find(name, version)
-      other_version.properties.values.each do |property|
-        define_property(property.dup)
-      end
-    end
   end
 end

data/lib/schema_test/fingerprint_rewriter.rb

@@ -0,0 +1,93 @@
+module SchemaTest
+  # Rewrites `assert_valid_json_for_schema` calls in test files so that
+  # they carry an up-to-date `fingerprint:` argument matching the
+  # compiled schema. This means a schema change shows up as a diff in
+  # the test files themselves, pointing at exactly which API endpoints
+  # changed, and lets the assertion verify the fingerprint at runtime.
+  #
+  # The call site reported at runtime is the line the call *starts* on,
+  # which for a multi-line call is the line with the opening paren. The
+  # rewriter therefore scans forward to find the matching closing paren
+  # before inserting or replacing the argument.
+  class FingerprintRewriter
+    FINGERPRINT_ARGUMENT = /fingerprint:\s*("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|[^\s,)]+)/
+
+    def initialize(contents, line_indexes_with_fingerprints)
+      @lines = contents.split("\n")
+      @line_indexes_with_fingerprints = line_indexes_with_fingerprints
+    end
+
+    def output
+      @line_indexes_with_fingerprints.each do |start_index, fingerprint|
+        next unless @lines[start_index]
+        annotate_call(start_index, fingerprint)
+      end
+      @lines.join("\n") + "\n"
+    end
+
+    private
+
+    def annotate_call(start_index, fingerprint)
+      close = find_closing_paren(start_index)
+      return unless close
+      end_index, paren_column = close
+
+      # If the call already carries a fingerprint argument, replace it.
+      (start_index..end_index).each do |index|
+        if @lines[index] =~ FINGERPRINT_ARGUMENT
+          @lines[index] = @lines[index].sub(FINGERPRINT_ARGUMENT, "fingerprint: '#{fingerprint}'")
+          return
+        end
+      end
+
+      argument = "fingerprint: '#{fingerprint}'"
+      close_line = @lines[end_index]
+      before_paren = close_line[0...paren_column]
+
+      if before_paren.strip.empty?
+        # The closing paren is on its own line; append the argument to the
+        # last argument line so we don't leave a leading comma dangling.
+        insert_index = (start_index...end_index).to_a.reverse.find { |index| !@lines[index].strip.empty? } || start_index
+        @lines[insert_index] = "#{@lines[insert_index].sub(/,\s*\z/, '')}, #{argument}"
+      else
+        @lines[end_index] = "#{before_paren.sub(/,\s*\z/, '')}, #{argument}#{close_line[paren_column..-1]}"
+      end
+    end
+
+    # Finds the closing paren matching the first opening paren at or after
+    # the start line, returning [line_index, column] or nil. Skips parens
+    # inside string literals and trailing comments.
+    def find_closing_paren(start_index)
+      depth = 0
+      started = false
+      (start_index...@lines.length).each do |line_index|
+        line = @lines[line_index]
+        string_delimiter = nil
+        column = 0
+        while column < line.length
+          char = line[column]
+          if string_delimiter
+            if char == '\\'
+              column += 2
+              next
+            elsif char == string_delimiter
+              string_delimiter = nil
+            end
+          elsif char == '"' || char == "'"
+            string_delimiter = char
+          elsif char == '#'
+            break
+          elsif char == '('
+            depth += 1
+            started = true
+          elsif char == ')'
+            depth -= 1
+            return [line_index, column] if started && depth.zero?
+          end
+          column += 1
+        end
+      end
+      nil
+    end
+  end
+end

data/lib/schema_test/minitest.rb

@@ -2,23 +2,41 @@ require 'schema_test'
 
 module SchemaTest
   module Minitest
-    def assert_valid_json_for_schema(json, name, version:, schema: nil)
-      install_assert_api_expansion_hook
+    def assert_valid_json_for_schema(json, name, arguments)
+      version = arguments[:version]
 
-      definition = SchemaTest::Definition.find(name, version)
-      raise "Unknown definition #{name}, version: #{version}" unless definition.present?
+      if SchemaTest.configuration.compiled
+        schema = SchemaTest.load_compiled_schema(name, version: version)
+        actual_fingerprint = SchemaTest.schema_fingerprint(schema)
 
-      expected_schema = definition.as_json_schema
+        if arguments[:fingerprint] != actual_fingerprint
+          if ENV['CI']
+            flunk "Schema fingerprint mismatch for #{name.inspect} (version: #{version.inspect}) at #{caller[0]}. The compiled schema has changed; run the tests locally to update the fingerprint."
+          else
+            install_fingerprint_rewrite_hook
+            queue_write_schema_fingerprint(caller[0], actual_fingerprint)
+          end
+        end
+
+        assert_json_schema_validates_against(json, schema)
+      else
+        install_assert_api_expansion_hook
+
+        schema = arguments[:schema]
+
+        definition = SchemaTest::Definition.find(name, version)
+        raise "Unknown definition #{name}, version: #{version}" unless definition.present?
+
+        expected_schema = definition.as_json_schema
 
-      if schema != expected_schema
-        if ENV['CI']
+        if schema != expected_schema && ENV['CI']
           flunk "Outdated API schema assertion at #{caller[0]}"
-        else
-          queue_write_expanded_assert_api_call(caller[0], __method__, name, version, expected_schema)
         end
-      end
 
-      assert_json_schema_validates_against(json, expected_schema)
+        queue_write_expanded_assert_api_call(caller[0], __method__, name, version, definition.location, expected_schema)
+
+        assert_json_schema_validates_against(json, expected_schema)
+      end
     end
 
     def assert_json_schema_validates_against(json, schema)
@@ -31,12 +49,17 @@ module SchemaTest
     @@__api_schema_calls_for_expansion = {}
     @@__api_schema_expansion_hook_installed = false
 
-    def queue_write_expanded_assert_api_call(call_site, method, name, version, expected_schema)
+    def queue_write_expanded_assert_api_call(call_site, method, name, version, location, expected_schema)
       file, line = call_site.split(':')
       line_index = line.to_i.pred
+      schema_call = [line_index, method, name, version, location, expected_schema]
 
       @@__api_schema_calls_for_expansion[file] ||= []
-      @@__api_schema_calls_for_expansion[file] << [line_index, method, name, version, expected_schema]
+      if (existing_call = @@__api_schema_calls_for_expansion[file].find { |call| line_index == call[0] })
+        return if existing_call == schema_call
+        raise "Expected schema does not match for duplicate API schema assertion at #{call_site}"
+      end
+      @@__api_schema_calls_for_expansion[file] << [line_index, method, name, version, location, expected_schema]
     end
 
     def install_assert_api_expansion_hook
@@ -48,11 +71,36 @@ module SchemaTest
     def expand_assert_api_calls
      @@__api_schema_calls_for_expansion.each do |file, line_indexes_with_schemas|
        original_contents = File.read(file)
-       rewriter = SchemaTest::Rewriter.new(original_contents, line_indexes_with_schemas)
+       rewriter_options = { disable_rubocop: SchemaTest.configuration.disable_rubocop }
+       rewriter = SchemaTest::Rewriter.new(original_contents, line_indexes_with_schemas, options: rewriter_options)
        new_contents = rewriter.output
        raise "Error rewriting file" if new_contents.blank?
        File.open(file, 'w') { |f| f.puts new_contents }
      end
     end
+
+    @@__schema_fingerprints = {}
+    @@__schema_fingerprint_hook_installed = false
+
+    def queue_write_schema_fingerprint(call_site, fingerprint)
+      file, line = call_site.split(':')
+      line_index = line.to_i.pred
+      @@__schema_fingerprints[file] ||= {}
+      @@__schema_fingerprints[file][line_index] = fingerprint
+    end
+
+    def install_fingerprint_rewrite_hook
+      return if @@__schema_fingerprint_hook_installed
+      at_exit { write_schema_fingerprints }
+      @@__schema_fingerprint_hook_installed = true
+    end
+
+    def write_schema_fingerprints
+      @@__schema_fingerprints.each do |file, line_indexes_with_fingerprints|
+        original_contents = File.read(file)
+        rewriter = SchemaTest::FingerprintRewriter.new(original_contents, line_indexes_with_fingerprints)
+        File.open(file, 'w') { |f| f.print rewriter.output }
+      end
+    end
   end
 end

data/lib/schema_test/property.rb

@@ -1,20 +1,15 @@
 module SchemaTest
   class Property
-    attr_reader :name, :type, :description, :optional
+    NULL_TYPE = 'null'.freeze
+
+    attr_reader :name, :_type, :description
 
     def initialize(name, type, description=nil)
       @name = name
-      @type = type
+      @_type = type
       @description = description
       @optional = false
-    end
-
-    def as_structure(_=nil)
-      if @optional
-        { name => nil }
-      else
-        name
-      end
+      @nullable = false
     end
 
     def as_json_schema
@@ -25,28 +20,69 @@ module SchemaTest
     end
 
     def ==(other)
+      return false unless other.is_a?(SchemaTest::Property)
+
       name == other.name &&
-        type == other.type &&
+        _type == other._type &&
         description == other.description &&
-        optional == other.optional
+        optional? == other.optional? &&
+        nullable? == other.nullable?
+    end
+
+    def optional(object)
+      object.tap(&:optional!)
+    end
+
+    def nullable(object)
+      object.tap(&:nullable!)
     end
 
     def optional?
-      optional
+      @optional
     end
 
     def optional!
       @optional = true
     end
 
+    def nullable?
+      @nullable
+    end
+
+    def nullable!
+      @nullable = true
+    end
+
+    def lookup_object(name, *versions)
+      UnresolvedProperty.new(name, versions: versions)
+    end
+
+    def type(name, version: nil)
+      lookup_object(name, version || @version)
+    end
+
+    def base_json_schema_type
+      @_type.to_s
+    end
+
     def json_schema_type
-      @type.to_s
+      if nullable?
+        [base_json_schema_type, NULL_TYPE]
+      else
+        base_json_schema_type
+      end
     end
 
     def json_schema_format
       nil
     end
 
+    class Nil < SchemaTest::Property
+      def initialize(name, description=nil)
+        super(name, :null, description)
+      end
+    end
+
     class Boolean < SchemaTest::Property
       def initialize(name, description=nil)
         super(name, :boolean, description)
@@ -64,7 +100,7 @@ module SchemaTest
         super(name, :float, description)
       end
 
-      def json_schema_type
+      def base_json_schema_type
         'number'
       end
     end
@@ -75,12 +111,26 @@ module SchemaTest
       end
     end
 
+    class Date < SchemaTest::Property
+      def initialize(name, description=nil)
+        super(name, :date, description)
+      end
+
+      def base_json_schema_type
+        'string'
+      end
+
+      def json_schema_format
+        'date'
+      end
+    end
+
     class DateTime < SchemaTest::Property
       def initialize(name, description=nil)
         super(name, :datetime, description)
       end
 
-      def json_schema_type
+      def base_json_schema_type
         'string'
       end
 
@@ -96,30 +146,37 @@ module SchemaTest
     end
 
     class SchemaTest::Property::Object < SchemaTest::Property
-      attr_reader :version
+      attr_reader :version, :excluded_property_names
 
-      def initialize(name, description: nil, version: nil, from: nil, properties: nil, &block)
-        @name = name
-        @description = description
+      def initialize(name, description: nil, version: nil, from: nil, properties: nil, except: [], &block)
+        super(name, :object, description)
         @version = version
         @specific_properties = properties
         @properties = {}
+        @excluded_property_names = except
         @from = from
         instance_eval(&block) if block_given?
       end
 
       def properties
         resolve
-        @properties
+        @properties.reject { |p| excluded_property_names.include?(p) }
+      end
+
+      def based_on(name, version: self.version, except: [])
+        @from = lookup_object(name, version)
+        @excluded_property_names = except
       end
 
       def ==(other)
-        super && properties.all? { |name, property| property == other.properties[name] }
+        super &&
+          properties.all? { |name, property| property == other.properties[name] } &&
+          excluded_property_names == other.excluded_property_names
       end
 
       def resolve
         if @from
-          @properties.merge!(@from.properties)
+          @properties = @from.properties.merge(@properties)
           @from = nil
         end
         if @specific_properties
@@ -146,8 +203,10 @@ module SchemaTest
         float: SchemaTest::Property::Float,
         string: SchemaTest::Property::String,
         datetime: SchemaTest::Property::DateTime,
+        date: SchemaTest::Property::Date,
         url: SchemaTest::Property::Uri,
-        html: SchemaTest::Property::String
+        html: SchemaTest::Property::String,
+        null: SchemaTest::Property::Nil
       }
 
       TYPES.each do |method_name, type_class|
@@ -160,12 +219,20 @@ module SchemaTest
         define_property(SchemaTest::Property::Array.new(name, of, desc, &block))
       end
 
-      def object(name, desc: nil, as: name, version: nil, &block)
+      def object(name, desc: nil, as: name, version: nil, except: [], &block)
         inferred_version = version || @version
         if block_given?
           define_property(SchemaTest::Property::Object.new(as, description: desc, version: inferred_version, &block))
         else
-          define_property(SchemaTest::Property::Object.new(as, description: desc, version: inferred_version, from: lookup_object(name, inferred_version)))
+          define_property(
+            SchemaTest::Property::Object.new(
+              as,
+              description: desc,
+              version: inferred_version,
+              from: lookup_object(name, inferred_version, nil),
+              except: except
+            )
+          )
         end
       end
 
@@ -185,15 +252,7 @@ module SchemaTest
         end
       end
 
-      def as_structure(include_root=true)
-        if include_root
-          { name => properties.values.map(&:as_structure) }
-        else
-          properties.values.map(&:as_structure)
-        end
-      end
-
-      def json_schema_type
+      def base_json_schema_type
         'object'
       end
 
@@ -202,15 +261,20 @@ module SchemaTest
       def define_property(attribute)
         @properties[attribute.name] = attribute
       end
-
-      def lookup_object(name, version)
-        UnresolvedProperty.new(name, version: version)
-      end
     end
 
     class UnresolvedProperty < SchemaTest::Property::Object
+      def initialize(name, versions:)
+        @name = name
+        @versions = versions
+      end
+
       def resolve
-        SchemaTest::Definition.find!(name, version)
+        @versions.each do |v|
+          definition = SchemaTest::Definition.find(@name, v)
+          return definition if definition
+        end
+        raise SchemaTest::Error, "could not resolve schema #{@name.inspect}; tried versions: #{@versions.inspect}"
       end
 
       def ==(other)
@@ -220,20 +284,12 @@ module SchemaTest
       def properties
         resolve.properties
       end
-
-      def as_structure(*args)
-        resolve.as_structure(*args)
-      end
     end
 
     class AnonymousObject < SchemaTest::Property::Object
       def initialize(properties: nil, &block)
         super(nil, properties: properties, &block)
       end
-
-      def as_structure(_=nil)
-        super(false)
-      end
     end
 
     class Array < SchemaTest::Property
@@ -253,14 +309,6 @@ module SchemaTest
         super && @item_type == other.item_type
       end
 
-      def as_structure(_=nil)
-        if @item_type.is_a?(SchemaTest::Property)
-          { name => @item_type.as_structure(false) }
-        else
-          { name => [] }
-        end
-      end
-
       def as_json_schema
         super.tap do |json_schema|
           item_schema = @item_type.is_a?(SchemaTest::Property) ? @item_type.as_json_schema(false) : { 'type' => @item_type.to_s }

data/lib/schema_test/rewriter.rb

@@ -4,23 +4,37 @@ module SchemaTest
   OPENING_COMMENT = '# EXPANDED'.freeze
   CLOSING_COMMENT = '# END EXPANDED'.freeze
 
+  DISABLE_RUBOCOP_COMMENT = '# rubocop:disable all'.freeze
+  ENABLE_RUBOCOP_COMMENT = '# rubocop:enable all'.freeze
+
   class Rewriter
-    def initialize(contents, line_indexes_with_schemas)
+    def initialize(contents, line_indexes_with_schemas, options: {})
       @lines = contents.split("\n")
       @line_indexes_with_schemas = line_indexes_with_schemas
+
+      @disable_rubocop = options.fetch(:disable_rubocop, false)
     end
 
     def output
       current_offset = 0
-      line_indexes_with_schemas.sort_by { |(line,_)| line }.each do |index, method, name, version, expected_schema|
+      line_indexes_with_schemas.sort_by { |(line,_)| line }.each do |index, method, name, version, location, expected_schema|
         start_index = index + current_offset
-        if lines[start_index] =~ /#{OPENING_COMMENT}\s*\z/
+        if lines[start_index - 1].match?(/#{DISABLE_RUBOCOP_COMMENT}/)
+          lines.delete_at(start_index - 1)
+          start_index -= 1
+          current_offset -= 2
+        end
+
+        if lines[start_index] =~ /#{OPENING_COMMENT}/
           end_index = start_index + lines[start_index..-1].find_index { |line| line =~ /#{CLOSING_COMMENT}\s*\z/ }
+          lines.delete_at(end_index + 1) if lines[end_index + 1]&.match?(/#{ENABLE_RUBOCOP_COMMENT}/)
           json_variable_name = lines[start_index + 1].strip.gsub(/,\z/, '')
         else
           end_index = start_index
           json_variable_name = lines[start_index].match(/\(([^,]+)/)[1]
         end
+
+        original_method_definition_length = end_index - start_index
         start_indent = lines[start_index].match(/\A(\s*)/)[0].length
         (end_index - start_index + 1).times { |i| lines.delete_at(start_index) }
 
@@ -31,14 +45,16 @@ module SchemaTest
         expanded_schema_lines.unshift(json_variable_name + ',')
 
         method_string = [
-          (' ' * start_indent) + method.to_s + "( #{OPENING_COMMENT}",
+          disable_rubocop ? (' ' * start_indent) + DISABLE_RUBOCOP_COMMENT : nil,
+          (' ' * start_indent) + method.to_s + "( #{OPENING_COMMENT} from #{location}",
           *expanded_schema_lines.map { |line| (' ' * (start_indent + 2)) + line },
-          (' ' * start_indent) + ") #{CLOSING_COMMENT}"
-        ]
+          (' ' * start_indent) + ") #{CLOSING_COMMENT}",
+          disable_rubocop ? (' ' * start_indent) + ENABLE_RUBOCOP_COMMENT: nil,
+        ].compact
 
         method_string.reverse.each { |line| lines.insert(start_index, line) }
 
-        current_offset += method_string.count - 1
+        current_offset += method_string.count - original_method_definition_length - 1
       end
 
       lines.compact.join("\n") + "\n"
@@ -47,5 +63,6 @@ module SchemaTest
     private
 
     attr_reader :lines, :line_indexes_with_schemas
+    attr_reader :disable_rubocop
   end
 end

data/lib/schema_test/validator.rb

@@ -40,9 +40,13 @@ module SchemaTest
                   when 'format'
                     "format should be #{error['schema']['format']}"
                   when 'required'
-                    "missing some required attributes"
+                    "missing some required attributes: #{error['details'].inspect}"
                   else
-                    "type should be #{error['type']}"
+                    if error['type'] == 'type'
+                      "type should be one of #{error['schema']['type'].inspect}"
+                    else
+                      "type should be #{error['type']}"
+                    end
                   end
         "value at #{error['data_pointer']} (#{error['data'].inspect}) failed validation: #{message}"
       end

data/lib/schema_test/version.rb

@@ -1,3 +1,3 @@
 module SchemaTest
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/schema_test.rb

@@ -1,5 +1,9 @@
+require 'json'
+require 'digest'
 require 'schema_test/version'
 require 'schema_test/rewriter'
+require 'schema_test/fingerprint_rewriter'
+require 'schema_test/collapser'
 require 'schema_test/definition'
 require 'schema_test/collection'
 require 'schema_test/validator'
@@ -10,6 +14,13 @@ module SchemaTest
 
   SCHEMA_VERSION = "http://json-schema.org/draft-07/schema#"
 
+  # The number of leading hex characters of the schema digest kept as a
+  # fingerprint. The fingerprint only needs to change when the schema
+  # changes (it is compared against a single expected value, never
+  # searched for collisions), so a short prefix keeps the assertion lines
+  # readable while remaining collision-free in practice.
+  FINGERPRINT_LENGTH = 12
+
   class << self
     def reset!
       @configuration = nil
@@ -33,7 +44,7 @@ module SchemaTest
 
     # Define a new schema
     def define(name, collection: nil, **attributes, &block)
-      definition = SchemaTest::Definition.new(name, attributes, &block)
+      definition = SchemaTest::Definition.new(name, location: definition_location(caller[0]), **attributes, &block)
       if collection
         collection(collection, of: name, version: attributes[:version])
       end
@@ -43,7 +54,67 @@ module SchemaTest
     # Explicitly define a new schema collection (an array of other schema
     # objects)
     def collection(name, of:, **attributes)
-      SchemaTest::Collection.new(name, of, attributes)
+      SchemaTest::Collection.new(name, of, location: definition_location(caller[1]), **attributes)
+    end
+
+    # Compile all definitions to JSON Schema files in a `compiled`
+    # directory within each definition path. The compiled files mirror
+    # the layout of the original definition files, so a definition
+    # declared in `api/v3/film.rb` is written to
+    # `compiled/api/v3/film.json`.
+    def compile!
+      load_definitions
+      SchemaTest::Definition.all.each do |definition|
+        begin
+          definition_path = owning_definition_path(definition)
+          next unless definition_path
+          path = Pathname.new(definition_path).join('compiled', compiled_relative_path(definition))
+          path.dirname.mkpath
+          File.write(path, JSON.pretty_generate(definition.as_json_schema) + "\n")
+        rescue => e
+          warn "SchemaTest: failed to compile #{definition.name} (version: #{definition.version}): #{e.message}"
+        end
+      end
+    end
+
+    # Load a pre-compiled JSON schema from the compiled directory.
+    # Because compiled files mirror the original definition layout, the
+    # file may live in a nested subdirectory, so the compiled tree is
+    # searched recursively for the expected filename.
+    def load_compiled_schema(name, version: nil)
+      filename = compiled_filename(name, version)
+      configuration.definition_paths.each do |definition_path|
+        compiled_root = Pathname.new(definition_path).join('compiled')
+        match = Pathname.glob(compiled_root.join('**', filename)).first
+        return JSON.parse(match.read) if match
+      end
+      raise SchemaTest::Error, "Could not find compiled schema for #{name.inspect} (version: #{version.inspect})"
+    end
+
+    # A stable fingerprint of a compiled schema. The fingerprint is
+    # derived from the schema's semantic content, so it changes whenever
+    # the schema changes but is unaffected by pretty-print formatting.
+    def schema_fingerprint(schema)
+      Digest::SHA256.hexdigest(JSON.generate(schema))[0, FINGERPRINT_LENGTH]
+    end
+
+    # Collapse expanded schema assertions in test files back to
+    # simple one-line calls. Pass file paths or directory paths.
+    # Directories are globbed for **/*.rb files.
+    def collapse!(*paths)
+      files = paths.flat_map do |path|
+        if File.directory?(path)
+          Dir[File.join(path, '**', '*.rb')]
+        else
+          [path]
+        end
+      end
+      files.each do |file|
+        contents = File.read(file)
+        next unless contents.include?(OPENING_COMMENT)
+        collapser = SchemaTest::Collapser.new(contents)
+        File.write(file, collapser.output)
+      end
     end
 
     # Validate some JSON data against a schema or schema definition
@@ -58,9 +129,69 @@ module SchemaTest
 
     private
 
+    # The filename a definition compiles to, e.g. `film.json` or
+    # `film.v2.json` for versioned definitions.
+    def compiled_filename(name, version)
+      if version
+        "#{name}.v#{version}.json"
+      else
+        "#{name}.json"
+      end
+    end
+
+    # The relative source file a definition was declared in (without the
+    # trailing line number), or nil if it has no known location.
+    def definition_source_file(definition)
+      return nil unless definition.location
+      source = definition.location.rpartition(':').first
+      source = definition.location if source.empty?
+      source.empty? ? nil : source
+    end
+
+    # The definition path a definition's source file lives under, so
+    # that each schema is compiled exactly once into the `compiled`
+    # directory of its owning path rather than duplicated into every
+    # definition path. Definitions whose source cannot be located (for
+    # example, those constructed directly without a location) fall back
+    # to the first configured definition path.
+    def owning_definition_path(definition)
+      source = definition_source_file(definition)
+      if source
+        owning = configuration.definition_paths.find do |definition_path|
+          Pathname.new(definition_path).join(source).exist?
+        end
+        return owning if owning
+      end
+      configuration.definition_paths.first
+    end
+
+    # The path a definition compiles to, relative to the `compiled`
+    # directory. The directory mirrors the location of the source
+    # definition file (e.g. `api/v3/film.rb` -> `api/v3/film.json`).
+    # Definitions without a known location are written to the root of
+    # the compiled directory.
+    def compiled_relative_path(definition)
+      filename = compiled_filename(definition.name, definition.version)
+      source = definition_source_file(definition)
+      return Pathname.new(filename) unless source
+      Pathname.new(source).dirname.join(filename)
+    end
+
+    def definition_location(caller_line)
+      path, line = caller_line.split(':').take(2)
+      configuration.definition_paths.each do |definition_path|
+        if path.start_with?(definition_path.to_s)
+          path = Pathname.new(path).relative_path_from(definition_path)
+          break
+        end
+      end
+      [path, line].join(':')
+    end
+
     def load_definitions
-      globbed_paths = configuration.definition_paths.map { |path| path.join('**', '*.rb') }
-      Dir[globbed_paths.join(',')].each do |schema_file|
+      configuration.definition_paths.map! { |p| Pathname.new(p) }
+      globbed_paths = configuration.definition_paths.map { |path| path.join('**', '*.rb').to_s }
+      Dir[*globbed_paths].each do |schema_file|
         require schema_file
       end
     end

data/schema-test.gemspec

@@ -39,7 +39,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'json_schemer'
 
   spec.add_development_dependency "bundler", "~> 2"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "byebug"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: schema-test
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - James Adam
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-09-01 00:00:00.000000000 Z
+date: 2026-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -101,6 +101,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/dependabot.yml"
 - ".github/workflows/tests.yml"
 - ".gitignore"
 - ".rspec"
@@ -113,13 +114,14 @@ files:
 - bin/console
 - bin/setup
 - lib/schema_test.rb
+- lib/schema_test/collapser.rb
 - lib/schema_test/collection.rb
 - lib/schema_test/configuration.rb
 - lib/schema_test/definition.rb
+- lib/schema_test/fingerprint_rewriter.rb
 - lib/schema_test/minitest.rb
 - lib/schema_test/property.rb
 - lib/schema_test/rewriter.rb
-- lib/schema_test/test_helper.rb
 - lib/schema_test/validator.rb
 - lib/schema_test/version.rb
 - schema-test.gemspec
@@ -146,7 +148,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: API testing against declarative schemas

data/lib/schema_test/test_helper.rb

@@ -1,59 +0,0 @@
-module SchemaTest
-  class TestHelper
-    def assert_api_schema(name, version:, structure: nil)
-      install_asset_api_expansion_hook
-
-      definition = ApiSchema::Definition.find(name, version)
-      raise "Unknown definition #{name}, version: #{version}" unless definition.present?
-
-      expected_structure = definition.as_structure
-
-      if structure != expected_structure
-        if ENV['CI']
-          flunk "Outdated API schema assertion at #{caller[0]}"
-        else
-          queue_write_expanded_assert_api_call(caller[0], __method__, name, version, expected_structure)
-        end
-      end
-
-      assert_json_response_structure(*expected_structure)
-    end
-
-    private
-
-    @@__api_schema_calls_for_expansion = {}
-    @@__api_schema_expansion_hook_installed = false
-
-    def queue_write_expanded_assert_api_call(call_site, method, name, version, expected_structure)
-      file, line = call_site.split(':')
-      line_index = line.to_i.pred
-
-      @@__api_schema_calls_for_expansion[file] ||= []
-      @@__api_schema_calls_for_expansion[file] << [line_index, method, name, version, expected_structure]
-    end
-
-    def install_asset_api_expansion_hook
-      return if @@__api_schema_expansion_hook_installed
-      at_exit { expand_assert_api_calls }
-      @@__api_schema_expansion_hook_installed = true
-    end
-
-    def expand_assert_api_calls
-      @@__api_schema_calls_for_expansion.each do |file, line_indexes_with_structures|
-        rewriter = SchemaTest::Rewriter.new(File.read(file), line_indexes_with_structures)
-        File.open(file, 'w') { f.puts rewriter.output }
-      end
-    end
-  end
-end
-
-if const_defined?(Rails)
-  ActionController::TestCase.send(:include, SchemaTest::TestHelper)
-  ActionDispatch::IntegrationTest.send(:include, SchemaTest::TestHelper)
-
-  SchemaTest.definition_paths << Rails.root.join('test', 'schema_definitions', '**', '*.rb')
-  SchemaTest.definition_paths << Rails.root.join('spec', 'schema_definitions', '**', '*.rb')
-
-  SchemaTest.load_definitions
-end
-