lucid 0.0.4 → 0.0.5

data/lib/lucid/interface_rb/rb_lucid.rb

@@ -0,0 +1,119 @@
+module Lucid
+  module InterfaceRb
+    # It is necessary for the RbLucid module to be mixed in to the top level
+    # object. This is what allows TDL test definitions and hooks to be
+    # resolved as valid methods.
+    module RbLucid
+      class << self
+        attr_writer :rb_language
+
+        def alias_adverb(adverb)
+          alias_method adverb, :register_rb_step_definition
+        end
+
+        def build_rb_world_factory(domain_modules, proc)
+          @rb_language.build_rb_world_factory(domain_modules, proc)
+        end
+
+        def register_rb_hook(phase, tag_names, proc)
+          @rb_language.register_rb_hook(phase, tag_names, proc)
+        end
+
+        def register_rb_transform(regexp, proc)
+          @rb_language.register_rb_transform(regexp, proc)
+        end
+
+        def register_rb_step_definition(regexp, proc_or_sym, options = {})
+          @rb_language.register_rb_step_definition(regexp, proc_or_sym, options)
+        end
+      end
+
+      # Registers any number of +domain_modules+ (Ruby Modules) and/or a Proc.
+      # The +proc+ will be executed once before each scenario to create an
+      # Object that the scenario's steps will run within. Any +domain_modules+
+      # will be mixed into this Object (via Object#extend).
+      #
+      # This method is typically called from one or more Ruby scripts under
+      # <tt>common/support</tt>. You can call this method as many times as you
+      # like (to register more modules), but if you try to register more than
+      # one Proc you will get an error.
+      #
+      # Lucid will not yield anything to the +proc+. Examples:
+      #
+      #    Domain do
+      #      MyClass.new
+      #    end
+      #
+      #    Domain(MyModule)
+      #
+      def Domain(*domain_modules, &proc)
+        RbLucid.build_rb_world_factory(domain_modules, proc)
+      end
+
+      # Registers a proc that will run before each Scenario. You can register as many
+      # as you want (typically from ruby scripts under <tt>support/hooks.rb</tt>).
+      def Before(*tag_expressions, &proc)
+        RbLucid.register_rb_hook('before', tag_expressions, proc)
+      end
+
+      # Registers a proc that will run after each Scenario. You can register as many
+      # as you want (typically from ruby scripts under <tt>support/hooks.rb</tt>).
+      def After(*tag_expressions, &proc)
+        RbLucid.register_rb_hook('after', tag_expressions, proc)
+      end
+
+      # Registers a proc that will be wrapped around each scenario. The proc
+      # should accept two arguments: two arguments: the scenario and a "block"
+      # argument (but passed as a regular argument, since blocks cannot accept
+      # blocks in 1.8), on which it should call the .call method. You can register
+      # as many  as you want (typically from ruby scripts under <tt>support/hooks.rb</tt>).
+      def Around(*tag_expressions, &proc)
+        RbLucid.register_rb_hook('around', tag_expressions, proc)
+      end
+
+      # Registers a proc that will run after each Step. You can register as
+      # as you want (typically from ruby scripts under <tt>support/hooks.rb</tt>).
+      def AfterStep(*tag_expressions, &proc)
+        RbLucid.register_rb_hook('after_step', tag_expressions, proc)
+      end
+
+      # Registers a proc that will be called with a step definition argument if it
+      # matches the pattern passed as the first argument to Transform. Alternatively, if
+      # the pattern contains captures then they will be yielded as arguments to the
+      # provided proc. The return value of the proc is consequently yielded to the
+      # step definition.
+      def Transform(regexp, &proc)
+        RbLucid.register_rb_transform(regexp, proc)
+      end
+
+      # Registers a proc that will run after Lucid is configured. You can register as
+      # as you want (typically from ruby scripts under <tt>support/hooks.rb</tt>).
+      # TODO: Deprecate this
+      def AfterConfiguration(&proc)
+        RbLucid.register_rb_hook('after_configuration', [], proc)
+      end
+
+      # Registers a new Ruby StepDefinition. This method is aliased
+      # to <tt>Given</tt>, <tt>When</tt> and <tt>Then</tt>, and
+      # also to the i18n translations whenever a feature of a
+      # new language is loaded.
+      #
+      # If provided, the +symbol+ is sent to the <tt>Domain</tt> object
+      # as defined by #Domain. A new <tt>Domain</tt> object is created
+      # for each scenario and is shared across step definitions within
+      # that scenario. If the +options+ hash contains an <tt>:on</tt>
+      # key, the value for this is assumed to be a proc. This proc
+      # will be executed in the context of the <tt>Domain</tt> object
+      # and then sent the +symbol+.
+      #
+      # If no +symbol+ if provided then the +&proc+ gets executed in
+      # the context of the <tt>Domain</tt> object.
+      def register_rb_step_definition(regexp, symbol = nil, options = {}, &proc)
+        proc_or_sym = symbol || proc
+        RbLucid.register_rb_step_definition(regexp, proc_or_sym, options)
+      end
+    end
+  end
+end
+
+extend(Lucid::InterfaceRb::RbLucid)

data/lib/lucid/interface_rb/rb_step_definition.rb

@@ -0,0 +1,122 @@
+require 'lucid/step_match'
+require 'lucid/core_ext/string'
+require 'lucid/core_ext/proc'
+require 'lucid/interface_rb/regexp_argument_matcher'
+
+module Lucid
+  module InterfaceRb
+    # A Ruby Step Definition holds a Regexp and a Proc, and is created
+    # by calling <tt>Given</tt>, <tt>When</tt> or <tt>Then</tt>
+    # in the <tt>step_definitions</tt> ruby files. See also RbLucid.
+    #
+    # Example:
+    #
+    #   Given /I have (\d+) lucid testing on the mind/ do
+    #     # some code here
+    #   end
+    #
+    class RbStepDefinition
+
+      class MissingProc < StandardError
+        def message
+          "Step definitions must always have a proc or symbol"
+        end
+      end
+
+      class << self
+        def new(rb_language, pattern, proc_or_sym, options)
+          raise MissingProc if proc_or_sym.nil?
+          super rb_language, parse_pattern(pattern), create_proc(proc_or_sym, options)
+        end
+
+        private
+
+        def parse_pattern(pattern)
+          return pattern if pattern.is_a?(Regexp)
+          raise ArgumentError unless pattern.is_a?(String)
+          p = Regexp.escape(pattern)
+          p = p.gsub(/\\\$\w+/, '(.*)') # Replace $var with (.*)
+          Regexp.new("^#{p}$")
+        end
+
+        def create_proc(proc_or_sym, options)
+          return proc_or_sym if proc_or_sym.is_a?(Proc)
+          raise ArgumentError unless proc_or_sym.is_a?(Symbol)
+          message = proc_or_sym
+          target_proc = parse_target_proc_from(options)
+          lambda do |*args|
+            target = instance_exec(&target_proc)
+            target.send(message, *args)
+          end
+        end
+
+        def parse_target_proc_from(options)
+          return lambda { self } unless options.key?(:on)
+          target = options[:on]
+          case target
+          when Proc
+            target
+          when Symbol
+            lambda { self.send(target) }
+          else
+            lambda { raise ArgumentError, "Target must be a symbol or a proc" }
+          end
+        end
+      end
+
+      def initialize(rb_language, regexp, proc)
+        @rb_language, @regexp, @proc = rb_language, regexp, proc
+        @rb_language.available_step_definition(regexp_source, file_colon_line)
+      end
+
+      def regexp_source
+        @regexp.inspect
+      end
+
+      def to_hash
+        flags = ''
+        flags += 'm' if (@regexp.options & Regexp::MULTILINE) != 0
+        flags += 'i' if (@regexp.options & Regexp::IGNORECASE) != 0
+        flags += 'x' if (@regexp.options & Regexp::EXTENDED) != 0
+        {'source' => @regexp.source, 'flags' => flags}
+      end
+
+      def ==(step_definition)
+        regexp_source == step_definition.regexp_source
+      end
+
+      def arguments_from(step_name)
+        args = RegexpArgumentMatcher.arguments_from(@regexp, step_name)
+        @rb_language.invoked_step_definition(regexp_source, file_colon_line) if args
+        args
+      end
+
+      def invoke(args)
+        begin
+          args = @rb_language.execute_transforms(args)
+          @rb_language.current_domain.lucid_instance_exec(true, regexp_source, *args, &@proc)
+        rescue Lucid::ArityMismatchError => e
+          e.backtrace.unshift(self.backtrace_line)
+          raise e
+        end
+      end
+
+      def backtrace_line
+        @proc.backtrace_line(regexp_source)
+      end
+
+      def file_colon_line
+        case @proc
+        when Proc
+          @proc.file_colon_line
+        when Symbol
+          ":#{@proc}"
+        end
+      end
+
+      def file
+        @file ||= file_colon_line.split(':')[0]
+      end
+    end
+  end
+end

data/lib/lucid/interface_rb/rb_transform.rb

@@ -0,0 +1,57 @@
+module Lucid
+  module InterfaceRb
+    # A Ruby Transform holds a Regexp and a Proc, and is created
+    # by calling <tt>Transform in the <tt>support</tt> ruby files.
+    # See also RbLucid.
+    #
+    # Example:
+    #
+    #   Transform /^(\d+) lucid tests$/ do |lucid_string|
+    #     lucid_string.to_i
+    #   end
+    #
+    class RbTransform
+      class MissingProc < StandardError
+        def message
+          "Transforms must always have a proc with at least one argument"
+        end
+      end
+
+      def initialize(rb_language, pattern, proc)
+        raise MissingProc if proc.nil? || proc.arity < 1
+        @rb_language, @regexp, @proc = rb_language, Regexp.new(pattern), proc
+      end
+
+      def match(arg)
+        arg ? arg.match(@regexp) : nil
+      end
+
+      def invoke(arg)
+        if matched = match(arg)
+          args = matched.captures.empty? ? [arg] : matched.captures
+          @rb_language.current_domain.lucid_instance_exec(true, @regexp.inspect, *args, &@proc)
+        end
+      end
+
+      def to_s
+         convert_captures(strip_anchors(@regexp.source))
+      end
+
+    private
+      def convert_captures(regexp_source)
+        regexp_source.gsub(/(\()(?!\?:)/,'(?:')
+      end
+
+      def strip_captures(regexp_source)
+        regexp_source.
+          gsub(/(\()/, '').
+          gsub(/(\))/, '')
+      end
+
+      def strip_anchors(regexp_source)
+        regexp_source.
+          gsub(/(^\^|\$$)/, '')
+      end
+    end
+  end
+end

data/lib/lucid/interface_rb/rb_world.rb

@@ -0,0 +1,136 @@
+require 'gherkin/formatter/ansi_escapes'
+
+module Lucid
+  module InterfaceRb
+    # Defines the basic DSL methods available in all Lucid test definitions.
+    #
+    # You can, and probably should, extend this DSL with your own methods that
+    # make sense in your own domain.
+    # @see Lucid::InterfaceRb::RbLucid#Domain
+    module RbDomain
+
+      AnsiEscapes = Gherkin::Formatter::AnsiEscapes
+
+      # Call a Transform with a string from another Transform definition
+      def Transform(arg)
+        rb = @__lucid_runtime.load_code_language('rb')
+        rb.execute_transforms([arg]).first
+      end
+
+      # @private
+      attr_writer :__lucid_runtime, :__natural_language
+
+      # Run a single Gherkin step
+      # @example Call another step
+      #   step "I am logged in"
+      # @example Call a step with quotes in the name
+      #   step %{the user "Jeff" is logged in}
+      # @example Passing a table
+      #   step "the following users exist:", table(%{
+      #     | name   | email           |
+      #     | Jeff   | jeff@jeff.com   |
+      #     | Harley | harley@jeff.com |
+      #   })
+      # @example Passing a multiline string
+      #   step "the email should contain:", "Dear sir,\nYou've won a prize!\n"
+      # @param [String] name The name of the step
+      # @param [String,Lucid::AST::DocString,Lucid::AST::Table] multiline_argument
+      def step(name, multiline_argument=nil)
+        @__lucid_runtime.invoke(name, multiline_argument)
+      end
+
+      # Run a matcher of Gherkin
+      # @example
+      #   steps %{
+      #     Given the user "Jeff" exists
+      #     And I am logged in as "Jeff"
+      #   }
+      # @param [String] steps_text The Gherkin matcher to run
+      def steps(steps_text)
+        @__lucid_runtime.invoke_steps(steps_text, @__natural_language, caller[0])
+      end
+
+      # Parse Gherkin into a {Lucid::AST::Table} object.
+      #
+      # Useful in conjunction with the #step method.
+      # @example Create a table
+      #   users = table(%{
+      #     | name   | email           |
+      #     | Jeff   | jeff@jeff.com   |
+      #     | Harley | harley@jeff.com |
+      #   })
+      # @param [String] text_or_table The Gherkin string that represents the table
+      def table(text_or_table, file=nil, line_offset=0)
+        @__lucid_runtime.table(text_or_table, file, line_offset)
+      end
+
+      # Create an {Lucid::AST::DocString} object
+      #
+      # Useful in conjunction with the #step method, when
+      # want to specify a content type.
+      # @example Create a multiline string
+      #   code = multiline_string(%{
+      #     puts "this is ruby code"
+      #   %}, 'ruby')
+      def doc_string(string_without_triple_quotes, content_type='', line_offset=0)
+        # TODO: rename this method to multiline_string
+        @__lucid_runtime.doc_string(string_without_triple_quotes, content_type, line_offset)
+      end
+
+      # @deprecated Use {#puts} instead.
+      def announce(*messages)
+        STDERR.puts AnsiEscapes.failed + "WARNING: #announce is deprecated. Use #puts instead:" + caller[0] + AnsiEscapes.reset
+        puts(*messages)
+      end
+
+      # Print a message to the output.
+      #
+      # @note Lucid might surprise you with the behavior of this method. Instead
+      #   of sending the output directly to STDOUT, Lucid will intercept and cache
+      #   the message until the current step has finished, and then display it.
+      #   
+      #   If you'd prefer to see the message immediately, call {Kernel.puts} instead.
+      def puts(*messages)
+        @__lucid_runtime.puts(*messages)
+      end
+
+      # Pause the tests and ask the operator for input
+      def ask(question, timeout_seconds=60)
+        @__lucid_runtime.ask(question, timeout_seconds)
+      end
+
+      # Embed an image in the output
+      def embed(file, mime_type, label='Screenshot')
+        @__lucid_runtime.embed(file, mime_type, label)
+      end
+
+      # Mark the matched step as pending.
+      def pending(message = "TODO")
+        if block_given?
+          begin
+            yield
+          rescue Exception
+            raise Pending.new(message)
+          end
+          raise Pending.new("Expected pending '#{message}' to fail. No Error was raised. No longer pending?")
+        else
+          raise Pending.new(message)
+        end
+      end
+
+      # Prints the list of modules that are included in the Domain
+      def inspect
+        modules = [self.class]
+        (class << self; self; end).instance_eval do
+          modules += included_modules
+        end
+        sprintf("#<%s:0x%x>", modules.join('+'), self.object_id)
+      end
+
+      # see {#inspect}
+      def to_s
+        inspect
+      end
+    end
+  end
+end

data/lib/lucid/interface_rb/regexp_argument_matcher.rb

@@ -0,0 +1,21 @@
+require 'gherkin/formatter/argument'
+
+module Lucid
+  module InterfaceRb
+    class RegexpArgumentMatcher
+      def self.arguments_from(regexp, step_name)
+        match = regexp.match(step_name)
+        if match
+          n = 0
+          match.captures.map do |val|
+            n += 1
+            offset = match.offset(n)[0]
+            Gherkin::Formatter::Argument.new(offset, val)
+          end
+        else
+          nil
+        end
+      end
+    end
+  end
+end