govuk-content-schema-test-helpers 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2e5b0d8aa1f1b503bcaae77e1ff8cab0be160d7e
-  data.tar.gz: 38e3efdeb49fc8d9c281ad083031de80a965603b
+  metadata.gz: 906bc8e45e2ba472d55fff389747c51b6fcd0681
+  data.tar.gz: a025e7bcb2d6a365dfd44326e0dfca7146f4d464
 SHA512:
-  metadata.gz: b72867225ec2fb2ed2287abc1023639e22f372048a29699f7f073f9ece7c719850a8faee006a09d0f581438da0e27c34a526d0a5aa65fd3ffe7ca2831cc008e6
-  data.tar.gz: f859e915528ba45b48c22fd2dabf2d78260ba09a18a498b102bacf89cefe13d31cefae5bcf42335c608dd90bf25775518280125ef76d27d2e1a59b443e907457
+  metadata.gz: 3b6b22ea8e2bfe16f49d993fa61469fc850e10f4fe1544003dcde64a35b455d8033d81766f9ff67342bd14ac49801a816411dc5d7ccbfd1ff6b958dfef3415e1
+  data.tar.gz: 8ea79a0196fa515f97abd91ffebe086df58d1823481c3ece47818da1317583295503c986ddc51e90cc4be326265a30198d171a53e025223d46faa1f83d5c58e0

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Crown Copyright (Government Digital Service)
+
+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,106 @@
+# govuk-content-schema-test-helpers
+
+This app provides test helpers for working with [alphagov/govuk-content-schemas](https://github.com/alphagov/govuk-content-schemas). This consists of two things:
+
+* code for validating a JSON document against a JSON schema in govuk-content-schemas
+* code for fetching example JSON documents from govuk-content-schemas
+
+
+## Technical documentation
+
+### Dependencies
+
+- [alphagov/govuk-content-schemas](https://github.com/alphagov/govuk-content-schemas) - contains the examples and schemas returned by this gem
+
+### Usage
+
+#### Configuration and setup
+
+Firstly, you will need a copy of [govuk-content-schemas](http://github.com/alphagov/govuk-content-schemas) on your file system. By default these should be in a sibling directory to your project. Alternatively, you can specify their location with the `GOVUK_CONTENT_SCHEMAS_PATH` environment variable. You should probably duplicate this paragraph (excluding this sentence) in your own `README`.
+
+You will need to configure which type of schemas your app uses. A good place to do this is in `test_helper.rb` or `spec_helper.rb`:
+
+```ruby
+  require 'govuk-content-schema-test-helpers'
+
+  GovukContentSchemaTestHelpers.configure do |config|
+    config.schema_type = 'frontend' # or 'publisher'
+    config.project_root = Rails.root
+  end
+```
+
+If you are not using Rails, you'll need to set `project_root` differently. Assuming the file you are adding this to is one directory down from your project root:
+```ruby
+  config.project_root = File.absolute_path(File.join(File.basename(__FILE__), '..'))
+```
+
+#### Loading an example document
+
+```ruby
+  GovukContentSchemaTestHelpers::Examples.new.get('finder', 'contacts')
+  # => '{ "some": "json" }'
+```
+
+#### RSpec matcher
+
+To use the built-in RSpec matcher, add this to spec_helper.rb:
+
+```ruby
+  require 'govuk-content-schema-test-helpers/rspec_matchers'
+  include GovukContentSchemaTestHelpers::RSpecMatchers
+```
+
+Then:
+```
+  expect(presented).to be_valid_against_schema('finder')
+```
+
+or as an argument matcher:
+
+```ruby
+  expect(publishing_api).to receive(:put_content_item)
+        .with("/first-finder", be_valid_against_schema('finder'))
+```
+
+#### Test::Unit/Minitest
+
+Setup:
+
+```ruby
+  require 'govuk-content-schema-test-helpers/test_unit'
+  include GovukContentSchemaTestHelpers::TestUnit
+```
+
+Then in a test:
+```ruby
+  assert_valid_against_schema(presented_hash, 'case_study')
+```
+
+#### Validating against the schema manually
+
+```ruby
+  validator = GovukContentSchemaTestHelpers::Validator.new('finder', '{ "some": "json" }')
+  validator.valid?
+  # => false
+  validator.errors
+  # => ["The property '#/' did not contain a required property of 'base_path'", ...]
+```
+
+### Running the test suite
+
+The tests in this project rely upon [govuk-content-schemas](http://github.com/alphagov/govuk-content-schemas) on your file system. By default these should be in a sibling directory to your project. Alternatively, you can specify their location with the `GOVUK_CONTENT_SCHEMAS_PATH` environment variable.
+
+Assuming you already have govuk-content-schemas cloned:
+
+```
+  bundle exec rake
+```
+
+
+## Licence
+
+[MIT License](LICENCE)
+
+## Versioning policy
+
+This is versioned according to [Semantic Versioning 2.0](http://semver.org/).

data/lib/govuk-content-schema-test-helpers/configuration.rb

@@ -0,0 +1,27 @@
+module GovukContentSchemaTestHelpers
+  class ConfigurationError < StandardError; end
+
+  class Configuration
+    attr_writer :schema_type, :project_root
+
+    def schema_type
+      @schema_type || raise(ConfigurationError, 'GovukContentSchemaTestHelpers.configuration.schema_type must be set (and not nil)')
+    end
+
+    def project_root
+      @project_root || raise(ConfigurationError, 'GovukContentSchemaTestHelpers.configuration.project_root must be set (and not nil)')
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configuration=(config)
+    @configuration = config
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+end

data/lib/govuk-content-schema-test-helpers/examples.rb

@@ -0,0 +1,25 @@
+module GovukContentSchemaTestHelpers
+  class Examples
+    def initialize
+      Util.check_govuk_content_schemas_path!
+    end
+
+    def get(schema_name, example_name)
+      path = example_path(schema_name, example_name)
+      check_example_file_exists!(path)
+      File.read(path)
+    end
+
+    def check_example_file_exists!(path)
+      if !File.exists?(path)
+        raise ImproperlyConfiguredError, "Schema file not found: #{path}."
+      end
+    end
+
+  private
+    def example_path(schema_name, example_name)
+      schema_type = GovukContentSchemaTestHelpers.configuration.schema_type
+      File.join(Util.govuk_content_schemas_path, "/formats/#{schema_name}/#{schema_type}/examples/#{example_name}.json").to_s
+    end
+  end
+end

data/lib/govuk-content-schema-test-helpers/exceptions.rb

@@ -0,0 +1,3 @@
+module GovukContentSchemaTestHelpers
+  class ImproperlyConfiguredError < RuntimeError; end
+end

data/lib/govuk-content-schema-test-helpers/rspec_matchers.rb

@@ -0,0 +1,22 @@
+module GovukContentSchemaTestHelpers
+  module RSpecMatchers
+    RSpec::Matchers.define :be_valid_against_schema do |schema_name|
+      match do |actual|
+        validator = Validator.new(schema_name, actual)
+        validator.valid?
+      end
+
+      # Required for a helpful message with RSpec 3
+      description do |actual|
+        validator = Validator.new(schema_name, actual)
+        "to be valid against '#{schema_name}' schema. Errors: #{validator.errors}"
+      end
+
+      # Required for a helpful message with RSpec 2
+      failure_message_for_should do |actual|
+        validator = Validator.new(schema_name, actual)
+        "to be valid against '#{schema_name}' schema. Errors: #{validator.errors}"
+      end
+    end
+  end
+end

data/lib/govuk-content-schema-test-helpers/test_unit.rb

@@ -0,0 +1,8 @@
+module GovukContentSchemaTestHelpers
+  module TestUnit
+    def assert_valid_against_schema(content_item_hash, format)
+      validator = GovukContentSchemaTestHelpers::Validator.new(format, content_item_hash.to_json)
+      assert validator.valid?, "JSON not valid against #{format} schema: #{validator.errors.to_s}"
+    end
+  end
+end

data/lib/govuk-content-schema-test-helpers/util.rb

@@ -0,0 +1,17 @@
+module GovukContentSchemaTestHelpers
+  module Util
+    def self.govuk_content_schemas_path
+      relative_path = ENV['GOVUK_CONTENT_SCHEMAS_PATH'] || '../govuk-content-schemas'
+      project_root = GovukContentSchemaTestHelpers.configuration.project_root
+      File.absolute_path(relative_path, project_root)
+    end
+
+    def self.check_govuk_content_schemas_path!
+      if !File.exists?(Util.govuk_content_schemas_path)
+        message = "Dependency govuk-content-schemas cannot be found at: #{govuk_content_schemas_path}."
+        message += " Clone it to that directory, or set GOVUK_CONTENT_SCHEMAS_PATH (see README.md for details)."
+        raise ImproperlyConfiguredError, message
+      end
+    end
+  end
+end

data/lib/govuk-content-schema-test-helpers/validator.rb

@@ -0,0 +1,29 @@
+require 'json-schema'
+
+module GovukContentSchemaTestHelpers
+  class Validator
+    def self.schema_path(schema_name)
+      schema_type = GovukContentSchemaTestHelpers.configuration.schema_type
+      File.join(Util.govuk_content_schemas_path, "/formats/#{schema_name}/#{schema_type}/schema.json").to_s
+    end
+
+    # schema_name should be a string, such as 'finder'
+    # document should be a JSON string of the document to validate
+    def initialize(schema_name, document)
+      Util.check_govuk_content_schemas_path!
+      @schema_path = GovukContentSchemaTestHelpers::Validator.schema_path(schema_name)
+      if !File.exists?(@schema_path)
+        raise ImproperlyConfiguredError, "Schema file not found: #{@schema_path}."
+      end
+      @document = document
+    end
+
+    def valid?
+      errors.empty?
+    end
+
+    def errors
+      @errors ||= JSON::Validator.fully_validate(@schema_path, @document)
+    end
+  end
+end

data/lib/govuk-content-schema-test-helpers/version.rb

@@ -0,0 +1,3 @@
+module GovukContentSchemaTestHelpers
+  VERSION = '1.0.1'
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: govuk-content-schema-test-helpers
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Jamie Cobbett
@@ -75,7 +75,17 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
+- README.md
 - lib/govuk-content-schema-test-helpers.rb
+- lib/govuk-content-schema-test-helpers/configuration.rb
+- lib/govuk-content-schema-test-helpers/examples.rb
+- lib/govuk-content-schema-test-helpers/exceptions.rb
+- lib/govuk-content-schema-test-helpers/rspec_matchers.rb
+- lib/govuk-content-schema-test-helpers/test_unit.rb
+- lib/govuk-content-schema-test-helpers/util.rb
+- lib/govuk-content-schema-test-helpers/validator.rb
+- lib/govuk-content-schema-test-helpers/version.rb
 homepage: https://github.com/alphagov/govuk-content-schema-test-helpers
 licenses:
 - MIT