edsl 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9f097097fb3758a17ebdf2773fad9a81db56ae733288676e8e8ed04ea53cdd9
-  data.tar.gz: e385e0e3eb350e6bc4e5f61f8492408b92fdfd071196be2c667d2393e41a8f12
+  metadata.gz: 6436be2a1cda4e3ab53243cfddb9b19563530c5c8b55afe918562434c168b5d4
+  data.tar.gz: 78067b244a23b49e6401a68766551d6f35972e09e798d972bf0d7ca467db7957
 SHA512:
-  metadata.gz: 326e347590d35861c9a2470a774bb0e24287578990907a9770d34c0e993f38461cfeee07249303e67a6894eb76a02a04e7af06249433eb6cb176c645e7f68d4e
-  data.tar.gz: a5ce2cc40b44e3d2a3fff8dcdff72b3737f41087056cf7d79b4ed484e07c69650f5a4c1959f82710e81cf0a39ff7e2b5fac2459583b60a14765237057efd768e
+  metadata.gz: 65efa208961743a6a4da88502620b197bf7fc60eb5abe20bb23418bc398e2b9d5b9259122590f8083fea4a1a59af9a5e5dcc90f7c7d07d6feabf1812394ae40b
+  data.tar.gz: 46555775d32e1ecfa8bb79f5cfaf3d83937b98291027053ea8d1d4b19fd0dc4cebc6e4393886359f58c0a4ad7711fe9fe2c4d3dcad89baf3e37f71a0c3ecef69

data/.gitignore

@@ -7,6 +7,8 @@
 /spec/reports/
 /tmp/
 /.idea/
+*.gem
+scratch.rb
 
 # rspec failure tracking
 .rspec_status

data/.rubocop.yml

@@ -1,4 +1,9 @@
-# Offense count: 1
+AllCops:
+  Exclude:
+    - 'spec/*'
+    - 'scratch.rb'
+    - '*.gemspec'
+
 Lint/Debugger:
   Exclude:
     - 'bin/console'

data/README.md

@@ -1,13 +1,132 @@
-# EDSL
+# EDSL - Element DSL
 
-This gem implements an extensible DSL for implementing the page object, pattern.
-It is very similar to PageObject and can almost be used as a drop-in replacement for it.
-However, this gem focuses the element DSL portion only.
+This gem implements an extensible DSL for declaring web elements as part of a page object pattern.  This gem does **not** implement the page object pattern, for an implementation of page object using this gem see edsl-pageobject.
 
-This gem was created to simplify the process of creating abstractions for web automation.
-Because EDSL is easy to extend, you can create custom DSL methods that are first class citizens
+This gem was created out of the need to rapidly produce abstractions for non-standard web elements. With EDSL support for new accessors and other DSL methods can be implemented without needing to modify any EDSL source or monkey patching.  It allows you to rapidly prototype using lambdas, or to build full classes to use in place of existing elements.
+
+
+## Accessors
+The DSL includes accessors for all Watir elements and makes it easy to add custom accessors.  The accessors for Watir elements are not hand crafted ruby code, they're generated by code that extends EDSL when `edsl/watir_elements` is included.  
+
+Below are the two lines of code that implement the support for buttons and links:
+ 
+```ruby
+CLICKABLE_ELEMENTS = %i[button a link].freeze
+CLICKABLE_ELEMENTS.each { |tag| EDSL.define_accessor(tag, how: tag, default_method: :click) }
+```
+
+`EDSL.define_accessor` is the quickest way to add a new accessor.  With it you provide a name for your accessor (here we're just using the name of the tag as the name of the accessor) as well as the _default_ set of options to be used in the call to `element`.
+
+Most accessors can be implemented as a custom call to `element` in the DSL. Depending on the options passed to `element` you can retrieve any in the DOM.  Filling out all those options for every element you wanted to locate would be tedious, so `define_accessor` will define a new method that takes the default options provided, merges them with the ones provided by the developer using the new accessor and then calls `element`.
+
+The options hash for `element` can contain the following keys:
+
+* 	__how__ - The method to call, or a proc to call to locate this element. i.e. `:div`
+*   __default_method__ - The method to call when `name` is called.  If not provided it will be the same as calling `name_element`
+*   __assign_method__ - The method to call when `name=` is called.  If not set the `name=` method will not be created.
+*  __presence_method__ - The method to call when `name?` is called.  If not provided it will default to `:present?`
+*  __hooks__ - CptHook::HookDefintions to apply to the element before returning it in `name_element`.  If not supplied, hooks are not applied.
+*  __wrapper_fn__ - Optional, can be set to a proc that will be called with the Watir element and it's parent container as arguments.
+
+__Anything left in the hash after edsl options are deleted are passed to :how__
+
+These options allow for several possibilities, for example we could create a new `span_button` for spans that are clickable like buttons with:
+
+```ruby
+EDSL.define_accessor(:span_button, how: span, default_method: :click)
+
+```
+
+For more complex needs one can use the `EDSL.extend_dsl` method and define new DSL methods directly.  Here's an example from edsl-pageobject where an additional parameter was needed.
+
+```ruby
+EDSL.extend_dsl do
+  def section(name, section_class, opts)
+    element(name, { how: :div, assign_method: :populate_with,
+                    wrapper_fn: lambda { |element, _container|section_class.new(element, self) } }.merge(opts))
+  end
+end
+```
+
+This makes use of the `:wrapper_fn` option to create a new instance of the provided section class with the actual element as it's root and return that when asked for `name` or `name_element`.
+
+## Consuming accessors
+In order to make use of accessors you need to include the EDSL module into a class.  EDSL assumes that the class including it respond to any of the methods provided in the `:how` option. The easy way to do that is to inherit from `EDSL::ElementContainer`. The key piece of "magic" in it is that it inherits from `SimpleDelegator` and can be initialized with a Watir element or browser.
+
+Most accessors have a signature of `accessor(name, opts)` where `name` determines the method names generated and `opts` provide options.  At a minimum `opts` should include the locators for the element.  For Watir accessors the options are the same as the corresponding Watir calls.	
+
+#### First a simple example using one of the Watir accessors
+
+```ruby
+class LoginPage < EDSL::ElementContainer
+  text_field(:username, id: 'user_name')
+end
+
+# Now we could do:
+page = LoginPage.new(browser)
+
+page.username?                        # See if the text field exists
+page.username = 'zerocool`            # Set the username
+name = page.username                  # Get the username
+username_edit = page.username_element # The the underlying Watir element
+```
+
+#### Due to the way DSL extensions work, it is possible to override behavior at the top level.  
+
+For example, let's say for some link what we care about is where it points, not visiting it.  The default method for a link would be to call `click` forcing us to use `page.link_element.href` to get what we're after when a more `page.link` or `page.link_href` would make it easier to compare with values from a fixture.  We can accomplish this when we declare the link like so:
+
+```ruby
+link(:result_link, index: 0, default_method: :href)
+```
+
+#### We can even find our own elements
+By supplying a block to any accessor that block will be called to locate the element.
+
+```ruby
+link(:result_link, default_method: :href) { some_variable? : link(index: 0) ? link(index: 1) }
+```
+
+#### We can customize value types
+Let's say we had a text field for entering dates we want to be able to take advantage of Chronic and make our lives easier.  We can define a couple lambda functions provide those in the options.
+
+```ruby
+# Return a date, either by parsing a string or returning the passed value back
+v_to_d = lambda { |val| val.is_a?(String) ? Chronic.parse(val) : val }
+
+# Set an element based on a date, or a string Chronic can parse to a date
+DATE_FORMAT = '%m/%d/%Y'.freeze  # Americans ammiright?
+chronic_set = lambda { |name, container, value| container.send("#{name}_element").set(v_to_d.call(value).strftime(DATE_FORMAT)) }
+
+# Return a date from the value in the element
+chronic_get = lambda { |name, container| Chronic.parse(container.send("#{name}_element").value) }
+
+text_field(:date_input, id: 'the_date', assign_method: chronic_set, default_method: chronic_get )
+
+# Now we can do fun things like
+page.date_input = 'next Tuesday'
+``` 
+
+Another way we could accomplish the same task is to provide a wrapper function that wraps the element in a decorator to modify the behavior like so:
+
+```ruby
+class DateEdit < SimpleDelegatopr
+  def value
+    Chronic.parse(super)
+  end
+  
+  def set(val)
+  	super(val_to_date(val).strftime(DATE_FORMAT))
+  end
+  
+  def val_to_date(val)
+    val.is_a?(String) ? Chronic.parse(val) : val
+  end
+end
+
+text_field(:date_input, id: 'the_date', 
+           wrapper_fn: lambda { |ele, _parent| DateEdit.new(ele) } )
+```
 
-This is still very much a work in progress.  Primary documentation can be found in code comments for now.
 
 ## Installation
 
@@ -25,9 +144,6 @@ Or install it yourself as:
 
     $ gem install edsl
 
-## Usage
-
-TODO: Write usage instructions here
 
 ## Development
 

data/edsl.gemspec

@@ -8,9 +8,9 @@ Gem::Specification.new do |spec|
   spec.authors       = ['Donavan Stanley']
   spec.email         = ['donavan.stanley@gmail.com']
 
-  spec.summary       = 'An easy to extend DSL for web elements'
-  spec.description   = 'Page object pattern without PageObject'
-  spec.homepage      = 'https://github.com/jdonavan'
+  spec.summary       = 'An easy to extend DSL for web elements.'
+  spec.description   = 'This gem serves as a base for implementing the page object pattern.'
+  spec.homepage      = 'https://github.com/donavan/edsl'
   spec.license       = 'MIT'
 
   spec.metadata['homepage_uri'] = spec.homepage
@@ -28,11 +28,13 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '~> 1.16'
   spec.add_development_dependency 'pry'
   spec.add_development_dependency 'pry-byebug'
+  spec.add_development_dependency 'pry-stack_explorer'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'simplecov'
 
-  spec.add_runtime_dependency 'watir'
-  spec.add_runtime_dependency 'cpt_hook'
-  spec.add_runtime_dependency 'facets'
+  spec.add_runtime_dependency 'cpt_hook', '~> 0.3'
+  spec.add_runtime_dependency 'facets', '~> 3.1'
+  spec.add_runtime_dependency 'watir', '~> 6.14'
 end

data/lib/edsl/dsl.rb

@@ -1,26 +1,43 @@
 # Root module for the gem
 require 'cpt_hook'
 
+# Top level module for the gem
 module EDSL
+  # rubocop:disable Metrics/AbcSize
+
   # Ensure the DSL methods are applied when we're included
   def self.included(cls)
     cls.extend EDSL::DSL
 
-    cls.send(:define_method, :resolve_with) do |with_var|
-      return self if with_var == :page
-      return :self if with_var == :element
-      with_var
-    end
+    add_resolvers(cls)
 
     cls.send(:define_method, :apply_hooks) do |hook_defs, element|
       return nil if element.nil?
       return element if hook_defs.nil?
+
       hd = hook_defs.dup
       hd.hooks.each { |hook| hook.call_chain.each { |cc| cc.resolve_with { |c| resolve_with(c) } } }
-      hd.hooks.each { |hook| hook.call_chain.each { |cc| cc.resolve_contexts { |c| resolve_with(c) } } }
+      hd.hooks.each { |hook| hook.call_chain.each { |cc| cc.resolve_contexts { |c| resolve_context(c) } } }
       CptHook::Hookable.new(element, hd, self)
     end
   end
+  # rubocop:enable Metrics/AbcSize
+
+  def self.add_resolvers(cls)
+    cls.send(:define_method, :resolve_with) do |with_var|
+      return with_var.call if with_var.is_a?(Proc)
+      return self if with_var == :parent
+      return :self if with_var == :element
+
+      with_var
+    end
+
+    cls.send(:define_method, :resolve_context) do |context|
+      return context.call if context.is_a?(Proc)
+
+      context
+    end
+  end
 
   # Use a block to add new methods to the DSL.
   def self.extend_dsl(&block)
@@ -33,6 +50,16 @@ module EDSL
     DSL.define_accessor(acc_name, default_opts)
   end
 
+  # Allow an accessor to be accessed by a different name
+  def self.alias_accessor(new_name, acc_name)
+    DSL.alias_accessor(new_name, acc_name)
+  end
+
+  # Allow multiple accessors to be defined at once
+  def self.define_accessors(accessor_array)
+    DSL.define_accessors(accessor_array)
+  end
+
   # These methods will be extended into any class which includes EDSL.
   # They provide a mechanism for declaring HTML elements as properties of another object
   module DSL
@@ -53,37 +80,59 @@ module EDSL
     #  element(:username, id: 'some_id', how: Proc.new { |name, container, opts| container.text_field(opts) }, default_method: :value, assign_method: :set)
     #
     def element(name, opts)
-      how = opts.delete(:how)
-      default_method = opts.delete(:default_method)
+      element_method = _add_element_method(name, opts)
+      _add_common_methods(name, element_method, opts)
+      _add_assignment_methods(name, element_method, opts)
+    end
+
+    # Helper function to reduce perceived complexity of element
+    def _add_assignment_methods(name, element_method, opts)
       assign_method = opts.delete(:assign_method)
-      presence_method = opts.delete(:presence_method) || :present?
-      hooks = opts.delete(:hooks)
-      wrapper_fn = opts.delete(:wrapper_fn) || lambda { |_e, _p| return _e }
+      return unless assign_method
 
-      ele_meth = "#{name}_element"
-      define_method(ele_meth) do
-        ele = yield name, self, opts if block_given?
-        ele ||= how.call(name, self, opts) if how.is_a?(Proc)
-        ele ||= send(how, opts)
-        ele = wrapper_fn.call(ele, self)
-        hooks.nil? ? ele : send(:apply_hooks, hooks, ele)
+      define_method("#{name}=") do |value|
+        return assign_method.call(name, self, value) if assign_method.is_a?(Proc)
+
+        send(element_method).send(assign_method, value)
       end
+    end
+
+    # Helper function to reduce perceived complexity of element
+    def _add_common_methods(name, element_method, opts)
+      default_method = opts.delete(:default_method)
+      presence_method = opts.delete(:presence_method) || :present?
 
       define_method(name) do
         return default_method.call(name, self) if default_method.is_a?(Proc)
-        default_method.nil? ? send(ele_meth) : send(ele_meth).send(default_method)
+
+        default_method.nil? ? send(element_method) : send(element_method).send(default_method)
       end
 
       define_method("#{name}?") do
-        send(ele_meth).send(presence_method)
+        return presence_method.call(name, self) if presence_method.is_a?(Proc)
+
+        send(element_method).send(presence_method)
       end
+    end
 
-      return unless assign_method
+    # rubocop:disable Metrics/AbcSize
+    # Helper function to reduce perceived complexity of element
+    def _add_element_method(name, opts)
+      how = opts.delete(:how)
+      hooks = opts.delete(:hooks)
+      wrapper_fn = opts.delete(:wrapper_fn) || ->(e, _p) { return e }
 
-      define_method("#{name}=") do |value|
-        send(ele_meth).send(assign_method, value)
+      ele_meth = "#{name}_element"
+      define_method(ele_meth) do
+        ele = yield if block_given?
+        ele ||= how.call(name, self, opts) if how.is_a?(Proc)
+        ele ||= send(how, opts)
+        ele = wrapper_fn.call(ele, self)
+        hooks.nil? ? ele : send(:apply_hooks, hooks, ele)
       end
+      ele_meth
     end
+    # rubocop:enable Metrics/AbcSize
 
     # This vastly simplifies defining custom accessors.
     # If we had to use the base element method for every field that would be tedious.
@@ -100,10 +149,12 @@ module EDSL
       end
     end
 
+    # Allow an accessor to be accessed by a different name
     def self.alias_accessor(new_name, acc_name)
       self.class.send(:alias_method, new_name, acc_name)
     end
 
+    # Allow multiple accessors to be defined at once
     def self.define_accessors(accessor_array)
       accessor_array.each { |acc| define_accessor(*acc) }
     end

data/lib/edsl/element_container.rb

@@ -14,7 +14,7 @@ module EDSL
     include EDSL
 
     attr_reader :parent_container
-    alias_method :root_element, :__getobj__
+    alias root_element __getobj__
 
     def initialize(element, parent = nil)
       super(element)

data/lib/edsl/version.rb

@@ -1,3 +1,3 @@
 module EDSL
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.2.0'.freeze
 end

data/lib/edsl/watir_elements.rb

@@ -1,16 +1,19 @@
+require 'facets/string/snakecase'
+
 module EDSL
   # This module extends the DSL to include the various Watir elements
   module WatirElements
     SPECIAL_ELEMENTS = %i[button a radio_set input select textarea].freeze
 
-    Watir.tag_to_class.keys.reject { |k| SPECIAL_ELEMENTS.include?(k) }.each do |tag|
+    TEXT_ELEMENTS = Watir.tag_to_class.keys.reject { |k| SPECIAL_ELEMENTS.include?(k) }.map { |t| t.to_s.snakecase }.freeze
+    TEXT_ELEMENTS.each do |tag|
       EDSL.define_accessor(tag, how: tag, default_method: :text)
     end
 
     CLICKABLE_ELEMENTS = %i[button a link].freeze
     CLICKABLE_ELEMENTS.each { |tag| EDSL.define_accessor(tag, how: tag, default_method: :click) }
 
-    CONTENT_EDITABLE_ELEMENTS = %i[text_field textarea text_area].freeze
+    CONTENT_EDITABLE_ELEMENTS = %i[text_field textarea].freeze
     CONTENT_EDITABLE_ELEMENTS.each { |tag| EDSL.define_accessor(tag, how: tag, default_method: :value, assign_method: :set) }
 
     SETABLE_ELEMENTS = %i[radio checkbox].freeze

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: edsl
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Donavan Stanley
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-10-22 00:00:00.000000000 Z
+date: 2018-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-stack_explorer
+  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'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -95,13 +109,13 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: watir
+  name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :runtime
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -112,31 +126,45 @@ dependencies:
   name: cpt_hook
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: facets
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-description: Page object pattern without PageObject
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: watir
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.14'
+description: This gem serves as a base for implementing the page object pattern.
 email:
 - donavan.stanley@gmail.com
 executables: []
@@ -160,12 +188,12 @@ files:
 - lib/edsl/element_container.rb
 - lib/edsl/version.rb
 - lib/edsl/watir_elements.rb
-homepage: https://github.com/jdonavan
+homepage: https://github.com/donavan/edsl
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/jdonavan
-  source_code_uri: https://github.com/jdonavan
+  homepage_uri: https://github.com/donavan/edsl
+  source_code_uri: https://github.com/donavan/edsl
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -185,5 +213,5 @@ rubyforge_project:
 rubygems_version: 2.7.7
 signing_key: 
 specification_version: 4
-summary: An easy to extend DSL for web elements
+summary: An easy to extend DSL for web elements.
 test_files: []