testable 0.3.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 9fe925fea55efebca8a07a490fb639669355cecf
-  data.tar.gz: 750388f14ff7df442cba5c4abb60ea51125a70c6
+SHA256:
+  metadata.gz: '083ac4911fb96ee2707e3946552a38db979b4c33d6b09442aa16a6a8cd4acdb1'
+  data.tar.gz: 0c9c0ccfab44a16c9536e312b3dd3c9e2bef3d14bd7a9e00e16bdad653421fc7
 SHA512:
-  metadata.gz: 4ae956962245d4326c31028c59b96fb060d1e46765d8db56309eadfe8460bb308a79876bfcafaa57fdfde38ad9e2a9c676c83c10ce9f7eef8df231a3938d0c57
-  data.tar.gz: 2b986d69188ff6df56efe57e3dbb5724d83ed21bc6aefc0acb19198ad2e3f8b8da21dbf1c9aa31b7cdbbce156757528bed75d1f116c635c9f66b0cc736c19598
+  metadata.gz: 11c1aafcde6440266d55a64ea3b8b042aa6ad79ca3e6b7295496876841b14b28dab980a74df42de0407313fecf96c558aeb8b8c2c5ba1e074447931bc6011621
+  data.tar.gz: cc5f40958a85ed215afce15a5377d7e4b34743bce463f8391c02976ab7330bd2e19b55681c3894a54870b7dd97447a42acc90275360063a6b09e17480e727e46

data/.gitignore

@@ -1,41 +1,53 @@
-# Ruby-Specific
+# Testable Generated
 
+testable.log
+
+# 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
-
-# Mac OS-Specific
+# IDE Files
 
-*.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,8 +1,8 @@
 AllCops:
   Exclude:
     - testable.gemspec
-    - test/*.rb
     - spec/**/*
+    - examples/**/*
 
 # Removing need for frozen string literal comment.
 Style/FrozenStringLiteralComment:
@@ -30,15 +30,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 +46,42 @@ 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?
+
+# 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/.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,22 @@
 # Testable
 
-[![Build Status](https://circleci.com/gh/jeffnyman/testable.svg?style=shield)](https://circleci.com/gh/jeffnyman/testable)
+> **Testable /ˈtestəb(ə)l/**
+>
+> _adjective_
+>
+> _able to be tested or tried._
+
+----
+
 [![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)
+[![License](http://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/jeffnyman/testable/blob/master/LICENSE.md)
 
-[![Dependency Status](https://gemnasium.com/jeffnyman/testable.png)](https://gemnasium.com/jeffnyman/testable)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://rubydoc.info/github/jeffnyman/testable/master/frames)
+[![Inline docs](http://inch-ci.org/github/jeffnyman/testable.png)](http://inch-ci.org/github/jeffnyman/github)
 
-The Testable gem aims to be a micro-framework that will provide a semantic DSL to construct a fluent interface for test execution libraries.
+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).
 
-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.
+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,22 +42,31 @@ 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:
+Probably the best way to get a feel for the current state of the code is to look at the examples:
+
+* [Testable Info](https://github.com/jeffnyman/testable/blob/master/examples/testable-info.rb)
+* [Testable Basics](https://github.com/jeffnyman/testable/blob/master/examples/testable-watir.rb)
+* [Testable Watir](https://github.com/jeffnyman/testable/blob/master/examples/testable-watir-test.rb)
+* [Testable Context](https://github.com/jeffnyman/testable/blob/master/examples/testable-watir-context.rb)
+* [Ready script](https://github.com/jeffnyman/testable/blob/master/examples/testable-watir-ready.rb)
+* [Events script](https://github.com/jeffnyman/testable/blob/master/examples/testable-watir-events.rb)
+* [Data setter script](https://github.com/jeffnyman/testable/blob/master/examples/testable-watir-datasetter.rb)
 
-* [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)
+You'll see references to "Veilus" and a "localhost" in the script. I'm using my own [Veilus application](https://veilus.herokuapp.com/). As far as the localhost, you can use the [Veilus repo](https://github.com/jeffnyman/veilus) to get a local copy to play around with.
 
-If you clone the repository, you can see this script in action by running the command `rake script:standard` or `rake script:factory`.
+## Design Principles
 
-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.
+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.
 
-More details will be forthcoming as the project evolves.
+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.
 
-## Implementation Ideas
+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.
 
-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.
+Testable is built around the the idea that automation should largely be small-footprint, low-fiction, and high-yield.
 
-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.
+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
 
@@ -61,9 +78,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 +99,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,62 @@
 #!/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_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
+    system("ruby ./examples/testable-watir.rb")
+  end
+
+  desc "Run the Testable Watir example test"
+  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 factory script"
-  task :factory do
-    system("ruby ./test/testable-factory.rb")
+  desc "Run the Testable Watir data setter script"
+  task :dataset do
+    system("ruby ./examples/testable-watir-datasetter.rb")
   end
 end
 
@@ -24,12 +64,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-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