RubyGems - mache - Versions diffs - 1.0.0 → 1.0.1 - Mend

mache 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4a33c9e84520e543f6693fd7895d9fb6c6835626
-  data.tar.gz: 7370d76223bd10fe2444e2d091e9ddd64219181a
+  metadata.gz: 57a3cffa66255ddaa95d41917a45842c4eb4f6e1
+  data.tar.gz: 54565c4f1a3b141facd22ecc3f70acf20d7402a7
 SHA512:
-  metadata.gz: 771ff8e66362d6788b046bb94e092a100dacd2f952ee960f0b2530b47eca889a0b8a2a57ba7c4ac40116214663d3d14ca89db988e861f6ed46ed1d52c0bc37a9
-  data.tar.gz: 4b203e4da5927d68605208ed06b8aa54a81d7c3c8f69d5c1f19cc13b1019e9c3fd7442cfb857aa11ac244b634d967a4fd1badcdc9e9ae3c28db66115b29b634b
+  metadata.gz: a713135868ef06a9df6cf2e40a430703de6eac61fe96e6c49eabc3fe039a71e0aa7b31fccac4ba56a02487e4c25af1411ac520b3c3728ae23a2b280723d1675f
+  data.tar.gz: 440ebba8dc3a9149e259c80640aa49a738f2e8de5ff967ec3b42482f0ce1a9d13ab466ebac58fc5bd324db0a61cb50770009cd6b162d9fe8ac668e200ac711ea

data/.gitignore CHANGED Viewed

@@ -1,3 +1,4 @@
 *.gem
 .bundle
+.yardoc
 Gemfile.lock

data/.yardopts ADDED Viewed

	@@ -0,0 +1 @@
1	+ --markup markdown

data/README.md CHANGED Viewed

@@ -1,12 +1,39 @@
-# Mache
+# Mâché
 [![Build Status](https://travis-ci.org/nullobject/mache.svg?branch=master)](https://travis-ci.org/nullobject/mache)
-A [page object](https://martinfowler.com/bliki/PageObject.html) library for writing cleaner acceptance tests with [Capybara](https://github.com/teamcapybara/capybara).
+Mâché (pronounced "mash-ay") helps you to write cleaner and more expressive
+acceptance tests for your web applications using page objects.
+## What is a page object?
+A [page object](https://martinfowler.com/bliki/PageObject.html) is a data
+structure which provides an interface to your web application for the purposes
+of test automation. For example, it could represent a single HTML page, or
+perhaps even a fragment of HTML on a page.
+From Martin Fowler:
+> A page object wraps an HTML page, or fragment, with an application-specific
+> API, allowing you to manipulate page elements without digging around in the
+> HTML.
+[Capybara](https://github.com/teamcapybara/capybara) can only get us part of
+the way there. It allows us to work with an API rather than manipulating the
+HTML directly, but what it provides isn't an *application specific* API. It
+gives us low-level API methods like `find`, `fill_in`, and `click_button`, but
+it doesn't provide us with high-level methods to do things like "sign in to the
+app" or "click the Dashboard item in the navigation bar".
+This is where page objects come in. Using Mâché we can for instance define a
+page object class called `SignInPage` and use it any time we want to automate
+authenticating with our app. It could handle visiting the sign in page,
+entering the user's credentials, and clicking the "Sign in" button.
 ## Getting started
-Consider the following HTML snippet:
+Let's dive straight in and take a look at an example. Consider the following
+HTML fragment for the welcome page in our app:
 ```html
 <html>
@@ -26,9 +53,9 @@ Consider the following HTML snippet:
 </html>
 ```
-To define a page object class to wrap this HTML snippet, we extend the
-`Mache::Page` class. The only method our class needs to provide is `path`, this
-tells Mache where to go when we want to visit the page.
+To define a `WelcomePage` page object class to wrap this HTML page, we extend
+the `Mache::Page` class. The only method our class needs to provide is `path`,
+this tells Mâché where to go when we want to visit the page:
 ```ruby
 class WelcomePage < Mache::Page
@@ -38,26 +65,32 @@ class WelcomePage < Mache::Page
 end
 ```
-This is how we visit our page object:
+We can visit our welcome page using our page object:
 ```ruby
 page = WelcomePage.visit
 page.current? # true
 ```
-Any Capybara API methods will be forwarded to the underlying node:
+Mâché also handily exposes the Capybara API on our page object:
 ```ruby
 page.find("body > main").text # "lorem ipsum"
 ```
+We can also use the `node` attribute to get the underlying Capybara node object:
+```ruby
+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
 that we expect to find on the page using a CSS selector.
-Let's define a `main` element:
+Let's define a `main` element to represent the main section of our HTML page:
 ```ruby
 class WelcomePage < Mache::Page
@@ -69,7 +102,7 @@ class WelcomePage < Mache::Page
 end
 ```
-Now we can query the element on our page object:
+We can query the `main` element as an attribute of our page object:
 ```ruby
 page.has_main? # true
@@ -79,10 +112,12 @@ page.main.text # "lorem ipsum"
 ### Components
-For elements that can be shared across an number of page object classes, it may
+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 class can contain any number of elements or other
-components:
+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
@@ -90,8 +125,8 @@ class Header < Mache::Component
 end
 ```
-Our page object class can mount our component at a given CSS selector using the
-`component` macro:
+We can mount the `Header` component in our page object class at a given CSS
+selector using the `component` macro:
 ```ruby
 class WelcomePage < Mache::Page
@@ -104,7 +139,7 @@ class WelcomePage < Mache::Page
 end
 ```
-Querying a component on our page object is much the same as an element:
+Querying a component of our page object is much the same as with an element:
 ```ruby
 page.has_header? # true
@@ -114,7 +149,9 @@ page.header.title.text # "Welcome"
 ## Example
-Let's look at a more complete example for our `WelcomePage`:
+Let's look at a more complete example for our `WelcomePage`. Note that the
+`Header`, `NavItem`, and `Nav` components can be reused in any other page
+object classes we may define later for our web application.
 ```ruby
 class Header < Mache::Component
@@ -142,28 +179,29 @@ class WelcomePage < Mache::Page
 end
 ```
-We can use our page objects to write expressive tests:
+We can use our page objects to write very expressive acceptance tests:
 ```ruby
-feature "Home page" do
+feature "Welcome page" do
   let(:home_page) { WelcomePage.visit }
-  scenario "A user visits the home page" do
+  scenario "A user visits the welcome page" do
     expect(home_page).to be_current
+    # header
     expect(home_page).to have_header
     expect(home_page.header.title).to eq("Welcome")
+    # nav
     expect(home_page).to have_nav
     expect(home_page.nav).to have_items
     expect(home_page.nav.items.count).to be(3)
+    expect(home_page.nav.items[0]).to be_selected
     expect(home_page.nav.items[0].text).to eq("foo")
     expect(home_page.nav.items[1].text).to eq("bar")
     expect(home_page.nav.items[2].text).to eq("baz")
-    expect(home_page.nav.items[0]).to be_selected
+    # main
     expect(home_page.main.text).to eq("lorem ipsum")
   end
 end

data/lib/mache/component.rb CHANGED Viewed

@@ -1,6 +1,22 @@
 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

data/lib/mache/dsl.rb CHANGED Viewed

@@ -24,16 +24,18 @@ module Mache
         define_helper_methods(name, selector)
       end
-      def component(name, type, selector)
+      def component(name, klass, selector)
         define_method(name.to_s) do
-          type.new(@node.find(selector))
+          klass.new(node: @node.find(selector))
         end
         define_helper_methods(name, selector)
       end
-      def components(name, type, selector)
+      def components(name, klass, selector)
         define_method(name.to_s) do
-          @node.all(selector, minimum: 1).map { |element| type.new(element) }
+          @node.all(selector, minimum: 1).map do |element|
+            klass.new(node: element)
+          end
         end
         define_helper_methods(name, selector)
       end

data/lib/mache/node.rb CHANGED Viewed

@@ -1,17 +1,27 @@
 require "mache/dsl"
 module Mache
-  # An abstract class that wraps a capybara node object and exposes the mache
-  # DSL. It also delegates any capybara methods to the underlying node object.
+  # The Node class represents a wrapped HTML page, or fragment. It exposes all
+  # methods from the Mache {DSL}, and forwards any Capybara API methods to the
+  # {#node} object.
+  #
+  # @abstract
   class Node
     include DSL
+    # The underlying Capybara node object wrapped by this node.
+    #
+    # @return [Capybara::Node] the node object
     attr_reader :node
-    def initialize(node)
-      @node = node
+    # Returns a new instance of Node.
+    #
+    # @param node [Capybara::Node] the Capybara node object to wrap
+    def initialize(node:)
+      @node ||= node
     end
+    # Forwards any Capybara API calls to the node object.
     def method_missing(name, *args, &block)
       if @node.respond_to?(name)
         @node.send(name, *args, &block)
@@ -20,6 +30,7 @@ module Mache
       end
     end
+    # @!visibility private
     def respond_to_missing?(name, include_private = false)
       @node.respond_to?(name) || super
     end

data/lib/mache/page.rb CHANGED Viewed

@@ -2,27 +2,60 @@ require "capybara"
 require "mache/node"
 module Mache
-  # A page provides a DSL for querying a wrapped capybara node object node. A
-  # page can also has a path which can be visited.
+  # The Page class wraps an HTML page with an application-specific API. You can
+  # extend it to define your own API for manipulating the pages of your web
+  # application.
+  #
+  # @example
+  #
+  #   class WelcomePage < Mache::page
+  #     element :main, "#main"
+  #     component :nav, Nav, "#nav"
+  #   end
+  #
+  #   page = WelcomePage.new(path: "/welcome")
+  #   page.visit
+  #   page.current # true
+  #   page.main.text # lorem ipsum
+  #
   class Page < Node
+    # The path where the page is located, without any domain information.
+    #
+    # @return [String] the path string
+    # @example
+    #   "/welcome"
+    #   "/users/sign_in"
     attr_reader :path
+    # Returns a new page object.
+    #
+    # @param node [Capybara::Node] the Capybara node to attach to
+    # @param path [String] the path where the page is located
     def initialize(node: Capybara.current_session, path: nil)
       @node ||= node
       @path ||= path
     end
+    # Visits the page at its {#path}.
+    #
+    # @return [Page] the page object
     def visit
       @node.visit(path)
       self
     end
+    # Tests whether the page is current.
+    #
+    # @return [Boolean] `true` if the page is current, `false` otherwise
     def current?
       @node.current_path == path
     end
+    # Creates a new page object and calls {#visit} on it.
+    #
+    # @return [Page] the page object
     def self.visit
-      new.tap(&:visit)
+      new.visit
     end
   end
 end

data/lib/mache/version.rb CHANGED Viewed

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

data/mache.gemspec CHANGED Viewed

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.version = Mache::VERSION
   spec.authors = ["Joshua Bassett"]
   spec.email = ["josh.bassett@gmail.com"]
-  spec.summary = "A page object library for writing cleaner acceptance tests with Capybara."
-  spec.description = "Mache provides a DSL for writing page object clases to use in your acceptance tests."
+  spec.summary = "A library for writing cleaner and more expressive acceptance tests using page objects."
+  spec.description = "Mâché provides helps you to write cleaner and more expressive acceptance tests for your web applications using page objects."
   spec.homepage = "https://github.com/nullobject/mache"
   spec.license = "MIT"
   spec.files = `git ls-files -z`.split("\x0").reject do |f|

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mache
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Joshua Bassett
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2017-03-07 00:00:00.000000000 Z
+date: 2017-03-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capybara
@@ -94,8 +94,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.47'
-description: Mache provides a DSL for writing page object clases to use in your acceptance
-  tests.
+description: Mâché provides helps you to write cleaner and more expressive acceptance
+  tests for your web applications using page objects.
 email:
 - josh.bassett@gmail.com
 executables: []
@@ -107,6 +107,7 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE
 - README.md
@@ -142,5 +143,6 @@ rubyforge_project:
 rubygems_version: 2.5.2
 signing_key:
 specification_version: 4
-summary: A page object library for writing cleaner acceptance tests with Capybara.
+summary: A library for writing cleaner and more expressive acceptance tests using
+  page objects.
 test_files: []