mache 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 57a3cffa66255ddaa95d41917a45842c4eb4f6e1
-  data.tar.gz: 54565c4f1a3b141facd22ecc3f70acf20d7402a7
+  metadata.gz: a7d084d201649e516f630f6a837d312fcd6e62ec
+  data.tar.gz: 5cc13f16c2078c326c9979d953690cf7c3f34eb6
 SHA512:
-  metadata.gz: a713135868ef06a9df6cf2e40a430703de6eac61fe96e6c49eabc3fe039a71e0aa7b31fccac4ba56a02487e4c25af1411ac520b3c3728ae23a2b280723d1675f
-  data.tar.gz: 440ebba8dc3a9149e259c80640aa49a738f2e8de5ff967ec3b42482f0ce1a9d13ab466ebac58fc5bd324db0a61cb50770009cd6b162d9fe8ac668e200ac711ea
+  metadata.gz: afd3efc23afd21149227b50c0a461cb3f61ce49b30d4894560d76e1a6b9befdc850518b84247f4ff91ec4694eb5c5b73760c8c2da87dfc111efb190018fa05ef
+  data.tar.gz: d05c14504c5bc9ed11b9f0e918307b53860b242a68cf7fa42dc1ff67f286269cb9f89a98d91089d6e554be099eed786e07199aedcaed058a2e3b20e2aef6999e

data/.rubocop.yml

@@ -6,12 +6,18 @@ AllCops:
 Metrics/BlockLength:
   ExcludedMethods: describe
 
+Style/BlockDelimiters:
+  Enabled: false
+
 Style/Documentation:
   Exclude:
     - "spec/**/*"
 
-Style/StringLiterals:
-  EnforcedStyle: double_quotes
-
 Style/FrozenStringLiteralComment:
   Enabled: false
+
+Style/SpaceInsideHashLiteralBraces:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes

data/README.md

@@ -87,7 +87,7 @@ page.node # <Capybara::Node>
 ### Elements
 
 To make our page object more useful, we can define an element on our page
-object class using the `element` macro. An element is simply a HTML element
+object class using the `element` macro. An element is simply an HTML element
 that we expect to find on the page using a CSS selector.
 
 Let's define a `main` element to represent the main section of our HTML page:
@@ -106,21 +106,19 @@ We can query the `main` element as an attribute of our page object:
 
 ```ruby
 page.has_main? # true
-page.main.visible? # true
 page.main.text # "lorem ipsum"
 ```
 
 ### Components
 
 For elements that can be shared across any number of page object classes it may
-be useful to define a reusable component by extending the `Mache::Component`
-class. A component can contain any number of elements (or even other
-components).
+be useful to define a reusable component by extending the `Mache::Node` class.
+A component can contain any number of elements (or even other components).
 
 Let's define a `Header` component to represent the header of our HTML page:
 
 ```ruby
-class Header < Mache::Component
+class Header < Mache::Node
   element :title, "h1"
 end
 ```
@@ -143,7 +141,6 @@ Querying a component of our page object is much the same as with an element:
 
 ```ruby
 page.has_header? # true
-page.header.visible? # true
 page.header.title.text # "Welcome"
 ```
 
@@ -154,17 +151,17 @@ Let's look at a more complete example for our `WelcomePage`. Note that the
 object classes we may define later for our web application.
 
 ```ruby
-class Header < Mache::Component
+class Header < Mache::Node
   element :title, "h1"
 end
 
-class NavItem < Mache::Component
+class NavItem < Mache::Node
   def selected?
     node[:class].include?("selected")
   end
 end
 
-class Nav < Mache::Component
+class Nav < Mache::Node
   components :items, NavItem, "a"
 end
 

data/lib/mache/dsl.rb

@@ -1,42 +1,127 @@
 module Mache
-  # Provides the mache DSL for nodes.
-  module DSL
+  # See {ClassMethods} for documentation.
+  module DSL # :nodoc:
     def self.included(base)
       base.extend ClassMethods
     end
 
-    module ClassMethods #:nodoc:
+    # Provides a set of macro-like methods for wrapping HTML fragments in {Node}
+    # objects.
+    #
+    # ## Elements
+    #
+    # The {#element} method wraps an HTML fragment in a {Node} and exposes it as
+    # an *attribute* of the declaring class.
+    #
+    # The following example declares the `main` element, which is found on the
+    # welcome page using the `#main` selector:
+    #
+    #     class WelcomePage < Mache::Page
+    #       element :main, "#main"
+    #     end
+    #
+    # The `main` element can be accessed as an attribute of a `WelcomePage`
+    # instance:
+    #
+    #     page = WelcomePage.new
+    #     page.has_main? # true
+    #     page.main.text # lorem ipsum
+    #
+    # ## Components
+    #
+    # The {#component} method wraps an HTML fragment in a user-defined class and
+    # exposes it as an *attribute* of the declaring class.
+    #
+    # The following example declaring the `alert` component, which is found on
+    # the welcome page using the `#alert` selector. The component will be
+    # wrapped in the user-defined `Alert` class:
+    #
+    #     class WelcomePage < Mache::Page
+    #       component :alert, Alert, "#alert"
+    #     end
+    #
+    # The `Alert` class can define an API for accessing the alert HTML fragment:
+    #
+    #     class Alert < Mache::Node
+    #       element :close_button, "button.close"
+    #
+    #       def dismiss
+    #         close_button.click
+    #       end
+    #     end
+    #
+    module ClassMethods
       def automation(*ids)
         ids.map { |id| %([data-automation="#{id}"]) }.join(" ")
       end
 
-      def element(name, selector)
+      # Defines an element that wraps an HTML fragment.
+      #
+      # @param name [String, Symbol] the elements collection name
+      # @param selector [String] the selector to find the element
+      # @param options [Hash] the options to pass to the Capybara finder
+      def element(name, selector, options = {})
         define_method(name.to_s) do
-          @node.find(selector)
+          Node.new(node: @node.find(selector, options))
         end
+
         define_helper_methods(name, selector)
       end
 
-      def elements(name, selector)
+      # Defines a collection of elements that wrap HTML fragments.
+      #
+      # @param name [String, Symbol] the elements collection name
+      # @param selector [String] the selector to find the elements
+      # @param options [Hash] the options to pass to the Capybara finder
+      def elements(name, selector, options = {})
+        options = {minimum: 1}.merge(options)
+
         define_method(name.to_s) do
-          @node.all(selector, minimum: 1)
+          @node.all(selector, options).map do |node|
+            Node.new(node: node)
+          end
         end
+
         define_helper_methods(name, selector)
       end
 
-      def component(name, klass, selector)
+      # Defines a component that wraps an HTML fragment.
+      #
+      # @param name [String, Symbol] the elements collection name
+      # @param klass [Class] the component class
+      # @param selector [String] the selector to find the component
+      # @param options [Hash] the options to pass to the Capybara finder
+      def component(name, klass, selector, options = {})
+        unless klass < Node
+          raise ArgumentError, "Must be given a subclass of Node"
+        end
+
         define_method(name.to_s) do
-          klass.new(node: @node.find(selector))
+          klass.new(node: @node.find(selector, options))
         end
+
         define_helper_methods(name, selector)
       end
 
-      def components(name, klass, selector)
+      # Defines a collection of components that wrap HTML fragments.
+      #
+      # @param name [String, Symbol] the elements collection name
+      # @param klass [Class] the component class
+      # @param selector [String] the selector to find the components
+      # @param options [Hash] the options to pass to the Capybara finder
+      def components(name, klass, selector, options = {})
+        unless klass < Node
+          raise ArgumentError, "Must be given a subclass of Node"
+        end
+
+        options = {minimum: 1}.merge(options)
+
         define_method(name.to_s) do
-          @node.all(selector, minimum: 1).map do |element|
-            klass.new(node: element)
+          @node.all(selector, options).map do |node|
+            klass.new(node: node)
           end
         end
+
         define_helper_methods(name, selector)
       end
 

data/lib/mache/version.rb

@@ -1,3 +1,3 @@
 module Mache
-  VERSION = "1.0.1".freeze
+  VERSION = "2.0.0".freeze
 end

data/lib/mache.rb

@@ -1,3 +1,3 @@
-require "mache/component"
+require "mache/node"
 require "mache/page"
 require "mache/version"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mache
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Joshua Bassett
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-10 00:00:00.000000000 Z
+date: 2017-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -114,7 +114,6 @@ files:
 - Rakefile
 - bin/console
 - lib/mache.rb
-- lib/mache/component.rb
 - lib/mache/dsl.rb
 - lib/mache/node.rb
 - lib/mache/page.rb

data/lib/mache/component.rb

@@ -1,22 +0,0 @@
-require "mache/node"
-
-module Mache
-  # The Component class wraps a fragment of HTML and can be used in any number
-  # of {Page} classes using the `component` macro. A component can contain
-  # elements and other components.
-  #
-  # @example
-  #
-  #   class NavItem < Mache::Component
-  #     def selected?
-  #       node[:class].include?("selected")
-  #     end
-  #   end
-  #
-  #   class Nav < Mache::Component
-  #     components :items, NavItem, "a"
-  #   end
-  #
-  class Component < Node
-  end
-end