watir-rspec 0.0.2 → 0.0.3

data/.yardopts

@@ -0,0 +1,6 @@
+--readme README.md
+--no-private
+--hide-void-return
+--title "Watir-RSpec"
+--files LICENSE
+--default-return ""

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Jarmo Pertman
+Copyright (c) 2012-2013 Jarmo Pertman
 
 MIT License
 
@@ -19,4 +19,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,80 +1,139 @@
-# Watir::RSpec
-
-Use Watir with RSpec with ease.
-
-## Installation
-
-Add these lines to your application's Gemfile:
-
-    group :test do
-      gem 'watir-rspec'
-    end
-
-And add these lines to your spec\_helper.rb file:
-
-    RSpec.configure do |config|
-      # Add Watir::RSpec::HtmlFormatter to get links to the screenshots, html and
-      # all other files created during the failing examples.
-      config.add_formatter('documentation')
-      config.add_formatter(Watir::RSpec::HtmlFormatter)
-
-      # Open up the browser for each example.
-      config.before :all do
-        @browser = Watir::Browser.new
-      end
-
-      # Close that browser after each example.
-      config.after :all do
-        @browser.close if @browser
-      end
-
-      # Include RSpec::Helper into each of your example group for making it possible to
-      # write in your examples instead of:
-      #   @browser.goto "localhost"
-      #   @browser.text_field(:name => "first_name").set "Bob"
-      #
-      # like this:
-      #   goto "localhost"
-      #   text_field(:name => "first_name").set "Bob"
-      #
-      # This needs that you've used @browser as an instance variable name in
-      # before :all block.
-      config.include Watir::RSpec::Helper
-    end
-
-
-When using Rails and writing specs to requests directory, add an additional filter for RSpec:
-
-    config.before :all, :type => :request do
-      @browser = Watir::Browser.new :chrome
-    end
-
-    config.after :all, :type => :request do
-      @browser.close if @browser
-    end
-
-    config.include Watir::RSpec::Helper, :type => :request
-
-## Usage
-
-Just use the browser in your examples. If you haven't included
-Watir::RSpec::Helper, then you need to use the @browser instance variable when
-calling Watir::Browser methods, otherwise you may omit it.
-
-When creating/downloading/uploading files in your examples and using
-Watir::RSpec::HtmlFormatter then you can generate links automatically to these files when example
-fails. To do that you need to use Watir::RSpec.file\_path method for generating
-unique file name:
-
-    uploaded_file_path = Watir::RSpec.file_path("uploaded.txt")
-    File.open(uploaded_file_path, "w") {|file| file.write "Generated File Input"}
-
-If you're using Rails, then you also need to install [watir-rails](https://github.com/watir/watir-rails) gem.
-
-## Contributing
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+# Watir::RSpec
+
+Use [Watir](http://watir.com) with [RSpec](http://rspec.info) with ease.
+
+## Installation
+
+Add these lines to your application's Gemfile:
+
+````ruby
+group :test do
+  gem 'watir-rspec'
+end
+````
+
+And add these lines to your spec\_helper.rb file:
+
+````ruby
+RSpec.configure do |config|
+  # Add Watir::RSpec::HtmlFormatter to get links to the screenshots, html and
+  # all other files created during the failing examples.
+  config.add_formatter('documentation')
+  config.add_formatter(Watir::RSpec::HtmlFormatter)
+
+  # Open up the browser for each example.
+  config.before :all do
+    @browser = Watir::Browser.new
+  end
+
+  # Close that browser after each example.
+  config.after :all do
+    @browser.close if @browser
+  end
+
+  # Include RSpec::Helper into each of your example group for making it possible to
+  # write in your examples instead of:
+  #   @browser.goto "localhost"
+  #   @browser.text_field(:name => "first_name").set "Bob"
+  #
+  # like this:
+  #   goto "localhost"
+  #   text_field(:name => "first_name").set "Bob"
+  #
+  # This needs that you've used @browser as an instance variable name in
+  # before :all block.
+    config.include Watir::RSpec::Helper
+  end
+````
+
+
+When using Rails and writing specs to requests directory, add an additional filter for RSpec:
+
+````ruby
+config.before :all, :type => :request do
+  @browser = Watir::Browser.new :chrome
+end
+
+config.after :all, :type => :request do
+  @browser.close if @browser
+end
+
+config.include Watir::RSpec::Helper, :type => :request
+````
+
+## Usage
+
+### Executing browser methods
+
+If you did include ````Watir::Rspec::Helper```` then it is possible to write code like this in your specs:
+
+````ruby
+text_field(:id => "something").set "foo"
+````
+
+If you did not include ````Watir::RSpec::Helper```` then you have to use browser variable:
+
+````ruby
+@browser.text_field(:id => "something").set "foo"
+````
+
+### Testing asynchronous functionality
+
+````Watir::RSpec```` adds convenience methods ````#within```` and ````#during```` to all of the RSpec matchers,
+which help to write better and more beautiful test code.
+
+Let us pretend that the following div will appear dynamically after some Ajax request.
+
+We can use the standard way:
+
+````ruby
+Watir::Wait.until(5) { div(:id => "something").present? }
+````
+
+Or we can use ````#within```` method:
+
+````ruby
+div(:id => "something").should be_present.within(5)
+````
+
+````#during```` is the opposite of ````#within```` - it means that during the specified time something should be true/false.
+
+PS! There is one caveat when using ````#within```` or ````#during```` - it cannot be used in every possible situation.
+
+For example, this won't work as expected:
+
+````ruby
+div(:id => "something").text.should eq("foo").within(5)
+````
+
+The reason is that RSpec will check if value of ````#text```` will change to ````"foo"````, but it is just some ````String````,
+which won't change ever. The rule of thumb is that ````#should```` should be always called on an instance of
+the ````Element```` and ````#within/#duration```` on the matcher for that ````Element```` (e.g. ````be_present````, ````be_visible````, ````exist```` etc.).
+
+### Files created during specs
+
+When creating/downloading/uploading files in your examples and using
+````Watir::RSpec::HtmlFormatter```` then you can generate links automatically to these files when example
+fails. To do that you need to use ````Watir::RSpec.file_path```` method for generating
+unique file name:
+
+````ruby
+uploaded_file_path = Watir::RSpec.file_path("uploaded.txt")
+File.open(uploaded_file_path, "w") {|file| file.write "Generated File Input"}
+````
+
+### Rails support
+
+If you're using Rails, then you also need to install [watir-rails](https://github.com/watir/watir-rails) gem.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+Copyright (c) Jarmo Pertman (jarmo.p@gmail.com). See LICENSE for details.

data/Rakefile

@@ -1 +1,4 @@
 require "bundler/gem_tasks"
+
+require "yard"
+YARD::Rake::YardocTask.new

data/lib/watir/rspec/helper.rb

@@ -3,11 +3,19 @@ module Watir
     module Helper
       extend Forwardable
 
+      # @return [Watir::Browser] a latest browser instance if it is initialized with 
+      #   @browser or $browser variable name.
       def browser
         @browser || $browser
       end
 
-      def method_missing name, *args #:nodoc:
+      # Will dispatch all missing methods to the {#browser} instance.
+      # @example Makes it possible to use Watir::Browser methods without specifying the browser instance in the specs like this:
+      #  it "should do something" do
+      #    # notice that we're calling Watir::Browser#text_field here directly
+      #    text_field(:id => "foo").should be_present
+      #  end
+      def method_missing(name, *args)
         if browser.respond_to?(name)
           Helper.module_eval %Q[
             def #{name}(*args)

data/lib/watir/rspec/html_formatter.rb

@@ -9,7 +9,8 @@ module Watir
     # * saves html of the browser upon test failure
     # * saves all files generated/downloaded during the test and shows them in the report
     class HtmlFormatter < ::RSpec::Core::Formatters::HtmlFormatter
-      def initialize(output) # :nodoc:
+      # @private
+      def initialize(output)
         @output_path = File.expand_path(ENV["WATIR_RESULTS_PATH"] || (output.respond_to?(:path) ? output.path : "tmp/spec-results/index.html"))
         FileUtils.rm_rf File.dirname(@output_path), :verbose => true if File.exists?(@output_path)
 
@@ -23,18 +24,21 @@ module Watir
         super(File.open(@output_path, "w"))
       end
 
-      def example_group_started(example_group) # :nodoc:
+      # @private
+      def example_group_started(example_group)
         @files_saved_during_example.clear
         super
       end
 
-      def example_started(example) # :nodoc:
+      # @private
+      def example_started(example)
         @files_saved_during_example.clear
         super
       end
 
-      def extra_failure_content(exception) # :nodoc:
-        browser = example_group.before_all_ivars[:@browser]
+      # @private
+      def extra_failure_content(exception)
+        browser = example_group.before_all_ivars[:@browser] || $browser
         return super unless browser && browser.exists?
 
         save_screenshot browser
@@ -47,10 +51,13 @@ module Watir
         super + content.join($/)
       end
 
-      # Generates unique file name and path for each example.
+      # Generate unique file path for the current spec. If the file
+      # will be created during that spec and spec fails then it will be
+      # shown automatically in the html report.
       #
-      # All file names generated with this method will be shown
-      # on the report.
+      # @param [String] File name to be used for file.
+      #   Will be used as a part of the complete name.
+      # @return [String] Absolute path for the unique file name.
       def file_path(file_name, description=nil)
         extension = File.extname(file_name)
         basename = File.basename(file_name, extension)
@@ -61,7 +68,7 @@ module Watir
 
       private
 
-      def link_for(file) # :nodoc:
+      def link_for(file)
         return unless File.exists?(file[:path])
 
         description = file[:desc] ? file[:desc] : File.extname(file[:path]).upcase[1..-1]
@@ -69,7 +76,7 @@ module Watir
         "<a href='#{path.relative_path_from(Pathname.new(@output_path).dirname)}'>#{description}</a>&nbsp;"
       end
 
-      def save_html(browser) # :nodoc:
+      def save_html(browser)
         file_name = file_path("browser.html")
         begin
           html = browser.html
@@ -80,7 +87,7 @@ module Watir
         file_name
       end
 
-      def save_screenshot(browser, description="Screenshot") # :nodoc:
+      def save_screenshot(browser, description="Screenshot")
         file_name = file_path("screenshot.png", description)
         browser.screenshot.save(file_name)
         file_name

data/lib/watir/rspec/version.rb

@@ -1,5 +1,5 @@
 module Watir
   class RSpec
-    VERSION = "0.0.2"
+    VERSION = "0.0.3"
   end
 end

data/lib/watir/rspec.rb

@@ -7,109 +7,118 @@ if defined? ActiveRecord
 end
 
 module Watir
-  # add #within(timeout) and #during(timeout) methods for every matcher for allowing to wait until some condition is met.
-  #     div.click
-  #     another_div.should be_present.within(5)
-  #
-  #     expect {
-  #       div.click
-  #     }.to change {another_div.text}.from("before").to("after").within(5)
-  #
-  #     expect {
-  #       div.click
-  #     }.to make {another_div.present?}.within(5)
-  #
-  #     expect {
-  #       div.click
-  #     }.to change {another_div.text}.soon
-  #
   class RSpec
     class << self
-        def add_within_and_during_to_matcher const
-          const.class_eval do
-
-            inst_methods = instance_methods.map &:to_sym
+      # Add #within(timeout) and #during(timeout) methods for every matcher for allowing to wait until some condition is met.
+      #     div.click
+      #     another_div.should be_present.within(5)
+      #
+      #     expect {
+      #       div.click
+      #     }.to change {another_div.text}.from("before").to("after").within(5)
+      #
+      #     expect {
+      #       div.click
+      #     }.to make {another_div.present?}.within(5)
+      #
+      #     expect {
+      #       div.click
+      #     }.to change {another_div.text}.soon
+      #
+      # @private
+      def add_within_and_during_to_matcher const
+        const.class_eval do
+
+          inst_methods = instance_methods.map &:to_sym
+
+          if !(inst_methods.include?(:__matches?) || inst_methods.include?(:__does_not_match?)) && 
+            (inst_methods.include?(:matches?) || inst_methods.include?(:does_not_match?))
+
+            def within(timeout)
+              @within_timeout = timeout
+              self
+            end
 
-            if !(inst_methods.include?(:__matches?) || inst_methods.include?(:__does_not_match?)) && 
-              (inst_methods.include?(:matches?) || inst_methods.include?(:does_not_match?))
+            def during(timeout)
+              @during_timeout = timeout
+              self
+            end
 
-              def within(timeout)
-                @within_timeout = timeout
-                self
-              end
+            def soon 
+              within(30)
+            end      
 
-              def during(timeout)
-                @during_timeout = timeout
-                self
-              end
+            def seconds
+              # for syntactic sugar
+              self
+            end
 
-              def soon 
-                within(30)
-              end      
+            alias_method :second, :seconds
 
-              def seconds
-                # for syntactic sugar
-                self
-              end
+            def minutes
+              @within_timeout *= 60 if @within_timeout
+              @during_timeout *= 60 if @during_timeout
+              self
+            end
 
-              alias_method :second, :seconds
+            alias_method :minute, :minutes
+          end
 
-              def minutes
-                @within_timeout *= 60 if @within_timeout
-                @during_timeout *= 60 if @during_timeout
-                self
-              end
+          if inst_methods.include? :matches?
+            alias_method :__matches?, :matches? 
 
-              alias_method :minute, :minutes
+            def matches?(actual)
+              match_with_wait {__matches?(actual)}
             end
+          end
 
-            if inst_methods.include? :matches?
-              alias_method :__matches?, :matches? 
+          if inst_methods.include? :does_not_match?
+            alias_method :__does_not_match?, :does_not_match?
 
-              def matches?(actual)
-                match_with_wait {__matches?(actual)}
-              end
+            def does_not_match?(actual)
+              match_with_wait {__does_not_match?(actual)}
             end
-
-            if inst_methods.include? :does_not_match?
-              alias_method :__does_not_match?, :does_not_match?
-
-              def does_not_match?(actual)
-                match_with_wait {__does_not_match?(actual)}
-              end
-            elsif inst_methods.include? :matches?
-              def does_not_match?(actual)
-                match_with_wait {!__matches?(actual)}
-              end
+          elsif inst_methods.include? :matches?
+            def does_not_match?(actual)
+              match_with_wait {!__matches?(actual)}
             end
+          end
 
-            private
-
-            def match_with_wait
-              if @within_timeout
-                timeout = @within_timeout; @within_timeout = nil
-                Watir::Wait.until(timeout) {yield} rescue false
-              elsif @during_timeout
-                timeout = @during_timeout; @during_timeout = nil
-                Watir::Wait.while(timeout) {yield} rescue true        
-              else
-                yield
-              end
+          private
+
+          def match_with_wait
+            if @within_timeout
+              timeout = @within_timeout; @within_timeout = nil
+              Watir::Wait.until(timeout) {yield} rescue false
+            elsif @during_timeout
+              timeout = @during_timeout; @during_timeout = nil
+              Watir::Wait.while(timeout) {yield} rescue true        
+            else
+              yield
             end
           end
         end
+      end
 
-        def file_path(file_name, description=nil)
-          formatter.file_path(file_name, description=nil)
-        end
+      # Generate unique file path for the current spec. If the file
+      # will be created during that spec and spec fails then it will be
+      # shown automatically in the html report.
+      #
+      # @param [String] File name to be used for file.
+      #   Will be used as a part of the complete name.
+      # @return [String] Absolute path for the unique file name.
+      # @raise [RuntimeError] when {Watir::RSpec::HtmlFormatter} is not in use.
+      def file_path(file_name, description=nil)
+        formatter.file_path(file_name, description=nil)
+      end
 
-        private
+      private
 
-        def formatter
-          @formatter ||= begin
-                           formatter = ::RSpec.configuration.formatters.find {|f| f.kind_of? Watir::RSpec::HtmlFormatter}
-                           unless formatter
-                             raise <<-EOF
+      def formatter
+        @formatter ||= begin
+                         formatter = ::RSpec.configuration.formatters.find {|f| f.kind_of? Watir::RSpec::HtmlFormatter}
+                         unless formatter
+                           raise <<-EOF
   Watir::RSpec::HtmlFormatter is not set as a RSpec formatter.
 
   You need to add it into your spec_helper.rb file like this:
@@ -117,42 +126,43 @@ module Watir
       config.add_formatter('documentation')
       config.add_formatter(Watir::RSpec::HtmlFormatter)
     end
-  EOF
-                           end
-                           formatter
+                           EOF
                          end
-        end
-
-
+                         formatter
+                       end
       end
 
-    end
-  end
 
-  # patch for #within(timeout) method
-  module ::RSpec::Matchers
-    class BuiltIn::Change
-      def matches?(event_proc)
-        raise_block_syntax_error if block_given?
+    end
 
-        # to make #change work with #in(timeout) method
-        unless defined? @actual_before
-          @actual_before = evaluate_value_proc
-          event_proc.call
-        end
-        @actual_after = evaluate_value_proc
+  end
+end
 
-        (!change_expected? || changed?) && matches_before? && matches_after? && matches_expected_delta? && matches_min? && matches_max?
+# patch for #within(timeout) method
+# @private
+module ::RSpec::Matchers
+  class BuiltIn::Change
+    def matches?(event_proc)
+      raise_block_syntax_error if block_given?
+
+      # to make #change work with #in(timeout) method
+      unless defined? @actual_before
+        @actual_before = evaluate_value_proc
+        event_proc.call
       end
-    end
+      @actual_after = evaluate_value_proc
 
-    alias_method :make, :change
+      (!change_expected? || changed?) && matches_before? && matches_after? && matches_expected_delta? && matches_min? && matches_max?
+    end
   end
 
-  matchers = RSpec::Matchers::BuiltIn.constants.map(&:to_sym)
-  matchers.delete :BaseMatcher
-  matchers.each do |const|
-    Watir::RSpec.add_within_and_during_to_matcher RSpec::Matchers::BuiltIn.const_get const
-  end
+  alias_method :make, :change
+end
+
+matchers = RSpec::Matchers::BuiltIn.constants.map(&:to_sym)
+matchers.delete :BaseMatcher
+matchers.each do |const|
+  Watir::RSpec.add_within_and_during_to_matcher RSpec::Matchers::BuiltIn.const_get const
+end
 
 Watir::RSpec.add_within_and_during_to_matcher RSpec::Matchers::DSL::Matcher

data/watir-rspec.gemspec

@@ -16,4 +16,8 @@ Gem::Specification.new do |gem|
   gem.version       = Watir::RSpec::VERSION
 
   gem.add_dependency "rspec", "~>2.0"
+
+  gem.add_development_dependency "yard"
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "redcarpet"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: watir-rspec
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-29 00:00:00.000000000 Z
+date: 2013-01-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -27,6 +27,54 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Use Watir with RSpec with ease.
 email:
 - jarmo.p@gmail.com
@@ -35,6 +83,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .yardopts
 - Gemfile
 - LICENSE
 - README.md