watirsplash 0.1.9

data/History.rdoc

@@ -0,0 +1,51 @@
+=== Version 0.1.9 / 2010-05-01
+
+ * Changed name of the library to WatirSplash due to name conflict
+   - this means that all watirspec commands are now obsolete and you have to use watirsplash commands instead
+   - all WatiRspec constants (module names etc) are now named as WatirSplash
+
+=== Version 0.1.8 / 2010-04-19
+
+ * tidied up some code, no changes in functionality
+
+=== Version 0.1.7 / 2010-04-15
+
+ * minor fix
+
+=== Version 0.1.6 / 2010-04-08
+
+ * browser was not closed when Watir::IE#run_error_checks throwed an exception
+
+=== Version 0.1.5 / 2010-04-08
+
+ * fixed a problem where HtmlFormatter threw an ugly exception due to the problem when browser was not opened
+
+=== Version 0.1.4 / 2010-04-06
+
+ * added dependency for win32screenshot
+
+=== Version 0.1.3 / 2010-04-06
+
+ * fixed a bug where inner table was not shown with Watir::Table#to_a when it was not a direct child, but some other element was in between for example form, span, div etc.
+
+=== Version 0.1.2 / 2010-04-05
+
+ * Added match_array matcher for RSpec for using with Array when regular expressions are needed. It is useful when verifying html tables with #to_a method.
+    expected_array = ["1", "2", /\d+/, "3"]
+    
+    ["1", "2", "66", "3"].should match_array(expected_array)
+    table(:id => "table_id").to_a.should match_array(expected_array)
+
+=== Version 0.1.1 / 2010-04-04
+
+* Watir::Table#to_a and Watir::TableRow#to_a work now well with tr, th, td elements, colspan and nested tables.
+This means that you can test easily tables now:
+    expected_table = [["one", "two"], ["three", "four"]]
+    table(:id => "table_id").to_a.should =~ expected_table
+
+* removed strict version requirements for dependencies
+
+
+=== Version 0.1.0 / 2010-04-03
+
+First release of WatiRspec, a small library for combining Watir and RSpec for browser-based functional testing in Ruby.

data/License.txt

@@ -0,0 +1,24 @@
+(The MIT License)
+
+Copyright (c) 2010 Jarmo Pertman
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE

data/README.rdoc

@@ -0,0 +1,171 @@
+= WatirSplash
+
+* Web: http://github.com/jarmo/WatirSplash
+* Author: Jarmo Pertman (mailto:jarmo.p[at]gmail.com)
+
+== DESCRIPTION:
+
+WatirSplash is a small library for easier browser-based functional testing in Ruby.
+It combines Watir (http://www.watir.com) for controlling the browser (currently mainly IE) and
+RSpec (http://rspec.info) for testing framework. This powerful combination gives you
+the ability to write easily well-maintained and easy-to-read specs (specifications in RSpec) so
+you don't need to have any extra documentation for your applications.
+
+WatirSplash makes it easier to use best features of both of these tools together so
+you won't have to spend time on thinking how to do that yourself - you can start
+testing right away!
+
+== FEATURES:
+
+* generate command for generating default project structure
+* generate_common command for generating common ui-tests directory
+* Browser will be opened and closed for each example group automatically
+* You can use Watir method names directly without having to specify a browser object:
+    text_field(:name => "locator") # instead of @browser.text_field(:name => "locator")
+* All needed libraries will be loaded and helper modules will be included automatically
+* All JavaScript errors will be detected automatically
+* Some additional methods to help using Watir (download_file, wait_until, wait_until! etc.)
+
+* Custom html formatter for RSpec:
+* Saves screenshot of the browser window
+* Saves html of the page
+* Saves all the files created/downloaded during the example and shows them on the report
+* Automatically archives test results for later reviewing
+
+== SYNOPSIS:
+
+    describe "Google" do
+        before :all do
+            goto "http://google.com"
+            url.should =~ /google/
+        end
+        
+        it "has search field" do
+            text_field = text_field(:name => "q")
+            text_field.should exist
+            text_field.should be_visible
+        end
+        
+        it "performs search" do
+            text_field(:name => "q").set "Bing"
+            button(:name => "btnG").click
+            text.should include("Bing")
+        end
+    end
+    
+    C:\project\ui-test>watirsplash spec\google_spec.rb
+    Results will be saved into the directory C:/project/ui-test/results
+    Google
+      has search field
+      performs search
+
+    Finished in 6.782388 seconds
+
+    2 examples, 0 failures
+
+== INSTALL:
+
+* install Ruby 1.8.6:
+    http://rubyinstaller.org/
+    
+* install ImageMagick with rmagick-win32 for making the screenshots:
+    http://rubyforge.org/frs/?group_id=12&release_id=42049
+    
+* update RubyGems:
+    gem update --system
+
+* install WatirSplash:
+    gem install watirsplash
+    
+== USAGE:
+    
+If you have a web-application project (it may have been written in any programming language) without any browser-based tests,
+then it has probably a directory structure similar to this example:
+    C:\example_project
+    ├───doc
+    ├───lib
+    └───test
+    
+Now from the command line go to this directory and execute generate command:
+    C:\>cd example_project
+
+    C:\example_project>watirsplash generate
+    Creating WatirSplash project directory structure to C:/example_project/ui-test...
+    Done
+    
+After that the directory structure will be something like this:
+    C:\example_project
+    ├───doc
+    ├───lib
+    ├───test
+    └───ui-test
+        └───spec
+    
+The contents of that ui-test directory will be:
+    ui-test\application_helper.rb
+    ui-test\config.rb
+    ui-test\environment.rb
+    ui-test\ide_runner.rb
+    
+    ui-test\spec
+    ui-test\spec\dummy_spec.rb
+    
+Just check out all the files to see some example code and comments in it and execute dummy_spec.rb
+to verify that everything works correctly:
+    watirsplash spec\dummy_spec.rb
+    
+You can have whatever directory structure for your tests just make sure that all test files have _spec.rb in
+the end of their filename (if using default RSpec options).
+    
+== USAGE FOR MULTIPLE PROJECTS:
+
+Usually you're going to write tests for multiple different projects. It would be shame if you'd
+going to create all those common helper methods again for different projects or just copy-paste
+the code from previous project's helpers. This is the place where ui-test-common comes into play.
+    
+ui-test-common would be a place where you can hold all your common functionality in helper
+modules/methods/classes and then use those things in your tests so you won't have multiple
+copies of similar or even same code in different places. So it helps you
+to keep DRY (http://en.wikipedia.org/wiki/Don't_repeat_yourself).
+    
+After finding yourself in a situation where a new project comes into play, then execute
+generate_common command once somewhere in a higher level of a directory tree than your project's ui-test directory
+to generate ui-test-common directory:
+    C:\example_project>cd ..
+
+    C:\>watirsplash generate_common
+    Creating WatirSplash common project directory structure to C:/ui-test-common...
+    Done
+
+It has a structure of:
+    C:\UI-TEST-COMMON
+    └───lib
+    
+    ui-test-common\config.rb
+    ui-test-common\environment.rb
+    ui-test-common\lib
+    ui-test-common\lib\common_application_helper.rb
+    
+In environment.rb under project/ui-test you shall add common functionality to your project.
+Add the following line before any other require statements to do that:
+    WatirSplash::Util.load_common
+    
+This gives you by default the access to every method in ui-test-common/lib/common_application_helper.rb
+    
+Now, in ui-test-common/config.rb change the URL to your hostname and in config.rb under project/ui-test:
+    URL = Config.full_url("/relative_path")
+    
+This gives you the ability to have host and port written only in one place.
+    
+Now move all the common functionality away from your project's files into ui-test-common files and start testing.
+From now on, add all common functionality into ui-test-common/lib
+
+== KNOWN PROBLEMS (& SOLUTIONS)
+
+=== PROBLEM #1
+
+If you see the following error message when running watirsplash:
+    R6034. An application has made an attempt to load the C runtime library incorrectly.
+ 
+Solution:
+    Install Microsoft Visual C++ 2008 SP1 Redistributable Package

data/Rakefile

@@ -0,0 +1,16 @@
+require 'rake'
+require 'spec/rake/spectask'
+
+Spec::Rake::SpecTask.new(:rcov) do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.rcov = true
+  t.rcov_dir = 'coverage'
+  t.rcov_opts << '--sort coverage --text-summary --aggregate coverage.data'
+end
+
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_opts << "--options" << "lib/spec.opts" <<
+          "--require" << "lib/watirsplash/html_formatter" <<
+          "--format" << "WatirSplash::HtmlFormatter:results/index.html"
+end

data/bin/watirsplash

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+watirsplash_dir = File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(watirsplash_dir) unless $LOAD_PATH.include?(watirsplash_dir)
+require 'watirsplash/runner'
+
+if ARGV.size == 1 && ::WatirSplash::Runner.respond_to?(ARGV[0])
+  exit ::WatirSplash::Runner.send(ARGV[0])
+else
+  exit ::WatirSplash::Runner.run
+end

data/lib/spec.opts

@@ -0,0 +1,5 @@
+--color
+--format
+nested
+--diff
+u

data/lib/watirsplash/autoit.rb

@@ -0,0 +1,54 @@
+# Helper class for AutoIt
+class AutoItHelper
+  extend WatirSplash::Waiter
+  
+  @@autoit = Watir.autoit
+
+  class << self
+    # clicks save button on window with specified title,
+    # activates window automatically and makes sure that the click
+    # was successful
+    def click_save(window_title="File Download")
+      click_button(window_title, "&Save")
+    end
+
+    # sets edit field value to field_value on window with specified title,
+    # activates window automatically and makes sure that the field's
+    # value got changed
+    def set_edit(field_value, window_title="Save As")
+      set_field(window_title, "Edit1", field_value)
+    end
+
+    # sets specified field's value on window with specified title,
+    # activates window automatically and makes sure that the field's
+    # value got changed
+    def set_field(window_title, field_name, field_value)
+      wait_until! do
+        activate_window(window_title) &&
+                @@autoit.ControlFocus(window_title, "", field_name) == 1 &&
+                @@autoit.ControlSetText(window_title, "", field_name, field_value) == 1 &&
+                @@autoit.ControlGetText(window_title, "", field_name) == field_value
+      end
+    end
+
+    # clicks specified button on window with specified title,
+    # activates window automatically and makes sure that the click
+    # was successful
+    def click_button(window_title, button_name)
+      wait_until! do
+        activate_window(window_title) &&
+                @@autoit.ControlFocus(window_title, "", button_name) == 1 &&
+                @@autoit.ControlClick(window_title, "", button_name) == 1 &&
+                wait_until(3) {@@autoit.WinExists(window_title) == 0}
+      end
+    end
+
+    # makes window active with specified title
+    # * returns true if activation was successful and false otherwise
+    def activate_window(window_title)
+      @@autoit.WinWait(window_title, "", 1) == 1 &&
+              @@autoit.WinActivate(window_title) != 0 &&
+              @@autoit.WinActive(window_title) != 0
+    end
+  end
+end

data/lib/watirsplash/html_formatter.rb

@@ -0,0 +1,118 @@
+require 'spec/runner/formatter/html_formatter'
+require 'win32screenshot'
+require 'rmagick'
+require 'pathname'
+require 'fileutils'
+
+module WatirSplash
+  # Custom RSpec formatter for WatirSplash
+  # * saves screenshot of the browser upon test failure
+  # * saves html of the browser upon test failure
+  # * saves javascript error dialog upon test failure
+  # * saves all files generated/downloaded during the test and shows them in the report
+  class HtmlFormatter < ::Spec::Runner::Formatter::HtmlFormatter
+
+    # currently used browser object
+    # needed for saving of screenshots and html
+    attr_writer :browser
+
+    def initialize(options, output) # :nodoc:
+      raise "output has to be a file path!" unless output.is_a?(String)
+      @output_dir = File.expand_path(File.dirname(output))
+      puts "Results will be saved into the directory #{@output_dir}"
+      @files_dir = File.join(@output_dir, "files")
+      if File.exists?(@output_dir)
+        archive_dir = File.join(@output_dir, "../archive")
+        FileUtils.mkdir_p(archive_dir) unless File.exists?(archive_dir)
+        FileUtils.mv @output_dir, File.join(archive_dir, "#{File.basename(@output_dir)}_#{File.mtime(@output_dir).strftime("%y%m%d_%H%M%S")}")
+      end
+      FileUtils.mkdir_p(@files_dir)
+      @files_saved_during_example = []
+      super
+    end
+
+    def example_started(example) # :nodoc:
+      @files_saved_during_example.clear
+      super
+    end
+
+    def extra_failure_content(failure) # :nodoc:
+      save_javascript_error
+      save_html
+      save_screenshot
+
+      content = []
+      content << "<span>"
+      @files_saved_during_example.each {|f| content << link_for(f)}
+      content << "</span>"
+      super + content.join($/)
+    end
+
+    def link_for(file) # :nodoc:
+      return unless File.exists?(file[:path])
+
+      description = file[:desc] ? file[:desc] : File.extname(file[:path]).upcase[1..-1]
+      path = Pathname.new(file[:path])
+      "<a href='#{path.relative_path_from(Pathname.new(@output_dir))}'>#{description}</a>&nbsp;"
+    end
+
+    def save_html # :nodoc:
+      begin
+        html = @browser.html
+        file_name = file_path("browser.html")
+        File.open(file_name, 'w') {|f| f.puts html}
+      rescue => e
+        $stderr.puts "saving of html failed: #{e.message}"
+        $stderr.puts e.backtrace
+      end
+      file_name
+    end
+
+    def save_screenshot(description="Screenshot", hwnd=@browser.hwnd) # :nodoc:
+      begin
+        @browser.bring_to_front
+        width, height, blob = Win32::Screenshot.capture_hwnd(hwnd)
+        file_name = file_path("screenshot.png", description)
+        img = Magick::ImageList.new
+        img.from_blob(blob)
+        img.write(file_name)
+      rescue => e
+        $stderr.puts "saving of screenshot failed: #{e.message}"
+        $stderr.puts e.backtrace
+      end
+      file_name
+    end
+
+    def save_javascript_error # :nodoc:
+      file_name = nil
+      begin
+        if @browser.is_a?(Watir::IE) && @browser.status =~ /Error on page/
+          autoit = Watir::autoit
+          autoit.AutoItSetOption("MouseCoordMode", 0)
+          autoit.ControlClick("[TITLE:#{@browser.title}]", "", "[CLASS:msctls_statusbar32]", "left", 2)
+          popup_title = "[REGEXPTITLE:^(Windows )?Internet Explorer$]"
+          autoit.WinWait(popup_title, "", 10)
+          file_name = save_screenshot("JS_Error", autoit.WinGetHandle(popup_title).hex)
+          autoit.WinClose(popup_title)
+        end
+      rescue => e
+        $stderr.puts "saving of javascript error failed: #{e.message}"
+        $stderr.puts e.backtrace
+      end
+      file_name
+    end
+
+    # Generates unique file name and path for each example.
+    #
+    # All file names generated with this method will be shown
+    # on the report.
+    def file_path(file_name, description=nil)
+      extension = File.extname(file_name)
+      basename = File.basename(file_name, extension)
+      file_path = File.join(@files_dir, "#{basename}_#{Time.now.strftime("%H%M%S")}_#{example_group_number}_#{example_number}#{extension}")
+      @files_saved_during_example.unshift(:desc => description, :path => file_path)
+      file_path
+    end
+
+  end
+end

data/lib/watirsplash/runner.rb

@@ -0,0 +1,97 @@
+module WatirSplash
+
+  # WatirSplash runner class is responsible for:
+  # * generating directory structures for projects
+  # * starting RSpec with specified settings
+  class Runner
+    @@template_directory = File.join(File.dirname(__FILE__), "../../templates/")
+
+    class << self
+
+      # Run RSpec with custom settings
+      # * loads spec.opts from project's directory if exists
+      # * loads environment.rb from project's directory if exists
+      # * loads custom Formatter
+      def run
+        unless ARGV.empty?
+          require "watirsplash"
+          load_formatter
+          load_options
+          load_project_env
+        else
+          return help
+        end
+
+        ::Spec::Runner::CommandLine.run
+      end
+
+      # Generates ui-test project structure for project
+      def generate
+        ui_test_dir = File.join(Dir.pwd, "ui-test")
+        puts "Creating WatirSplash project directory structure to #{ui_test_dir}..."
+        require "fileutils"
+        FileUtils.cp_r File.join(@@template_directory, "project/."), ui_test_dir
+        puts "Done"
+        return 0
+      rescue => e
+        puts "Failed:"
+        puts e.message
+        return -1
+      end
+
+      # Generates ui-test-common directory structure
+      def generate_common
+        common_dir = File.join(Dir.pwd, "ui-test-common")
+        puts "Creating WatirSplash common project directory structure to #{common_dir}..."
+        require "fileutils"
+        FileUtils.cp_r File.join(@@template_directory, "common/."), common_dir
+        puts "Done"
+        return 0
+      rescue => e
+        puts "Failed:"
+        puts e.message
+        return -1
+      end
+
+      # Shows help
+      def help
+        puts %Q{WatirSplash:
+Usage: watirsplash (COMMAND|FILE(:LINE)?|DIRECTORY|GLOB)+ [options]
+Commands:
+          * generate - generate default directory structure for new project
+          * generate_common - generate common project directory structure
+          * help - show this help
+          * --help - show RSpec's help
+
+All other commands/options will be passed to RSpec directly.}
+
+        return 1
+      end
+
+      private
+
+      def load_formatter
+        ARGV << "--require" << "watirsplash/html_formatter.rb"
+        ARGV << "--format" << "WatirSplash::HtmlFormatter:#{File.join(Dir.pwd, "results/index.html")}"
+      end
+
+      def load_options
+        ARGV << "--options"
+        project_spec_opts = File.join(Dir.pwd, "spec.opts")
+        if File.exists?(project_spec_opts)
+          ARGV << project_spec_opts
+        else
+          ARGV << "#{File.join(File.dirname(__FILE__), "../spec.opts")}"
+        end
+      end
+
+      def load_project_env
+        project_env_file = File.join(Dir.pwd, "environment.rb")
+        if File.exists?(project_env_file)
+          ARGV << "--require" << project_env_file
+        end
+      end
+
+    end
+  end
+end

data/lib/watirsplash/spec.rb

@@ -0,0 +1,43 @@
+Spec::Runner.configure do |config| #:nodoc:
+  config.include(WatirSplash::SpecHelper)
+
+  config.before(:all) do
+    open_browser_at "about:blank"
+  end
+
+  config.after(:all) do
+    close
+  end
+end
+
+module Spec #:nodoc:all
+  class ExampleGroup
+    subject {self}
+  end
+end
+
+# match_array is useful for matching arrays where some elements are regular expressions.
+#    expected_array = ["1", "2", /\d+/, "3"]
+#
+#    ["1", "2", "66", "3"].should match_array(expected_array)
+#    table(:id => "table_id").to_a.should match_array(expected_array)
+Spec::Matchers.define :match_array do |array2|
+  match do |array1|
+    raise "match_array works only with Array objects!" unless array1.is_a?(Array) && array2.is_a?(Array)
+    match?(array1, array2)
+  end
+
+  def match?(array1, array2)
+    array2.each_with_index do |element, i|
+      if element.is_a?(Array)
+        return false unless match?(array1[i], element)
+      elsif element.is_a?(Regexp)
+        return false unless array1[i] =~ element
+      else
+        return false unless array1[i] == element
+      end
+    end
+
+    true
+  end
+end

data/lib/watirsplash/spec_helper.rb

@@ -0,0 +1,68 @@
+module WatirSplash
+  # main helper module
+  #
+  # these methods can be used in specs directly
+  module SpecHelper
+    include Waiter
+
+    # opens the browser at specified url
+    def open_browser_at url
+      @browser = Watir::Browser.new
+      @browser.speed = :fast
+      add_checker Watir::PageCheckers::JAVASCRIPT_ERRORS_CHECKER
+      begin
+        formatter.browser = @browser
+      rescue
+      end
+      goto url
+      maximize
+    end
+
+    # downloads file with browser
+    #
+    # you need to use click_no_wait to use this method:
+    #   button(:id => "something").click_no_wait # opens a browser save as dialog
+    #   download_file("document.pdf")
+    #
+    # * raises an exception if saving the file is unsuccessful
+    # * returns absolute file_path of the saved file
+    def download_file file_name
+      AutoItHelper.click_save
+      file_path = native_file_path(file_path(file_name))
+      AutoItHelper.set_edit(file_path)
+      AutoItHelper.click_save("Save As")
+      wait_until! {File.exists?(file_path)}
+      file_path
+    end
+
+    # returns WatirSplash::HtmlFormatter object, nil if not in use
+    def formatter
+      @formatter ||= Spec::Runner.options.formatters.find {|f| f.kind_of?(WatirSplash::HtmlFormatter) rescue false}
+    end
+
+    # returns unique file path for use in examples.
+    #
+    # all file names generated with this method will
+    # be shown on the report upon test failure.
+    def file_path(file_name, description=nil)
+      formatter.file_path(file_name, description)
+    rescue
+      extension = File.extname(file_name)
+      basename = File.basename(file_name, extension)
+      file_path = File.join(Dir.pwd, "#{basename}_#{Time.now.strftime("%H%M%S")}#{extension}")
+      file_path
+    end
+
+    # returns native file path
+    # e.g. on Windows:
+    #   native_file_path("c:/blah/blah2/file.txt") => c:\\blah\\blah2\\file.txt 
+    def native_file_path(file_path)
+      File::ALT_SEPARATOR ? file_path.gsub(File::SEPARATOR, File::ALT_SEPARATOR) : file_path
+    end
+
+    def method_missing name, *arg #:nodoc:
+      @browser.respond_to?(name) ? @browser.send(name, *arg) : super
+    end
+
+  end
+end