waw 0.2.2

data/lib/waw/wspec/dsl.rb

@@ -0,0 +1,201 @@
+require 'test/unit/assertions'
+module Waw
+  module WSpec
+    # 
+    # Provides the DSL of the .wspec scenario language.
+    #
+    class DSL
+      include ::Waw::ScopeUtils
+      include ::Test::Unit::Assertions
+      include HTMLAnalysis
+    
+      # Creates a DSL instance for a given scenario
+      def initialize(waw_kernel, scenario)
+        @waw_kernel = waw_kernel
+        @scenario = scenario
+        @browser = Browser.new
+      end
+      
+      # Returns waw kernel
+      def waw_kernel
+        @waw_kernel
+      end
+      
+      #################################################################### Semi-private utilities
+      
+      # Executes some code
+      def __execute(&block)
+        self.instance_eval(&block)
+      end
+      alias :by_the_way :__execute
+    
+      # A stack of execution context  
+      def __stack
+        @stack ||= []
+      end
+      
+      # Returns the last because clause
+      def __last_because
+        __stack.last || @scenario.name
+      end
+      
+      # Adds an assertion
+      def add_assertion
+        @scenario.add_assertion
+      end
+      
+      #################################################################### About scoping
+      
+      # Delegates to waw ressources
+      def method_missing(name, *args, &block)
+        if args.empty? and resources and resources.has_resource?(name)
+          resources[name]
+        else
+          super(name, *args, &block)
+        end
+      end
+      
+      #################################################################### About browser
+      
+      # Returns the current browser instance
+      def browser
+        @browser
+      end
+      
+      # Returns current browser contents (used by HTMLAnalysis)
+      def browser_contents
+        browser.contents
+      end
+      alias :contents :browser_contents
+      
+      # Returns the URL of the index page (the web_base actually)
+      # This method returns nil unless the Waw application has been loaded
+      def index_page
+        config && config.web_base
+      end
+      
+      # Goes to a given location and returns the HTTPResponse object
+      def go(location)
+        browser.location = location
+        browser.response
+      end
+      
+      # Simply returns args
+      def with(args = {})
+        args
+      end
+      
+      #################################################################### About scenario execution
+      
+      # Because some condition holds...
+      def because(msg="Unknown cause", &block)
+        raise ArgumentError, "WSpec because/therefore expects a block" unless block
+        __stack.push(msg)
+        yield(browser)
+        __stack.pop
+      end
+      alias :therefore :because
+      
+      #################################################################### About reaching pages
+      
+      # Asserts that a page can be reached, leading to a Net::HTTPSuccess result
+      def i_reach(which_page)
+        result = go(which_page)
+        assert Net::HTTPSuccess===result, __last_because + " (cannot actually reach #{which_page}: #{result})"
+      end
+      
+      # Asserts that a page could be reached (requesting headers leads to a Net::HTTPSucess result)
+      def i_could_reach(which_page)
+        return if which_page.nil? or '#'==which_page 
+        case which_page
+          when Tag
+            i_could_reach(which_page[:href])
+          when Array
+            which_page.each{|link| i_could_reach(link)}
+          when String
+            result = browser.headers_fetch(which_page)
+            assert Net::HTTPSuccess===result, __last_because + " (could not reach #{which_page}: #{result})"
+          else
+            raise ArgumentError, "Unable to use #{which_page} for i_could_reach"
+        end
+      end
+      
+      # Asserts that a page cannot be reached, leading to a Net::HTTPNotFound or a Net::HTTPForbidden (403)
+      # result
+      def i_dont_reach(which_page)
+        result = go(which_page)
+        assert (Net::HTTPNotFound===result or Net::HTTPForbidden===result), __last_because + " (can reach #{which_page}: #{result})"
+      end
+      
+      # Asserts that a page may not be reached, leading to a Net::HTTPForbidden (403) result.
+      def i_may_not_reach(which_page)
+        result = go(which_page)
+        assert (Net::HTTPForbidden===result or Net::HTTPBadRequest===result), __last_because + " (may actually reach #{which_page}: #{result})"
+      end
+      
+      #################################################################### About seeing something on the page
+      
+      # Asserts that something can be seen on the current page
+      def i_see(what)
+        assert i_see?(what), __last_because + " (don't see #{what})"
+      end
+      
+      # Asserts that something is not present on the current page
+      def i_dont_see(what)
+        assert !i_see?(what), __last_because + " (actually see #{what})"
+      end
+      
+      # Asserts that I see a particular tag (see HTMLAnalysis.tag)
+      def i_see_tag(name, opts = nil)
+        assert has_tag?(name, opts), __last_because + " (don't see tag <#{name} #{opts.inspect})"
+      end
+      
+      # Asserts that I see a particular link (see HTMLAnalysis.link)
+      def i_see_link(opts = nil)
+        assert has_link?(opts), __last_because + " (dont see link <a #{opts.inspect})"
+      end
+      
+      #################################################################### About link-based navigation
+      
+      # Following a link
+      def i_follow(link)
+        link = case link
+          when String
+            link
+          when Tag
+            link[:href]
+          when ::Waw::ActionController::Action
+            link.href
+          else
+            raise ArgumentError, "Unable to apply i_follow to #{link.inspect}"
+        end
+        i_reach(link)
+      end
+      
+      #################################################################### About forms and action
+      
+      # Submits some form with optional arguments
+      def i_submit(form, args = {})
+        assert_not_nil form, __last_because + "(form has not been found)"
+        raise ArgumentError, "i_submit requires a Tag instance, #{form.inspect} received" unless Tag===form
+        i_invoke(form[:action], args)
+      end
+      
+      # Directly invoke an action or service server side, bypassing 
+      # form lookup and so on.
+      def i_invoke(action, args = {})
+        result = case action
+          when String
+            browser.invoke_service(action, args)
+          when ::Waw::ActionController::Action
+            browser.invoke_action(action, args)
+          else
+            raise ArgumentError, "Unable to apply i_invoke on #{action.inspect}, unable to catch the associated action"
+        end
+        assert Net::HTTPSuccess===result, __last_because + " (invoking #{action.inspect} led to: #{result})"
+        result
+      end
+      
+    end # class DSL
+  end # module WSpec
+end # module Waw

data/lib/waw/wspec/html_analysis.rb

@@ -0,0 +1,136 @@
+require 'waw/wspec/html_analysis/tag'
+module Waw
+  module WSpec
+    #
+    # Provides utility methods for analysis of XML/HTML contents.
+    #
+    # This module expects an accessor to a browser instance. Otherwise,
+    # the browser_contents method may be overrided.
+    #
+    module HTMLAnalysis
+
+      # Yields the block passing browser contents as first argument
+      def browser_contents
+        browser.contents
+      end
+      
+      # Decodes a string of HTML attributes as a hash with symbols as keys
+      def decode_attributes_string(str)
+        attrs = {}
+        str.scan(/([a-z]+)=["'](.*?)["']/) do |match|
+          attrs[match[0].to_sym] = match[1]
+        end
+        attrs
+      end
+      
+      #################################################################### Tag helpers
+      
+      # Find tags inside the browser contents. If a block is given, yield it with
+      # each tag information. Otherwise, returns an array of found tags, that can be
+      # empty.
+      def all_tags(name, opts = nil, contents = browser_contents)
+        found = [] unless block_given?
+        contents.scan(/(<\s*#{name}\s*(.*?)\/?>)/) do |match|
+          tag = Tag.new(match[0], name, decode_attributes_string(match[1]))
+          next unless tag.matches?(opts)
+          block_given? ? yield(tag) : (found << tag)
+        end
+        found
+      end
+      alias :tags :all_tags
+      
+      # Iterates over a tag specification
+      def each_tag(name, opts = nil, contents = browser_contents, &block)
+        tags(name, opts, contents, &block)
+      end
+      
+      # Shortcut for <code>tags(name, opts, contents)[0]</code>. Returns nil if no such 
+      # tag can be found
+      def first_tag(name, opts = nil, contents = browser_contents)
+        tags(name, opts, contents)[0]
+      end
+      alias :tag :first_tag
+
+      # Look for some html tag
+      def has_tag?(name, opts = nil, contents = browser_contents)
+        return tags(name, opts, contents).size != 0
+      end
+
+      #################################################################### Links helpers
+      
+      # Shortcut for <code>tags('a', {:href => /^(.*?)$/}.merge(opts), contents, &block)</code>
+      def all_links(opts = nil, contents = browser_contents, &block)
+        tags('a', {:href => /^(.*?)$/}.merge(opts || {}), contents, &block)
+      end
+      alias :links :all_links
+      
+      # Same as all_links, but retains internal links only (i.e. <code>not(URI::Generic.absolute?)</code>)
+      def all_internal_links(opts = nil, contents = browser_contents, &block)
+        if block
+          all_links(opts, contents).each do |link|
+            yield(link) unless URI.parse(link[:href]).absolute?
+          end
+        else
+          all_links(opts, contents).reject{|link| URI.parse(link[:href]).absolute?}
+        end
+      end
+      alias :internal_links :all_internal_links
+      
+      # Same as all_links, but retains external links only (i.e. <code>URI::Generic.absolute?</code>)
+      def all_external_links(opts = nil, contents = browser_contents, &block)
+        if block
+          all_links(opts, contents).each do |link|
+            yield(link) if URI.parse(link[:href]).absolute?
+          end
+        else
+          all_links(opts, contents).select{|link| URI.parse(link[:href]).absolute?}
+        end
+      end 
+      alias :external_links :all_external_links
+      
+      # Shortcut for <code>links(name, opts, contents)[0]</code>. Returns nil if no such 
+      # link can be found
+      def first_link(opts = nil, contents = browser_contents)
+        links(opts, contents)[0]
+      end
+      alias :link :first_link
+
+      # Checks if some link can be found
+      def has_link?(opts = nil, contents = browser_contents)
+        return links(opts, contents).size != 0
+      end
+      
+      #################################################################### Form helpers
+      
+      # Shortcut for <code>tag('form', opts, contents)</code>
+      def form(opts = nil, contents = browser_contents)
+        if opts[:action] and ::Waw::ActionController::Action===opts[:action]
+          action = opts[:action]
+          opts = {:id => action.id}.merge(opts || {}).forget(:action)
+          form = tag('form', opts, contents)
+          form[:action] = action if form
+          form
+        else
+          tag('form', opts, contents)
+        end
+      end
+      
+      #################################################################### Text helpers
+      
+      # Assert that the user sees something in the browser contents
+      def i_see?(what, contents = browser_contents)
+        case what
+          when NilClass
+            false
+          when String, Regexp
+            not(contents.index(what).nil?)
+          when Tag
+            true
+          else
+            raise ArgumentError, "Unable to see #{what}, not understood"
+        end
+      end
+      
+    end # module HTMLAnalysis
+  end # module WSpec
+end # module Waw

data/lib/waw/wspec/html_analysis/tag.rb

@@ -0,0 +1,56 @@
+module Waw
+  module WSpec
+    module HTMLAnalysis
+      
+      # A tag helper class
+      class Tag
+
+        # Result of the regexp matching applied to get this tag
+        attr_reader :match
+        
+        # Name of the tag
+        attr_reader :name
+        
+        # Tag attributes
+        attr_reader :attributes
+        
+        # Creates a Tag instance
+        def initialize(match, name, attributes)
+          @match, @name, @attributes = match, name, attributes
+        end
+        
+        # Returns the value of an attribute
+        def [](key)
+          attributes[key]
+        end
+        
+        # Forces the value of an attribute
+        def []=(key, value)
+          attributes[key] = value
+        end
+        
+        # Checks if this tags has a given attribute
+        def has_attribute?(name)
+          attributes.has_key?(name)
+        end
+        
+        # Checks if this tag matches a given attributes specification
+        def matches?(opts = {})
+          return true if (opts.nil? or opts.empty?)
+          opts.each_pair do |name, value|
+            return false unless self.has_attribute?(name)
+            case value
+              when Regexp
+                return false unless value =~ self[name]
+              else
+                return false unless value.to_s == self[name]
+            end
+          end
+          true
+        end
+        
+      end # class Tag
+
+    end # module HTMLAnalysis
+  end # module WSpec
+end # module Waw

data/lib/waw/wspec/runner.rb

@@ -0,0 +1,70 @@
+require 'waw'
+require 'waw/wspec'
+
+if RUBY_VERSION >= "1.9"
+  # These classes don't seem to exist in some Ruby 1.9 installations
+  module Test
+    module Unit
+      class AssertionFailedError < StandardError
+      end
+    end
+  end
+else
+  # These classes don't seem to exist in some Ruby 1.8 installations
+  module MiniTest
+    class Assertion < StandardError
+    end
+  end
+end
+
+# The autoloaded scenarios
+$scenarios = []
+def scenario(name, &block)
+  $scenarios << Waw::WSpec::Scenario.new(name, &block)
+end
+alias :requirement :scenario
+
+# We run the whole suite at end
+at_exit {
+  begin
+    puts "Running wspec test suite now"
+  
+    # Load waw through rack in a different thread
+    puts "Loading waw application and web server"
+    t = Thread.new(Waw.kernel) do |app|
+      begin
+        server = Rack::Handler::Mongrel
+      rescue LoadError => e
+        server = Rack::Handler::WEBrick
+      end
+      options = {:Port => Waw.config.web_port, :Host => "0.0.0.0", :AccessLog => []}
+      server.run app, options
+    end
+  
+    # Wait until the server is loaded
+    try, ok = 0, false
+    begin
+      puts "Attempting to reach the web server..."
+      Net::HTTP.get(URI.parse(Waw.config.web_base))
+      ok = true
+    rescue Errno::ECONNREFUSED => ex
+      sleep 0.1
+    end until (ok or (try += 1)>10)
+  
+    # Create the suite and run it
+    if ok
+      s = ::Waw::WSpec::Suite.new($scenarios)
+      t1 = Time.now
+      s.run(Waw.kernel)
+      t2 = Time.now
+      puts "\nFinished in #{Time.now - t1} seconds.\n"
+      puts "#{s.scenario_count} high-level requirements, #{s.assertion_count} assertions, #{s.failure_count} failures, #{s.error_count} errors"
+    else
+      raise WawError, "Unable to reach the local web server... sorry!"
+    end
+
+  ensure   
+    # Kill the web server thread
+    t.kill if t
+  end
+}