webspicy 0.1.0.pre.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b34d2485758616a81425a1f39fd0e5350fea1799
+  data.tar.gz: 8756493dea8e750857c172399dcebe2edcc2a76b
+SHA512:
+  metadata.gz: 5ee96045a18f309ca39859a8459cc2cf11b1dd02d3fbc9a45186f7f5ef45af46b5121f5626303e52eca886196b8baa0eb34c17e57702e5408514092a78c089de
+  data.tar.gz: 83db0b47519892d12acc7b73ff4bf2ec97642ffebb680d2f0535915c6f11321172656a0dee2ddd62c33317cd9045b0bb8104f28a997f9c7f92c2293fe39a009f

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/LICENSE.md

@@ -0,0 +1,22 @@
+# The MIT Licence
+
+    Copyright (c) 2017 - Enspirit SPRL (Bernard Lambeau)
+
+    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,7 @@
+# Webspicy
+
+A description, specification and test framework for black box web services seen as software operations.
+
+## Work in progress
+
+Please refer to the examples for now. More documentation coming soon.

data/Rakefile

@@ -0,0 +1,11 @@
+#
+# Install all tasks found in tasks folder
+#
+# See .rake files there for complete documentation.
+#
+Dir["tasks/*.rake"].each do |taskfile|
+  load taskfile
+end
+
+# We run tests by default
+task :default => :test

data/examples/restful/Gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gem "rake", "~> 10"
+gem 'sinatra', "~> 2.0"
+gem "webspicy", path: "../.."

data/examples/restful/Gemfile.lock

@@ -0,0 +1,69 @@
+PATH
+  remote: ../..
+  specs:
+    webspicy (0.0.1)
+      finitio (~> 0.5.2)
+      http (~> 0.5)
+      path (~> 1.3)
+      rspec (~> 3.6)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.5.1)
+      public_suffix (~> 2.0, >= 2.0.2)
+    citrus (3.0.2)
+    diff-lcs (1.3)
+    domain_name (0.5.20170404)
+      unf (>= 0.0.5, < 1.0.0)
+    finitio (0.5.2)
+      citrus (>= 2.4, < 4.0)
+    http (0.9.9)
+      addressable (~> 2.3)
+      http-cookie (~> 1.0)
+      http-form_data (~> 1.0.1)
+      http_parser.rb (~> 0.6.0)
+    http-cookie (1.0.3)
+      domain_name (~> 0.5)
+    http-form_data (1.0.3)
+    http_parser.rb (0.6.0)
+    mustermann (1.0.0)
+    path (1.3.3)
+    public_suffix (2.0.5)
+    rack (2.0.3)
+    rack-protection (2.0.0)
+      rack
+    rake (10.5.0)
+    rspec (3.6.0)
+      rspec-core (~> 3.6.0)
+      rspec-expectations (~> 3.6.0)
+      rspec-mocks (~> 3.6.0)
+    rspec-core (3.6.0)
+      rspec-support (~> 3.6.0)
+    rspec-expectations (3.6.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.6.0)
+    rspec-mocks (3.6.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.6.0)
+    rspec-support (3.6.0)
+    sinatra (2.0.0)
+      mustermann (~> 1.0)
+      rack (~> 2.0)
+      rack-protection (= 2.0.0)
+      tilt (~> 2.0)
+    tilt (2.0.7)
+    unf (0.1.4)
+      unf_ext
+    unf_ext (0.0.7.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake (~> 10)
+  sinatra (~> 2.0)
+  webspicy!
+
+BUNDLED WITH
+   1.14.6

data/examples/restful/Rakefile

@@ -0,0 +1,21 @@
+require 'webspicy'
+
+namespace :webspicy do
+
+  config = Webspicy::Configuration.new do |c|
+    c.host = "http://127.0.0.1:4567"
+    c.add_folder Path.dir/"webspicy"
+  end
+
+  task :check do
+    Webspicy::Checker.new(config).call
+  end
+
+  task :test do
+    Webspicy::Tester.new(config).call
+  end
+
+end
+
+task :test => :"webspicy:test"
+task :default => :test

data/examples/restful/app.rb

@@ -0,0 +1,32 @@
+require 'sinatra'
+require 'json'
+
+TODOLIST = [
+  {
+    id: 1,
+    description: "Refactor the framework"
+  },
+  {
+    id: 2,
+    description: "Write documentation"
+  }
+]
+
+disable :show_exceptions
+enable :raise_errors
+
+get '/todo/' do
+  content_type :json
+  TODOLIST.to_json
+end
+
+get '/todo/:id' do |id|
+  content_type :json
+  todo = TODOLIST.find{|todo| todo[:id] == Integer(id) }
+  if todo.nil?
+    status 404
+    {error: "No such todo"}.to_json
+  else
+    todo.to_json
+  end
+end

data/examples/restful/webspicy/schema.fio

@@ -0,0 +1,4 @@
+Todo = {
+  id          : Integer
+  description : String
+}

data/examples/restful/webspicy/todo/getTodo.yml

@@ -0,0 +1,52 @@
+---
+name: |-
+  Todo
+
+url: |-
+  /todo/{id}
+
+services:
+- method: |-
+    GET
+
+  description: |-
+    Returns a single todo item
+
+  preconditions: |-
+
+  input_schema: |-
+    {
+      id: Integer
+    }
+
+  output_schema: |-
+    Todo
+
+  error_schema: |-
+    {
+      error: String
+    }
+
+  examples:
+
+    - description: |-
+        when requested on an existing TODO
+      params:
+        id: 1
+      expected:
+        content_type: application/json
+        status: 200
+      assert:
+        - "pathFD('', id: 1)"
+
+  counterexamples:
+
+    - description: |-
+        when requested on an unexisting TODO
+      params:
+        id: 999254654
+      expected:
+        content_type: application/json
+        status: 404
+      assert:
+        - "pathFD('', error: 'No such todo')"

data/examples/restful/webspicy/todo/getTodos.yml

@@ -0,0 +1,39 @@
+---
+name: |-
+  Todo
+
+url: |-
+  /todo/
+
+services:
+- method: |-
+    GET
+
+  description: |-
+    Returns the list of todo items
+
+  preconditions: |-
+
+  input_schema: |-
+    {
+    }
+
+  output_schema: |-
+    [Todo]
+
+  error_schema: |-
+    {
+    }
+
+  examples:
+
+    - description: |-
+        when requested
+      params: {}
+      expected:
+        content_type: application/json
+        status: 200
+      assert:
+        - notEmpty
+
+  counterexamples: []

data/lib/webspicy/checker.rb

@@ -0,0 +1,26 @@
+module Webspicy
+  class Checker
+
+    def initialize(config)
+      @config = config
+    end
+    attr_reader :config
+
+    def call
+      Webspicy.with_scope_for(config) do |scope|
+        client = scope.get_client
+        scope.each_resource_file do |file, folder|
+          RSpec.describe file.relative_to(folder).to_s do
+
+            it 'meets the formal doc data schema' do
+              Webspicy.resource(file.load, file)
+            end
+
+          end
+        end
+        RSpec::Core::Runner.run config.rspec_options
+      end
+    end
+
+  end
+end

data/lib/webspicy/client/http_client.rb

@@ -0,0 +1,70 @@
+module Webspicy
+  class HttpClient < Client
+
+    def call(test_case, service, resource)
+      # Instantiate the parameters
+      headers = test_case.headers
+      params = test_case.dress_params? ? service.dress_params(test_case.params) : test_case.params
+
+      # Instantiate the url and strip parameters
+      url, params = resource.instantiate_url(params)
+
+      # Globalize the URL if required
+      url = scope.to_real_url(url)
+
+      # Invoke the service now
+      api = Api.new
+      api.public_send(service.method.to_s.downcase.to_sym, url, params, headers)
+
+      # Return the result
+      Resource::Service::Invocation.new(service, test_case, api.last_response)
+    end
+
+    class Api
+
+      attr_reader :last_response
+
+      def get(url, params, headers = nil)
+        headers, url = headers_and_url_for(url, params, headers)
+
+        Webspicy.info("GET #{url} -- #{params.inspect}")
+
+        @last_response = HTTP[headers].get(url, params: params)
+
+        Webspicy.debug("Headers: #{@last_response.headers.to_hash}")
+        Webspicy.debug("Response: #{@last_response.body}")
+      end
+
+      def post(url, params, headers = nil)
+        headers, url = headers_and_url_for(url, params, headers)
+
+        Webspicy.info("POST #{url} -- #{params.inspect}")
+
+        @last_response = HTTP[headers].post(url, body: params.to_json)
+
+        Webspicy.debug("Headers: #{@last_response.headers.to_hash}")
+        Webspicy.debug("Response: #{@last_response.body}")
+      end
+
+      def post_form(url, params, headers = nil)
+        headers, url = headers_and_url_for(url, params, headers)
+
+        Webspicy.info("POST #{url} -- #{params.inspect}")
+
+        @last_response = HTTP[headers].post(url, form: params)
+
+        Webspicy.debug("Headers: #{@last_response.headers.to_hash}")
+        Webspicy.debug("Response: #{@last_response.body}")
+      end
+
+    private
+
+      def headers_and_url_for(url, params, headers)
+        headers = headers || {}
+        [ headers, url ]
+      end
+
+    end
+
+  end
+end

data/lib/webspicy/client.rb

@@ -0,0 +1,20 @@
+module Webspicy
+  class Client
+
+    def initialize(scope)
+      @scope = scope
+    end
+    attr_reader :scope
+
+    def config
+      scope.config
+    end
+
+    def before(*args, &bl)
+      config.before_listeners.each do |beach|
+        beach.call(*args, &bl)
+      end
+    end
+
+  end
+end

data/lib/webspicy/configuration.rb

@@ -0,0 +1,168 @@
+module Webspicy
+  class Configuration
+
+    def initialize
+      @folders = []
+      @before_listeners = []
+      @rspec_options = default_rspec_options
+      @run_counterexamples = default_run_counterexamples
+      @file_filter = default_file_filter
+      @service_filter = default_service_filter
+      @client = HttpClient
+      yield(self) if block_given?
+    end
+
+    # Adds a folder to the list of folders where test case definitions are
+    # to be found.
+    def add_folder(folder)
+      folder = Path(folder)
+      raise "Folder `#{folder}` does not exists" unless folder.exists? && folder.directory?
+      @folders << folder
+    end
+    attr_reader :folders
+
+    # Sets whether counter examples have to be ran or not.
+    def run_counterexamples=(run_counterexamples)
+      @run_counterexamples = run_counterexamples
+    end
+    attr_reader :run_counterexamples
+
+    # Whether counter examples must be ran or not.
+    def run_counterexamples?
+      @run_counterexamples
+    end
+
+    # Returns the defaut value for run_counterexamples
+    def default_run_counterexamples
+      ENV['ROBUST'].nil? || ENV['ROBUST'] != 'no'
+    end
+    private :default_run_counterexamples
+
+    # Installs a host (resolver).
+    #
+    # The host resolver is responsible from transforming URLs found in
+    # .yml test files to an absolute URL invoked by the client. Supported
+    # values are:
+    #
+    # - String: taken as a prefix for all relative URLs. Using this option
+    #   lets specify all webservices through relative URLs and having the
+    #   host itself as global configuration variable.
+    # - Proc: all URLs are passed to the proc, relative and absolute ones.
+    #   The result of the proc is used as URL to use in practice.
+    #
+    # When no host provider is provided, all URLs are expected to be absolute
+    # URLs, otherwise an error will be thrown at runtime.
+    def host=(host)
+      @host = host
+    end
+    attr_reader :host
+
+    # Installs a file filter.
+    #
+    # A file filter can be added to restrict the scope attention only to the
+    # files that match the filter installed. Supported values are:
+    #
+    # - Proc: each file (a Path instance) is passed in turn. Only files for
+    #   which a truthy value is returned will be considered by the scope.
+    # - Regexp: the path of each file is matched against the regexp. Only files
+    #   that match are considered by the scope.
+    # - ===: any instance responding to `===` can be used as a matcher, following
+    #   Ruby conventions. The match is done on a Path instance.
+    #
+    def file_filter=(file_filter)
+      @file_filter = file_filter
+    end
+    attr_reader :file_filter
+
+    # Returns the default file filter to use.
+    #
+    # By default no file filter is set, unless a RESOURCE environment variable is
+    # set. In that case, a file filter is set that matches the file name to the
+    # variable value, through a regular expression.
+    def default_file_filter
+      ENV['RESOURCE'] ? Regexp.compile(ENV['RESOURCE']) : nil
+    end
+    private :default_file_filter
+
+    # Installs a service filter.
+    #
+    # A service filter can be added to restrict the scope attention only to the
+    # services that match the filter installed. Supported values are:
+    #
+    # - Proc: each service is passed in turn. Only services for which a truthy value
+    #   is returned will be considered by the scope.
+    # - ===: any instance responding to `===` can be used as a matcher, following
+    #   Ruby conventions. The match is done on a Service instance.
+    #
+    def service_filter=(service_filter)
+      @service_filter = service_filter
+    end
+    attr_reader :service_filter
+
+    # Returns the default service filters.
+    #
+    # By default no filter is set unless a METHOD environment variable is set.
+    # In that case, a service filter is returned that filters the services whose
+    # HTTP method match the variable value.
+    def default_service_filter
+      ENV['METHOD'] ? ->(s){ s.method.to_s.downcase == ENV['METHOD'].downcase } : nil
+    end
+    private :default_service_filter
+
+
+    # Installs a client class to use to invoke web services for real.
+    #
+    # This configuration allows defining a subclass of Client to be used for
+    # actually invoking web services. Options are:
+    #
+    # - HttpClient: Uses the HTTP library to make real HTTP call to a web server.
+    #
+    # Note that this configuration variable expected a client *class*, not an
+    # instance
+    def client=(client)
+      @client = client
+    end
+    attr_reader :client
+
+    # Installs a listener that will be called before each web service invocation.
+    #
+    # The `listener` must respond to `call`.
+    def before_each(&listener)
+      raise "Must respond to call" unless listener.respond_to?(:call)
+      @before_listeners << listener
+    end
+
+    # Returns the list of listeners that must be called before each web service
+    # invocation.
+    def before_listeners
+      @before_listeners
+    end
+
+    # Allows setting the options passed at RSpec, which is used by both the runner
+    # and checker classes.
+    #
+    # `options` is supposed to be valid RSpec options, to be passed at
+    # `RSpec::Core::Runner.run`
+    def rspec_options=(options)
+      @rspec_options = options
+    end
+    attr_reader :rspec_options
+
+    # Returns the default rspec options.
+    #
+    # By default rspec colors are enabled and the format set to 'documentation'.
+    # The following environment variables <-> rspec options are supported:
+    #
+    # - FAILFAST <-> --fail-fast
+    #
+    def default_rspec_options
+      options = ["--color", "--format=documentation"]
+      if ENV['FAILFAST']
+        options << (ENV['FAILFAST'] == 'no' ? "--no-fail-fast" : "--fail-fast=#{ENV['FAILFAST']}")
+      end
+      options
+    end
+    private :default_rspec_options
+
+  end
+end

data/lib/webspicy/formaldoc.fio

@@ -0,0 +1,47 @@
+Method =
+    String( s | s =~ /^(GET|POST|POST_FORM|PUT|DELETE|PATCH)$/ )
+
+Schema =
+    .Finitio::System <fio> String
+      \( s | ::Webspicy.schema(s) )
+      \( s | raise "Unsupported"  )
+
+Resource =
+    .Webspicy::Resource <info> {
+        name: String
+        url: String
+        services: [Service]
+    }
+
+Service =
+    .Webspicy::Resource::Service <info> {
+        method          : Method
+        description     : String
+        preconditions   : String
+        postconditions  :? String
+        input_schema    : Schema
+        output_schema   : Schema
+        error_schema    : Schema
+        blackbox        :? String
+        examples        :? [TestCase]
+        counterexamples :? [TestCase]
+    }
+
+TestCase =
+    .Webspicy::Resource::Service::TestCase <info> {
+        description      : String
+        dress_params     :? Boolean
+        params           : Params
+        headers          :? .Hash
+        seeds            :? String
+        requester        :? String
+        expected: {
+            status       :  Integer
+            content_type :? String
+            error        :? String
+            headers      :? .Hash
+        }
+        assert :? [String]
+    }
+
+Params = .Array|.Hash