rspec_starter 1.5.0 → 1.6.0

data/lib/rspec_starter/helpers.rb

@@ -0,0 +1,74 @@
+# Helper methods that can be used anywhere in RspecStarter.
+module RspecStarter
+  def self.helpers
+    @helpers ||= Helpers.new
+  end
+
+  # A class that provides helper methods that can be used anywhere in RspecStarter.
+  class Helpers
+    def class_for_task_name(string_or_symbol)
+      string_or_symbol.to_s.camelize.constantize
+    end
+
+    def project_is_rails_app?
+      @project_is_rails_app ||= File.file?(File.join(Dir.pwd, 'config', 'application.rb'))
+    end
+
+    def project_is_rails_engine?
+      return false unless project_has_lib_dir?
+
+      Dir["#{Dir.pwd}/lib/**/*.rb"].each do |file|
+        return true if File.readlines(file).detect { |line| line.match(/\s*class\s+.*<\s+::Rails::Engine/) }
+      end
+      false
+    end
+
+    def project_has_lib_dir?
+      @project_has_lib_dir ||= Dir.exist?("#{Dir.pwd}/lib")
+    end
+
+    # Taken from https://stackoverflow.com/questions/11784109/detecting-operating-systems-in-ruby/13586108
+    def operating_system_name
+      @operating_system_name ||= begin
+        host_os = RbConfig::CONFIG['host_os']
+        case host_os
+        when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
+          :windows
+        when /darwin|mac os/
+          :macosx
+        when /linux/
+          :linux
+        when /solaris|bsd/
+          :unix
+        else
+          :unknown
+        end
+      end
+    end
+
+    def is_linux?
+      operating_system_name == :linux
+    end
+
+    def is_mac?
+      operating_system_name == :maxosx
+    end
+
+    def xvfb_installed?
+      @xvfb_installed ||= RspecStarter.which("xvfb-run")
+    end
+
+    def xvfb_not_installed?
+      !xvfb_installed?
+    end
+
+    # This is ugly, but it gives us some added flexibility.  Users can invoke the rspec_starter method from any script or
+    # executable.  This method attempts to find out the file name of the script/exectuable.
+    #
+    # This method may not return a pretty result in all cases, but it's decent if the user has defined a script in their project
+    # (possibly in the bin folder, or root of the project).
+    def starter_script_file_name
+      caller.last.split(":")[0]
+    end
+  end
+end

data/lib/rspec_starter/legacy.rb

@@ -0,0 +1,16 @@
+# This module loads the legacy RspecStarter code that uses the non-block DSL. It will be removed in 2.0.0.
+# The file is loaded when RspecStarter starts, but most of the legacy code is not loaded until the
+# 'invoke_legacy_starter' method is called.
+module RspecStarter
+  def self.invoke_legacy_starter(defaults)
+    require 'rspec_starter/legacy/legacy_runner'
+    # puts "[DEPRECATION NOTICE] Your #{helpers.starter_script_file_name} file uses an old method for starting RSpec.\n" \
+    #   "RspecStarter 1.6.0 introduced a new interface that is faster and more flexible.\n" \
+    #   "To upgrade:\n" \
+    #   "  1. Run 'rspec_starter --init' to install a new bin/start_rspec file.\n" \
+    #   "  2. Your old bin/start_rspec will be renamed to bin/start_rspec.bak. If you customized\n" \
+    #   "     this file, open it up and consider moving the changes to the new bin/start_rspec file.\n" \
+    #   "     See https://github.com/roberts1000/rspec_starter for instructions on the new interface.\n".colorize(:yellow)
+    LegacyRunner.new(defaults).run
+  end
+end

data/lib/rspec_starter/legacy/help.rb

@@ -0,0 +1,40 @@
+module RspecStarter
+  # Method that support the help option on the bin/start_rspec script.
+  module Help
+    def should_show_help?
+      ARGV.any? { |option| option.include? "--help" }
+    end
+
+    def show_help
+      # Figure out the file name that invoked the rspec_starter helper.  This is the name of the script; it be called anything.
+      script_name = calling_file_name
+      puts "Usage: #{script_name.colorize(:light_blue)} #{'[options] [options for RSpec]'.colorize(:light_blue)}\n"
+      puts "       #{script_name} will look for its own options first then pass any remaining options to rspec"
+
+      # rubocop:disable Metrics/LineLength
+      puts "\nOptions: (run 'rspec --help' to see RSpec's options)"
+      puts "       #{'--no-xvfb'.colorize(:light_blue)}   DO NOT run XVFB (this can speed up RSpec when running tests that don't need XVFB)"
+      puts "       #{'--no-prep'.colorize(:light_blue)}   DO NOT prepare the test database (can speed up testing if you know the DB is clean)"
+
+      puts "\nExamples:"
+      puts "       #{script_name.colorize(:light_blue)} #{'spec/features'.colorize(:light_blue)} (only run specs in the specs/features folder)"
+      puts "       #{script_name.colorize(:light_blue)} #{'spec/features/some_spec:53'.colorize(:light_blue)} (run the spec on line 53 of the spec/features_some_spec.rb file)"
+      puts "       #{script_name.colorize(:light_blue)} #{'--no-xvfb'.colorize(:light_blue)} #{'spec/requests/some_spec'.colorize(:light_blue)} (don't start XVFB since it's not needed for request specs)"
+      puts "       #{'SIMPLECOV_FORMATTER=rcov'.colorize(:light_blue)} #{script_name.colorize(:light_blue)} (use with environment variables)\n"
+      # rubocop:enable Metrics/LineLength
+    end
+
+    # This is ugly, but it gives us some added flexibility.  Users can invoke the rspec_starter method from any script or
+    # executable.  This method attempts to find out the name of the script/exectuable.
+    # "caller" returns the method stack, and because of the location of this file in the gem, we happen to be the 4th item in the
+    # the array (hence "caller[3]" below).
+    #
+    # This method may not return a pretty result in all cases, but it's decent if the user has defined a script in their project
+    # (possibly in the bin folder, or root of the project).
+    def calling_file_name
+      # rubocop:disable Performance/Caller
+      caller[3].split(":")[0]
+      # rubocop:enable Performance/Caller
+    end
+  end
+end

data/lib/rspec_starter/legacy/legacy_runner.rb

@@ -0,0 +1,90 @@
+require 'pathname'
+require 'open3'
+
+require_relative 'help'
+require_relative 'steps/step'
+require_relative 'steps/verify_xvfb_step'
+require_relative 'steps/prepare_database_step'
+require_relative 'steps/remove_tmp_folder_step'
+require_relative 'steps/invoke_rspec_step'
+
+module RspecStarter
+  # This is a simple class that encapulates the process of running RSpec.  When a Runner is created, it creates a set of
+  # steps that will be executed, in order, when the 'run' method is invoked.  Each step encapsulates an action that can be
+  # taken to help invoke Rspec.  Steps are typically independent do not depend on information from other steps.  However
+  # this is not a hard rule.  If more complex steps are needed, feel free to create them.  Each steps knows about the main
+  # runner object, so the runner object is a good place to store shared info.
+  class LegacyRunner
+    include Help
+    attr_reader :xvfb_installed, :step_num, :steps
+
+    def initialize(defaults)
+      @steps = []
+      @step_num = 1
+      @xvfb_installed = RspecStarter.which("xvfb-run")
+      @prep_db_step = PrepareDatabaseStep.new(defaults, self)
+      @run_rspec_step = InvokeRspecStep.new(defaults, self)
+      @steps << VerifyXvfbStep.new(defaults, self)
+      @steps << @prep_db_step
+      @steps << RemoveTmpFolderStep.new(defaults, self)
+      @steps << @run_rspec_step
+    end
+
+    def run
+      return show_help if should_show_help? # If we show help, exit and don't do anything else.
+
+      @steps.each do |step|
+        next unless step.should_execute?
+
+        step.execute
+        @step_num += 1
+        break if step.failed?
+      end
+
+      finalize_exit
+    end
+
+    def project_is_rails_app?
+      File.file?(File.join(Dir.pwd, 'config', 'application.rb'))
+    end
+
+    def project_is_rails_engine?
+      return false unless project_has_lib_dir?
+
+      Dir["#{Dir.pwd}/lib/**/*.rb"].each do |file|
+        return true if File.readlines(file).detect { |line| line.match(/\s*class\s+.*<\s+::Rails::Engine/) }
+      end
+      false
+    end
+
+    def project_has_lib_dir?
+      Dir.exist?("#{Dir.pwd}/lib")
+    end
+
+    def operating_system_name
+      result = `uname`
+      return 'Linux' if result.include?('Linux')
+      return 'MacOS' if result.include?('Darwin')
+
+      'Unknown'
+    end
+
+    def is_linux?
+      operating_system_name == 'Linux'
+    end
+
+    def is_mac?
+      operating_system_name == 'MacOS'
+    end
+
+    def xvfb_installed?
+      @xvfb_installed
+    end
+
+    def finalize_exit
+      exit(1) if @run_rspec_step.rspec_exit_status.nonzero?
+      exit(1) if @prep_db_step.exit_status.nonzero?
+      exit(0)
+    end
+  end
+end

data/lib/rspec_starter/{steps → legacy/steps}/invoke_rspec_step.rb

@@ -5,6 +5,7 @@ module RspecStarter
 
     def initialize(defaults, runner)
       super(runner)
+
       @allow_xvfb = defaults.fetch(:allow_xvfb, true)
       @relevant_options = ["--no-xvfb"]
       @success_or_skipped = nil # Will be updated once step executes
@@ -42,6 +43,7 @@ module RspecStarter
       return base if @runner.is_mac?
       return base unless @allow_xvfb
       return base if @user_wants_to_skip_xvfb
+
       @runner.xvfb_installed? ? "xvfb-run #{base}" : base
     end
   end

data/lib/rspec_starter/{steps → legacy/steps}/prepare_database_step.rb

@@ -5,6 +5,7 @@ module RspecStarter
 
     def initialize(defaults, runner)
       super(runner)
+
       @prepare_database = defaults.fetch(:prepare_db, true)
       @relevant_options << '--no-prep-db'
       @user_wants_to_skip = ARGV.any? { |option| option.include?("--no-prep-db") }
@@ -19,6 +20,7 @@ module RspecStarter
     def should_execute?
       return false if @user_wants_to_skip
       return false unless @prepare_database
+
       @runner.project_is_rails_app? || @runner.project_is_rails_engine?
     end
 
@@ -41,7 +43,6 @@ module RspecStarter
       end
     end
 
-
     private
 
     def rebuild_command
@@ -52,6 +53,7 @@ module RspecStarter
     # return a zero exit status.  We need to see if 'rake aborted!' has been written to the output.
     def successful?(stderr)
       return false if @exit_status.nonzero?
+
       !stderr.include?("rake aborted!")
     end
   end

data/lib/rspec_starter/{steps → legacy/steps}/remove_tmp_folder_step.rb

@@ -3,6 +3,7 @@ module RspecStarter
   class RemoveTmpFolderStep < RspecStarter::Step
     def initialize(defaults, runner)
       super(runner)
+
       @remove_tmp_folder = defaults.fetch(:remove_tmp, true)
       @runner = runner
       @relevant_options << "--no-remove-tmp"
@@ -16,11 +17,13 @@ module RspecStarter
 
     def should_execute?
       return false if @user_wants_to_skip_removal
+
       @remove_tmp_folder
     end
 
     def execute
       return @success_or_skipped = true unless should_execute?
+
       existed_before = tmp_folder_exists?
 
       print "[#{@runner.step_num}] Removing #{'tmp'.colorize(:light_blue)} folder ... "

data/lib/rspec_starter/{steps → legacy/steps}/verify_xvfb_step.rb

@@ -5,6 +5,7 @@ module RspecStarter
   class VerifyXvfbStep < RspecStarter::Step
     def initialize(defaults, runner)
       super(runner)
+
       @relevant_options << '--no-xvfb'
       @use_xvfb = defaults.fetch(:use_xvfb, true)
       @user_wants_to_skip_xvfb = ARGV.any? { |option| option.include?("--no-xvfb") }
@@ -21,6 +22,7 @@ module RspecStarter
 
     def should_execute?
       return false if @user_wants_to_skip_xvfb
+
       @use_xvfb
     end
 

data/lib/rspec_starter/option.rb

@@ -0,0 +1,84 @@
+module RspecStarter
+  # Option objects hold the information that Step subclasses want to register as options.
+  class Option
+    attr_reader :name, :default, :description, :key, :owner, :switch, :switch_description
+
+    def initialize(name:, default:, description: "", owner:, switch:, switch_description: "")
+      @owner = owner
+      @switch = switch
+      @switch_description = switch_description
+      @simplified_switch = switch.nil? ? nil : self.class.simplified_switch_name(switch)
+      @description = description
+      @default = default
+      self.name = name
+      @key = name || @simplified_switch
+      validate
+    end
+
+    def name=(value)
+      @name = value.nil? ? nil : value.to_s
+    end
+
+    # Remove leading hyphens
+    # Convert remaining hyphens to underscores
+    # Undercase
+    def self.simplified_switch_name(switch)
+      switch.sub(/^-*/, "").sub("-", "_").underscore
+    end
+
+    # Does this option apply to the DSL inside the RspecStarter.start block. If so, users can use it like this:
+    #   RspecStarter.start do
+    #     task :foo, option_name_here: "some_value"
+    #   end
+    def is_dsl_option?
+      !name.nil?
+    end
+
+    private
+
+    def validate
+      validate_name_has_no_hyphens
+      validate_switch_starts_with_hyphens
+      validate_name_or_switch_present
+      validate_default_is_true_false_for_switch
+      validate_switch_is_like_name
+    end
+
+    def validate_name_has_no_hyphens
+      return unless name
+      return unless name.include?("-")
+
+      raise "#{owner.name}#register_options is trying to register #{name}. Option names should not include hyphens"
+    end
+
+    def validate_switch_starts_with_hyphens
+      return unless switch
+      return unless switch[0] != "-" || switch[2] == "-"
+
+      raise "#{owner.name}#register_options is trying to register switch #{switch}. The switch name must start with '--' or '-'"
+    end
+
+    def validate_name_or_switch_present
+      return unless switch.nil? && name.nil?
+
+      raise "#{owner.name}#register_options is trying to create an option but 'name:' or 'switch:' are not specified. " \
+        "At least one must be specified."
+    end
+
+    def validate_default_is_true_false_for_switch
+      return unless switch && ![true, false].include?(default)
+
+      raise "#{owner.name}#register_options is trying to create an option for switch #{switch}. Options with switches " \
+        "can only return true/false. Set the 'default' argument to true or false for the option."
+    end
+
+    def validate_switch_is_like_name
+      return unless  !switch.nil? && !name.nil?
+      return if name == @simplified_switch
+
+      raise "#{owner.name}#register_options is trying to create an option with name #{name} and switch #{switch}. " \
+        "The switch must be the same as the name when hyphens are converted to underscores and leading hyphens " \
+        "are removed."
+    end
+  end
+end

data/lib/rspec_starter/options.rb

@@ -0,0 +1,96 @@
+module RspecStarter
+  # Manages the option registration process for the Step subclasses.
+  # Holds raw option information so it can organized when steps run.
+  class Options
+    attr_reader :present_switches, :registered_task_options, :rspec_args_string
+
+    def initialize(environment, args)
+      @environment = environment
+      # These are the ARGV args that are passed to the command line.
+      @command_line_args = args
+      # Task classes that are used in the RspecStarter.start block: VerifyDisplayServer, StartRspec, etc...
+      @task_classes = environment.unique_task_classes
+      # The options that each Task wants to use.
+      @registered_task_options = {}
+
+      # Tasks register the command line switches they care about and RspecStarter has some global switches that it uses. This
+      # holds the list of switches that the user provided that match a task switch or a global switch. If the user doesn't
+      # supply a switch, or supplies a switch that nobody cares about, this will be an empty list.
+      @present_switches = nil
+
+      load_registered_task_options
+      initialize_present_switches
+
+      # The args that should be passed to rspec when it starts.
+      @rspec_args_string = nil
+      initialize_rspec_args_string
+    end
+
+    # If 'switch' is given, the option can only return 'true' or 'false'. 'default' must be set to 'true' or 'false'. When
+    # the switch isn't specified the user, the default (which must be true/false) is return. When the user specifies the default
+    # !default is returned.
+
+    # If switch is not given, default an be set to anything.
+
+    # If name isn't specified, this option is only a commandline switch.
+    # If name is specified, this option can be used inside the start block on a task.
+    def register_task_option(klass, name: nil, default: nil, description: "", switch: nil, switch_description: "")
+      new_option = RspecStarter::Option.new(name: name, default: default, description: description, owner: klass, switch: switch,
+                                            switch_description: switch_description)
+      @registered_task_options[klass] << new_option
+    end
+
+    def all_task_options
+      hash = {}
+      @registered_task_options.each do |_task_class, options|
+        options.each do |option|
+          hash[option.switch] = option unless hash.has_key?(option.switch)
+        end
+      end
+
+      list = []
+      hash.each { |_switch, option| list << option }
+      list
+    end
+
+    def all_switches
+      (global_switches + all_task_switches).sort
+    end
+
+    def global_switches
+      ['--help', '-h']
+    end
+
+    def all_task_switches
+      list = Set.new
+      @registered_task_options.each do |_task_class, options|
+        options.each { |option| list << option.switch unless option.switch.nil? }
+      end
+      list.to_a
+    end
+
+    def registered_task_option(task_class)
+      @registered_task_options[task_class]
+    end
+
+    private
+
+    def initialize_rspec_args_string
+      list = @command_line_args.dup
+      all_switches.each { |switch| list.delete(switch) }
+      @rspec_args_string = list.join(" ")
+    end
+
+    def load_registered_task_options
+      # Give each step class the ability to register options that we should know about.
+      @task_classes.each do |klass|
+        @registered_task_options[klass] = []
+        klass.provide_options_to(self)
+      end
+    end
+
+    def initialize_present_switches
+      @present_switches = all_switches.select { |switch| @command_line_args.include?(switch) }.to_a
+    end
+  end
+end