lopata 0.1.3 → 0.1.8

data/lib/lopata/scenario.rb

@@ -1,43 +1,65 @@
 require 'rspec/expectations'
 
+# Scenario runtime class.
+#
+# All the scenarios are running in context of separate Lopata::Scenario object.
+#
 class Lopata::Scenario
   include RSpec::Matchers
 
+  # @private
   attr_reader :execution
 
+  # @private
   def initialize(execution)
     @execution = execution
   end
 
   # Marks current step as pending
+  # @example
+  #     it 'pending step' do
+  #       pending
+  #       expect(1).to eq 2
+  #     end
+  #
+  # Pending steps wont be failed
   def pending(message = nil)
     execution.current_step.pending!(message)
   end
 
+  # @return [Hash] metadata available for current step
+  # @note The metadata keys also availalbe as methods (via method_missing)
   def metadata
     execution.metadata
   end
 
   private
 
+  # @private
   def method_missing(method, *args, &block)
-    if metadata.keys.include?(method)
+    if execution.let_methods.include?(method)
+      instance_exec(*args, &execution.let_methods[method])
+    elsif metadata.keys.include?(method)
       metadata[method]
     else
       super
     end
   end
 
+  # @private
   def respond_to_missing?(method, *)
-    metadata.keys.include?(method) or super
+    execution.let_methods.include?(method) or metadata.keys.include?(method) or super
   end
 
+  # @private
+  # Scenario execution and live-cycle information
   class Execution
     attr_reader :scenario, :status, :steps, :title, :current_step
 
     def initialize(title, options_title, metadata = {})
       @title = [title, options_title].compact.reject(&:empty?).join(' ')
       @metadata = metadata
+      @let_methods = {}
       @status = :not_runned
       @steps = []
       @scenario = Lopata::Scenario.new(self)
@@ -45,11 +67,12 @@ class Lopata::Scenario
 
     def run
       @status = :running
+      sort_steps
       world.notify_observers(:scenario_started, self)
-      steps_in_running_order.each(&method(:run_step))
+      steps.each(&method(:run_step))
       @status = steps.any?(&:failed?) ? :failed : :passed
       world.notify_observers(:scenario_finished, self)
-      @scenario = nil # cleanup memory after scenario executon
+      cleanup
     end
 
     def run_step(step)
@@ -57,18 +80,19 @@ class Lopata::Scenario
       @current_step = step
       step.run(scenario)
       skip_rest if step.failed? && step.skip_rest_on_failure?
+      @current_step = nil
     end
 
     def world
-      @world ||= Lopata::Config.world
+      Lopata.world
     end
 
     def failed?
       status == :failed
     end
 
-    def steps_in_running_order
-      steps.reject(&:teardown_group?) + steps.select(&:teardown_group?)
+    def sort_steps
+      @steps = steps.reject(&:teardown_group?) + steps.select(&:teardown_group?)
     end
 
     def skip_rest
@@ -82,5 +106,31 @@ class Lopata::Scenario
         @metadata
       end
     end
+
+    def let_methods
+      if current_step
+        @let_methods.merge(current_step.let_methods)
+      else
+        @let_methods
+      end
+    end
+
+    def let(method_name, &block)
+      # define_singleton_method method_name, &block
+      base =
+        if current_step && !current_step.groups.empty?
+          current_step.groups.last.let_methods
+        else
+          @let_methods
+        end
+      base[method_name] = block
+    end
+
+    def cleanup
+      @title = nil
+      @metadata = nil
+      @steps = nil
+      @scenario = nil
+    end
   end
 end

data/lib/lopata/scenario_builder.rb

@@ -1,19 +1,41 @@
+# Context for scenario creation.
 class Lopata::ScenarioBuilder
-  attr_reader :title, :common_metadata
+  # @private
+  attr_reader :title, :common_metadata, :options, :diagonals
+  # @private
   attr_accessor :shared_step, :group
 
+  # Defines one or more scenarios.
+  #
+  # @example
+  #     Lopata.define 'scenario' do
+  #       setup 'test user'
+  #       action 'login'
+  #       verify 'home page displayed'
+  #     end
+  #
+  # Given block will be calculated in context of the ScenarioBuilder
+  #
+  # @param title [String] scenario unique title
+  # @param metadata [Hash] metadata to be used within the scenario
+  # @param block [Block] the scenario definition
+  # @see Lopata.define
   def self.define(title, metadata = {}, &block)
     builder = new(title, metadata)
     builder.instance_exec &block
     builder.build
   end
 
+  # @private
   def initialize(title, metadata = {})
     @title, @common_metadata = title, metadata
+    @diagonals = []
+    @options = []
   end
 
+  # @private
   def build
-    filters = Lopata::Config.filters
+    filters = Lopata.configuration.filters
     option_combinations.each do |option_set|
       metadata = common_metadata.merge(option_set.metadata)
       scenario = Lopata::Scenario::Execution.new(title, option_set.title, metadata)
@@ -31,35 +53,104 @@ class Lopata::ScenarioBuilder
     end
   end
 
-  def as(*args, &block)
-    @roles = args.flatten
-    @roles << CalculatedValue.new(&block) if block_given?
-    @role_options = nil
+  # @!group Defining variants
+
+  # Define option for the scenario.
+  #
+  # The scenario will be generated for all the options.
+  # If more then one option given, the scenarios for all options combinations will be generated.
+  #
+  # @param metadata_key [Symbol] the key to access option data via metadata.
+  # @param variants [Hash{String => Object}] variants for the option
+  #   Keys are titles of the variant, values are metadata values.
+  #
+  # @example
+  #   Lopata.define 'scenario' do
+  #     option :one, 'one' => 1, 'two' => 2
+  #     option :two, 'two' => 2, 'three' => 3
+  #     # will generate 4 scenarios:
+  #     # - 'scenario one two'
+  #     # - 'scenario one three'
+  #     # - 'scenario two two'
+  #     # - 'scenario two three'
+  #   end
+  #
+  # @see #diagonal
+  def option(metadata_key, variants)
+    @options << Option.new(metadata_key, variants)
   end
 
-  def role_options
-    @role_options ||= build_role_options
+  # Define diagonal for the scenario.
+  #
+  # The scenario will be generated for all the variants of the diagonal.
+  # Each variant of diagonal will be selected for at least one scenario.
+  # It may be included in more then one scenario when other diagonal or option has more variants.
+  #
+  # @param metadata_key [Symbol] the key to access diagonal data via metadata.
+  # @param variants [Hash{String => Object}] variants for the diagonal.
+  #   Keys are titles of the variant, values are metadata values.
+  #
+  # @example
+  #   Lopata.define 'scenario' do
+  #     option :one, 'one' => 1, 'two' => 2
+  #     diagonal :two, 'two' => 2, 'three' => 3
+  #     diagonal :three, 'three' => 3, 'four' => 4, 'five' => 5
+  #     # will generate 3 scenarios:
+  #     # - 'scenario one two three'
+  #     # - 'scenario two three four'
+  #     # - 'scenario one two five'
+  #   end
+  #
+  # @see #option
+  def diagonal(metadata_key, variants)
+    @diagonals << Diagonal.new(metadata_key, variants)
   end
 
+  # Define additional metadata for the scenario
+  #
+  # @example
+  #     Lopata.define 'scenario' do
+  #       metadata key: 'value'
+  #       it 'metadata available' do
+  #         expect(metadata[:key]).to eq 'value'
+  #       end
+  #     end
   def metadata(hash)
     raise 'metadata expected to be a Hash' unless hash.is_a?(Hash)
     @common_metadata ||= {}
     @common_metadata.merge! hash
   end
 
-  def without_user
-    @without_user = true
-  end
-
+  # Skip scenario for given variants combination
+  #
+  # @example
+  #     Lopata.define 'multiple options' do
+  #       option :one, 'one' => 1, 'two' => 2
+  #       option :two, 'two' => 2, 'three' => 3
+  #       skip_when { |opt| opt.metadata[:one] == opt.metadata[:two] }
+  #       it 'not equal' do
+  #         expect(one).to_not eq two
+  #       end
+  #     end
+  #
   def skip_when(&block)
     @skip_when = block
   end
 
+  # @private
   def skip?(option_set)
     @skip_when && @skip_when.call(option_set)
   end
 
-  %i{ setup action it teardown verify context }.each do |name|
+  # @!endgroup
+
+  # @!group Defining Steps
+
+  # @private
+  # @macro [attach] define_step_method
+  #   @!scope instance
+  #   @method $1
+  def self.define_step_method(name)
     name_if = "%s_if" % name
     name_unless = "%s_unless" % name
     define_method name, ->(*args, **metadata, &block) { add_step(name, *args, metadata: metadata, &block) }
@@ -71,6 +162,124 @@ class Lopata::ScenarioBuilder
     }
   end
 
+  # Define setup step.
+  # @example
+  #   setup do
+  #   end
+  #
+  #   # setup from named shared step
+  #   setup 'create user'
+  #
+  #   # setup with both shared step and code block
+  #   setup 'create user' do
+  #     @user.update(admin: true)
+  #   end
+  #
+  # Setup step used for set test data.
+  # @overload setup(*steps, &block)
+  #   @param steps [Array<String, Symbol, Proc>] the steps to be runned as a part of setup.
+  #     String - name of shared step to be called.
+  #     Symbol - metadata key, referenced to shared step name.
+  #     Proc - in-place step implementation.
+  #   @param block [Block] The implementation of the step.
+  define_step_method :setup
+
+  # Define action step.
+  # @example
+  #   action do
+  #   end
+  #
+  #   # action from named shared step
+  #   action 'login'
+  #
+  #   # setup with both shared step and code block
+  #   action 'login', 'go dashboard' do
+  #     @user.update(admin: true)
+  #   end
+  #
+  # Action step is used for emulate user or external system action
+  #
+  # @overload action(*steps, &block)
+  #   @param steps [Array<String, Symbol, Proc>] the steps to be runned as a part of action.
+  #     String - name of shared step to be called.
+  #     Symbol - metadata key, referenced to shared step name.
+  #     Proc - in-place step implementation.
+  #   @param block [Block] The implementation of the step.
+  define_step_method :action
+
+  # Define teardown step.
+  # @example
+  #   setup { @user = User.create! }
+  #   teardown { @user.destroy }
+  # Teardown step will be called at the end of scenario running.
+  # But it suggested to be decared right after setup or action step which require teardown.
+  #
+  # @overload teardown(*steps, &block)
+  #   @param steps [Array<String, Symbol, Proc>] the steps to be runned as a part of teardown.
+  #     String - name of shared step to be called.
+  #     Symbol - metadata key, referenced to shared step name.
+  #     Proc - in-place step implementation.
+  #   @param block [Block] The implementation of the step.
+  define_step_method :teardown
+
+  # Define verify steps.
+  # @example
+  #   verify 'home page displayed' # call shared step.
+  # Usually for validation shared steps inclusion
+  #
+  # @overload verify(*steps, &block)
+  #   @param steps [Array<String, Symbol, Proc>] the steps to be runned as a part of verification.
+  #     String - name of shared step to be called.
+  #     Symbol - metadata key, referenced to shared step name.
+  #     Proc - in-place step implementation.
+  #   @param block [Block] The implementation of the step.
+  define_step_method :verify
+
+  # Define group of steps.
+  # The metadata for the group may be overriden
+  # @example
+  #   context 'the task', task: :created do
+  #     verify 'task setup'
+  #     it 'created' do
+  #       expect(metadata[:task]).to eq :created
+  #     end
+  #   end
+  # Teardown steps within group will be called at the end of the group, not scenario
+  # @overload context(title, **metadata, &block)
+  #   @param title [String] context title
+  #   @param metadata [Hash] the step additional metadata
+  #   @param block [Block] The implementation of the step.
+  define_step_method :context
+
+  # Define single validation step.
+  # @example
+  #   it 'works' do
+  #     expect(1).to eq 1
+  #   end
+  # @overload it(title, &block)
+  #   @param title [String] validation title
+  #   @param block [Block] The implementation of the step.
+  define_step_method :it
+
+  # Define runtime method for the scenario.
+  #
+  # @note
+  #   The method to be called via #method_missing, so it wont override already defined methods.
+  #
+  # @example
+  #   let(:square) { |num| num * num }
+  #   it 'calculated' do
+  #     expect(square(4)).to eq 16
+  #   end
+  def let(method_name, &block)
+    steps << Lopata::Step.new(:let) do
+      execution.let(method_name, &block)
+    end
+  end
+
+  # @!endgroup
+
+  # @private
   def add_step(method_name, *args, condition: nil, metadata: {}, &block)
     step_class =
       case method_name
@@ -78,84 +287,43 @@ class Lopata::ScenarioBuilder
       when /^(context)/ then Lopata::GroupStep
       else Lopata::Step
       end
-    step = step_class.new(method_name, *args, condition: condition, shared_step: shared_step, group: group, &block)
+    step = step_class.new(method_name, *args, condition: condition, shared_step: shared_step, &block)
     step.metadata = metadata
     steps << step
   end
 
+  # @private
   def steps
     @steps ||= []
   end
 
+  # @private
   def steps_with_hooks
     s = []
-    unless Lopata::Config.before_scenario_steps.empty?
-      s << Lopata::ActionStep.new(:setup, *Lopata::Config.before_scenario_steps)
+    unless Lopata.configuration.before_scenario_steps.empty?
+      s << Lopata::ActionStep.new(:setup, *Lopata.configuration.before_scenario_steps)
     end
 
     s += steps
 
-    unless Lopata::Config.after_scenario_steps.empty?
-      s << Lopata::ActionStep.new(:teardown, *Lopata::Config.after_scenario_steps)
+    unless Lopata.configuration.after_scenario_steps.empty?
+      s << Lopata::ActionStep.new(:teardown, *Lopata.configuration.after_scenario_steps)
     end
 
     s
   end
 
-  def cleanup(*args, &block)
-    add_step_as_is(:cleanup, *args, &block)
-  end
-
-  def add_step_as_is(method_name, *args, &block)
-    steps << Lopata::Step.new(method_name, *args) do
-      # do not convert args - symbols mean name of instance variable
-      # run_step method_name, *args, &block
-      instance_exec(&block) if block
-    end
-  end
-
-  def let(method_name, &block)
-    steps << Lopata::Step.new(nil) do
-      define_singleton_method method_name, &block
-    end
-  end
-
-  def build_role_options
-    return [] unless roles
-    [Diagonal.new(:as, roles.map { |r| [nil, r] })]
-  end
-
-  def roles
-    return false if @without_user
-    @roles ||= [Lopata::Config.default_role].compact
-  end
-
-  def option(metadata_key, variants)
-    options << Option.new(metadata_key, variants)
-  end
-
-  def diagonal(metadata_key, variants)
-    diagonals << Diagonal.new(metadata_key, variants)
-  end
-
-  def options
-    @options ||= []
-  end
-
-  def diagonals
-    @diagonals ||= []
-  end
-
+  # @private
   def option_combinations
-    combinations = combine([OptionSet.new], options + diagonals + role_options)
-    while !(diagonals + role_options).all?(&:complete?)
-      combinations << OptionSet.new(*(options + diagonals + role_options).map(&:next_variant))
+    combinations = combine([OptionSet.new], options + diagonals)
+    while !diagonals.all?(&:complete?)
+      combinations << OptionSet.new(*(options + diagonals).map(&:next_variant))
     end
     combinations.reject { |option_set| skip?(option_set) }
   end
 
+  # @private
   def combine(source_combinations, rest_options)
-    # raise 'source_combinations cannot be empty' if source_combinations.blank?
     return source_combinations if rest_options.empty?
     combinations = []
     current_option = rest_options.shift
@@ -167,40 +335,50 @@ class Lopata::ScenarioBuilder
     combine(combinations, rest_options)
   end
 
+  # @private
   def world
-    @world ||= Lopata::Config.world
+    Lopata.world
   end
 
-  # Набор вариантов, собранный для одного теста
+  # Set of options for scenario
   class OptionSet
+    # @private
     attr_reader :variants
+
+    # @private
     def initialize(*variants)
       @variants = {}
       variants.compact.each { |v| self << v }
     end
 
+    # @private
     def +(other_set)
       self.class.new(*@variants.values).tap do |sum|
         other_set.each { |v| sum << v }
       end
     end
 
+    # @private
     def <<(variant)
       @variants[variant.key] = variant
     end
 
+    # @private
     def [](key)
       @variants[key]
     end
 
+    # @private
     def each(&block)
       @variants.values.each(&block)
     end
 
+    # @private
     def title
       @variants.values.map(&:title).compact.join(' ')
     end
 
+    # @return [Hash{Symbol => Object}] metadata for this option set
     def metadata
       @variants.values.inject({}) do |metadata, variant|
         metadata.merge(variant.metadata(self))
@@ -208,6 +386,7 @@ class Lopata::ScenarioBuilder
     end
   end
 
+  # @private
   class Variant
     attr_reader :key, :title, :value, :option
 
@@ -256,6 +435,7 @@ class Lopata::ScenarioBuilder
       end
   end
 
+  # @private
   class CalculatedValue
     def initialize(&block)
       @proc = block
@@ -266,6 +446,7 @@ class Lopata::ScenarioBuilder
     end
   end
 
+  # @private
   class Option
     attr_reader :variants, :key
     def initialize(key, variants)
@@ -301,6 +482,7 @@ class Lopata::ScenarioBuilder
     end
   end
 
+  # @private
   class Diagonal < Option
     def level_variants
       [next_variant]