testable 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0b41932f26b804cd3a7216914b135ed21c72e716734b485452d8ba89fade529
-  data.tar.gz: f0b824f615eebe4edd4520f1c1705ee50dc76a6efd2ba7c5281931e42910b162
+  metadata.gz: c59c802e12f855543871b0917b7043a6dca602714c79cf5624d0033b86f8ce68
+  data.tar.gz: 3011ecba1297734eff0491ce54f4b8192bc5bdafe61b2736598af3649b790455
 SHA512:
-  metadata.gz: fa8a4ac245684d7b7ac89104534eb2aa285779c2ed1b064c04fe2a248d73f56cf16b7fc9fab5c593cd37f3e270759aa4e13227418c04e1a4d926eb68a921aa6d
-  data.tar.gz: ec136ec9fb01d955d3e40f2984a10764d03a5e7eb2a9c32a804a40f1db3cf17af856ad778ecd3b48f8b7f6e8d3ae7652accffe77b73eaac5b40c37d738da3190
+  metadata.gz: c9b98f008221c0bd278f690f6aee6fe32c5ea84ffe3c55a977d015ef25100846291bf9a753080caffec7e13d8fcc81f9f3e757cdf7e9f980ab4ce0abf8289ae0
+  data.tar.gz: b977fd589e01f32b48af6ed449087c2a3db1d05ed0aa0f87ee2b74d876259695b61ec0d117f1691f426b77f285ed7809876324243fd0e1e2d42fdee5436df903

data/.hound.yml

@@ -2,6 +2,7 @@ AllCops:
   Exclude:
     - testable.gemspec
     - spec/**/*
+    - examples/**/*
 
 # Removing need for frozen string literal comment.
 Style/FrozenStringLiteralComment:
@@ -75,3 +76,12 @@ Naming/PredicateName:
   NameWhitelist:
     - has_correct_title?
     - has_correct_url?
+
+# Sometimes this seems like a better way to do things.
+Style/DoubleNegation:
+  Enabled: false
+
+# This is entirely for the addition of the match? method to String
+# and that's only needed if you are using an outdated Ruby.
+Style/MultilineIfModifier:
+  Enabled: False

data/README.md

@@ -1,14 +1,16 @@
 # Testable
 
-Testable is an automated test micro-framework that provides a thin wrapper around [Watir](http://watir.com/) and [Capybara](http://teamcapybara.github.io/capybara/). Testable is based on many ideas from tools like [SitePrism](https://github.com/natritmeyer/site_prism) and [Watirsome](https://github.com/p0deje/watirsome), while also being a logical evolution of my own tool, [Tapestry](https://github.com/jeffnyman/tapestry).
-
-An automated test framework provides a machine-executable abstraction around testing and encodes a set of guiding principles and heuristics for writing tests-as-code.
+> **Testable /ˈtestəb(ə)l/**
+>
+> _adjective_
+>
+> _able to be tested or tried._
 
-One of the obstacles to covering the gap between principles of testing and the practice of testing is the mechanics of writing tests. These mechanics are focused on abstractions. A lot of the practice of testing comes down to that: finding the right abstractions. Any automated test framework should be capable of consuming your preferred abstractions because ultimately your automation is simply a tool that supports testing, which means how the framework encourages tests to be expressed should have high fidelty with how human tests would be expressed.
+----
 
-Testable is built, as are all of my test-supporting tools, on the idea that automation should largely be small-footprint, low-fiction, and high-yield.
+Testable is an automated test micro-framework that provides a thin wrapper around [Watir](http://watir.com/) and [Capybara](http://teamcapybara.github.io/capybara/). Testable is based on many ideas from tools like [SitePrism](https://github.com/natritmeyer/site_prism) and [Watirsome](https://github.com/p0deje/watirsome), while also being a logical evolution of my own tool, [Tapestry](https://github.com/jeffnyman/tapestry).
 
-The code that a test-supporting micro-framework allows should be modular, promoting both high cohesion and low coupling, as well as promoting a single level of abstraction. These concepts together lead to lightweight design as well as support traits that make change affordable. That makes the automation code less expensive to maintain and easier to change. That, ultimately, has a positive impact on the cost of change but, more importantly, allows Testable to be fit within a cost of mistake model, where the goal is to get feedback as quickly as possible regarding when mistakes are made.
+One of the core goals of Testable is to be a mediating influence between higher-level tests (acceptance criteria) and lower-level implementations of those tests. You can see some of the design principles for more details on what guided construction.
 
 ## Installation
 
@@ -34,7 +36,21 @@ You can also install Testable just as you would any other gem:
 
 ## Usage
 
-Instructions coming soon.
+Instructions will be coming soon. However, there are a series of scripts in the `examples` directory and a series of commands in the `Rakefile` that will let you execute those scripts.
+
+## Design Principles
+
+An automated test framework provides a machine-executable abstraction around testing and encodes a set of guiding principles and heuristics for writing tests-as-code.
+
+One of the obstacles to covering the gap between principles of testing and the practice of testing is the mechanics of writing tests. These mechanics are focused on abstractions. A lot of the practice of testing comes down to that: finding the right abstractions.
+
+An automated test framework should be capable of consuming your preferred abstractions because ultimately the automation is simply a tool that supports testing, which means how the framework encourages tests to be expressed should have high fidelity with how human tests would be expressed.
+
+Testable is built around the the idea that automation should largely be small-footprint, low-fiction, and high-yield.
+
+The code that a test-supporting micro-framework allows should be modular, promoting both high cohesion and low coupling, as well as promoting a single level of abstraction. These concepts together lead to lightweight design as well as support traits that make change affordable for tests.
+
+That makes the automation code less expensive to maintain and easier to change. That, ultimately, has a positive impact on the cost of change but, more importantly, allows Testable to be fit within a cost of mistake model, where the goal is to get feedback as quickly as possible regarding when mistakes are made.
 
 ## Development
 

data/Rakefile

@@ -16,6 +16,18 @@ namespace :script_testable do
   end
 end
 
+namespace :script_capybara do
+  desc "Run the Testable Capybara script"
+  task :capybara do
+    system("ruby ./examples/testable-capybara.rb")
+  end
+
+  desc "Run the Testable Capybara context script"
+  task :context do
+    system("ruby ./examples/testable-capybara-context.rb")
+  end
+end
+
 namespace :script_watir do
   desc "Run the Testable Watir script"
   task :watir do
@@ -26,6 +38,26 @@ namespace :script_watir do
   task :test do
     system("ruby ./examples/testable-watir-test.rb")
   end
+
+  desc "Run the Testable Watir context script"
+  task :context do
+    system("ruby ./examples/testable-watir-context.rb")
+  end
+
+  desc "Run the Testable Watir events script"
+  task :events do
+    system("ruby ./examples/testable-watir-events.rb")
+  end
+
+  desc "Run the Testable Watir ready script"
+  task :ready do
+    system("ruby ./examples/testable-watir-ready.rb")
+  end
+
+  desc "Run the Testable Watir data setter script"
+  task :dataset do
+    system("ruby ./examples/testable-watir-datasetter.rb")
+  end
 end
 
 namespace :spec do

data/examples/testable-capybara-context.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+$LOAD_PATH << "./lib"
+
+require "rspec"
+include RSpec::Matchers
+
+require "testable"
+include Testable::Context
+
+Capybara.configure do |config|
+  config.run_server = false
+  config.default_driver = :selenium
+  config.app_host = "https://veilus.herokuapp.com"
+end
+
+class HomePage < Testable::Page
+  element :login_form, "#open"
+  element :username,   "#username"
+  element :password,   "#password"
+  element :login,      "#login-button"
+
+  def path
+    "/"
+  end
+
+  def login_as_admin
+    login_form.click
+    username.set "admin"
+    password.set "admin"
+    login.click
+  end
+end
+
+class Navigation < Testable::Node
+  elements :items, "a"
+
+  element :page_list, "#navlist"
+  element :overlord,  "#overlord"
+  element :planets,   "#planets"
+  element :warp,      "#warp"
+  element :stardate,  "#stardate"
+end
+
+class MenuItem < Testable::Node
+  components :items, Navigation, "#areas"
+end
+
+class LandingPage < Testable::Page
+  component :navigation, Navigation, "#areas"
+  element :logo, "#site-image"
+end
+
+on_visit(HomePage).login_as_admin
+
+on(LandingPage) do |action|
+  action.navigation.page_list.click
+  puts action.navigation.overlord.text
+  puts action.navigation.items
+  puts action.navigation.items[0].text
+  expect(action.navigation).to have_items
+  expect(action.navigation.items[0].text).to eq("Home")
+  expect(action.navigation.items.count).to be(8)
+  action.navigation.overlord.click
+end

data/examples/testable-capybara-rspec.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+$LOAD_PATH << "./lib"
+
+# Run this with:
+# rspec ./examples/testable-capybara-rspec.rb
+
+require "rspec"
+include RSpec::Matchers
+
+require "testable"
+include Testable::Context
+
+require "capybara/rspec"
+
+RSpec.configure do |config|
+  config.expose_dsl_globally = true
+end
+
+Capybara.configure do |config|
+  config.run_server = false
+  config.default_driver = :selenium
+  config.app_host = "https://veilus.herokuapp.com"
+end
+
+class HomePage < Testable::Page
+  element :login_form, "#open"
+  element :username,   "#username"
+  element :password,   "#password"
+  element :login,      "#login-button"
+
+  def path
+    "/"
+  end
+
+  def login_as_admin
+    login_form.click
+    username.set "admin"
+    password.set "admin"
+    login.click
+  end
+end
+
+class Navigation < Testable::Node
+  elements :items, "a"
+
+  element :page_list, "#navlist"
+  element :overlord,  "#overlord"
+  element :planets,   "#planets"
+  element :warp,      "#warp"
+  element :stardate,  "#stardate"
+end
+
+class LandingPage < Testable::Page
+  component :navigation, Navigation, "#areas"
+
+  def go_to_overlord
+    navigation.page_list.click
+    navigation.overlord.click
+  end
+end
+
+feature "navigation" do
+  background do
+    on_visit(HomePage).login_as_admin
+  end
+
+  scenario "navigates to overlord" do
+    on(LandingPage).go_to_overlord
+  end
+end

data/examples/testable-capybara.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+$LOAD_PATH << "./lib"
+
+require "rspec"
+include RSpec::Matchers
+
+require "testable"
+
+Capybara.configure do |config|
+  config.run_server = false
+  config.default_driver = :selenium
+  config.app_host = "https://veilus.herokuapp.com"
+end
+
+class HomePage < Testable::Page
+  element :login_form, "#open"
+  element :username,   "#username"
+  element :password,   "#password"
+  element :login,      "#login-button"
+
+  def path
+    "/"
+  end
+end
+
+home_page = HomePage.visit
+
+puts home_page.current?
+expect(home_page).to be_current
+
+puts home_page.find("article").text
+
+puts home_page.login_form.inspect
+
+puts home_page.has_login_form?
+puts home_page.has_no_login_form?
+
+expect(home_page).to have_login_form
+
+# The next statement would (correctly) fail.
+# expect(home_page).to have_no_login_form
+
+home_page.login_form.click
+home_page.username.set "admin"
+home_page.password.set "admin"
+home_page.login.click

data/examples/testable-watir-context.rb

@@ -50,11 +50,11 @@ end
 Testable.start_browser :firefox
 
 on_visit(Home) do
-  @active.login_form.click
-  @active.username.set "admin"
-  @active.password(id: 'password').set "admin"
-  @active.login.click
-  expect(@active.message.text).to eq('You are now logged in as admin.')
+  @context.login_form.click
+  @context.username.set "admin"
+  @context.password(id: 'password').set "admin"
+  @context.login.click
+  expect(@context.message.text).to eq('You are now logged in as admin.')
 end
 
 on(Navigation) do |page|

data/lib/testable/capybara/dsl.rb

@@ -0,0 +1,82 @@
+module Testable
+  module DSL
+    # The DSL module is mixed into the Node class to provide the DSL for
+    # defining elements and components.
+    def self.included(caller)
+      caller.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # The ClassMethods provide a set of macro-like methods for wrapping
+      # HTML fragments in Node objects.
+
+      # Defines an element that wraps an HTML fragment.
+      def element(name, selector, options = {})
+        define_method(name.to_s) do
+          Node.new(node: @node.find(selector, options))
+        end
+
+        define_helpers(name, selector)
+      end
+
+      # Defines a collection of elements that wrap HTML fragments.
+      def elements(name, selector, options = {})
+        options = { minimum: 1 }.merge(options)
+
+        define_method(name.to_s) do
+          @node.all(selector, options).map do |node|
+            Node.new(node: node)
+          end
+        end
+
+        define_helpers(name, selector)
+      end
+
+      # Defines a component that wraps an HTML fragment.
+      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, options))
+        end
+
+        define_helpers(name, selector)
+      end
+
+      # Defines a collection of components that wrap HTML fragments.
+      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, options).map do |node|
+            klass.new(node: node)
+          end
+        end
+
+        define_helpers(name, selector)
+      end
+
+      private
+
+      def define_helpers(name, selector)
+        define_existence_predicates(name, selector)
+      end
+
+      def define_existence_predicates(name, selector)
+        define_method("has_#{name}?") do
+          @node.has_selector?(selector)
+        end
+
+        define_method("has_no_#{name}?") do
+          @node.has_no_selector?(selector)
+        end
+      end
+    end
+  end
+end

data/lib/testable/capybara/node.rb

@@ -0,0 +1,30 @@
+require "testable/capybara/dsl"
+
+module Testable
+  class Node
+    # The Node class represents a wrapped HTML page or fragment. It exposes all
+    # methods of the Cogent DSL, making sure that any Capybara API methods
+    # are passed to the node instance.
+    include DSL
+
+    attr_reader :node
+
+    # A Capybara node is being wrapped in a node instance.
+    def initialize(node:)
+      @node = node
+    end
+
+    # Any Capybara API calls will be sent to the node object.
+    def method_missing(name, *args, &block)
+      if @node.respond_to?(name)
+        @node.send(name, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @node.respond_to?(name) || super
+    end
+  end
+end

data/lib/testable/capybara/page.rb

@@ -0,0 +1,29 @@
+require "capybara"
+require "testable/capybara/node"
+
+module Testable
+  class Page < Node
+    # The `Page` class wraps an HTML page with an application-specific API.
+    # This can be extended to define an API for manipulating the pages of
+    # the web application.
+    attr_reader :path
+
+    def self.visit
+      new.visit
+    end
+
+    def initialize(node: Capybara.current_session, path: nil)
+      @node = node
+      @path = path
+    end
+
+    def visit
+      @node.visit(path)
+      self
+    end
+
+    def current?
+      @node.current_path == path
+    end
+  end
+end

data/lib/testable/context.rb

@@ -14,8 +14,8 @@ module Testable
     #    on_visit(TestPage)
     def on_visit(definition, &block)
       create_active(definition)
-      @active.visit
-      verify_page(@active)
+      @context.visit
+      verify_page(@context)
       call_block(&block)
     end
 
@@ -54,6 +54,7 @@ module Testable
     # whether a given page has been reached would make the context definition
     # look sloppy.
     def verify_page(context)
+      return unless defined?(context.url_match_attribute)
       return if context.url_match_attribute.nil?
       return if context.has_correct_url?
 
@@ -61,12 +62,12 @@ module Testable
     end
 
     def create_active(definition)
-      @active = definition.new unless @active.is_a?(definition)
+      @context = definition.new unless @context.is_a?(definition)
     end
 
     def call_block(&block)
-      yield @active if block
-      @active
+      yield @context if block
+      @context
     end
   end
 end

data/lib/testable/extensions/core_ruby.rb

@@ -0,0 +1,13 @@
+class String
+  # This is only required if using a version of Ruby before 2.4. A match?
+  # method for String was added in version 2.4.
+  def match?(string, pos = 0)
+    !!match(string, pos)
+  end unless //.respond_to?(:match?)
+end
+
+class FalseClass
+  def exists?
+    false
+  end
+end

data/lib/testable/version.rb

@@ -1,7 +1,7 @@
 module Testable
   module_function
 
-  VERSION = "0.4.0".freeze
+  VERSION = "0.5.0".freeze
 
   def version
     """

data/lib/testable.rb

@@ -6,6 +6,9 @@ require "testable/element"
 require "testable/locator"
 require "testable/attribute"
 
+require "testable/capybara/page"
+
+require "testable/extensions/core_ruby"
 require "testable/extensions/data_setter"
 require "testable/extensions/dom_observer"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: testable
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Jeff Nyman
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-08-10 00:00:00.000000000 Z
+date: 2019-08-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -156,6 +156,9 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- examples/testable-capybara-context.rb
+- examples/testable-capybara-rspec.rb
+- examples/testable-capybara.rb
 - examples/testable-info.rb
 - examples/testable-watir-context.rb
 - examples/testable-watir-datasetter.rb
@@ -165,9 +168,13 @@ files:
 - examples/testable-watir.rb
 - lib/testable.rb
 - lib/testable/attribute.rb
+- lib/testable/capybara/dsl.rb
+- lib/testable/capybara/node.rb
+- lib/testable/capybara/page.rb
 - lib/testable/context.rb
 - lib/testable/element.rb
 - lib/testable/errors.rb
+- lib/testable/extensions/core_ruby.rb
 - lib/testable/extensions/data_setter.rb
 - lib/testable/extensions/dom_observer.js
 - lib/testable/extensions/dom_observer.rb
@@ -185,7 +192,7 @@ metadata:
   source_code_uri: https://github.com/jeffnyman/testable
   changelog_uri: https://github.com/jeffnyman/testable/blob/master/CHANGELOG.md
 post_install_message: "\n(::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::)\n
-  \ Testable 0.4.0 has been installed.\n(::) (::) (::) (::) (::) (::) (::) (::) (::)
+  \ Testable 0.5.0 has been installed.\n(::) (::) (::) (::) (::) (::) (::) (::) (::)
   (::) (::) (::)\n  "
 rdoc_options: []
 require_paths: