rspec_starter 1.5.0 → 1.6.0

data/exe/rspec_starter

@@ -13,6 +13,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 require "cri"
 require 'fileutils'
+require 'rspec_starter/helpers'
 
 module Cri
   # A small monkey patch to force the cri gem to stop coloring output.
@@ -23,6 +24,7 @@ module Cri
   end
 end
 
+# rubocop:disable Metrics/BlockLength
 command = Cri::Command.define do
   usage       'rspec_starter [options]'
   # aliases     :ds, :stuff
@@ -35,12 +37,22 @@ command = Cri::Command.define do
   end
 
   flag :i, :init, "(re)initialize your project bin/start_rspec file" do |_value, _cmd|
+    helpers = RspecStarter::Helpers.new
+
     if File.file?("bin/start_rspec")
       FileUtils.mv("bin/start_rspec", "bin/start_rspec.bak")
       puts "bin/start_rspec renamed to bin/start_rspec.bak"
     end
 
-    template_path = File.expand_path('../lib/templates/start_rspec', __dir__)
+    template_path =
+      if helpers.project_is_rails_app?
+        File.expand_path('../lib/templates/rails_start_rspec', __dir__)
+      elsif helpers.project_is_rails_app?
+        File.expand_path('../lib/templates/rails_engine_start_rspec', __dir__)
+      else
+        File.expand_path('../lib/templates/start_rspec', __dir__)
+      end
+
     FileUtils.cp(template_path, "bin/start_rspec")
     File.chmod(0o775, "bin/start_rspec")
     puts "bin/start_rspec created"
@@ -56,6 +68,7 @@ command = Cri::Command.define do
   run do |options, args, cmd|
   end
 end
+# rubocop:enable Metrics/BlockLength
 
 begin
   command.run(ARGV)

data/lib/rspec_starter.rb

@@ -1,7 +1,37 @@
+require 'active_support/core_ext/string/inflections'
 require 'English'
 require 'colorize'
+require 'open3'
+require 'rbconfig'
+
+require 'rspec_starter/core_ext/string'
+
+require 'rspec_starter/help'
+require 'rspec_starter/helpers'
+require 'rspec_starter/helpers/which'
+require 'rspec_starter/option'
+require 'rspec_starter/options'
+require 'rspec_starter/step_options'
+require 'rspec_starter/environment'
+
 require "rspec_starter/version"
-require_relative 'rspec_starter/runner'
+require "rspec_starter/errors/step_error"
+require "rspec_starter/errors/step_stopper"
+
+require 'rspec_starter/runner'
+require 'rspec_starter/step_context'
+require 'rspec_starter/step'
+require 'rspec_starter/task_context'
+require 'rspec_starter/rspec_starter_task'
+require 'rspec_starter/command_context'
+require 'rspec_starter/command'
+
+require 'rspec_starter/tasks/rebuild_rails_app_database'
+require 'rspec_starter/tasks/remove_tmp_folder'
+require 'rspec_starter/tasks/start_rspec'
+require 'rspec_starter/tasks/verify_display_server'
+
+require 'rspec_starter/legacy'
 
 # Setup pry for development when running "rake console". Guard against load
 # errors in production (since pry is only loaded as a DEVELOPMENT dependency
@@ -13,29 +43,44 @@ rescue LoadError
 end
 # rubocop:enable Lint/HandleExceptions
 
-# Entry point for the RspecStarter gem.
+# The main entry point for the RspecStarter gem. The 'bin/start_rspec' file contains a block of code like this:
+#
+#   RspecStarter.start do
+#     command "echo 'something'"
+#     task :some_task_name
+#     ... more tasks and commands ...
+#   end
+#
+# The start method that is executed is show below. The call to 'instance_eval(&block)' below is the special sauce that
+# makes 'self' equal the RspecStarter module inside the block.
 module RspecStarter
-  # The 'start' method takes arguments that can be used to control the steps that are executed when running Rspec.  These
-  # arguments are specified by the developer when configuring how the app prefers to run RSpec.  In addition to the arguments,
-  # the end user can pass command line options to the script/executable that is executing 'start'.  The command line options
-  # allow the end user to customize execution on a per-run basis.  In general, the arguments have the ability to turn features
-  # on and off while the command line options allow users to turn features off.  For example, a developer could probably
-  # configure his aplication to always prepare the database before running RSpec.  When the command is run, the developer might
-  # want to bypass preparing the database for a specific run because he already knows the database is clean (this will save some
-  # startup time).  On the other hand, if the developer has configured 'start' to never prepare the database, he cannot
-  # enable it via the command line on a specific run.
-  #
-  # Arguments List
-  #   defaults(Hash)
-  #     :prepare_db  => (true/false)     Should the database be rebuilt?
-  #     :remove_tmp  => (true/false)     Should the tmp folder inside the application be removed before starting RSpec?
-  #     :allow_xvfb  => (true/false)     Should XVFB be allowed on systems that need it (like Linux)
-  #
-  # Command Line Options
-  #   --no-xvfb         Do not attempt to start XVFB on Linux.  On Macs, this doesn't do anything since XVFB doesn't exist.
-  #   --no-prep-db      Do not try to rebuild the database.  This is useful when the db is already clean and want to save time.
-  #   --no-remove-tmp   Do not attempt to remove the tmp folder.
-  def self.start(defaults={})
-    Runner.new(defaults).run
+  def self.start(defaults={}, &block)
+    # If a block is missing, then the user is using the old method based starter.
+    return invoke_legacy_starter(defaults) unless block_given?
+
+    # Loads the information from the bin/start_rspec file and loads/parses the options. Provides info to the @runner.
+    @environment = Environment.new(ARGV, &block)
+
+    # Holds the step objects and executes them.
+    @runner = Runner.new(@environment)
+
+    # The bin/start_rspec file in the host application sets the APP_ROOT to the root folder of the host application.
+    Dir.chdir APP_ROOT do
+      # If we show help, exit and don't do anything else. We need to run the help in the context of the app root
+      # so the help output can show file paths relative to where the user is running (and not relative to this gem).
+      return show_help if should_show_help?
+
+      begin
+        @runner.run
+      rescue StepError
+        # The runner executes steps (which are tasks and commands). If a step reports a problem and the 'stop_on_problem' option
+        # is set to 'true' (for a given step), the step will raise a StepError error. That is the signal that execution should
+        # terminate immediately.
+        exit(@runner.largest_exit_status)
+      end
+
+      # If we get here RSpec has been started and the rspec_starter's job is done.
+      exit(0)
+    end
   end
 end

data/lib/rspec_starter/command.rb

@@ -0,0 +1,59 @@
+module RspecStarter
+  # Commands are steps that execute shell scripts or shell commands. They can be created using the command method
+  # inside the RspecStarter.start block. Commands execute quietly unless you specifically set 'quiet: false'.
+  #
+  #   RspecStarter.start do
+  #     command "echo 'Done'"
+  #     command "echo 'This command shows the echo'", quiet: false
+  #   end
+  #
+  class Command < RspecStarterStep
+    attr_accessor :status, :stderr, :stdout
+
+    def initialize(id, runner, command_string, options)
+      super(id, runner, options)
+      @command_string = command_string
+    end
+
+    def self.default_quiet
+      true
+    end
+
+    def print_starting_message
+      print "Executing #{colored_command_string} ..." + (quiet? ? "" : "\n")
+    end
+
+    def execute
+      if quiet?
+        @stdout, @stderr, @status = Open3.capture3(@command_string)
+      else
+        @verbose_command_passed = system(@command_string)
+        @status = $CHILD_STATUS
+        print "Executed #{colored_command_string} -"
+      end
+
+      problem(exit_status: @status.exitstatus) if command_failed?
+    end
+
+    private
+
+    def initialize_name
+      @name = :command
+    end
+
+    def write_error_info
+      puts @stdout
+      puts @stderr
+      puts "There was an error running '#{@command_string}'. It returned with exit status #{@status.exitstatus}.\n" \
+        "See the output above for details or manually run the command for more information.".colorize(:red)
+    end
+
+    def colored_command_string
+      @command_string.colorize(:light_blue)
+    end
+
+    def command_failed?
+      @status.exitstatus > 0 || @verbose_command_passed == false
+    end
+  end
+end

data/lib/rspec_starter/command_context.rb

@@ -0,0 +1,38 @@
+module RspecStarter
+  # CommandContext's are created to when parsing the RspecStater.start block. They hold the args for Commands. They are
+  # asked to create instances of Command from this information when it is time to execute. The also resolve the options
+  # that each Command is allowed to access.
+  class CommandContext < StepContext
+    attr_reader :command_string
+
+    def initialize(environment:, id:, command_string:, requested_args:)
+      super(environment: environment, id: id, requested_args: requested_args)
+
+      @command_string = command_string
+    end
+
+    def instantiate(runner)
+      Command.new(@id, runner, @command_string, build_options)
+    end
+
+    def step_class
+      Command
+    end
+
+    def is_task?
+      false
+    end
+
+    def is_command?
+      true
+    end
+
+    private
+
+    def build_options
+      options = super
+      apply_args_to_options(options)
+      options
+    end
+  end
+end

data/lib/rspec_starter/core_ext/string.rb

@@ -1,7 +1,10 @@
 # Add some ome simple colorization methods for formatting console output.
-# Prefix methods with rs_ so they don't collide with other gems.
 class String
-  def rs_colorize(color_code)
-    "\e[#{color_code}m#{self}\e[0m"
+  def highlight
+    colorize(:light_blue)
+  end
+
+  def warning
+    colorize(:yellow)
   end
 end

data/lib/rspec_starter/environment.rb

@@ -0,0 +1,57 @@
+module RspecStarter
+  # Load the environment for RspecStarter.
+  class Environment
+    attr_reader :options
+
+    # &start_block is the start block from the host application's bin/start_rspec file. It looks like this:
+    #
+    #  RspecStarter.start do
+    #    command "something"
+    #    task :task_one
+    #    command "something"
+    #    task :task two
+    #    ... more commands and tasks...
+    #  end
+    def initialize(args, &start_block)
+      @next_id = 0
+      @step_info = {}
+
+      load_step_info(&start_block)
+
+      @options = Options.new(self, args, &start_block)
+      # This will lazily load once execution starts.
+    end
+
+    def step_contexts
+      @step_info.values
+    end
+
+    def unique_task_classes
+      @step_info.values.select(&:is_task?).collect(&:step_class).uniq
+    end
+
+    def command(string, **args)
+      step_id = next_id
+      @step_info[step_id] = CommandContext.new(environment: self, id: step_id, command_string: string, requested_args: args)
+    end
+
+    def task(task_name, **args)
+      step_id = next_id
+      klass = RspecStarter.helpers.class_for_task_name(task_name)
+      @step_info[step_id] = TaskContext.new(environment: self, id: step_id, step_class: klass, requested_args: args)
+    end
+
+    private
+
+    def next_id
+      @next_id += 1
+    end
+
+    def load_step_info(&start_block)
+      # This evaluates the start block and sets 'self' to an instance of Environment. The 'command' and 'task' methods
+      # in this class capture the 'command' and 'task' calls in the block. From there, we can determine the Steps classes that the
+      # user is trying to load.
+      instance_eval(&start_block)
+    end
+  end
+end

data/lib/rspec_starter/errors/step_error.rb

@@ -0,0 +1,9 @@
+module RspecStarter
+  # This error is raised when execution should completely stop. The current step should be finalized before this
+  # error is raised. Once this error is raised, RspecStarter will halt and report a non-zero exit status to the user.
+  class StepError < StandardError
+    def initialize(msg="")
+      super
+    end
+  end
+end

data/lib/rspec_starter/errors/step_stopper.rb

@@ -0,0 +1,9 @@
+module RspecStarter
+  # This error is raised when a step wants to gracefully stop execution. It does not prevent later steps from running.
+  # It only ends on the current step execution.
+  class StepStopper < StandardError
+    def initialize(msg="")
+      super
+    end
+  end
+end

data/lib/rspec_starter/help.rb

@@ -1,40 +1,87 @@
+# Code that shows output when 'bin/start_rspec --help' or 'bin/start_rspec -h' is executed.
 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" }
+  def self.should_show_help?
+    ARGV.any? { |option| option.include?("--help") || option.include?("-h") }
+  end
+
+  def self.show_help
+    # Figure out the file name that invoked the rspec_starter helper and treat it as the name of the
+    # script.  We install a bin/rspec_starter file, but the user could call it anything.
+    script_name = helpers.starter_script_file_name
+    colored_script_name = script_name.colorize(:light_blue)
+
+    write_help_usage_section(script_name, colored_script_name)
+    write_help_command_line_options_section(colored_script_name)
+    write_help_examples_section(colored_script_name)
+    write_available_tasks
+    write_task_info(colored_script_name)
+
+    puts ""
+
+    exit(0)
+  end
+
+  def self.write_help_usage_section(script_name, colored_script_name)
+    puts "Usage: #{colored_script_name} #{'[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."
+  end
+
+  def self.write_help_command_line_options_section(colored_script_name)
+    puts "\nCommand Line Options: (run #{'rspec --help'.colorize(:light_blue)} to see RSpec's options)"
+    puts "       This list is computed dynamically based on the tasks that are enabled in the #{colored_script_name} file."
+
+    max_length = @environment.options.all_task_switches.max_by(&:length).size
+
+    @environment.options.all_task_options.each do |option|
+      next unless option.switch
+
+      length = option.switch.length
+      padding = max_length - length + 5 # 5 is the number of spaces past the longest swtich to start the description column
+      puts "       #{option.switch.colorize(:light_blue)}#{' ' * padding}#{option.switch_description}"
     end
+  end
+
+  def self.write_help_examples_section(colored_script_name)
+    # rubocop:disable Metrics/LineLength
+    puts "\nExamples:"
+    puts "       #{colored_script_name} #{'spec/features'.colorize(:light_blue)} (only run specs in the specs/features folder)"
+    puts "       #{colored_script_name} #{'spec/features/some_spec:53'.colorize(:light_blue)} (run the spec on line 53 of the spec/features_some_spec.rb file)"
+    puts "       #{colored_script_name} #{'--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)} #{colored_script_name} (use with environment variables)\n"
+    # rubocop:enable Metrics/LineLength
+  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
+  def self.write_available_tasks
+    subclasses = ObjectSpace.each_object(Class).select { |klass| klass < RspecStarterTask }.sort { |a, b| a.name <=> b.name }
+
+    puts "\nAvailable Tasks:"
+    subclasses.each do |klass|
+      task_name = RspecStarterTask.name_for_class(klass).to_s
+      puts "       #{task_name.colorize(:light_blue)} - #{klass.description}"
     end
+  end
+
+  def self.write_task_info(colored_script_name)
+    puts "\nTask Options:"
+    puts "       These options can be used inside the #{colored_script_name} file on #{"task".colorize(:light_blue)} lines."
+    puts "       This list is computed dynamically based on the tasks that are enabled in the #{colored_script_name} file."
+    puts "       Every task accepts the following options:"
+    puts "          #{"quiet".colorize(:light_blue)} (true/false - Tell the task to be verbose. Some tasks may disregard at times.)"
+    puts "          #{"stop_on_problem".colorize(:light_blue)} (true/false - Tell the task to stop startup if it encounters a problem.)"
+    puts ""
+
+    sorted_task_options = Hash[@environment.options.registered_task_options.sort_by do |klass, options|
+      RspecStarterTask.name_for_class(klass)
+    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
+    sorted_task_options.each do |klass, options|
+      dsl_options = options.select(&:is_dsl_option?).sort {|a,b| a.name <=> b.name }
+      unless dsl_options.empty?
+        puts "       :#{RspecStarterTask.name_for_class(klass).to_s.colorize(:light_blue)}"
+        dsl_options.each do |option|
+                  puts "          #{option.name.colorize(:light_blue)} (#{option.description})"
+        end
+      end
     end
   end
 end