gless 1.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/

data/.rvmrc

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+
+# This is an RVM Project .rvmrc file, used to automatically load the ruby
+# development environment upon cd'ing into the directory
+
+# First we specify our desired <ruby>[@<gemset>], the @gemset name is optional,
+# Only full ruby name is supported here, for short names use:
+#     echo "rvm use 1.9.3" > .rvmrc
+environment_id="ruby-1.9.3-p194@gless"
+
+# Uncomment the following lines if you want to verify rvm version per project
+# rvmrc_rvm_version="1.14.12 (stable)" # 1.10.1 seams as a safe start
+# eval "$(echo ${rvm_version}.${rvmrc_rvm_version} | awk -F. '{print "[[ "$1*65536+$2*256+$3" -ge "$4*65536+$5*256+$6" ]]"}' )" || {
+#   echo "This .rvmrc file requires at least RVM ${rvmrc_rvm_version}, aborting loading."
+#   return 1
+# }
+
+# First we attempt to load the desired environment directly from the environment
+# file. This is very fast and efficient compared to running through the entire
+# CLI and selector. If you want feedback on which environment was used then
+# insert the word 'use' after --create as this triggers verbose mode.
+if [[ -d "${rvm_path:-$HOME/.rvm}/environments"
+  && -s "${rvm_path:-$HOME/.rvm}/environments/$environment_id" ]]
+then
+  \. "${rvm_path:-$HOME/.rvm}/environments/$environment_id"
+  [[ -s "${rvm_path:-$HOME/.rvm}/hooks/after_use" ]] &&
+    \. "${rvm_path:-$HOME/.rvm}/hooks/after_use" || true
+else
+  # If the environment file has not yet been created, use the RVM CLI to select.
+  rvm --create  "$environment_id" || {
+    echo "Failed to create RVM environment '${environment_id}'."
+    return 1
+  }
+fi

data/README.md

@@ -0,0 +1,242 @@
+# Gless #
+
+A wrapper for Watir (specifically watir-webdriver, which is built on
+top of selenium-webdriver) based on modelling web page and web site
+structure.  It's intended to make it easier to model complex
+application workflow in an RSpec or Cucumber web site test suite.
+
+This gem attempts to provide a more robust model for web application testing,
+on top of Watir-WebDriver which already has significant improvements over just
+Selenium or WebDriver, based on describing pages and then interacting with the
+descriptions.
+
+Feel free to contact the author at rlpowell@digitalkingdom.org
+
+## Overview And Motivation ##
+
+Gless takes Watir elements and collects them into pages.  It then
+inserts a session layer on top of the pages.  The session layer is
+in charge of knowing what page the browser is on, managing
+transitions, and checking that they worked.  On top of this sits an
+application layer, which is the code that uses Gless for its
+testing.
+
+The motivation is seperation of testing types.
+
+At the page level, which is code provided by a user of Gless, the
+code has very little error correction, and mostly consists of just
+the elements themselves, but might have some light code tying
+elements together.  For example, a "log me in" method that simply
+takes a username and password and clicks the login button, and does
+no error checking at any step, would go here.
+
+At the session level, which is part of Gless itself and if you need
+more features please send me a pull request, are various functions
+to do page-level error correction.  The big one here is long\_wait,
+which watches a page for changes and only moves on when it sees what
+it expects.
+
+At the application level, which is code provided by a user of Gless,
+you can write any multi-page workflows you like, without having to
+pay any real attention to what page your on in the code, except in
+as much as if your interactions don't match the site workflow your
+tests are likely to fail. :)  For example, a method to register an
+account from scratch and log in with it, which presumably involves
+several site pages, would go here.
+
+## An Example ##
+
+The best way to see how to use this library is to look in the
+examples/ directory, but here's some stripped down examples.
+
+A partial page definition:
+
+```ruby
+    element :home     , :link , :href => "https://github.com/"         , :validator => true , :click_destination => :LoginPage
+    element :explore  , :link , :href => "https://github.com/explore"  , :validator => true , :click_destination => :ExplorePage
+    element :search   , :link , :href => "https://github.com/search"   , :validator => true , :click_destination => :SearchPage
+
+    element :search_input  , :text_field  , :class => 'text'  , :validator => true
+    element :search_button , :button , :text => 'Search' , :validator => true
+
+    url %r{^:base_url/search}
+
+    expected_title %r{^(Code Search · GitHub|Search · \S+ · GitHub)$}
+```
+
+Given that definition, whenever the session code detects that it
+*should* be on the search page (i.e. when the "search" element is
+clicked), all of those elements will be checked for existence, the
+url will be checked, and the title will be checked.
+
+All of that is entirely automatic; the code that would trigger all
+that would just be
+
+  @session.search.click
+
+An example of page code that might use such a page definition:
+
+```ruby
+def search_for stuff
+  self.search_input.set stuff
+  self.search_button.click
+end
+```
+
+An example of applicaiton level code that might use that page level
+code (plus some other stuff not shown here):
+
+
+```ruby
+def search_and_go name
+  @session.search.click
+  @session.search_for name
+  @session.goto_repository name
+end
+```
+
+As you can see, the application level can encode extremely
+complicated actions, in this case "go to the search page, search for
+a repository, and go to that repository page", in a compact way that
+has a sensible abstraction pattern.
+
+## Writing Code Around Gless ##
+
+### Configuration File ###
+
+Gless expects you to have a configuration file named
+lib/config/development.yml (the word "development" there can be
+altered by changing the ENVIRONMENT environment variable) under your
+test application.  See examples/ for a detailed example.
+
+The parts that Gless uses directly, and hence are required:
+
+```yaml
+:global: # This tag distinguishes the global config from the per-test configs; *do not remove*
+  :debug: false
+  :thumbnails: false    # Whether to create small-ish "thumbnail" pictures on the replay page; requires the imagemagick system package and the mini_magick gem
+  :browser:
+    :type: local                # Local or remote
+    :browser: firefox   # Which browser to use
+    :port: 4444         # If remote, port to connect to the selenimu server, otherwise ignored
+```
+
+### The Pages ###
+
+All of your site page description classes *must* be descendants of Gless::BasePage.
+
+It is often useful to have your own base page class as well for
+headers and footers and so on.  See examples/ for a complete example
+as usual, but here's a partial one:
+
+
+```ruby
+rpowell@ut00-s00000> cat examples/test_github/lib/pages/test_github_base_page.rb
+module TestGithub
+  class TestGithub::BasePage < Gless::BasePage
+
+    element :home     , :link , :href => "https://github.com/"         , :validator => true , :click_destination => :LoginPage
+    element :explore  , :link , :href => "https://github.com/explore"  , :validator => true , :click_destination => :ExplorePage
+    element :search   , :link , :href => "https://github.com/search"   , :validator => true , :click_destination => :SearchPage
+    element :features , :link , :href => "https://github.com/features" , :validator => true , :click_destination => :FeaturesPage
+    element :blog     , :link , :href => "https://github.com/blog"     , :validator => true , :click_destination => :BlogPage
+
+  end
+
+  class BlogPage < TestGithub::BasePage
+
+    url %r{^:base_url/blog$}
+
+    expected_title 'The Official GitHub Blog · GitHub'
+
+    # Stub page, but BasePage stuff still works
+
+  end
+end
+```
+
+### The Application ###
+
+Your application layer that sits on top of Gless must itself have
+certain features, as other aspects of Gless do call back into the
+application layer and/or make use of it.  Here's some minimal
+boilerplate that you should start with:
+
+```ruby
+module TestGithub
+
+  class TestGithub::Application
+    include RSpec::Matchers
+
+    attr_accessor :browser
+    attr_accessor :session
+    attr_accessor :site
+    attr_accessor :base_url
+
+    def initialize( browser, config, logger )
+      @logger = logger
+      @browser = browser
+      @config = config
+
+      @session = Gless::Session.new( @browser, @config, @logger, self )
+
+      @session.should be_true
+    end
+end
+```
+
+## Debugging Gless Applications/Tests ##
+
+If your configuration file has ":debug: true", then Gless will
+produce some pretty verbose logging of what it's doing.
+
+A less crazy version is ":verbose: true".
+
+It will also create a replay log directory which is intended to be
+viewed in a browser.  The directory location defaults to
+~/public_html/watir_replay/test/ ; the initialization of
+Gless::Logger determines that location.  Most actions that Gless
+performs will cause the replay log to be updated a copy of the HTML
+source as Gless/Watir/Selenium/WebDriver sees it.
+
+If you have ":screenshots: true" (along with debugging), screenshots
+will also be taken showing the visual state of the browser at the
+time.  This is quite slow, especially if the page is large.  In
+addition, if you have imagemagick installed, and the mini_magick
+gem, and ":thumbnails: true", then smaller pictures will be included
+on the main replay index page, rather than the full-sized ones.
+
+## Requirements ##
+
+Ruby 1.9.3 is used for development of this project.
+
+Gless expects that you're running tests under RSpec or Cucumber;
+significant modification would likely be required to make it run
+otherwise, as it uses RSpec's `should` extensively.
+
+The following should be sufficient to allow all the rake tasks to
+run:
+
+    gem install yard-tomdoc redcarpet watir-webdriver rspec
+
+In addition, you'll need the mini\_magick gem and the imagemagick OS
+package if you want thumbnails in the logging output.
+
+## Tests ##
+
+Gless doesn't have any; if you can tell me how I should test something
+like this besides "just run the sample app", please feel free to
+suggest.
+
+## Documentation ##
+
+Other than this readme, the internal API documentation is in YARD
+markup.  Various things you can do:
+
+* `rake doc`
+ + generate the documentation
+* `yard list` and `yard ri`
+ + command line access to the documentation
+* `yard server`
+ + pretty web interface to the documentation
+

data/Rakefile

@@ -0,0 +1,41 @@
+#require 'rspec/core/rake_task'
+require 'yard'
+require 'yard/rake/yardoc_task'
+require 'rake/clean'
+
+lib = File.expand_path('../lib/', __FILE__)
+
+$:.unshift lib unless $:.include?(lib)
+
+CLEAN.include('gless*.gem')
+CLOBBER.include('doc/', '.yardoc')
+
+desc "Build the gless gem."
+task :build do
+  sh %{gem build gless.gemspec}
+end
+
+desc "Build then install the gless gem."
+task :install => :build do
+  require 'gless'
+  sh %{gem install gless-#{Gless::VERSION}.gem}
+end
+
+#desc "Run specs for gless gem"
+#RSpec::Core::RakeTask.new do
+#end
+
+desc "Generate yard documentation for the api"
+YARD::Rake::YardocTask.new do
+end
+
+desc "Generate yard documentation for the api"
+YARD::Rake::YardocTask.new :doc do
+end
+
+desc "Clean existing gems and re-install"
+task :devinst do
+  ['clean','build','install'].each { |task| Rake::Task[task].invoke }
+end
+
+task :default => :install

data/TODO

@@ -0,0 +1,4 @@
+- it would be nice to retry clicking an elements automatically if the expected
+  page transition doesn't occur ; have a session variable for
+  whether we should retry, and if we should, if .arrived? is false,
+  retry the last action

data/TODO-session

@@ -0,0 +1,65 @@
+Some old notes about the session object; may or may not still be
+relevant, likely mostly already be implemented at this point.
+
+# session.rb
+#
+# Provides a proxy to the varous page model objects that are encountered in a
+# session.  Methods that are not specific to the session object are passed
+# through to the current page model object.
+#
+# When the session is instantiated, the type of the session is given.  This
+# type determines what page model collections get loaded (ie for Cloud,
+# Orchestra, a test app, or github, for example)  During this initiation, the
+# various page model classes of that collection are loaded and queried for what
+# urls correspond to the page model.
+#
+# When a session object creates a page model object, it passes itself to that
+# object during creation, and stores that object as the current proxy target.
+#
+# If a page model object performs an action that will result in a new target
+# page, and its parent session object is not nil, the page model object will
+# suggest to the parent session object what the following page will be -- it is
+# up to the session object to validate that the target has correctly changed
+# (discuss alternative thoughts?)
+#
+# Requirements:
+# - page model classes have 'path' directive which takes one or more regular
+# expressions (usually one) to specify a matching url pattern.
+# - page model classes have a getter method for the path, that can be called
+# by the session object
+# - page model objects have a instance variable for the current session, which
+# is passed in along with the url when being instantiated
+# - page model objects should cause an exception if they are instantiated with
+# an incompatible url (maybe? - discuss)
+# - page model objects can be instantiated with no session or url (ie they are
+# optional)
+# - page model objects will tell their parent session object when an action
+# they take takes the browser to another page, ideally with the new target page
+# - session objects, when instantiated, will load all of the page model classes
+# for the passed in type -- for each model loaded this way, the session model
+# will interrogate it for the matching path pattern and store this for lookup
+# later.
+# - session class will have a minimal public methods collection, primarily
+# acting as a proxy for the contained page object.
+# - session objects will retain a history of proxy method calls and page
+# transitions for logging/debugging purposes.
+# - sessions can be told to go to a url, which will change the current page
+#model object
+#
+# Path syntax:
+#
+# In the page model classes, the directive for the path is originally
+# recommended to be:
+#   path r'/accounts/([0-9]+)/apps'
+#
+# However, a more natural language would be preferred, such as:
+#   path '/accounts/:account_id/apps'
+#
+# This has the ability to use the provided real path as an argument, and pull
+# out and name the variable aspect of that path.  This is used in sinatra and
+# rails router code, so it has an established precident.  The trick is to be
+# able to parse that code to change it to the regular expression and variable
+# list.
+#
+# The method provided to query the path pattern would result in the pattern
+# itself, not the natural language representation.

data/examples/test_github/features/support/env.rb

@@ -0,0 +1,27 @@
+load 'lib/startup.rb'
+
+require 'rspec/expectations'
+World(RSpec::Matchers)
+World(RSpec::Expectations)
+
+Before do
+  require 'gless'
+
+  # FIXME: the tag entry here will have to change for parallel runs.
+  @logger, @config, @browser = Gless.setup( :test )
+
+  if @config.get :global, :debug
+    require 'debugger'
+  end
+end
+
+After do |scenario|
+  if @config.get :global, :debug
+    if scenario.failed?
+      @logger.debug "Since you're in debug mode, and we've just failed out, here's a debugger. #1"
+      debugger
+    end
+  else
+    @browser.close
+  end
+end

data/examples/test_github/features/support/step_definitions/test_github_steps.rb

@@ -0,0 +1,27 @@
+Given %r{^I start the application$} do
+  klass = @config.get :global, :site, :class
+  @application = Object.const_get(klass)::Application.new( @browser, @config, @logger )
+  @application.should be_true
+end
+
+When %r{^I fall through to the page object$} do
+  @application.session.features.click
+end
+
+When 'I go to the Gless repo via the search page' do
+  @application.goto_repository_from_anywhere 'gless', %r{^rlpowell\s*/\s*gless$}
+end
+
+When 'I poke lots of buttons' do
+  @application.poke_headers
+end
+
+Then 'I am on the Gless repo page' do
+  @application.session.arrived?.should be_true
+  @application.browser.url.should == 'https://github.com/rlpowell/gless'
+end
+
+Then %r{^I am on the Features page$} do
+  @application.browser.url.should == 'https://github.com/features/projects'
+end
+

data/examples/test_github/features/test_github/test_github.feature

@@ -0,0 +1,12 @@
+Feature: Test Github Searching
+
+  Scenario: Find The Gless Repo
+    Given I start the application
+    When I go to the Gless repo via the search page
+    Then I am on the Gless repo page
+
+  Scenario: Poke Around
+    Given I start the application
+    When I poke lots of buttons
+    And I fall through to the page object
+    Then I am on the Features page

data/examples/test_github/lib/config/development.yml

@@ -0,0 +1,12 @@
+:global: # This tag distinguishes the global config from the per-test configs; *do not remove*
+  :site:
+    :class: TestGithub
+    :url: https://github.com
+  :browser:
+    :type: remote		# Local or remote
+    :browser: chrome	# Which browser to use
+    :port: 7444		# If remote, port to connect to the selenimu server, otherwise ignored
+  :verbose: false       # Whether to engage in more verbose/info level logging
+  :debug: false	        # Whether to engage in debug logging
+  :screenshots: false   # Whether, if debugging is on, to create screenshots as part of the replay log
+  :thumbnails: false	# Whether, if screenshots are on, to create small-ish "thumbnail" pictures on the replay page; requires the imagemagick system package and the mini_magick gem

data/examples/test_github/lib/config/development.yml.example

@@ -0,0 +1,12 @@
+:global: # This tag distinguishes the global config from the per-test configs; *do not remove*
+  :site:
+    :class: TestGithub
+    :url: https://github.com
+  :browser:
+    :type: local        # local or remote
+    :browser: firefox	# Which browser to use
+    :port: 4444		# If remote, port to connect to the selenimu server, otherwise ignored
+  :verbose: false       # Whether to engage in more verbose/info level logging
+  :debug: false	        # Whether to engage in debug logging
+  :screenshots: false   # Whether, if debugging is on, to create screenshots as part of the replay log
+  :thumbnails: false	# Whether, if screenshots are on, to create small-ish "thumbnail" pictures on the replay page; requires the imagemagick system package and the mini_magick gem

data/examples/test_github/lib/pages/test_github/blog_page.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+
+module TestGithub
+  class BlogPage < TestGithub::BasePage
+
+    url %r{^:base_url/blog$}
+
+    expected_title 'The Official GitHub Blog · GitHub'
+
+    # Stub page, but BasePage stuff still works
+
+  end
+end

data/examples/test_github/lib/pages/test_github/explore_page.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+
+module TestGithub
+  class ExplorePage < TestGithub::BasePage
+
+    url %r{^:base_url/explore$}
+
+    expected_title 'Explore · GitHub'
+
+    # Stub page, but BasePage stuff still works
+
+  end
+end

data/examples/test_github/lib/pages/test_github/features_page.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+
+module TestGithub
+  class FeaturesPage < TestGithub::BasePage
+
+    url %r{^:base_url/features/projects$}
+
+    expected_title 'Features / Project Management · GitHub'
+
+    # Stub page, but BasePage stuff still works
+
+  end
+end

data/examples/test_github/lib/pages/test_github/login_page.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+module TestGithub
+  class LoginPage < TestGithub::BasePage
+
+    url %r{^:base_url/?$}
+
+    set_entry_url ':base_url'
+
+    expected_title 'GitHub · Build software better, together.'
+
+    # Stub page, but BasePage stuff still works
+
+  end
+end

data/examples/test_github/lib/pages/test_github/repo_page.rb

@@ -0,0 +1,14 @@
+# encoding: utf-8
+
+module TestGithub
+  class RepoPage < TestGithub::BasePage
+
+    # Not much of a restriction
+    url %r{^:base_url}
+
+    expected_title %r{^\S+ · GitHub$}
+
+    # Stub page, but BasePage stuff still works
+
+  end
+end

data/examples/test_github/lib/pages/test_github/search_page.rb

@@ -0,0 +1,61 @@
+# encoding: utf-8
+
+module TestGithub
+  class SearchPage < TestGithub::BasePage
+
+    element :search_input  , :text_field , :class => 'text'  , :validator => true
+    element :search_button , :button     , :text => 'Search' , :validator => true
+
+    url %r{^:base_url/search}
+
+    expected_title %r{^(Code Search · GitHub|Search · \S+ · GitHub)$}
+
+    def search_for stuff
+      self.search_input.set stuff
+      self.search_button.click
+    end
+
+    def goto_repository name
+      @session.log.debug "SearchPage: goto_repository: name: #{name}"
+      (find_repository name)[:link].click
+      @session.acceptable_pages = TestGithub::RepoPage
+    end
+
+    def find_repository name
+      @session.log.debug "SearchPage: find_repository: name: #{name}"
+      if name.is_a?(Regexp)
+        key = repositories.keys.find { |key| key =~ name }
+      elsif name.is_a?(String)
+        key = name
+      end
+
+      @session.log.debug "SearchPage: find_repository: key: #{key}"
+
+      repositories[key]
+    end
+
+    def repositories
+      repos = self.divs.select { |div| div.class_name == 'result' }
+
+      @session.log.debug "SearchPage: repositories: repos: #{repos.inspect}"
+
+      repositories = Hash.new
+      i = 0
+      repos.each do |repo|
+        link = repo.h2.a
+        data = Hash.new
+        data[:index] = i
+        data[:link] = link
+        data[:url] = link.href
+        data[:name] = link.text
+        repositories[link.text] = data
+        i += 1
+      end
+
+      @session.log.debug "SearchPage: repositories: final: #{repositories.inspect}"
+
+      repositories
+    end
+
+  end
+end

data/examples/test_github/lib/pages/test_github_base_page.rb

@@ -0,0 +1,11 @@
+module TestGithub
+  class TestGithub::BasePage < Gless::BasePage
+
+    element :home     , :link , :href => "https://github.com/"         , :validator => true , :click_destination => :LoginPage
+    element :explore  , :link , :href => "https://github.com/explore"  , :validator => true , :click_destination => :ExplorePage
+    element :search   , :link , :href => "https://github.com/search"   , :validator => true , :click_destination => :SearchPage
+    element :features , :link , :href => "https://github.com/features" , :validator => true , :click_destination => :FeaturesPage
+    element :blog     , :link , :href => "https://github.com/blog"     , :validator => true , :click_destination => :BlogPage
+
+  end
+end

data/examples/test_github/lib/startup.rb

@@ -0,0 +1,16 @@
+$: << File.dirname(__FILE__)
+
+require 'rubygems'
+require 'optparse'
+require 'yaml'
+require 'watir-webdriver'
+
+require 'gless'
+
+Gless::EnvConfig.env_dir = File.dirname(__FILE__)
+
+require 'pages/test_github_base_page'
+Dir["#{File.dirname(__FILE__)}/pages/*/*_page.rb"].each {|r| load r }
+Dir["#{File.dirname(__FILE__)}/pages/*_page.rb"].each {|r| load r }
+
+require 'test_github'