ui2api 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0e872bf99eb14e305a4b2e1102aaaa9a0a70a595
+  data.tar.gz: 76184318ae145400b35d4c991065077c4028f9d6
+SHA512:
+  metadata.gz: 76c017467309f509de73f77048ef2bde2074b5fd1368a642d3d30b6a57624cae3e3d3b27b754e6aaee2c287da9ec7678f8c4711c3a7662b421c107827dbe3fd5
+  data.tar.gz: d154b97b7793e9315b17de7fdb2550c8a10389182e246cbd75be1322b96d14c11fbf1ecacb784c7be227bc8573acef2ff1f5fd77fd50cd787285282e166726f0

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/Gemfile.lock
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+*.idea
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.5.0
+before_install: gem install bundler -v 1.16.1

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in ui2api.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Titus Fortner
+
+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,179 @@
+# UI2API
+
+As more web applications make use of an interface to interact with their service layer, people now have
+ more flexibility to set up and verify parts of their UI tests without needing to use a browser.
+
+This simple gem makes it easy to subclass `UI2API::Base` and provide all of the information necessary
+to interact with the different REST endpoints available in your application.
+
+This code is designed to be used with the [watir_model gem](https://github.com/titusfortner/watir_model). 
+The Model stores data in a way that makes it easy to compare the input and output from both the API and the UI.
+
+Note that while this gem can be used as the basis of an API Testing suite, its primary focus is on comparing
+input and output from UI to API and back. 
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ui2api'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ui2api
+
+## Usage
+
+1. Set the base url
+    ```ruby
+    UI2API::Base.base_url = 'https://restful-booker.herokuapp.com'
+    ```
+2. Create a subclass with an endpoint:
+    ```ruby
+    module API
+      class Booking < UI2API::Base
+        def self.endpoint
+          'booking'
+        end
+      end
+    end
+    ```
+
+3. Make API calls
+    ```ruby
+    booking = {firstname: 'Trey',
+               lastname: 'Ruecker',
+               totalprice: 83,
+               depositpaid: true,
+               bookingdates: {checkin: '3/23/2019',
+                              checkout: '3/27/2019'}}
+     
+    API::Booking.create(booking)
+    ```
+
+4. The Array or Hash of results is accessed with `#data`
+    ```ruby
+    booking = {firstname: 'David',
+               lastname: 'Jones',
+               totalprice: 183,
+               depositpaid: true,
+               bookingdates: {checkin: '3/23/2019',
+                              checkout: '3/27/2019'}}
+     
+    created_booking = API::Booking.create(booking)
+    booking_id = created_booking.data[:bookingid]
+     
+    stored_booking = API::Booking.show(id: booking_id).data
+     
+    expect(stored_booking).to eq booking
+    ```
+
+5. Use [Watir Model](https://github.com/titusfortner/watir_model)
+
+    Note that the code in the previous example will actually fail.
+    This is because we are storing dates as `String` values and the input `String`
+    does not match the output `String`
+
+    Hashes are hard to compare, which is why we have `WatirModel`. 
+    WatirModel is designed to store the canonical representation of related data in the appropriate data type,
+    specifically so that data can be correctly compared.
+
+    ```ruby
+    module Model
+      class BookingDates < WatirModel
+        key(:checkin, data_type: Date) { Faker::Date.forward }
+        key(:checkout, data_type: Date) { checkin + 4 }
+      end
+     
+      class Booking < WatirModel
+        key(:firstname) { Faker::Name.first_name }
+        key(:lastname) { Faker::Name.last_name }
+        key(:totalprice, data_type: Integer) { Faker::Commerce.price.round }
+        key(:depositpaid) { true }
+        key(:bookingdates, data_type: BookingDates) { BookingDates.new }
+        key(:additionalneeds)
+      end
+    end
+    ```
+
+    Because we have a model class defined that is named the same as the API class, `UI2API` will 
+    automatically attempt to create an instance of the model from the return value of the API call. 
+    It is accessible from a method based on the name of the API/Model classes, so in this case `#booking`:
+
+    ```ruby
+    booking = Model::Booking.new
+     
+    created_booking = API::Booking.create(booking)
+    booking_id = created_booking.data[:bookingid]
+     
+    stored_booking = API::Booking.show(id: booking_id).booking
+     
+    expect(stored_booking).to eq booking
+    ```
+
+6. Customize
+
+    You have a subclass, so if you need to add or change things before or after a call, just override the `UI2API` method
+    in your subclass:
+
+    ```ruby
+    module API
+      class Booking < UI2API::Base
+      
+        attr_reader :id
+        
+        def initialize(*)
+          super
+          return if @data.is_a?(Array)
+          @id = @data[:bookingid]
+        end
+      end
+    end
+    ```
+    Now we can use this like so:
+    ```ruby
+    booking = Model::Booking.new
+     
+    created_booking = API::Booking.create(booking)
+     
+    expect(created_booking.id).to eq created_booking.data[:bookingid]
+    ```
+    
+    Because this pattern comes in very handy, you can use `#define_attribute` to do the same thing:
+    
+    ```ruby
+    module API
+      class Booking < UI2API::Base
+        def initialize(*)
+          super
+          return if @data.is_a?(Array)
+          define_attribute(:id, @data[:bookingid])
+        end
+      end
+    end
+    ```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/titusfortner/ui2api.
+
+## History
+
+While I've been leveraging this approach at my past few jobs, my solutions were application specific and `<cough>` not
+satisfyingly elegant. My initial attempts at implementing this gem were much too over-engineered and weren't solving
+the actual general use case, so this project has stayed on the shelf in spite of the industry need for it. 
+Then at the 2017 Selenium Conference in Berlin, [Mark Winteringham](https://twitter.com/2bittester) gave
+a talk titled [REST APIs and WebDriver: In Perfect Harmony](https://www.youtube.com/watch?v=ugAlCZBMOvM).
+This gave me the outside vantage point I needed to see how to focus the project. I started by copying the functionality 
+of the code in [Mark's repo](https://github.com/mwinteringham/api-framework/tree/master/ruby), 
+and then added in some extra goodness that leveraging WatirModel provides.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/lib/ui2api.rb

@@ -0,0 +1,130 @@
+require "rest-client"
+require "json"
+require 'active_support/inflector'
+
+module UI2API
+  class Base
+    class << self
+
+      def index(opt = {})
+        new rest_call({method: :get,
+                       url: route(opt)}.merge opt)
+      end
+
+      def show(id:, **opt)
+        new rest_call({method: :get,
+                       url: "#{route(opt)}/#{id}".chomp('/')}.merge opt)
+      end
+
+      def create(obj = nil, opt = {})
+        new rest_call({method: :post,
+                       url: route(opt),
+                       payload: generate_payload(obj)}.merge opt)
+      end
+
+      def destroy(id:, **opt)
+        new rest_call({method: :delete,
+                       url: "#{route(opt)}/#{id}".chomp('/')}.merge opt)
+      end
+
+      def update(id:, with:, **opt)
+        new rest_call({method: :put,
+                       url: "#{route(opt)}/#{id}".chomp('/'),
+                       payload: generate_payload(with)}.merge opt)
+      end
+
+      def base_url=(base_url)
+        @@base_url = base_url
+      end
+
+      def base_url
+        @@base_url || ''
+      end
+
+      def route(opt = {})
+        "#{opt[:base_url] || base_url}/#{opt.delete(:endpoint) || endpoint}"
+      end
+
+      def endpoint
+        ''
+      end
+
+      def model_object
+        eval "Model::#{self.to_s[/[^:]*$/]}"
+      end
+
+      private
+
+      def rest_call(opt)
+        opt[:verify_ssl] = opt.delete(:ssl) if opt.key?(:ssl)
+        opt[:headers] ||= headers
+        RestClient::Request.execute(opt) do |response, request, result|
+          [response, request, result]
+        end
+      end
+
+      def generate_payload(obj)
+        case obj
+        when NilClass
+          model_object.new.to_api
+        when WatirModel
+          obj.to_api
+        when JSON
+          # noop
+        else
+          obj.to_json
+        end
+      end
+
+      def headers
+        {content_type: :json}
+      end
+    end
+
+    attr_reader :response, :code, :header, :data
+
+    def initialize(args)
+      response, _request, _result = *args
+      @response = response
+      @code = response.code
+      @header = response.instance_variable_get('@headers')
+      @data = JSON.parse(response.body, symbolize_names: true) rescue nil
+
+      set_watir_model_attr
+    end
+
+    def set_watir_model_attr
+      return unless defined?(model_object.new)
+      model = convert_to_model(@data) unless @data.nil?
+      var = model_object.to_s[/[^:]*$/].underscore
+      var = var.pluralize if @data.is_a? Array
+      define_attribute(var, model)
+      define_attribute(:id, @data[:id]) if @data.is_a? Hash
+    end
+
+    def convert_to_model(data)
+      if data.is_a? Hash
+        return if (model_object.valid_keys & data.keys).empty?
+        begin
+          model_object.convert(data)
+        rescue StandardError => ex
+          raise unless ex.message.include?('Can not convert Hash to Model')
+        end
+      elsif data.is_a? Array
+        data.map do |hash|
+          model = convert_to_model(hash)
+          model.nil? ? return : model
+        end
+      end
+    end
+
+    def model_object
+      self.class.model_object
+    end
+
+    def define_attribute(key, value)
+      instance_variable_set("@#{key}", value)
+      singleton_class.class_eval { attr_reader key }
+    end
+  end
+end

data/ui2api.gemspec

@@ -0,0 +1,35 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |spec|
+  spec.name          = "ui2api"
+  spec.version       = "0.3.0"
+  spec.authors       = ["Titus Fortner"]
+  spec.email         = ["titusfortner@gmail.com"]
+
+  spec.summary       = %q{A simple class for interacting with a Web App's API using test data}
+  spec.description   = %q{Send and receive data via a Web App's API, ideally using WatirModel objects. The goal is to
+compare test data with what is input and displayed via UI.}
+  spec.homepage      = "https://github.com/titusfortner/ui2api"
+  spec.license       = "MIT"
+
+  if spec.respond_to?(:metadata)
+    spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+
+  spec.require_paths = ["lib"]
+  spec.add_runtime_dependency "rest-client"
+  spec.add_runtime_dependency "faker"
+  spec.add_runtime_dependency "watir_model", "~> 0.5.0"
+
+  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "require_all"
+end

metadata

@@ -0,0 +1,154 @@
+--- !ruby/object:Gem::Specification
+name: ui2api
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Titus Fortner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-01-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  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: faker
+  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: watir_model
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: require_all
+  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: '0'
+description: |-
+  Send and receive data via a Web App's API, ideally using WatirModel objects. The goal is to
+  compare test data with what is input and displayed via UI.
+email:
+- titusfortner@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/ui2api.rb
+- ui2api.gemspec
+homepage: https://github.com/titusfortner/ui2api
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: A simple class for interacting with a Web App's API using test data
+test_files: []