lopata 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70e042bc80bb14342ec6b0f516df0934007677e8dd98ba04f2d65034ca6acbce
-  data.tar.gz: 5afff5a8553b777f02b0ee838f304d0d660afdc60042113423b52f08e91342db
+  metadata.gz: 51ff4a162c7617388f8856b342449e1475f2438d8a44a6c58c6168373b144969
+  data.tar.gz: 10580190d2a63826f971d1730523eacc34ed818b634329da1635db07d2627d27
 SHA512:
-  metadata.gz: 0f87e65d52c3bf6a15c85bfd5f900a48a576f256be20264a6df2360f8633694e88267f7cbd348325822b927538c5ad4407a55bd0ce3837c6ef630d685eec9074
-  data.tar.gz: 2d4c9fe43e2283e210e6c30e882941f99975e9e2b62a00d9a23b7f59208e02726c66b9c72bb2d612e117bd79c82f9fb3aa88e711ed4d3022226d9137f27b76e0
+  metadata.gz: 76f4fffc7d6755eb63d45a3297177c25b2e947c101dfad38b7a39e8bb474f00e3874d3b3fcf939a81d3ad550cc7d18335ac998104f0b0436db239d1f4688a0f5
+  data.tar.gz: '086e6cb580e94035e78607daa4a5ba6a5caf2211e37bc0e5cd9aa7cb1e2579fc22889e6fb90e17e6b4f290016a70d76f86d1d93d307d19e964b7584a3bee0451'

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,14 @@
 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'
 
 module Lopata
+  # Define the scenario.
+  # @see Lopata::ScenarioBuilder.define
   def self.define(*args, &block)
     Lopata::ScenarioBuilder.define(*args, &block)
   end
@@ -14,11 +17,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 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,85 @@
 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
     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 +92,8 @@ module Lopata
   end
 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

@@ -33,4 +33,4 @@ Lopata.configure do |c|
   c.after_scenario { cleanup @created_objects }
 end
 
-::FactoryBot.find_definitions unless Lopata::Config.readonly
+::FactoryBot.find_definitions

data/lib/lopata/generators/app.rb

@@ -11,10 +11,8 @@ module Lopata
       def create_root_files
         template 'Lopatafile', "#{name}/Lopatafile"
         template 'Gemfile', "#{name}/Gemfile"
-        template '.rspec', "#{name}/.rspec"
         template 'config/environments/qa.yml', "#{name}/config/environments/qa.yml"
         template 'config/initializers/capybara.rb', "#{name}/config/initializers/capybara.rb"
-        template 'spec/spec_helper.rb', "#{name}/spec/spec_helper.rb"
       end
 
       def init_dirs

data/lib/lopata/generators/templates/Gemfile

@@ -1,7 +1,5 @@
 source 'https://rubygems.org'
 gem 'selenium-webdriver'
-gem 'rspec', :require => 'spec'
-gem 'rake'
 gem 'activerecord', '~> 6.0.2'
 gem 'capybara', '~> 3.11.1'
 gem 'thor'

data/lib/lopata/generators/templates/config/environments/qa.yml

@@ -1,5 +1,4 @@
 url: http://yourapp.com
-name: QA
 # db:
 #   adapter: postgresql
 #   host: localhost

data/lib/lopata/observers/backtrace_formatter.rb

@@ -1,7 +1,11 @@
 module Lopata
   module Observers
+    # @private
     # Based on RSpec::Core::BacktraceFormatter
+    #
+    # Provides ability to format backtrace and find source code by file and line number.
     class BacktraceFormatter
+      # @private
       attr_accessor :exclusion_patterns, :inclusion_patterns
 
       def initialize
@@ -14,6 +18,10 @@ module Lopata
         inclusion_patterns << Regexp.new(Dir.getwd)
       end
 
+      # Filter backtrace.
+      #
+      # @param backtrace [Array<String>] exception backtrace
+      # @return [Array<String>] backtrace lines except ruby libraries, gems and executable files.
       def format(backtrace)
         return [] unless backtrace
         return backtrace if backtrace.empty?
@@ -28,6 +36,12 @@ module Lopata
           end
       end
 
+
+      # Extracts error message from excetion
+      #
+      # @param exeption [Exception]
+      # @param include_backtrace [Boolean] whether to add formatted backtrace to output
+      # @return [String] error message from excetion, incuding source code line.
       def error_message(exception, include_backtrace: false)
         backtrace = format(exception.backtrace)
         source_line = extract_source_line(backtrace.first)