testable 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 9fe925fea55efebca8a07a490fb639669355cecf
-  data.tar.gz: 750388f14ff7df442cba5c4abb60ea51125a70c6
+SHA256:
+  metadata.gz: f0b41932f26b804cd3a7216914b135ed21c72e716734b485452d8ba89fade529
+  data.tar.gz: f0b824f615eebe4edd4520f1c1705ee50dc76a6efd2ba7c5281931e42910b162
 SHA512:
-  metadata.gz: 4ae956962245d4326c31028c59b96fb060d1e46765d8db56309eadfe8460bb308a79876bfcafaa57fdfde38ad9e2a9c676c83c10ce9f7eef8df231a3938d0c57
-  data.tar.gz: 2b986d69188ff6df56efe57e3dbb5724d83ed21bc6aefc0acb19198ad2e3f8b8da21dbf1c9aa31b7cdbbce156757528bed75d1f116c635c9f66b0cc736c19598
+  metadata.gz: fa8a4ac245684d7b7ac89104534eb2aa285779c2ed1b064c04fe2a248d73f56cf16b7fc9fab5c593cd37f3e270759aa4e13227418c04e1a4d926eb68a921aa6d
+  data.tar.gz: ec136ec9fb01d955d3e40f2984a10764d03a5e7eb2a9c32a804a40f1db3cf17af856ad778ecd3b48f8b7f6e8d3ae7652accffe77b73eaac5b40c37d738da3190

data/.gitignore

@@ -1,41 +1,49 @@
-# Ruby-Specific
+# Ruby Generated
 
+/Gemfile.lock
 /.bundle/
 /.yardoc
-/Gemfile.lock
 /_yardoc/
-
-# Ouput-Specific
-
 /coverage/
 /doc/
 /pkg/
 /spec/reports/
-/spec/examples.txt
+/spec/coverage/
 /tmp/
-*.log
-*.tmp
-*.swp
-*.bak
 
-# IDE-Specific
+# Generated Reports
+reports/
 
-.idea
-.settings
-.project
-.classpath
-*.iws
+# Rspec Failure Tracking
 
-# Windows-Specific
+.rspec_status
 
-Thumbs.db
+# IDE Files
 
-# Mac OS-Specific
-
-*.DS_Store
-._*
+.idea/
+*.iml
+*.iws
+*.ipr
+.vscode/
+.settings/
+.metadata
+.classpath
+.loadpath
+.buildpath
+.project
 
-# Linux-Specific
+# OS Files
 
-.directory
-.Trash-*
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+$RECYCLE.BIN/
+Desktop.ini
+*.tmp
+*.bak
+*.swp
+*~.nib

data/.hound.yml

@@ -1,7 +1,6 @@
 AllCops:
   Exclude:
     - testable.gemspec
-    - test/*.rb
     - spec/**/*
 
 # Removing need for frozen string literal comment.
@@ -30,15 +29,15 @@ Style/SignalException:
   Enabled: false
 
 # This never works for validations.
-Style/AlignHash:
+Layout/AlignHash:
   EnforcedLastArgumentHashStyle: ignore_implicit
 
 # Align multi-line params with previous line.
-Style/AlignParameters:
+Layout/AlignParameters:
   EnforcedStyle: with_fixed_indentation
 
 # Indent `when` clause one step from `case`.
-Style/CaseIndentation:
+Layout/CaseIndentation:
   IndentOneStep: true
 
 # Don't force bad var names for reduce/inject loops.
@@ -46,23 +45,33 @@ Style/SingleLineBlockParams:
   Enabled: false
 
 # For method chains, keep the dot with the method name.
-Style/DotPosition:
+Layout/DotPosition:
   EnforcedStyle: leading
 
-# Allow methods with has_ for predicates.
-Style/PredicateName:
-  NameWhitelist:
-    - has_correct_url?
-    - has_correct_title?
-
 # Stop nesting so hard.
 Metrics/BlockNesting:
   Max: 2
 
 # Encourage short methods.
 Metrics/MethodLength:
-  Max: 10
+  Max: 15
+
+# Encourage short (as possible) modules.
+Metrics/ModuleLength:
+  Max: 100
 
 # Encourage fewer parameters.
 Metrics/ParameterLists:
   Max: 4
+
+# Remove execute permissions check.
+Lint/ScriptPermission:
+  Enabled: false
+
+# Testable Exceptions
+
+# Allow methods with has_ for predicates.
+Naming/PredicateName:
+  NameWhitelist:
+    - has_correct_title?
+    - has_correct_url?

data/.rubocop.yml

@@ -1,2 +1,6 @@
+inherit_mode:
+  merge:
+    - Exclude
+
 inherit_from:
   - .hound.yml

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.3.4
+before_install: gem install bundler -v 2.0.2

data/CODE_OF_CONDUCT.md

@@ -55,7 +55,7 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at jeffnyman@gmail.com. All
+reported by contacting the project team at TODO: Write your email address. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.

data/Gemfile

@@ -1,4 +1,6 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
+
+gem "coveralls", require: false
 
 # Specify your gem's dependencies in testable.gemspec
 gemspec

data/{LICENSE.txt → LICENSE.md}

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+**The MIT License (MIT)**
 
-Copyright (c) 2016 Jeff Nyman
+Copyright © 2019 Jeff Nyman
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,14 +1,14 @@
 # Testable
 
-[![Build Status](https://circleci.com/gh/jeffnyman/testable.svg?style=shield)](https://circleci.com/gh/jeffnyman/testable)
-[![Gem Version](https://badge.fury.io/rb/testable.svg)](http://badge.fury.io/rb/testable)
-[![License](http://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jeffnyman/testable/blob/master/LICENSE.txt)
+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).
 
-[![Dependency Status](https://gemnasium.com/jeffnyman/testable.png)](https://gemnasium.com/jeffnyman/testable)
+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.
 
-The Testable gem aims to be a micro-framework that will provide a semantic DSL to construct a fluent interface for test execution libraries.
+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.
 
-This fluent interface promotes the idea of compressibility of your test logic, allowing for more factoring, more reuse, and less repetition. You can use Testable directly as an automated test library or you can use it with other tools such as RSpec, Cucumber, or anything else that allows you to delegate down to a different level of abstraction.
+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.
+
+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.
 
 ## Installation
 
@@ -34,22 +34,7 @@ You can also install Testable just as you would any other gem:
 
 ## Usage
 
-Probably the best way to get a feel for the current state of the code is to look at the test scripts:
-
-* [Standard test script](https://github.com/jeffnyman/testable/blob/master/test/testable-standard.rb)
-* [Factory test script](https://github.com/jeffnyman/testable/blob/master/test/testable-factory.rb)
-
-If you clone the repository, you can see this script in action by running the command `rake script:standard` or `rake script:factory`.
-
-You'll see references to "Veilus" and a localhost URL. I'm using my own [Veilus application](https://veilus.herokuapp.com/). The localhost refers to using the [Veilus repo](https://github.com/jeffnyman/veilus) locally.
-
-More details will be forthcoming as the project evolves.
-
-## Implementation Ideas
-
-I want to hide driver details (i.e., Selenium) as much as possible but still allow access to the full API. Ideally I'd like to avoid the low-level Selenium and use a wrapper around it while not inventing my own. Since both watir-webdriver and capybara delegate down to Selenium, it seems wise to use one of those. (Or maybe allow for both as Symbiont currently does.) An open question is whether I should proxy the driver library to my own implementation or not. Symbiont currently does exactly that, which is a very different model than [page-object](https://github.com/cheezy/page-object), which has to add an incredible amount of wasted code rather than just relying on delegation and a proxy pattern.
-
-I don't want to presume a particular modeling structure, such as the use of page objects. That being said, most such modeling structures are really just classes that are being utilized in a certain way, which means I really want to model the more generic notion of an interface. An interface could, theoretically, be an application (screens), a site (pages), or an API (services). An interface would be a Screen class, a Page class, or a Service class. These then become screen objects, page objects or service objects. An open question is how those distinctions are purely conceptual versus have specific implementations.
+Instructions coming soon.
 
 ## Development
 
@@ -61,9 +46,11 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at [https://github.com/jeffnyman/testable](https://github.com/jeffnyman/testable). The testing ecosystem of Ruby is very large and this project is intended to be a welcoming arena for collaboration on yet another testing tool. As such, contributors are very much welcome but are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at [https://github.com/jeffnyman/testable](https://github.com/jeffnyman/testable). The testing ecosystem of Ruby is very large and this project is intended to be a welcoming arena for collaboration on yet another test-supporting tool.
+
+Everyone interacting in the Testable project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/jeffnyman/testable/blob/master/CODE_OF_CONDUCT.md).
 
-This gem follows [semantic versioning](http://semver.org).
+The Testable gem follows [semantic versioning](http://semver.org).
 
 To contribute to Testable:
 
@@ -80,4 +67,4 @@ To contribute to Testable:
 ## License
 
 Testable is distributed under the [MIT](http://www.opensource.org/licenses/MIT) license.
-See the [LICENSE](https://github.com/jeffnyman/testable/blob/master/LICENSE.txt) file for details.
+See the [LICENSE](https://github.com/jeffnyman/testable/blob/master/LICENSE.md) file for details.

data/Rakefile

@@ -1,22 +1,30 @@
 #!/usr/bin/env rake
 require "bundler/gem_tasks"
+
 require "rdoc/task"
-require "rspec/core/rake_task"
 require "rubocop/rake_task"
+require "rspec/core/rake_task"
 
 RuboCop::RakeTask.new
 
 RSpec::Core::RakeTask.new(:spec)
 
-namespace :script do
-  desc "Run the Testable standard script"
-  task :standard do
-    system("ruby ./test/testable-standard.rb")
+namespace :script_testable do
+  desc "Run the Testable info script"
+  task :info do
+    system("ruby ./examples/testable-info.rb")
+  end
+end
+
+namespace :script_watir do
+  desc "Run the Testable Watir script"
+  task :watir do
+    system("ruby ./examples/testable-watir.rb")
   end
 
-  desc "Run the Testable factory script"
-  task :factory do
-    system("ruby ./test/testable-factory.rb")
+  desc "Run the Testable Watir example test"
+  task :test do
+    system("ruby ./examples/testable-watir-test.rb")
   end
 end
 
@@ -24,12 +32,13 @@ namespace :spec do
   desc 'Clean all generated reports'
   task :clean do
     system('rm -rf spec/reports')
+    system('rm -rf spec/coverage')
   end
 
   RSpec::Core::RakeTask.new(all: :clean) do |config|
-    options  = %w(--color)
-    options += %w(--format documentation)
-    options += %w(--format html --out spec/reports/unit-test-report.html)
+    options  = %w[--color]
+    options += %w[--format documentation]
+    options += %w[--format html --out spec/reports/unit-test-report.html]
 
     config.rspec_opts = options
   end

data/bin/console

@@ -9,5 +9,5 @@ require "testable"
 require "pry"
 Pry.start
 
-# require "irb"
-# IRB.start
+require "irb"
+IRB.start(__FILE__)

data/examples/testable-info.rb

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby
+$LOAD_PATH << "./lib"
+
+require "testable"
+
+require "rspec"
+# rubocop:disable Style/MixinUsage
+include RSpec::Matchers
+# rubocop:enable Style/MixinUsage
+
+puts Testable::VERSION
+
+puts "================================="
+puts "Testable's Version"
+puts "================================="
+puts Testable.version
+
+puts "================================="
+puts "Testable's Dependencies"
+puts "================================="
+puts Testable.dependencies
+
+puts "================================="
+puts "Testable's API"
+puts "================================="
+puts Testable.api
+
+class Home
+  include Testable
+end
+
+Testable.start_browser :firefox, headless: true
+
+page = Home.new
+
+expect(Testable.browser).to be_an_instance_of(Watir::Browser)
+expect(Testable.browser.driver).to be_an_instance_of(
+  Selenium::WebDriver::Firefox::Marionette::Driver
+)
+
+expect(page).to be_a_kind_of(Testable)
+expect(page).to be_an_instance_of(Home)
+
+puts "================================="
+puts "Testable's Watir API"
+puts "================================="
+puts Testable.watir_api
+
+puts "================================="
+puts "Testable's Selenium API"
+puts "================================="
+puts Testable.selenium_api
+
+puts "================================="
+puts "Testable's Definition API"
+puts "================================="
+puts page.definition_api
+
+puts "================================="
+puts "Testable's Elements"
+puts "================================="
+puts Testable.elements?
+puts Testable.recognizes?("div")
+
+Testable.quit_browser

data/examples/testable-watir-context.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+$LOAD_PATH << "./lib"
+
+require "rspec"
+# rubocop:disable Style/MixinUsage
+include RSpec::Matchers
+# rubocop:enable Style/MixinUsage
+
+require "testable"
+# rubocop:disable Style/MixinUsage
+include Testable::Context
+# rubocop:enable Style/MixinUsage
+
+class Home
+  include Testable
+
+  url_is "https://veilus.herokuapp.com/"
+  url_matches(/heroku/)
+  title_is "Veilus"
+
+  # Elements can be defined with HTML-style names as found in Watir.
+  p          :login_form, id:    "open", visible: true
+  text_field :username,   id:    "username"
+  text_field :password
+  button     :login,      id:    "login-button"
+  div        :message,    class: "notice"
+
+  # Elements can be defined with a generic name.
+  # element :login_form, id:    "open", visible: true
+  # element :username,   id:    "username"
+  # element :password
+  # element :login,      id:    "login-button"
+  # element :message,    class: "notice"
+
+  def begin_with
+    move_to(0, 0)
+    resize_to(screen_width, screen_height)
+  end
+end
+
+class Navigation
+  include Testable
+
+  p     :page_list,     id: "navlist"
+  link  :planets,       id: "planets"
+
+  image :planet_logo,   id: "planet-logo"
+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.')
+end
+
+on(Navigation) do |page|
+  page.page_list.click
+  # page.page_list.wait_until(&:dom_updated?).click
+  page.planets.click
+  expect(page.planet_logo.exists?).to be true
+end
+
+Testable.quit_browser

data/examples/testable-watir-datasetter.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+$LOAD_PATH << "./lib"
+
+require "rspec"
+# rubocop:disable Style/MixinUsage
+include RSpec::Matchers
+# rubocop:enable Style/MixinUsage
+
+require "testable"
+# rubocop:disable Style/MixinUsage
+include Testable::Context
+# rubocop:enable Style/MixinUsage
+
+class Home
+  include Testable
+
+  url_is "https://veilus.herokuapp.com/"
+
+  p          :login_form, id: "open", visible: true
+  text_field :username,   id: "username"
+  text_field :password
+  button     :login,      id: "login-button"
+  div        :message,    class: 'notice'
+
+  def begin_with
+    move_to(0, 0)
+    resize_to(screen_width, screen_height)
+  end
+end
+
+class WarpTravel
+  include Testable
+
+  url_is "https://veilus.herokuapp.com/warp"
+
+  text_field :warp_factor, id: 'warpInput'
+  text_field :velocity,    id: 'velocityInput'
+  text_field :distance,    id: 'distInput'
+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
+end
+
+on_visit(WarpTravel).using_data("warp factor": 1, velocity: 1, distance: 4.3)
+
+Testable.quit_browser

data/examples/testable-watir-events.rb

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+$LOAD_PATH << "./lib"
+
+require "rspec"
+# rubocop:disable Style/MixinUsage
+include RSpec::Matchers
+# rubocop:enable Style/MixinUsage
+
+require "testable"
+
+class Dynamic
+  include Testable
+
+  url_is "https://veilus.herokuapp.com/practice/dynamic_events"
+
+  button :long,  id: 'long'
+  button :quick, id: 'quick'
+  button :stale, id: 'stale'
+  button :fade,  id: 'fade'
+
+  div :dom_events,    id: 'container1'
+  div :stale_event,   id: 'container2'
+  div :effect_events, id: 'container3'
+end
+
+Testable.start_browser :firefox
+
+page = Dynamic.new
+
+page.visit
+
+expect(page.dom_events.dom_updated?).to be_truthy
+expect(page.dom_events.wait_until(&:dom_updated?).spans.count).to eq(0)
+
+page.long.click
+
+expect(page.dom_events.dom_updated?).to be_falsey
+expect(page.dom_events.wait_until(&:dom_updated?).spans.count).to eq(4)
+
+page.quick.click
+
+expect(page.dom_events.wait_until(&:dom_updated?).spans.count).to eq(23)
+
+Testable.quit_browser

data/examples/testable-watir-ready.rb

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+$LOAD_PATH << "./lib"
+
+require "rspec"
+# rubocop:disable Style/MixinUsage
+include RSpec::Matchers
+# rubocop:enable Style/MixinUsage
+
+require "testable"
+
+class PageReady
+  include Testable
+
+  url_is "https://veilus.herokuapp.com"
+
+  element :logo, id: 'site-'
+  element :login_form, id: 'openski'
+
+  page_ready { [logo.exists?, "Test Gorilla logo is not present"] }
+end
+
+Testable.start_browser :firefox
+
+page = PageReady.new
+
+page.visit
+
+# Uncomment one of these at a time to see that the page_ready part
+# is working. The element definitions above are purposely incorrect.
+
+# page.when_ready { page.login_form.click }
+# page.login_form.click
+
+Testable.quit_browser

data/examples/testable-watir-test.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+$LOAD_PATH << "./lib"
+
+require "rspec"
+# rubocop:disable Style/MixinUsage
+include RSpec::Matchers
+# rubocop:enable Style/MixinUsage
+
+require "testable"
+
+class Home
+  include Testable
+
+  url_is "https://veilus.herokuapp.com/"
+  url_matches(/heroku/)
+  title_is "Veilus"
+
+  # Elements can be defined with HTML-style names as found in Watir.
+  p          :login_form, id:    "open", visible: true
+  text_field :username,   id:    "username"
+  text_field :password
+  button     :login,      id:    "login-button"
+  div        :message,    class: "notice"
+
+  # Elements can be defined with a generic name.
+  # element :login_form, id:    "open", visible: true
+  # element :username,   id:    "username"
+  # element :password
+  # element :login,      id:    "login-button"
+  # element :message,    class: "notice"
+
+  def begin_with
+    move_to(0, 0)
+    resize_to(screen_width, screen_height)
+  end
+end
+
+class Navigation
+  include Testable
+
+  p     :page_list,     id: "navlist"
+  link  :planets,       id: "planets"
+
+  image :planet_logo,   id: "planet-logo"
+end
+
+Testable.start_browser :firefox
+
+page = Home.new
+
+page.visit
+
+page.login_form.click
+page.username.set "admin"
+page.password(id: 'password').set "admin"
+page.login.click
+expect(page.message.text).to eq('You are now logged in as admin.')
+
+page = Navigation.new
+
+page.page_list.click
+# page.page_list.wait_until(&:dom_updated?).click
+
+page.planets.click
+expect(page.planet_logo.exists?).to be true
+
+Testable.quit_browser