restspec 0.0.4 → 0.1

data/lib/restspec/schema/types/datetime_type.rb

@@ -1,9 +1,25 @@
 module Restspec::Schema::Types
+  # Manages DateTime
+  #
+  # Options:
+  #   Example:
+  #     initial_interval: The initial interval (default: 2 months ago)
+  #     final_interval: The final interval (default: `Time.now`)
   class DateTimeType < BasicType
+    # Generates an example time formatted as ISO8601.
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @return [string] A time between 1 month ago and now formatted as ISO8601.
     def example_for(attribute)
       Faker::Time.between(initial_example_interval, final_example_interval).iso8601
     end
 
+    # Validates is the value is a correct time according to ISO8601.
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @param value [Object] the value of the attribute.
+    #
+    # @return [true, false] If the value is accord to ISO8601.
     def valid?(attribute, value)
       return false unless value.present?
       allowed_date_time_formats.any? do |format|

data/lib/restspec/schema/types/decimal_string_type.rb

@@ -1,9 +1,20 @@
 module Restspec::Schema::Types
   class DecimalStringType < DecimalType
+    # Generates a example decimal wrapped in a string. See {DecimalType#example_for}
+    # for more details of the example generation.
+    #
+    # @param (see DecimalType#example_for)
+    # @return A random decimal number wrapped in a string.
     def example_for(attribute)
       super(attribute).to_s
     end
 
+    # Checks is a value is a string and it contains a decimal number
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @param value [Object] the value of the attribute.
+    #
+    # @return [true, false] If the value is a string containing a decimal number.
     def valid?(attribute, value)
       return false unless value.is_a?(String)
       decimal_regex.match(value).present?
@@ -12,10 +23,6 @@ module Restspec::Schema::Types
     private
 
     def decimal_regex
-      @decimal_regex ||= build_regex
-    end
-
-    def build_regex
       integer_part_limit = to_regexp_limit(schema_options.fetch(:integer_part, nil))
       decimal_part_limit = to_regexp_limit(schema_options.fetch(:decimal_part, nil))
       /^\d#{integer_part_limit}([.,]\d#{decimal_part_limit})?$/
@@ -25,7 +32,11 @@ module Restspec::Schema::Types
       if limit.nil?
         default
       else
-        "{#{limit}}"
+        if limit > 1
+          "{1,#{limit}}"
+        else
+          "{0,#{limit}}"
+        end
       end
     end
   end

data/lib/restspec/schema/types/decimal_type.rb

@@ -1,12 +1,28 @@
 module Restspec::Schema::Types
+  # Represents a decimal number. It has the following options:
+  #   - example_options:
+  #     - integer_part: The integer part precision of the generated decimal. (Default: 2)
+  #     - decimal_part: The decimal part precision of the generated decimal. (Default: 2)
   class DecimalType < BasicType
+    # Generates a random decimal number of 2 digits as integer part
+    # and 2 digits as decimal part. Both can be overrided using the
+    # example options `integer_part` and `decimal_part`.
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @return A random decimal number.
     def example_for(attribute)
       integer_part = example_options.fetch(:integer_part, 2)
       decimal_part = example_options.fetch(:decimal_part, 2)
 
-      Faker::Number.decimal(integer_part, decimal_part)
+      Faker::Number.decimal(integer_part, decimal_part).to_f
     end
 
+    # Validates if the number is a numeric one.
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @param value [Object] the value of the attribute.
+    #
+    # @return [true, false] If the value is a number
     def valid?(attribute, value)
       value.is_a?(Numeric)
     end

data/lib/restspec/schema/types/embedded_schema_type.rb

@@ -1,22 +1,53 @@
 module Restspec::Schema::Types
+  # An embedded schema is an attribute with all
+  # the options of a given schema.
   class EmbeddedSchemaType < BasicType
     attr_accessor :schema_name
 
-    def initialize(options, options_when_name_is_present = {})
-      if options.is_a?(Symbol)
-        self.schema_name = options
-        super(options_when_name_is_present)
-      else
-        super(options)
-      end
+    def initialize(schema_name, options = {})
+      self.schema_name = schema_name
+      super(options)
     end
 
+    # Generates examples by creating a {SchemaExample} using
+    # the passed schema.
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema to use.
     def example_for(attribute)
       Restspec::Schema::SchemaExample.new(schema).value
     end
 
+    # Checks if the value is an embedded valid example of the schema
+    # used to initialize.
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @param value [Object] the value of the attribute.
+    #
+    # @example
+    #   # Let's assume this schema
+    #   schema :category do
+    #     attribute :name, string
+    #   end
+    #
+    #   # We can do this anywhere
+    #   schema :product do
+    #     attribute :name, string
+    #     attribute :category, embedded_schema(:category)
+    #   end
+    #
+    #   { name: 'Something', category: { name: 'Products' }  } # a valid product!
+    #   { name: 'Something' } # an invalid product!
+    #
+    # @return [true, false] If the value is an embedded valid example of the schema.
     def valid?(attribute, value)
-      Restspec::Schema::Checker.new(schema).check!(value)
+      begin
+        Restspec::Schema::Checker.new(schema).check!(value)
+        true
+      rescue  Restspec::Schema::Checker::NoAttributeError,
+              Restspec::Schema::Checker::InvalidationError,
+              Restspec::Schema::Checker::NoObjectError
+        false
+      end
     end
 
     private

data/lib/restspec/schema/types/hash_type.rb

@@ -1,24 +1,63 @@
 module Restspec::Schema::Types
+  # It represent embedded hashes, but not schematic ones. For them
+  # use the {EmbeddedSchemaType}.
+  #
+  # This Hash can receive the following options:
+  #   - schema_options:
+  #     - value_type: A type specifying the type of the values of the hash.
+  #     - keys: What are the keys that should be present in the hash.
+  #
   class HashType < BasicType
+    # Generates an empty hash for a example.
+    # It could be better soon.
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    #
+    # @return [Hash] An empty Hash.
     def example_for(attribute)
       {}
     end
 
+    # Checks if the object is a valid hash with the specified keys if they are specified
+    # or the specified value type.
+    #
+    # @example
+    #   HashType.new.valid?(attribute, { a: 1 })
+    #   # => true
+    #   HashType.new(schema_options: { keys: ['age', 'name'] }).valid?(attribute, { a: 1 })
+    #   # =>  false
+    #   HashType.new(schema_options: { keys: ['age', 'name'] }).valid?(attribute, { age: 1, name: 'John' })
+    #   # =>  true
+    #   HashType.new(schema_options: { value_type: StringType.new }).valid?(attribute, { a: 1 })
+    #   # =>  false
+    #   HashType.new(schema_options: { value_type: StringType.new }).valid?(attribute, { a: "1" })
+    #   # =>  true
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @param value [Object] the value of the attribute.
+    #
+    # @return [true, false] If the value is a correct Hash.
     def valid?(attribute, value)
-      is_hash = value.is_a?(Hash)
-      keys = schema_options.fetch(:keys, [])
+      value.is_a?(Hash) && valid_keys?(value) && valid_value_types?(attribute, value)
+    end
+
+    private
+
+    def valid_keys?(value)
+      keys = schema_options.fetch(:keys, nil)
+      return true if keys.nil?
+
+      keys.all? do |key|
+        value.has_key?(key)
+      end
+    end
 
-      if keys.empty?
-        is_hash
-      else
-        value_type = schema_options.fetch(:value_type, nil)
+    def valid_value_types?(attribute, value)
+      value_type = schema_options.fetch(:value_type, nil)
+      return true if value_type.nil?
 
-        is_hash && keys.all? do |key|
-          has_key = value.has_key?(key)
-          if has_key && value_type
-            has_key && value_type.totally_valid?(attribute, value[key])
-          end
-        end
+      value.all? do |key, val|
+        value_type.totally_valid?(attribute, val)
       end
     end
   end

data/lib/restspec/schema/types/integer_type.rb

@@ -1,9 +1,20 @@
 module Restspec::Schema::Types
   class IntegerType < BasicType
+    # Generates a random number.
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    #
+    # @return [Fixnum] A random number.
     def example_for(attribute)
-      Faker::Number.digit
+      Faker::Number.digit.to_i
     end
 
+    # Validates if the value is an integer (Fixnum).
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @param value [Object] the value of the attribute.
+    #
+    # @return [true, false] If the value is an integer.
     def valid?(attribute, value)
       value.is_a?(Fixnum)
     end

data/lib/restspec/schema/types/null_type.rb

@@ -1,9 +1,16 @@
 module Restspec::Schema::Types
   class NullType < BasicType
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    #
+    # @return nil
     def example_for(attribute)
       nil
     end
 
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @param value [Object] the value of the attribute.
+    #
+    # @return [true, false] If the value is nil.
     def valid?(attribute, value)
       value.nil?
     end

data/lib/restspec/schema/types/one_of_type.rb

@@ -1,9 +1,27 @@
 module Restspec::Schema::Types
+  # It will return an element of a set of elements while making a
+  # example and checks against that same set of element while
+  # validating. The following options are needed:
+  #
+  # elements: An array of the element to use
+  #
+  # @example:
+  #   attribute :pet_type, one_of(elements: %w{dog cat})
+  #
   class OneOfType < BasicType
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    #
+    # @return [Object] A sample of the elements array.
+    # @raise KeyError if the elements option was not initialized.
     def example_for(attribute)
       elements.sample
     end
 
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @param value [Object] the value of the attribute.
+    #
+    # @return [true, false] If the value is included in the elements.
+    # @raise KeyError if the elements option was not initialized.
     def valid?(attribute, value)
       elements.include?(value)
     end

data/lib/restspec/schema/types/schema_id_type.rb

@@ -1,29 +1,21 @@
 module Restspec::Schema::Types
   class SchemaIdType < BasicType
-    attr_accessor :schema_name
 
-    def initialize(options, options_when_name_is_present = {})
-      if options.is_a?(Symbol)
-        self.schema_name = options
-        super(options_when_name_is_present)
-      else
-        super(options)
-      end
+    def initialize(schema_name, options = {})
+      self.schema_name = schema_name
+      super(options)
     end
 
     def example_for(attribute)
       return sample_item.id if sample_item.present?
 
-      if create_response.code == 201 && create_response.body.try(:id)
+      if create_response.code == 201 && create_response.body.try(:id).present?
         create_response.body.id
       else
-        example_options.fetch(:hardcoded_fallback) {
-          raise "We couldn't fetch any information for this example"
-        }
+        hardcoded_fallback
       end
     rescue URI::InvalidURIError, Errno::ECONNREFUSED => e
-      puts "WARNING: Error calling api #{e}. Falling back to use a number."
-      Faker::Number.digit
+      hardcoded_fallback
     end
 
     def valid?(attribute, value)
@@ -33,6 +25,8 @@ module Restspec::Schema::Types
 
     private
 
+    attr_accessor :schema_name
+
     def find_endpoint(name)
       Restspec::EndpointStore.get(name)
     end
@@ -43,7 +37,7 @@ module Restspec::Schema::Types
 
     def get_index_endpoint
       if schema_name.present?
-        Restspec::EndpointStore.get_by_schema_and_name(schema_name, :index)
+        Restspec::EndpointStore.get_by_schema_name_and_role(schema_name, :index, :response)
       else
         find_endpoint(example_options.fetch(:fetch_endpoint))
       end
@@ -60,8 +54,7 @@ module Restspec::Schema::Types
 
     def get_create_endpoint
       if schema_name.present?
-        namespace = Restspec::Endpoints::Namespace.get_by_schema_name(schema_name)
-        namespace.get_endpoint(:create)
+        Restspec::EndpointStore.get_by_schema_name_and_role(schema_name, :create, :payload)
       else
         find_endpoint(example_options.fetch(:create_endpoint))
       end
@@ -87,5 +80,9 @@ module Restspec::Schema::Types
       fetch_endpoint = get_index_endpoint
       fetch_endpoint.execute.body
     end
+
+    def hardcoded_fallback
+      example_options.fetch(:hardcoded_fallback, Faker::Number.digit)
+    end
   end
 end

data/lib/restspec/schema/types/string_type.rb

@@ -1,9 +1,18 @@
 module Restspec::Schema::Types
   class StringType < BasicType
+    # Generates a random word.
+    #
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    #
+    # @return [String] A random word.
     def example_for(attribute)
       Faker::Lorem.word
     end
 
+    # @param attribute [Restspec::Schema::Attribute] the atribute of the schema.
+    # @param value [Object] the value of the attribute.
+    #
+    # @return [true, false] If the value is a string.
     def valid?(attribute, value)
       value.is_a?(String)
     end

data/lib/restspec/schema/types/type_methods.rb

@@ -0,0 +1,32 @@
+module Restspec::Schema::Types
+  module TypeMethods
+    # @private
+    # @!macro type_method
+    #   @!method $1(options = {})
+    #
+    #   Creates a new {$2} instance with the first argument
+    #   passed as parameter to the {$2} constructor.
+    #
+    #   @param options [Hash, Object] A hash of options or
+    #     something to instantiate the type.
+    def self.define_type_method(method_name, type_class)
+      define_method(method_name) do |options = {}|
+        type_class.new(options)
+      end
+    end
+
+    define_type_method :string, StringType
+    define_type_method :integer, IntegerType
+    define_type_method :decimal, DecimalType
+    define_type_method :boolean, BooleanType
+    define_type_method :decimal_string, DecimalStringType
+    define_type_method :schema_id, SchemaIdType
+    define_type_method :array, ArrayType
+    define_type_method :one_of, OneOfType
+    define_type_method :hash, HashType
+    define_type_method :null, NullType
+    define_type_method :embedded_schema, EmbeddedSchemaType
+    define_type_method :date, DateType
+    define_type_method :datetime, DateTimeType
+  end
+end

data/lib/restspec/schema/types.rb

@@ -19,21 +19,4 @@ require_relative './types/null_type'
 require_relative './types/embedded_schema_type'
 require_relative './types/date_type'
 require_relative './types/datetime_type'
-
-module Restspec::Schema::Types
-  ALL = {
-    string: StringType,
-    integer: IntegerType,
-    decimal: DecimalType,
-    boolean: BooleanType,
-    decimal_string: DecimalStringType,
-    schema_id: SchemaIdType,
-    array: ArrayType,
-    one_of: OneOfType,
-    hash: HashType,
-    null: NullType,
-    embedded_schema: EmbeddedSchemaType,
-    date: DateType,
-    datetime: DateTimeType
-  }
-end
+require_relative './types/type_methods'

data/lib/restspec/shortcuts.rb

@@ -1,5 +1,15 @@
 module Restspec
   class << self
+    # Shortcut for find a schema by name, create a {Restspec::Schema::SchemaExample} and call its {Restspec::Schema::SchemaExample#value value} method to get a example.
+    #
+    # @param schema_name [Symbol] The name of the schema.
+    # @param extensions [Hash] A set of extensions for the example.
+    #
+    # @example Without extensions
+    #   Restspec.example_for(:person) # { name: 'John', age: 25 }
+    #
+    # @example With extensions
+    #   Restspec.example_for(:person, age: 18) # { name: 'John', age: 18 }
     def example_for(schema_name, extensions = {})
       schema = Restspec::SchemaStore.get(schema_name)
       Schema::SchemaExample.new(schema, extensions).value

data/lib/restspec/stores/endpoint_store.rb

@@ -2,24 +2,49 @@ require 'delegate'
 
 module Restspec
   module Stores
+    # Provides methods for the {EndpointStore} object.
     class EndpointStoreDelegator < SimpleDelegator
+      # Stores an endpoint. It uses the {Restspec::Endpoints::Endpoint#full_name full_name}
+      # method of the endpoint to use as the key for the endpoint itself.
+      #
+      # @param endpoint [Restspec::Endpoints::Endpoint] the endpoint to store.
+      # @return [Restspec::Endpoints::Endpoint] the endpoint inserted.
       def store(endpoint)
         self[endpoint.full_name] = endpoint
       end
 
+      # Get is just an alias for Hash#[]
+      # @return [Restspec::Endpoints::Endpoint, nil] the endpoint found.
       def get(endpoint_name)
         self[endpoint_name]
       end
 
-      def get_by_schema_and_name(schema_name, endpoint_name)
+      # Get an endpoint by the schema, name and a role.
+      #
+      # @example
+      #   # Let's assume in the store there are 3 endpoints
+      #   # called :show, in different namespaces.
+      #
+      #   Restspec::EndpointStore.get_by_schema_name_and_role(:book, :show, :response)
+      #   # => this will only return the one whose schema is :book and are suitable for response.
+      #
+      # @return [Restspec::Endpoints::Endpoint, nil] the endpoint found.
+      def get_by_schema_name_and_role(schema_name, endpoint_name, role)
         values.find do |endpoint|
-          endpoint.schema_name == schema_name && endpoint.name == endpoint_name
+          endpoint.name == endpoint_name && endpoint.schema_for(role).try(:name) == schema_name
         end
       end
     end
 
+    # The Endpoint Store is a Hash extended using {Stores::EndpointStoreDelegator}
+    # This is where we store the endpoints to tests.
+    #
+    # It's important to note that, because this is a Hash, there can't be
+    # two endpoint with the same full name. There can't be two endpoints
+    # called `books/index` for example.
     EndpointStore = EndpointStoreDelegator.new(Hash.new)
   end
 
+  # (see Stores::EndpointStore)
   EndpointStore = Stores::EndpointStore
 end

data/lib/restspec/stores/namespace_store.rb

@@ -2,19 +2,38 @@ require 'delegate'
 
 module Restspec
   module Stores
+    # Provides methods for the {NamespaceStore} object.
     class NamespaceStoreDelegator < SimpleDelegator
+      # Stores the namespace. It uses the namespace's name as the hash key.
+      #
+      # @param namespace [Restspec::Endpoints::Namespace] the namespace to store.
+      # @raise [StandardError] if the namespace is an anonymous one.
       def store(namespace)
-        self << namespace
+        if namespace.anonymous?
+          raise "Can't add an anonymous namespace to the NamespaceStore"
+        else
+          self[namespace.name] = namespace
+        end
       end
 
+      # Get a namespace by name. It gets the name as string or symbol.
+      #
+      # @param namespace_name [String, Symbol] the namespace's name to use for search.
+      # @return [Restspec::Endpoints::Namespace, nil] the namespace found.
       def get(namespace_name)
-        possible_names = [namespace_name.to_s, namespace_name.to_sym]
-        find { |ns| possible_names.include?(ns.name) }
+        fetch(namespace_name.to_s) { fetch(namespace_name.to_sym, nil) }
       end
     end
 
-    NamespaceStore = NamespaceStoreDelegator.new(Array.new)
+    # The Namespace Store is a Hash extended using {Stores::NamespaceStoreDelegator}
+    # This is where we store the namespaces of the API.
+    #
+    # It's important to note that, because this is a Hash, there can't be
+    # two namespaces with the same name. Anonymous namespaces can't be stored
+    # here. They are just stored as children of each namespace.
+    NamespaceStore = NamespaceStoreDelegator.new(Hash.new)
   end
 
+  # (see Stores::NamespaceStore)
   NamespaceStore = Stores::NamespaceStore
 end

data/lib/restspec/stores/schema_store.rb

@@ -2,18 +2,33 @@ require 'delegate'
 
 module Restspec
   module Stores
+    # Provides methods for the {SchemaStore} object.
     class SchemaStoreDelegator < SimpleDelegator
+      # Stores a schema. It uses the name of the schema as the hash key.
+      #
+      # @param schema [Restspec::Schema::Schema] the schema to store.
+      # @return [Restspec::Schema::Schema] the schema inserted.
       def store(schema)
         self[schema.name] = schema
       end
 
+      # Get the schema. It's just an alias for the Hash#[] method
+      #
+      # @param schema_name the name of the schema.
+      # @return [Restspec::Schema::Schema, nil] the schema found.
       def get(schema_name)
         self[schema_name]
       end
     end
 
+    # The Schema Store is a Hash extended using {Stores::SchemaStoreDelegator}
+    # This is where we store the schemas to use.
+    #
+    # It's important to note that, because this is a Hash, there can't be
+    # two schemas with the same name.
     SchemaStore = SchemaStoreDelegator.new(Hash.new)
   end
 
+  # (see Stores::SchemaStore)
   SchemaStore = Stores::SchemaStore
 end

data/lib/restspec/values/status_code.rb

@@ -1,6 +1,17 @@
 module Restspec
   module Values
-    class StatusCode < Struct.new(:number_or_symbol)
+    # A value object that transforms a http status code (201) or
+    # a symbol with the status code message (:created) to a simple
+    # number (201).
+    class StatusCode
+      def initialize(number_or_symbol)
+        self.number_or_symbol = number_or_symbol
+      end
+
+      # @example
+      #   StatusCode.new(201).value # 201
+      #   StatusCode.new(:created).value # 201
+      # @return [Fixnum] the status code
       def value
         if number_or_symbol.is_a?(Symbol)
           Rack::Utils::SYMBOL_TO_STATUS_CODE.fetch(number_or_symbol)
@@ -8,6 +19,10 @@ module Restspec
           number_or_symbol
         end
       end
+
+      private
+
+      attr_accessor :number_or_symbol
     end
   end
 end

data/lib/restspec/version.rb

@@ -1,3 +1,3 @@
 module Restspec
-  VERSION = "0.0.4"
+  VERSION = "0.1"
 end

data/lib/restspec.rb

@@ -27,8 +27,10 @@ require "restspec/endpoints/dsl"
 require "restspec/endpoints/request"
 require "restspec/endpoints/response"
 require "restspec/endpoints/network"
+require "restspec/endpoints/has_schemas"
 require "restspec/endpoints/endpoint"
 require "restspec/endpoints/namespace"
+require "restspec/endpoints/url_builder"
 
 require "restspec/requirements/dsl"
 require "restspec/requirements/requirement"

data/restspec.gemspec

@@ -24,6 +24,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "guard-rspec", "~> 4.3"
   spec.add_development_dependency "rspec-nc", "~> 0.2"
   spec.add_development_dependency "simplecov", "~> 0.9.1"
+  spec.add_development_dependency "yard", "~> 0.8.7"
+  spec.add_development_dependency "redcarpet", "~> 3.2"
   spec.add_dependency "activesupport", "~> 4.0"
   spec.add_dependency "faker", "~> 1.4"
   spec.add_dependency "hashie", "~> 3.3"