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

mache 1.0.0 → 1.0.1

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: []