watir_api 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2866494791af1c0785b52cb294240c8f0a2c16a9
-  data.tar.gz: 0a7dd46130691e620357d03fcd66113372ee2ff2
+  metadata.gz: a5774f09a5ef7ee12f3a8726d05ddb0dd1da0ef6
+  data.tar.gz: 10f86cada217f8547693b7d5a257a02e74036ebb
 SHA512:
-  metadata.gz: 9abe2898a5c711ec90c37889123516c985e51165670040576b747983503c742f3134a12b25ce5c37b6b6508ab5a18edb0f8969a7ac49977226855e65d5b7e23d
-  data.tar.gz: f9a64cc277053f4c4530d978efa808bf2d22a34b15e777e9f466ea94156e909ac931edde90a2949980e070c5c0b8a7a7ae5dec79ca31c068fbba5bad397d059f
+  metadata.gz: a85d99f5328327fbd77d0e671d9524d6fc7fa04066d994674aa2cb6b6b7e7a8e7888203f5607f8484a65a744d36fb2c4931371464f0b7d6663f845b7f969fb16
+  data.tar.gz: 6e2ca0725ac604af8b222b49ec835eaeba33bb5607d85c16f0e679103ce47acc53e68d60f001542ee12d194db38a93928042b250c065a6abd44713d88d741a1e

data/README.md

@@ -1,7 +1,13 @@
-# WatirApi
+# Watir API
 
-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.
+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 `WatirApi::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 the canonical data and is used
+to make it easy to compare the input and output from both the API and the UI.
 
 ## Installation
 
@@ -21,8 +27,134 @@ Or install it yourself as:
 
 ## Usage
 
-This gem is still in beta; if you have suggestions to improve it, please write some code or
-raise an issue on Github
+1. Set the base url
+    ```ruby
+    WatirApi::Base.base_url = '"https://restful-booker.herokuapp.com"'
+    ```
+2. Create a subclass with an endpoint:
+    ```ruby
+    module API
+      class Booking < WatirApi::Base
+        def self.endpoint
+          'booking'
+        end
+      end
+    end
+    ```
+
+3. Make API calls
+    ```ruby
+    booking = {firstname: "Trey",
+               lastname: "Ruecker",
+               totalprice: 83,
+               depositpaid: true,
+               bookingdates: {checkin: '2019-02-23',
+                              checkout: '2019-02-27'}}
+     
+    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: '2019-03-23',
+                              checkout: '2019-03-27'}}
+     
+    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, `WatirApi` 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 `WatirApi` method
+    in your subclass:
+
+    ```ruby
+    module API
+      class Booking < WatirApi::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 < WatirApi::Base
+        def initialize(*)
+          super
+          return if @data.is_a?(Array)
+          define_attribute(:id, @data[:bookingid])
+        end
+      end
+    end
+    ```
 
 ## Contributing
 

data/lib/watir_api.rb

@@ -98,10 +98,8 @@ module WatirApi
       model = convert_to_model(@data) unless @data.nil?
       var = model_object.to_s[/[^:]*$/].underscore
       var = var.pluralize if @data.is_a? Array
-      instance_variable_set "@#{var}", model
-      singleton_class.class_eval { attr_accessor var }
-      @id = @data[:id] if @data.is_a? Hash
-      singleton_class.class_eval { attr_accessor :id } unless @id.nil?
+      define_attribute(var, model)
+      define_attribute(:id, @data[:id]) if @data.is_a? Hash
     end
 
     def convert_to_model(data)
@@ -123,5 +121,10 @@ module WatirApi
     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/watir_api.gemspec

@@ -3,7 +3,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = "watir_api"
-  spec.version       = "0.2.0"
+  spec.version       = "0.2.1"
   spec.authors       = ["Titus Fortner"]
   spec.email         = ["titusfortner@gmail.com"]
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: watir_api
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Titus Fortner