spaceborne 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1dcf4d04a9ffe84ac8e4fb669a2eec42f8fcbf9f
-  data.tar.gz: 6abc0a1a78d0651274724a2a0a07edc9d5d8a66e
+  metadata.gz: 1be4d255659704a43dfd8522c9e028e9cd34da75
+  data.tar.gz: 809d3a5002bb4de524e927ee403dfc8b4a6d79a5
 SHA512:
-  metadata.gz: a170cf92402110c4c7a2aea73fb342e47c2a2de35a2a2e606a6f0ec2bb3fafb42292559e79e24da750c2221b4c3a70e9a9af1ccd8b048c9bce0fdc50afd123c5
-  data.tar.gz: b5c318f6a08ceaa849321ee31467551d48974340bdf1fc907074946316982e1bfa930f6d7ff430f411fe5d9ab9cd660090e0453486f22a33e3f408d0fddf6d4c
+  metadata.gz: 620ae1514021b81d429d15f0fc9136c26be3f276bc131ee185701fc04a9bef2adc9215fe281733c3ded12add2f28dfbf8dddb51078653e9aa2d2de4bb9778ee5
+  data.tar.gz: ec66899ff1c619a07a462ca388c47e44eddcf655abb0161a9389d5d22c17ffd6133fe0afdffb056f14f5f382d51ea42d573429915ebb1da792a8299b7e13a43c

data/.rspec

@@ -1,3 +1,2 @@
 --format documentation
---color
---tag ~todos
+--color

data/Gemfile

@@ -1,4 +1,10 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in spaceborne.gemspec
 gemspec
+
+gem 'coveralls', require: false
+
+group :test do
+  gem 'webmock'
+  gem 'sinatra'
+end

data/README.md

@@ -12,48 +12,224 @@ gem 'spaceborne'
 
 And then execute:
 
-    $ bundle
+```ruby
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install spaceborne
+```ruby
+$ gem install spaceborne
+```
 
 ## Creating API tests
 
+### Making a request
+
+Spaceborne/airborne use curlyrest/rest-client to make the API requests. These are done in the manner that you actually think about the request, the http action verb, the url, headers, and body(optional depending on the verb). When creating a test, you can call any of the following methods: get, post, put, patch, delete, head, options.
+
+#### Parts of a request
+
+| part | description | restrictions |
+|:--- |:----|:----|
+|url|uri describing destination of the request|not including query/fragment|
+|headers|hash of request headers|*optional request modifiers*|
+|body|data being passed in the request|not on head/get requests|
+|query|data passed on url after '?'|added as a 'params' hash in headers|
+
+#### Optional request modifiers
+These are passed as headers, but will be removed from the actual request, taking the desired effect.
+
+| modifier | values | effect|
+|:---|:---|:---|
+|:use_curl| true, 'debug'|executes the command via curl, and if 'debug', output the command and response|
+|:use_proxy| url of the proxy | sends the request to the proxy |
+|:nonjson_data|true|forces content-type to application/x-www-form-urlencoded|
+
+#### Request examples
+passing request headers
+
+```ruby
+get 'http://example.com/api/v1/my_api', { 'x-auth-token' => 'my_token' }
+```
+
+passing a body (`post`, `put`, `patch`, `delete`) as a hash
+
+```ruby
+post 'http://example.com/api/v1/my_api', { :name => 'John Doe' }, { 'x-auth-token' => 'my_token' }
+```
+
+passing Query params via headers
+
+```ruby
+post 'http://example.com/api/v1/my_api', { }, { 'params' => {'param_key' => 'param_value' } }
+```
+
+make the request using curl and show me the entire request/response
+
+```ruby
+get 'http://example.com/api/v1/my_api', { 'x-auth-token' => 'my_token', use_curl: 'debug' }
+```
+
+
+### Validating a response
+
+Most of the power of spaceborne comes from being able to write expectations in a compact form that has great power at being able to perform the actual validation you have in mind. This allows you to build up positive and negative test cases and choose what parts of the response are important, or ignored. Here's an example that we'll look at.
+
 ```ruby
 require 'spaceborne'
 
-describe 'sample spec' do
-  it 'should validate types' do
+describe 'simple get sample' do
+  it 'should pass validation' do
     wrap_request do
       get 'http://example.com/api/v1/simple_get' #json api that returns { "name" : "John Doe" }
       expect_json_types(name: :string)
+      expect_json(name: 'John Doe')
     end
   end
+end
+```
+The parts of the example outside of the wrap_request block are typical rspec. The wrap_request is a spaceborne concept, saying that if anything fails inside of the block, to ouput to stdout information about the request, and response. This is to work around the issue of an expectation failing, and having good info about why, but having no idea what the request or response were that caused the failure. The actual request is done on the get line. Validation of the response is the following expect_ lines.
+
+#### Parts of response to validate
+
+* HTTP Status
+	* `expect_status`(200) - expect to get a status of 200
+* Headers
+	* `expect_header`(validators)
+	* `expect_header_types`(validators)
+* JSON
+	* `expect_json`(validators)
+	* `expect_json`(path, validators)
+	* `expect_json_types`(validators)
+	* `expect_json_types`(path, validators)
+	* `expect_json_keys`(validators)
+	* `expect_json_keys`(path, validators)
+	* `expect_json_sizes`(validators)
+	* `expect_json_sizes`(path, validators)
+
+##### Validators
+The validators mimic the structure of the response you're validating. For example, if your API returns the following json on a get call with Alex specified in the URL:
 
-  it 'should validate values' do
-    wrap_request do
-      get 'http://example.com/api/v1/simple_get' #json api that returns { "name" : "John Doe" }
-      expect_json(name: 'John Doe')
-    end
+```ruby
+{
+  "name": "Alex",
+  "address": {
+    "street": "Area 51",
+    "city": "Roswell",
+    "state": "NM",
+    "coordinates": {
+      "latitude": 33.3872,
+      "longitude": 104.5281 } },
+  "phones": [
+    { "type": "cell",
+      "number": "123-456-7890"},
+    { "type": "home",
+      "number": "987-654-3210"} ]
+}
+```
+
+some possible validations are:
+
+```ruby
+expect_json(name: 'Alex') # exact match because you asked for Alex
+expect_json_types(name: :string, address: {street: :string, city: :string, state: :string,
+  coordinates: {latitude: :float, longitude: :float}},
+  phones: :array_of_objects) # all the types and structure (cannot go into arrays this way)
+expect_json('address', state: /^[A-Z]{2}$/) # ensures address/state has 2 capital letters
+expect_json_types('phones.*', type: :string, number: :string) # looks at all elements in array
+expect_json_types('phones.1', type: :string, number: :string) # looks at second element in array
+expect_json_keys('address', [:street, :city, :state, :coordinates]) # ensure specified keys present
+expect_json_sizes(phones: 2) # expect the phones array size to be 2
+```
+
+Additionally, if an entire object could be null, but you'd still want to test the types if it does exist, you can wrap the expectations in a call to `optional`:
+
+```ruby
+it 'should allow optional nested hash' do
+  get '/simple_path_get' #may or may not return coordinates
+  expect_json_types('address.coordinates', optional(latitude: :float, longitude: :float))
+end
+```
+
+Additionally, when calling `expect_json`, you can provide a regex pattern in a call to `regex`:
+
+```ruby
+describe 'sample spec' do
+  it 'should validate types' do
+    get 'http://example.com/api/v1/simple_get' #json api that returns { "name" : "John Doe" }
+    expect_json(name: regex("^John"))
   end
 end
 ```
 
-## Development
+When calling `expect_json` or `expect_json_types`, you can optionally provide a block and run your own `rspec` expectations:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```ruby
+describe 'sample spec' do
+  it 'should validate types' do
+    get 'http://example.com/api/v1/simple_get' #json api that returns { "name" : "John Doe" }
+    expect_json(name: -> (name){ expect(name.length).to eq(8) })
+  end
+end
+```
 
+When calling `expect_*_types`, these are the valid types that can be tested against:
+
+* `:int` or `:integer`
+* `:float`
+* `:bool` or `:boolean`
+* `:string`
+* `:date`
+* `:object`
+* `:null`
+* `:array`
+* `:array_of_integers` or `:array_of_ints`
+* `:array_of_floats`
+* `:array_of_strings`
+* `:array_of_booleans` or `:array_of_bools`
+* `:array_of_objects`
+* `:array_of_arrays`
+
+If the properties are optional and may not appear in the response, you can append `_or_null` to the types above.
+
+Validation for headers follows the same pattern as above, although nesting of multiple levels isn't going to be needed.
+	
 ## Extensions to Airborne
 
 1. Uses curlyrest to allow extension of rest-client with curl requests
-2. Bundles groups of expectations so that if any fail, you will actually see the request and response printed out, rather than just seeing the expectation that failed
-3. json_body is only calculated once after request rather than on each call
+2. Uses wrap_request to bundle groups of expectations so that if any fail, you will actually see the request and response printed out, rather than just seeing the expectation that failed
+3. json_body is only parsed once after a request rather than on each expect call
 4. Expectations for headers use the same form as the expectations for json bodies
   * `expect_header same arguments/handling as expect_json`
   * `expect_header_types same arguments/handling as expect_json_types`
-5. Expectations returning a hash with keys that are unknown, but that have a defined structure are supported
-6. It is possible to use non-json data in a request
+5. It is possible to use non-json data in a request
+6. Expectations on a response with an array of hashes with keys that are unknown, but that have a defined structure are supported (using the '*' in a path)
+
+The following example shows how this works
+
+```ruby
+{ "array_of_hashes": [
+   { "husband": {"first": "fred", "last": "flinstone"}},
+   { "buddy": {"first": "barney", "last": "rubble"}},
+   { "wife": {"first": "wilma", "last": "flinstone"}}
+  ],
+  "hash_of_hashes": 
+   { "husband": {"first": "fred", "last": "flinstone"},
+     "buddy": {"first": "barney", "last": "rubble"},
+     "wife": {"first": "wilma", "last": "flinstone"}
+  }
+}
+```
+You can now validate the fact that each element in the collection has a key which is variant, but a value that has a defined format (first and last are strings).
+
+    expect_json_types('array_of_hashes.*.*', first: :string, last: :string)
+    expect_json_types('hash_of_hashes.*', first: :string, last: :string)
+
+
+## Development
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/lib/spaceborne.rb

@@ -37,7 +37,7 @@ module Airborne
     def make_request(method, url, options = {})
       @json_body = nil
       @request_body = nil
-      if options[:headers].has_key?(:use_proxy)
+      if options[:headers] && options[:headers].has_key?(:use_proxy)
         proxy_option = options[:headers][:use_proxy]
         RestClient.proxy = proxy_option
       end
@@ -69,7 +69,7 @@ module Airborne
 
     private
     def base_headers
-      { "Content-Type" => 'application/json' }.merge(Airborne.configuration.headers || {})
+      { content_type: :json }.merge(Airborne.configuration.headers || {})
     end
   end
 
@@ -113,7 +113,11 @@ module Airborne
     def get_by_path(path, json, &block)
       fail PathError, "Invalid Path, contains '..'" if /\.\./ =~ path
       type = false
-      parts = path.split('.')
+      if path.class == Symbol
+        parts = path.to_s.split('.')
+      else
+        parts = path.split('.')
+      end
       parts.each_with_index do |part, index|
         if part == '*' || part == '?'
           ensure_array_or_hash(path, json)

data/lib/spaceborne/version.rb

@@ -1,3 +1,3 @@
 module Spaceborne
-  VERSION = "0.1.7"
+  VERSION = "0.1.8"
 end

data/spaceborne.gemspec

@@ -19,10 +19,15 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_runtime_dependency 'rspec', '~> 3.1'
+  spec.add_runtime_dependency 'rest-client', '< 3.0', '>= 1.7.3'
+  spec.add_runtime_dependency 'rack-test', '~> 0.6', '>= 0.6.2'
+  spec.add_runtime_dependency 'rack'
+  spec.add_runtime_dependency 'activesupport'
+  spec.add_development_dependency 'webmock', '~> 0'
+
   spec.add_development_dependency "bundler", "~> 1.11"
   spec.add_development_dependency "rake", "~> 10.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "rest-client", "~> 2.0"
   spec.add_development_dependency "byebug", "~> 2.0"
   spec.add_development_dependency "airborne", "~> 0.2.13"
   spec.add_development_dependency "curlyrest", "~> 0.1.0"

metadata

@@ -1,71 +1,139 @@
 --- !ruby/object:Gem::Specification
 name: spaceborne
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.8
 platform: ruby
 authors:
 - Keith Williams
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-06-05 00:00:00.000000000 Z
+date: 2018-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
-  type: :development
+        version: '3.1'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.11'
+        version: '3.1'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.7.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.7.3
+- !ruby/object:Gem::Dependency
+  name: rack-test
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.2
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '1.11'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '1.11'
 - !ruby/object:Gem::Dependency
-  name: rest-client
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '10.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '10.0'
 - !ruby/object:Gem::Dependency
   name: byebug
   requirement: !ruby/object:Gem::Requirement