rspec_starter 1.5.0 → 1.6.0

data/lib/rspec_starter/rspec_starter_task.rb

@@ -0,0 +1,35 @@
+# Tasks are classes that implement an 'execute' method. Tasks can execute any ruby code they want inside the 'execute' method.
+# Tasks are defined by listing their name inside the RspecStarter.start block:
+#
+#   RspecStarter.start do
+#     task :verify_display_server
+#     task :rebuild_rails_app_database, stop_on_problem: true
+#     task :start_rspec, quiet: true
+#   end
+#
+# Tasks accept a `quiet` option which tells the task to be more or less verbose. Tasks accept a `stop_on_problem` method
+# that determines whether a problem should cause the entire start-up process to stop when the task encounters a problem.
+class RspecStarterTask < RspecStarterStep
+  def self.register_option(hash)
+    @options_registrar.register_task_option(self, hash)
+  end
+
+  def self.description
+    ""
+  end
+
+  private
+
+  # Convert something like VerifyDisplayServer to :verify_display_server
+  def self.name_for_class(klass)
+    klass.name.underscore.to_sym
+  end
+
+  def print_starting_message
+    print "#{@starting_message} ..."
+  end
+
+  def initialize_name
+    @name = self.class.name_for_class(self.class)
+  end
+end

data/lib/rspec_starter/runner.rb

@@ -1,88 +1,29 @@
-require 'pathname'
-require 'open3'
-require_relative 'core_ext/string'
-require_relative 'which'
-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.
+  # This class implements the main control loop that processes steps. It maintains a list of steps and executes
+  # each one. Steps can be skipped if command line options, or other options dictate turn off the step.
   class Runner
-    include Help
-    attr_reader :xvfb_installed, :step_num, :steps
+    attr_reader :environment
 
-    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
+    def initialize(environment)
+      @environment = environment
+      @steps = @environment.step_contexts.collect { |step_context| step_context.instantiate(self) }
     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
+        next if step.should_skip?
 
-    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/) }
+        print "[#{step.id}] "
+        step.run
       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)
+    def largest_exit_status
+      @steps.inject(0) do |max, step|
+        # If a step doesn't execute, it's exit_status will be nil.
+        current = step.exit_status || 0
+        max > current ? max : current
+      end
     end
   end
 end

data/lib/rspec_starter/step.rb

@@ -0,0 +1,181 @@
+# RspecStarterStep is essentially an abstract super class. It should not be instantiated directly. It primarily holds the
+# logic for executing a Task or Command. Steps (and their subclasses) maintain three different types of options.
+#   1. Command Options - These are specified on the command line when the bin/start_rspec command is run.
+#   2. Step Options - These are specified inside the bin/start_rspec file when a task or command is added to the step list.
+#   3. Step Defaults - Steps define default values when Command Options or Step Options are not given.
+class RspecStarterStep
+  attr_accessor :id, :exit_status, :name, :quiet, :options, :run_time, :runner, :successful
+
+  alias_method :successful?, :successful
+
+  def initialize(id, runner, options)
+    @id = id
+    initialize_name
+    @runner = runner
+    @options = options
+
+    @start_time = nil
+    @finish_time = nil
+    @run_time = nil
+
+    @exit_status = nil
+    @successful = nil
+    # This is set when the step runs
+    @starting_message = nil
+  end
+
+  def self.provide_options_to(registrar)
+    @options_registrar = registrar
+    register_options
+  end
+
+  # Tasks can implement this method and register options that they support.
+  def self.register_options
+  end
+
+  def should_skip?
+    false
+  end
+
+  def quiet?
+    options.quiet
+  end
+
+  def stop_on_problem?
+    options.stop_on_problem
+  end
+
+  def failed?
+    !@successful
+  end
+
+  def verbose?
+    !quiet?
+  end
+
+  def helpers
+    RspecStarter.helpers
+  end
+
+  def run
+    set_starting_message
+    print_starting_message
+    set_start_time
+    execute_step
+    set_finish_time
+    set_run_time
+    write_run_time
+    handle_step_failure
+  end
+
+  # Most subclasses will suppress output when they run.
+  def self.default_quiet
+    true
+  end
+
+  # Most subclasses will prefer to stop rspec_starter if they hit a problem.
+  def self.default_stop_on_problem
+    true
+  end
+
+  private
+
+  # rubocop:disable Style/RescueStandardError
+  # This method executes the step and ensures the output is displayed to the screen. If errors occur, it will not raise
+  # an error that terminates the entire process. This method is focused on running a step, getting results and displaying output.
+  # The `run` method does a final check at the end to determine if we should proceed to the next step, or raise an error
+  # that terminates everything.
+  def execute_step
+    # Tell the step to execute. Steps should raise a 'RspecStarter::StepStopper' error by calling the 'problem' method when they
+    # want to terminate the step and report a problem. Steps should raise a 'RspecStarter::StepStopper' error when they
+    # want to terminate the step and report success. The code the step runs may also trigger any Ruby error. Those errors
+    # are captured and are treated like a problem occured.
+    execute
+    # If we get here, the step didn't explicitly trigger a problem, trigger a success or raise an error.
+    # Assume success and trigger it now.
+    success
+  rescue RspecStarter::StepStopper => e
+    # If we get here, it's because the step called `problem` or `success`. Those two methods gracefully record final results
+    # for the step and format a message to show the user. Since the results are already recorded, we just need to display
+    # the message.
+    print e.message
+  rescue => e # Catch any other error
+    mark_result(success: false, exit_status: 1)
+    print formatted_problem_message(e.message)
+  end
+  # rubocop:enable Style/RescueStandardError
+
+  def handle_step_failure
+    return unless failed?
+
+    # If the task ran quietly, give it the opportunity to write any error output it might want to show.
+    write_error_info if quiet?
+    raise RspecStarter::StepError if stop_on_problem?
+  end
+
+  def write_run_time
+    puts " (#{run_time}s)"
+  end
+
+  def set_run_time
+    @run_time = (@finish_time - @start_time).round(3)
+  end
+
+  def set_start_time
+    @start_time = time_now
+  end
+
+  def set_starting_message
+    @starting_message = starting_message
+  end
+
+  def set_finish_time
+    @finish_time = time_now
+  end
+
+  def time_now
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+
+  def starting_message
+    "Add the starting_message method to your task and say what it's doing".warning
+  end
+
+  def mark_result(success:, exit_status:)
+    @successful = success
+    @exit_status = exit_status
+  end
+
+  def success(msg="")
+    mark_result(success: true, exit_status: 0)
+    raise RspecStarter::StepStopper, formatted_success_message(msg)
+  end
+
+  def problem(details="", exact: false, exit_status: 1)
+    mark_result(success: false, exit_status: exit_status)
+    raise RspecStarter::StepStopper, formatted_problem_message(details, exact: exact)
+  end
+
+  def formatted_success_message(msg)
+    (msg.empty? ? " Success!!" : " Success!! (#{msg})").colorize(:green)
+  end
+
+  def formatted_problem_message(details, exact: false)
+    details_part = details.empty? ? "" : " (#{details})"
+    msg = exact ? details : " #{problem_msg_label}#{details_part}"
+    msg.colorize(problem_msg_color)
+  end
+
+  def problem_msg_label
+    stop_on_problem? ? "Failed" : "Warning"
+  end
+
+  def problem_msg_color
+    stop_on_problem? ? :red : :yellow
+  end
+
+  # Do nothing by default. Subclasses will implement this method if they want to display error info.
+  # This method is only called in certain situations.
+  def write_error_info
+  end
+end

data/lib/rspec_starter/step_context.rb

@@ -0,0 +1,28 @@
+module RspecStarter
+  # StepContext is an abstract class. Subclasses hold the information from the RspecStarter.start block when the block is parsed,
+  # but they don't actually execute Steps. Their job is to instantiate Step objects, and bind the appropriate options to the
+  # objects so they can execute correctly.
+  class StepContext
+    attr_reader :environment, :id, :requested_args
+
+    def initialize(environment:, id:, requested_args:)
+      @environment = environment
+      @id = id
+      @requested_args = requested_args
+    end
+
+    private
+
+    def build_options
+      options = StepOptions.new
+      apply_global_options_to_options(options)
+      options
+    end
+
+    def apply_global_options_to_options(options)
+      options.add("quiet", step_class.default_quiet)
+      options.add("stop_on_problem", step_class.default_stop_on_problem)
+      options.add("rspec_args_string", environment.options.rspec_args_string)
+    end
+  end
+end

data/lib/rspec_starter/step_options.rb

@@ -0,0 +1,20 @@
+module RspecStarter
+  # StepOptions is like an OpenStruct. It lets us add getters and setters to an object dynamically. It's used to hold the
+  # options and values that uses specify on the commandline, and inside the RspecStarter.start bock. We used this custom class
+  # instead of an OpenStruct to avoid the performance issues associated with OpenStruct and to give the ability to add additional
+  # methods when needed.
+  class StepOptions
+    def add(key, value)
+      instance_variable_set("@#{key}", value)
+      self.class.define_method(key.to_s) do
+        instance_variable_get("@#{key}")
+      end
+    end
+
+    def update(key, value, add_missing: true)
+      return instance_variable_set("@#{key}", value) if respond_to?(key)
+
+      add(key, value) if add_missing
+    end
+  end
+end

data/lib/rspec_starter/task_context.rb

@@ -0,0 +1,63 @@
+module RspecStarter
+  # TaskContext's are created to when parsing the RspecStater.start block. They hold the args and Task class name. They are
+  # asked to create instances of Task subclasses from this information when it is time to execute. The also resolve the options
+  # that each Task is allowed to access.
+  class TaskContext < StepContext
+    attr_reader :step_class
+
+    def initialize(environment:, id:, step_class:, requested_args:)
+      super(environment: environment, id: id, requested_args: requested_args)
+
+      @step_class = step_class
+    end
+
+    def instantiate(runner)
+      @step_class.new(@id, runner, build_options)
+    end
+
+    def is_task?
+      true
+    end
+
+    def is_command?
+      false
+    end
+
+    private
+
+    def build_options
+      options = super
+      add_defaults_to_options(options)
+      apply_args_to_options(options)
+      apply_command_line_switches_to_options(options)
+      options
+    end
+
+    def add_defaults_to_options(options)
+      registered_options = environment.options.registered_task_option(@step_class)
+      registered_options.each { |option| options.add(option.key, option.default) }
+    end
+
+    def apply_args_to_options(options)
+      registered_options = environment.options.registered_task_option(@step_class)
+      dsl_option_names = registered_options.select(&:is_dsl_option?).collect { |option| option.name.to_sym }
+      @requested_args.each do |key, value|
+        next unless dsl_option_names.include?(key)
+
+        options.update(key, value, add_missing: false)
+      end
+    end
+
+    def apply_command_line_switches_to_options(options)
+      registered_options = environment.options.registered_task_option(@step_class)
+      present_switches = environment.options.present_switches
+      registered_options.each do |option|
+        # The switch could be nil for the option, which means the step isn't registering a switch for this option. The step
+        # developer just wants to register an option for the dsl (which is applied earlier).
+        if option.switch
+          options.update(option.key, !option.default, add_missing: false) if present_switches.include?(option.switch)
+        end
+      end
+    end
+  end
+end

data/lib/rspec_starter/tasks/rebuild_rails_app_database.rb

@@ -0,0 +1,50 @@
+# Rebuild the database for a rails application or a rails engine. This task honors the following command line options
+#   --skip-db-prep    Causes the task to be skipped
+class RebuildRailsAppDatabase < RspecStarterTask
+  def self.description
+    "Rebuild a Ruby on Rails application or engine database."
+  end
+
+  def self.register_options
+    register_option default: false, switch: '--skip-db-prep',
+                    switch_description: "DO NOT prepare the Rails application database"
+    register_option name: "command",
+                    default: "DISABLE_DATABASE_ENVIRONMENT_CHECK=1 RAILS_ENV=test rake db:drop db:create db:migrate",
+                    description: "A command string that is used to rebuild the database."
+  end
+
+  def should_skip?
+    options.skip_db_prep || options.command.nil? || options.command.empty?
+  end
+
+  def starting_message
+    "Running #{options.command.highlight}"
+  end
+
+  def execute
+    if quiet?
+      @stdout, @stderr, @status = Open3.capture3(options.command)
+    else
+      puts "\n\n"
+      @verbose_command_passed = system options.command
+      @status = $CHILD_STATUS
+      print @starting_message
+    end
+    problem if command_failed?
+  end
+
+  def write_error_info
+    puts @stdout
+    puts @stderr
+    puts "\n\nThere was an error rebuilding the test database.  See the output above for details " \
+      "or manually run '#{options.command}' for more information.".colorize(:red)
+  end
+
+  private
+
+  # Simply checking the exitstatus isn't good enough.  When rake aborts due to a bug, it will still
+  # return a zero exit status.  We need to see if 'rake aborted!' has been written to the output.
+  def command_failed?
+    @status.exitstatus.nonzero? || (!@stderr.nil? && @stderr.include?("rake aborted!")) || @verbose_command_passed == false
+  end
+end