restspec 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2630d035050223be7f59896a2d36084c4f1b710a
+  data.tar.gz: 180d28e725e189ffee1f2da1186d89bb6ed04048
+SHA512:
+  metadata.gz: c105cb126412bb60802fc54b83b9ad9e42cc50e14d41ddc9bb73f79acf396357906448d2f8657b01a1ca4cfe76597595bc2ae21debe281b2a09939442964611b
+  data.tar.gz: f6740670155d18921523cfef7a45dff961aa22745af928f23d214296bb492ba918a4fbd7310e39d795fd305cff24a0afc242e7750dc84169e330044ec7801eb9

data/.editorconfig

@@ -0,0 +1,21 @@
+# No .editorconfig files above the root directory
+root = true
+
+[*]
+indent_style = space
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{rb}]
+indent_size = 2
+
+[Gemfile*]
+indent_size = 2
+
+[Rakefile]
+indent_size = 2
+
+[Guardfile]
+indent_size = 2

data/.gitignore

@@ -0,0 +1,23 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+*.DS_Store
+.tags
+.tags_sorted_by_file
+
+examples/store-api/tmp/pids
+examples/store-api/tmp/
+examples/store-api/log/*.log
+examples/store-api/.rbenv-vars
+examples/store-api/db/*.sqlite3

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--require spec_helper
+--format documentation
+--format Nc

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in restspec.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,6 @@
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 juliogarciag
+
+MIT License
+
+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,188 @@
+# Restspec
+
+Restspec is a REST api framework built in top of RSpec to help you write robust and mantainable tests to ensure that your api behaves exactly as you want.
+
+## Installation
+
+Install it globally like this:
+
+    $ gem install restspec
+
+## Usage
+
+For a basic tutorial of how to use Restspec, please check [this file](https://github.com/platanus/restspec/blob/master/docs/tutorial.md).
+
+### The Restspec Approach
+
+You can skip this section but i think it will help you understand how things happens here. The Restspec design is founded in the separation of how your api components are modeled and what the actual tests are. In Restspec, you have three files intended to model your api:
+
+- endpoints.rb
+- schemas.rb
+- requirements.rb
+
+The only one that is completely necesary is the `endpoints.rb` file. This file is when you define what your endpoints are and give them names. For example, the following endpoint: `GET /users/:id/orders` can be mapped to an endpoint named `users/orders`. This name can be used to reference and execute the endpoint in the tests instead of repeating it many times.
+
+The next one, `schemas.rb`, represents the attributes your entities are made of, and the final one, `requirements.rb` only helps to ensure that some information is already present on the system when the tests begin.
+
+When we talk about endpoints as objects to reuse, we can think of the dependencies between the endpoints as dependencies between models. We can just make the `product/show` endpoint to depend on the `products/index` and the `products/create` endpoints to make sure that the test always run with a product.
+
+### Setup
+
+To create a new test for a given api, just run the following command:
+
+```bash
+$ restspec my-api-tests --api-prefix=http://my-api-domain/api/v1
+```
+
+This will create a folder called `my-api-tests` with the following contents:
+
+```
+.
+├── Gemfile
+├── Gemfile.lock
+└── spec
+    ├── api
+    │   └── restspec
+    │       ├── endpoints.rb
+    │       ├── requirements.rb
+    │       ├── schemas.rb
+    │       └── restspec_config.rb
+    ├── spec_helper.rb
+    └── support
+        ├── custom_macros.rb
+        └── custom_matchers.rb
+```
+
+Your tests go anywhere (you can put them in the api/ folder), the configuration file (`restspec_config.rb`) has his own documentation inside and the endpoints and schemas file are were you define the inner parts of the expected API. `requirements.rb` is a set of requirement to assert needs before some tests, like to test that an api key is valid or that the system already has some important data that can't be created through the api.
+
+### Endpoints
+
+In the endpoints file you can define your endpoints using an special dsl, like this:
+
+```ruby
+resources :products do
+  collection do
+    get :index
+  end
+
+  member do
+    get :show
+  end
+end
+```
+
+Check the endpoint DSL documentation [here](https://github.com/platanus/restspec/blob/master/docs/endpoints.md) for more details of the available methods and options. The only important thing about them is that they are the endpoints we have to test.
+
+### Schemas
+
+Schemas are how your data is shaped and they enforces the shape of the your data and how to generates random examples for that. You can define schemas using a special dsl like this:
+
+```ruby
+schema :product do
+  attribute :name, string
+  attribute :code, string
+  attribute :price, decimal | decimal_string
+  attribute :category_id, schema_id(:category), :for => [:examples]
+  attribute :category, embedded_schema(:category), :for => [:checks]
+end
+
+schema :category do
+  attribute :name, string
+end
+```
+
+As you can see, a schema is compound of attributes that are attached to one type. The types are useful for many things. The types documentation is located [here](https://github.com/platanus/restspec/blob/master/docs/types.md).
+
+The schemas DSL documentation is located [here](https://github.com/platanus/restspec/blob/master/docs/schemas.md). Schemas are a very important part of Restspec but they are not as necesary as the endpoints.
+
+### Tests
+
+To actually test something, let's create any test of type `api` (because in the `restspec/restspec_config` file we added helpers and macros only for this type of tests). To test an endpoint of your api you have to use the `endpoint` macro
+
+```ruby
+endpoint 'products/index' do
+end
+```
+
+To actually test an execution of the endpoint, you have to use the `test` method. Restspec tests are not unit ones because the cost of call a possible slow api can be high. Because of this, all the `it`s blocks that are under a `test` block will only execute the endpoint once. Because of this, we can test many assertions against only one api execution:
+
+```ruby
+endpoint 'products/index' do
+  test do
+    it { should have_status(:ok) }
+    it 'returns an array' do
+      expect(body).to be_kind_of(Array)
+    end
+  end
+end
+```
+
+We can call other endpoints from inside a test. For example:
+
+```ruby
+endpoint 'products/create' do
+  # ...
+  test 'Without a price' do
+    # This is the `payload` macro, to fill the request's payload
+    payload name: 'random name'
+
+    it 'has the price set to 0' do
+      product = read_endpoint(url_params: { id: body.id })
+      expect(product.price).to eq(0)
+    end
+  end
+end
+```
+
+Aditionally, we can test an endpoint that is intended to represent an action over a resource. For example, an update can be tested like this:
+
+```ruby
+endpoint 'products/update', resource: 'products/show' do
+  # initial_resource is the initial representation of the resource
+  payload do
+    { name: "#{initial_resource.name}-001" }
+  end
+
+  test do
+    it 'updates the name' do
+      # final resource is the representation of the resource after
+      # the endpoint has been executed
+      expect(final_resource.name).to_not eq(initial_resource.name)
+      expect(final_resource.name).to eq(request.payload.name)
+    end
+  end
+end
+```
+
+For more information about what can you do in your tests, you can see what are the [available matchers](https://github.com/platanus/restspec/blob/master/docs/matchers.md), the [available helpers](https://github.com/platanus/restspec/blob/master/docs/helpers.md) and the [available macros](https://github.com/platanus/restspec/blob/master/docs/macros.md).
+
+### Requirements
+
+They allow to check for something important before starting to test.
+
+```ruby
+requirement :check_warehouse_availability do
+  execution do
+    warehouses = read_endpoint('warehouses/index')
+    if !warehouses || warehouses.empty?
+      add_error "There is no warehouses in the system"
+    end
+  end
+end
+```
+
+To use them, you have to do the following in your test:
+
+```ruby
+endpoint 'products/create' do
+  ensure! :check_warehouse_availability
+end
+```
+
+## A note about the Roadmap
+
+Because the scope of this library is not small, we couldn't make a first release as small as we are acostumed. Anyway, we love to be able to deliver in small iterations, so there a [ROADMAP](https://github.com/platanus/restspec/blob/master/ROADMAP.md) file that we use to keep track of the objectives that we have. Althought many of the objectives of the gem are already done, there are more objectives that will expect to the following releases.
+
+## Contribute
+
+Please be sure to have the [EditorConfig](http://editorconfig.org/) plugin in your text editor to follow the guidelines proposed in the [.editorconfig](https://github.com/platanus/restspec/blob/master/.editorconfig) file. To contribute, please send us a PR and make sure that the current tests keeps working after that. You can help to complete the unit tests too. Anyway, when we have all tests together, we should have Travis working, but, right now, it's ok for us to just test the PR before going on.

data/ROADMAP.md

@@ -0,0 +1,11 @@
+# For 0.1.x
+- 100% Test coverage.
+- Include Travis.
+- Test the restspec binary.
+- Find a way to support a way of authentication based on cookies with an initial login.
+- Find a way to avoid example value clashes when using resource tests.
+- Schemas mixins or/and schemas inheritance.
+
+# For 0.2 (They require more thoughts)
+- Research pagination strategies and integrating them with `schema_id`.
+- Research some way to generate markdown from a mix of the schemas and endpoints. (Like Apiary and others)

data/Rakefile

@@ -0,0 +1,20 @@
+require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+namespace :restspec do
+  task :run_example_app do
+    Dir.chdir("examples/store-api") do
+      exec("BUNDLE_GEMFILE=Gemfile bundle exec rails s -p 3000")
+    end
+  end
+
+  task :run_example_tests do
+    Dir.chdir("examples/store-api-tests") do
+      exec("BUNDLE_GEMFILE=Gemfile bundle exec rspec spec/")
+    end
+  end
+end

data/bin/restspec

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+
+require 'thor/group'
+
+class RestspecRunner < Thor::Group
+  include Thor::Actions
+
+  argument :project
+
+  class_option :api_prefix, :desc => "api prefix to use", :required => true
+
+  def self.source_root
+    File.dirname(__FILE__)
+  end
+
+  def create_project_dir
+    empty_directory project
+  end
+
+  def copy_gemfile
+    copy_file 'templates/Gemfile', "#{project}/Gemfile"
+  end
+
+  def create_spec_folders
+    empty_directory "#{project}/spec"
+    empty_directory "#{project}/spec/api"
+    empty_directory "#{project}/spec/support"
+  end
+
+  def create_spec_helper
+    template 'templates/spec_helper.rb', "#{project}/spec/spec_helper.rb"
+  end
+
+  def create_rspec_config
+    template 'templates/restspec_config.rb', "#{project}/spec/api/restspec/restspec_config.rb"
+  end
+
+  def create_api_dsl_files
+    create_file "#{project}/spec/api/restspec/api_endpoints.rb"
+    create_file "#{project}/spec/api/restspec/api_schemas.rb"
+    create_file "#{project}/spec/api/restspec/api_requirements.rb"
+  end
+
+  def create_support_files
+    create_file "#{project}/spec/support/custom_matchers.rb"
+    copy_file "templates/custom_macros.rb", "#{project}/spec/support/custom_macros.rb"
+  end
+
+  def install_gems
+    inside(project) { run 'bundle install' }
+  end
+end
+
+RestspecRunner.start(ARGV)

data/bin/templates/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gem 'restspec'

data/bin/templates/custom_macros.rb

@@ -0,0 +1,3 @@
+module CustomMacros
+
+end

data/bin/templates/restspec_config.rb

@@ -0,0 +1,10 @@
+Restspec.configure do |config|
+  config.base_url = '<%= options[:api_prefix] %>'
+  config.schema_definition = "#{File.dirname __FILE__}/schemas.rb"
+  config.endpoints_definition = "#{File.dirname __FILE__}/endpoints.rb"
+  config.requirements_definition = "#{File.dirname __FILE__}/requirements.rb"
+  #
+  # => to add custom headers, use config.request.headers like this:
+  #
+  # config.request.headers['AUTHORIZATION'] = "Token token=\"#{config.custom.api_key}\""
+end

data/bin/templates/spec_helper.rb

@@ -0,0 +1,19 @@
+require 'restspec'
+
+Dir["#{File.dirname __FILE__}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.include Restspec::RSpec::ApiHelpers, :type => :api
+  config.extend Restspec::RSpec::ApiMacros, :type => :api
+  config.extend CustomMacros, :type => :api
+end
+
+require_relative './api/restspec/restspec_config'

data/docs/endpoints.md

@@ -0,0 +1,200 @@
+# Endpoints Full DSL
+
+## Top Level DSL
+
+### namespace
+
+The `namespace` method creates a namespace for a set of endpoints, giving them a prefix in his names.
+
+```ruby
+namespace :animals do
+  endpoint :show
+  endpoint :update
+end
+```
+
+### resource
+
+The `resource` method creates a special namespace that has a `base_path` attribute set to his name. It can optionally receives a `base_path` option with a different path.
+
+```ruby
+resource :animals do
+  endpoint :get
+end
+
+resource :light_sabers, base_path: '/light-sabers' do
+  endpoint :get
+end
+```
+
+It's important to note that the endpoints inside the `resource` block doesn't necessarily have the resource's namespace attached to them. For this to happen, we have to have the endpoints inside an `member` or `collection` method.
+
+## Namespace DSL
+
+### endpoint
+
+The `endpoint` method only specifies a new endpoint. The block it yields (using the endpoint dsl) specifies how the endpoint is.
+
+### member
+
+Inside the `member` block inside a `resource`, you can specify a set of endpoints that inherits the `base_path` of the resource and the `/:id` string for the final url.
+
+```ruby
+resource :books do # /books
+  member do # /books/:id
+    endpoint :show # /books/:id. The name is: books/show
+  end
+end
+```
+
+
+### collection
+
+Inside the `collection` method you can specify a set of endpoint that only inherits the `base_path`. It's useful to define resource collection actions, like typicals `create` or `index`.
+
+```ruby
+resource :books do # /books
+  collection do # /books
+    endpoint :create # /books
+  end
+end
+```
+
+### schema
+
+You can attach a namespace to an schema. For example, you can attach the `book` schema to the `books` namespace because `book` related endpoints should be related to entities that conforms to the `book` schema. This is useful for some types, matchers and macros that can take adventage of this relationship.
+
+```ruby
+resource :books do
+  schema :book
+end
+```
+
+### all
+
+The `all` method yields a block that will be executed in each endpoint defined.
+
+```ruby
+resource :books do
+  all do
+    method :get
+  end
+
+  endpoint :create # this will have the get method
+  endpoint :index # this too
+end
+```
+
+### url_param
+
+This is just a proxy using `all`. This method calls the method `url_param` of each one of the endpoints with the given params. Please look at the `url_param` method of the Endpoints DSL.
+
+### get, post, put, patch, delete, head
+
+This methods are shortcuts for the following pattern:
+
+```ruby
+resource :books do
+  endpoint :published do
+    method :get
+    path '/published'
+  end
+end
+
+# shortcut:
+resource :books do
+  get :published, '/published'
+end
+```
+
+## Endpoints DSL
+
+### method
+
+Defines what http method the endpoint holds.
+
+```ruby
+resource :books do
+  collection do
+    endpoint :index do
+      method :get
+    end
+  end
+end
+```
+
+### path
+
+Defines what path the endpoint holds. By default, is empty.
+
+```ruby
+resource :books do
+  collection do
+    endpoint :published do
+      method :get
+      path '/published'
+    end
+  end
+end
+```
+
+### schema
+
+Attaches an schema to the endpoint. This provides some data for helpers, matchers and macros. If the endpoint's schema is nil, the endpoint's schema will be his namespace's schema.
+
+```ruby
+resource :books do
+  collection do
+    endpoint :published do
+      method :get
+      path '/published'
+      schema :published_book
+    end
+  end
+end
+```
+
+### headers
+
+It is a hash that represents the endpoint headers. It can be modified to add new headers.
+
+```ruby
+resource :books do
+  collection do
+    endpoint :published do
+      method :get
+      path '/published'
+      schema :published_book
+      # Let's imagine this endpoint is going to a very weird system
+      headers['Content-Type'] = 'application/json; charset=windows-1252'
+    end
+  end
+end
+```
+
+### url_param
+
+It fills a url parameter (the part of the path with a colon behind: `:id`, `:book_id`, etc) with the given value or block
+
+```ruby
+resource :books do
+  member do
+    endpoint :show do
+      url_param(:id) { 998 }
+      method :get
+    end
+  end
+end
+```
+
+Or, using the shortcut for `get` requests:
+
+```ruby
+resource :books do
+  member do
+    get :show do
+      url_param(:id) { 998 }
+    end
+  end
+end
+```