lopata 0.1.2 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 996fe5f1c16b6fed5daadff4ce365a778c2f09d79562c221e497c541541e9012
-  data.tar.gz: 7200a98d6bead7fb3baed82bbdffbf1c6aca805d999a563f3ada78026344dfed
+  metadata.gz: 7f4b4814d88cd3b9da3a34159e3c1c977d05cbb0504d3dc0b2ab8034044dfbf0
+  data.tar.gz: 378e5a3c346c64cb4430577dcfab31cfefd54a2c8e8ee30046609cf10e1bdba4
 SHA512:
-  metadata.gz: 037ccc6d687292186b752de6924a2f3373d0934569f9e2d01567cac1a4607aa33ce70f53473ad0d737d07cdb1da231bb8b526f6c24f8c2e73d494978dfc94179
-  data.tar.gz: 7c90f679400d64d7ab676807cea167947cee47114cf9ea8daed84c517888bf5e7e64b475c1841f9e6cb886cf08184ca3acedaf6dc5af68a3518e74e4130f91b7
+  metadata.gz: ff0498d9c9b665d52f5a8d1e65cdc6dc9078f0df1cd4f7fd831393af04ee564a5cf9a9f55305bd4423ff92062cdb7fd4a728bb2be657f196f91447faddffa941
+  data.tar.gz: 063a3914c5e5dd088ad56e37ea527c540e8dc82f0d56e7dca4564e61699541000e4d801a80898b2d89eb6719cfd4d1a887d3884a52335f0e6339ffc9a91569fb

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/README.md

@@ -1,6 +1,6 @@
-# Lopata - functional acceptance testing
+# Lopata
 
-Motivation: use RSpec for functional testing.
+Functional acceptance testing using Ruby.
 
 ## Installation
 
@@ -20,3 +20,7 @@ Run tests:
 
     cd <project-name>
     lopata
+
+## Documentation
+
+See [features description](https://github.com/avolochnev/lopata/tree/master/features) for documentation.

data/exe/lopata

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 require 'bundler/setup'
-require_relative '../lib/lopata/runner'
+require 'lopata/runner'
 
 # use default command with arguments if given command is unknown.
 argv = ARGV.dup

data/lib/lopata.rb

@@ -1,11 +1,15 @@
 require 'lopata/id'
-require 'lopata/config'
+require 'lopata/configuration'
+require 'lopata/environment'
 require 'lopata/scenario_builder'
 require 'lopata/scenario'
 require 'lopata/step'
 require 'lopata/shared_step'
 
+# Namespace for all Lopata code.
 module Lopata
+  # Define the scenario.
+  # @see Lopata::ScenarioBuilder.define
   def self.define(*args, &block)
     Lopata::ScenarioBuilder.define(*args, &block)
   end
@@ -14,11 +18,57 @@ module Lopata
   def self.xdefine(*args, &block)
   end
 
+  # Register the shared step
+  #
+  # @example
+  #     Lopata.shared_step 'test user' do
+  #       setup { @user = create(:user) }
+  #     end
+  #
+  # Shared step may be used in scenarios by name:
+  # @example
+  #     Lopata.define 'user' do
+  #       setup 'test user'
+  #
+  #       it 'exists' do
+  #         expect(@user).to_not be_nil
+  #       end
+  #     end
+  # @param name [String] shared step unique name
+  # @param block [Block] shared step action sequence definition
   def self.shared_step(name, &block)
     Lopata::SharedStep.register(name, &block)
   end
 
+  # Yields the global configuration to a block.
+  # @yield [Lopata::Configuration] global configuration
+  #
+  # @example
+  #     Lopata.configure do |config|
+  #       config.before_scenario 'setup test user'
+  #     end
+  # @see Lopata::Configuration
   def self.configure(&block)
-    yield Lopata::Config
+    yield Lopata.configuration
+  end
+
+  # Returns global configuration object.
+  # @return [Lopata::Configuration]
+  # @see Lopata.configure
+  def self.configuration
+    @configuration ||= Lopata::Configuration.new
+  end
+
+  # @private
+  # Internal container for global non-configuration data.
+  def self.world
+    @world ||= Lopata::World.new
+  end
+
+  # Return global environment object
+  # @return [Lopata::Environment]
+  # @see Lopata::Environment
+  def self.environment
+    Lopata.configuration.environment
   end
 end

data/lib/lopata/active_record.rb

@@ -1,25 +1,118 @@
 module Lopata
+  # Helpers for ActiveRecord usage in tests.
+  #
+  # Make helpers available in scenarios by
+  #
+  #     require 'lopata/active_record'
+  #
+  # @example
+  #
+  #     # Configure db connection at config/environments/qa.yml like rails:
+  #     # db:
+  #     #   adapter: postgresql
+  #     #   host: your.database.host
+  #     #   username: username
+  #     #   password: password
+  #     #   database: database
+  #     require 'active_record'
+  #     require 'lopata/active_record'
+  #
+  #     class User < ActiveRecord::Base; end
+  #
+  #     Lopata.define 'User creation' do
+  #       setup do
+  #         @user = User.create!(username: 'testuser')
+  #       end
+  #       # Remove user from database after scenario
+  #       cleanup :user
+  #
+  #       it 'works' do
+  #         expect(@user).to_not be_nil
+  #       end
+  #     end
+  #
   module ActiveRecord
-    # To be included in Lopata::Scenario
+    # To be included in Lopata::Scenario. The methods may be used in runtime.
     module Methods
+      # Destroy ActiveRecord objects.
+      #
+      # Does nothing if 'keep' mode is enabled:
+      #
+      #     Lopata.configure do |c|
+      #       c.keep = true
+      #     end
+      #
+      # @param objects [Array<ActiveRecord::Base, Array<ActiveRecord::Base>, nil>] to be destroyed
+      # @see Lopata::Configuration#keep
       def cleanup(*objects)
-        return if Lopata::Config.ops[:keep]
+        return if Lopata.configuration.keep
         objects.flatten.compact.each do |o|
           begin
             o.reload.destroy!
           rescue ::ActiveRecord::RecordNotFound
-            # Already destroyed
+            # Already destroyed - skip
+          rescue ::ActiveRecord::InvalidForeignKey
+            # Possible async job created new relationships (e.g. history records). Try again once.
+            o.reload.destroy!
           end
         end
       end
 
+      # Reload ActiveRecord objects
+      #
+      # @example
+      #
+      #     # use in steps
+      #     reload @a, @b
+      #     # instead of
+      #     @a.reload; @b.reload
+      #
+      # @param objects [Array<ActiveRecord::Base, Array<ActiveRecord::Base>, nil>] to be reloaded
       def reload(*objects)
-        objects.flatten.each(&:reload)
+        objects.flatten.compact.each(&:reload)
+      end
+
+      # Marks object to be destroyed at the end of scenario
+      #
+      # @param object [ActiveRecord::Base] the object to be destoryed at the end of scenario
+      # @return the given object, so chains can be build
+      def cleanup_later(object)
+        return nil unless object
+        @created_objects ||= []
+        @created_objects << object
+        object
+      end
+
+      # Find ActiveRecord object of given class by params.
+      # Marks the returned object to be destroyed at the end of scenario.
+      #
+      # @example
+      #     action do
+      #       # UI actions creating the user
+      #       @user = find_created(User, username: 'testuser')
+      #     end
+      #     it 'created' do
+      #       expect(@user).to_not be_nil
+      #     end
+      #     # No cleanup needed
+      #     # cleanup :user
+      #
+      # @param cls [Class] active record model class
+      # @param params [Hash] options for record finding
+      # @return [ActiveRecord::Base, nil] the object or nil if not found
+      # @see #cleanup_later called on the hood
+      def find_created(cls, params)
+        cleanup_later cls.where(params).take
       end
     end
 
-    # To be included in Lopata::ScenarioBuilder
+    # To be included in Lopata::ScenarioBuilder. The methods may be used in build time.
     module DSL
+      # Mark instance variables to call #destroy at teardown phase of scenario or context running.
+      #
+      # Does nothing if 'keep' mode is enabled.
+      #
+      # @param vars [Array<Symbol, String>] instance variable names to be destroyed on teardown phase.
       def cleanup(*vars, &block)
         unless vars.empty?
           teardown do
@@ -32,5 +125,12 @@ module Lopata
   end
 end
 
+Lopata.configure do |c|
+  c.after_scenario { cleanup @created_objects }
+end
+
+params = Lopata.environment['db']
+ActiveRecord::Base.establish_connection(params) if params
+
 Lopata::Scenario.include Lopata::ActiveRecord::Methods
 Lopata::ScenarioBuilder.include Lopata::ActiveRecord::DSL

data/lib/lopata/condition.rb

@@ -1,4 +1,5 @@
 module Lopata
+  # @private
   class Condition
     attr_reader :condition, :positive
     def initialize(condition, positive: true)
@@ -18,7 +19,7 @@ module Lopata
       when Hash
         condition.keys.all? { |k| metadata[k] == condition[k] }
       when Array
-        condition.map { |key| metadata[key] }.none?(&:nil?)
+        condition.map { |key| metadata[key] }.all?
       else
         metadata[condition]
       end

data/lib/lopata/configuration.rb

@@ -0,0 +1,126 @@
+module Lopata
+  # Stores runtime configuration information
+  #
+  # @see Lopata.configure
+  # @see Lopata.configuration
+  class Configuration
+    # Build an object to store runtime configuration options and set defaults
+    def initialize
+      @before_start_hooks = []
+      @before_scenario_steps = []
+      @after_scenario_steps = []
+      @observers = [Lopata::Observers::ConsoleOutputObserver.new]
+      @role_descriptions = {}
+      @env = :qa
+    end
+
+    # Add the hook to be called before scenarios running
+    # The block will be called after framework initialization and before scenarios parsing.
+    # It usually allow to require and initialize the libraries used for project testing.
+    #
+    # @example
+    #     Lopata.configure do |c|
+    #       c.before_start do
+    #         require 'active_record'
+    #       end
+    #     end
+    def before_start(&block)
+      @before_start_hooks << block
+    end
+
+    # @private
+    def run_before_start_hooks
+      @before_start_hooks.each(&:call)
+    end
+
+    # Defines 'before scenario' steps.
+    # Given steps will be runned before each scenario in context of scenario.
+    # It may be shared step names, and|or block.
+    #
+    # @example
+    #     Lopata.configure do |c|
+    #       c.before_scenario 'setup test user'
+    #     end
+    #
+    # @param steps [Array<String>] name of shared steps
+    # @param block [Proc] block of code
+    def before_scenario(*steps, &block)
+      before_scenario_steps.append(*steps) unless steps.empty?
+      before_scenario_steps.append(block) if block_given?
+    end
+
+    # Defines 'after scenario' steps.
+    # Given steps will be runned after each scenario in context of scenario.
+    # It may be shared step names, and|or block.
+    #
+    # @example
+    #     Lopata.configure do |c|
+    #       c.after_scenario 'cleanup test user'
+    #     end
+    #
+    # @param steps [Array<String>] name of shared steps
+    # @param block [Proc] block of code
+    def after_scenario(*steps, &block)
+      after_scenario_steps.append(*steps) unless steps.empty?
+      after_scenario_steps.append(block) if block_given?
+    end
+
+    # @private
+    attr_reader :before_scenario_steps, :after_scenario_steps
+
+    # Add an observer to the set Lopata to be used for this run.
+    #
+    # @param observer [Lopata::Observers::BaseObserver] a observer instance.
+    #
+    # @see Lopata::Observers::BaseObserver
+    def add_observer(observer)
+      @observers << observer
+    end
+
+    # @private
+    attr_reader :observers
+
+    # @private
+    def filters
+      @filters ||= []
+    end
+
+    # @private
+    attr_accessor :web_logging_params
+
+    # @private
+    def init_lopata_logging(url, project_code, build_number)
+      require 'lopata/observers/web_logger'
+      self.web_logging_params = { url: url, project_code: project_code, build_number: build_number }
+      add_observer Lopata::Observers::WebLogger.new
+    end
+
+    # @return [Hash{Symbol => String}] map or role codes to role name.
+    # @see Lopata::Role
+    attr_accessor :role_descriptions
+
+    # @return [Symbol,nil] user role to be used in scenario if not specified
+    # @see Lopata::Role
+    attr_accessor :default_role
+
+    # @return [Symbol] environment code.
+    #   Default is :qa
+    # @see Lopata::Environment
+    attr_accessor :env
+
+    # @return [Boolean] keep generated test data after scenarios running.
+    #   Default is false
+    #   Set to true for keeping generated data.
+    #   Use 'lopata --keep' modifier to set keep mode on running.
+    # @see Lopata::ActiveRecord::Methods#cleanup
+    attr_accessor :keep
+
+    # @private
+    attr_accessor :environment
+
+    # @private
+    def load_environment
+      self.environment = Lopata::Environment.new(env)
+    end
+  end
+end

data/lib/lopata/environment.rb

@@ -0,0 +1,36 @@
+module Lopata
+  # Settings of test enviromnet the scenarios to be runned.
+  #
+  # Lopata allows to define different environments the scenarios to be runned on.
+  # Set environment name via command line 'lopata -e stage' or via configuration:
+  #
+  #     Lopata.configure do |c|
+  #       c.env = :stage
+  #     end
+  #
+  # The environment params are loaded from './config/environments/<env>.yml'.
+  class Environment
+    # Loads environment configuration for given env
+    # @param env [Symbol] environment key
+    #    Loads golobl configured environment if not given.
+    # @see Lopata::Configuration#env
+    def initialize(env = Lopata.configuration.env)
+      require 'yaml'
+      @config = {}
+      config_filename = "./config/environments/#{Lopata.configuration.env}.yml"
+      @config = YAML::load(File.open(config_filename)) if File.exists?(config_filename)
+    end
+
+    # Access to environment settings
+    # @param key [Symbol] environment configuration key is set on yml configuration.
+    def [](key)
+      @config[key]
+    end
+
+    %w{url}.each do |opt|
+      define_method opt do
+        @config[opt]
+      end
+    end
+  end
+end

data/lib/lopata/factory_bot.rb

@@ -1,23 +1,63 @@
 require_relative 'active_record'
 
 module Lopata
+  # Helpers for FactoryBot usage in tests.
+  #
+  # Make helpers available in scenarios by
+  #
+  #     require 'lopata/factory_bot'
+  #
+  # Automatically adds ActiveRecord helpers.
+  # @see Lopata::ActiveRecord
+  #
+  # Allows to create ActiveRecord object by FactoryBot definitions.
+  # All the objects created by FactoryBot helpers will be destroyed automatically
+  # at the end of scenario.
+  # @see Lopata::ActiveRecord::Methods#cleanup
+  #
+  # @example
+  #
+  #     # Configure db connection at config/environments/qa.yml like rails:
+  #     # db:
+  #     #   adapter: postgresql
+  #     #   host: your.database.host
+  #     #   username: username
+  #     #   password: password
+  #     #   database: database
+  #     require 'active_record'
+  #     require 'factory_bot'
+  #     require 'lopata/facotory_bot'
+  #
+  #     class User < ActiveRecord::Base; end
+  #
+  #     FactoryBot.define do
+  #       factory :user do
+  #         username { 'testuser' }
+  #       end
+  #     end
+  #
+  #     Lopata.define 'User creation' do
+  #       setup do
+  #         @user = create(:user)
+  #       end
+  #       # No cleanup needed - @user will be destroyed automatically
+  #       # cleanup :user
+  #
+  #       it 'works' do
+  #         expect(@user).to_not be_nil
+  #       end
+  #     end
+  #
   module FactoryBot
     # To be included in Lopata::Scenario
     module Methods
+      # Wrapper for FactoryBot#create
+      # Calls the FactoryBot#create with given paramters and returns it result.
+      # Additionally store the created object for destroying at the end of scenario.
+      # @see Lopata::ActiveRecord::Methods#cleanup
       def create(*params)
         cleanup_later ::FactoryBot.create(*params)
       end
-
-      def find_created(cls, params)
-        cleanup_later cls.where(params).take
-      end
-
-      def cleanup_later(object)
-        return nil unless object
-        @created_objects ||= []
-        @created_objects << object
-        object
-      end
     end
 
     # To be included in Lopata::ScenarioBuilder
@@ -29,8 +69,4 @@ end
 Lopata::Scenario.include Lopata::FactoryBot::Methods
 Lopata::ScenarioBuilder.include Lopata::FactoryBot::DSL
 
-Lopata.configure do |c|
-  c.after_scenario { cleanup @created_objects }
-end
-
-::FactoryBot.find_definitions unless Lopata::Config.readonly
+::FactoryBot.find_definitions