rspec_starter 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb6c3b840f892e7eb22465923f63708c2dd3942a21fb86754caf1ed9a25984f3
-  data.tar.gz: a37965d96323b5bf2f40611000e8c74c7f9b269c36dd461a0b3317fcccbdda3d
+  metadata.gz: 07651d1f45ae7e33bb3d5de51c198c87f6be0749803084eeae6ed4e2e2a2dfdb
+  data.tar.gz: '00769c37402ced8b3ce2c3d362bd6277d348d77e9f50d20c639ec2921425a47d'
 SHA512:
-  metadata.gz: 9b83cc5cd091593252a806854b35913e420ea38a90bdee5bfd26a2af270e13820ef40d3c7f2364e07d8e8e3e31d6b5b4fdbe45d55c0f44690300b3018b920136
-  data.tar.gz: e342445d01317ca1f239abca6dd566285863fb0d1411ef46df87b7cff91a8f1eb8b31528931a98262bb281a94fad205bd2d33e6141131bfa9c08fd1603656c81
+  metadata.gz: a06b48f11b0e5240dcc51761de9304e342d67e7d1d194823b1d3f64af98ad65499bcfafcefef8d2b1903f80e51ee9ad4bc39cd8fa12d2e29a90cdbd5b3c9ddc7
+  data.tar.gz: 5dc317a2c50d27d56bae0a2e7d556d803fe2c913fae7ed9aad9b9645e2ba0363cc111e83d5ff900a65e2237db941c5562358e34edb2293774fe5c8802c19d14c

data/.rubocop.yml

@@ -9,3 +9,12 @@ inherit_gem:
 
 # Place custom settings below this comment.  All customizations will OVERRIDE rubocop_plus rules.  rubocop_plus & rubocop
 # do not attempt to merge these settings with their defaults.  Long term changes should be ported to the rubocop_plus gem.
+
+Rails:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
+
+Style/Alias:
+  Enabled: false

data/.travis.yml

@@ -1,11 +1,11 @@
 language: ruby
 cache: bundler
 rvm:
-  - 2.3.7
-  - 2.4.5
-  - 2.5.3
-  - 2.6.1
-before_install: gem install bundler -v 2.0.1
+  - 2.3.8
+  - 2.4.9
+  - 2.5.7
+  - 2.6.5
+before_install: gem install bundler -v 2.0.2
 notifications:
   email:
     on_success: never # default: change

data/CHANGELOG.md

@@ -1,43 +1,54 @@
 # CHANGELOG
 
+Issues marked as **(Internal)** mark internal development work. Issues are tracked at https://github.com/roberts1000/rspec_starter/issues.
+
+## 1.6.0 (Dec 09, 2019)
+
+1. [#56](../../issues/56) Move old starter code to a `legacy` folder so it can still be used. **(Internal)**
+1. [#58](../../issues/58) Add step based interface.
+1. [#59](../../issues/59) Use `rake ~> 13.0` for development. **(Internal)**
+1. [#61](../../issues/61) Use `pry-byebug ~> 3.7.0` for development. **(Internal)**
+1. [#63](../../issues/63) Modernize the CHANGELOG. **(Internal)**
+1. [#66](../../issues/66) Update ruby versions and use bundler 2.0.2 in `travis.yml`. **(Internal)**
+
 ## 1.5.0 (Feb 19, 2019)
 
-1. Report an exit status of 1 if DB Preparation or RSpec fails.  (Issue #51)
+1. [#51](../../issues/51) Report an exit status of 1 if DB Preparation or RSpec fails.
 
 ## 1.4.0 (Oct 12, 2018)
 
-1. Isolate rebuild command string into a dedicated method..  (Issue #41)
-1. Add instructions for creating custom steps.  (Issue #43)
-1. Fix database rebuild command hanging when there's too much output.  (Issue #45)
+1. [#41](../../issues/41) Isolate rebuild command string into a dedicated method. **(Internal)**
+1. [#43](../../issues/43) Add instructions for creating custom steps.
+1. [#45](../../issues/45) Fix the database rebuild command hanging when there's too much output.
 
 ## 1.3.0 (Aug 30, 2018)
 
-1. Change `cri` version to `~> 2.0`.  (Issue #37)
+1. [#37](../../issues/37) Change `cri` version to `~> 2.0`.
 
 ## 1.2.0 (Aug 08, 2018)
 
-1. Remove rubocop_plus from Gemfile.  (Issue #23)
-1. Update ruby versions in .travis.yml.  (Issue #24)
-1. Use `bundler` `1.16.3` in .travis.yml.  (Issue #26)
-1. Use `cri` `~> 2.12.0`.  (Issue #29)
-1. Remove support for Ruby 2.2.  (Issue #31)
-1. Use `rake` `~> 12.0` in development.  (Issue #33)
+1. [#23](../../issues/23) Remove `rubocop_plus` from Gemfile. **(Internal)**
+1. [#24](../../issues/24) Update ruby versions in `.travis.yml`. **(Internal)**
+1. [#26](../../issues/26) Use `bundler` `1.16.3` in `.travis.yml`. **(Internal)**
+1. [#29](../../issues/29) Use `cri` `~> 2.12.0`.
+1. [#31](../../issues/31) Remove support for Ruby 2.2.
+1. [#33](../../issues/33) Use `rake` `~> 12.0` in development. **(Internal)**
 
 ## 1.1.1 (May 06, 2018)
 
-1. Cleanup rubocop issues in the `start_rspec` template that is installed in user applications.  (Issue #6)
+1. [#6](../../issues/6) Cleanup rubocop issues in the `start_rspec` template.
 
 ## 1.1.0 (Feb 02, 2018)
 
-1. Ensure the XVFB is detected correctly.  (Issue #5)
-1. Prepare the database when the project is a Rails engine.  (Issue #7)
-1. Add an `rspec_starter --init` command that installs an initial script.  (Issue #9)
-1. Add rubocop_plus gem for internal code cleanup.  (Issue #11)
-1. Change the highlight color of the output from yellow to blue.  (Issue #15)
+1. [#5](../../issues/5) Ensure XVFB is detected correctly.
+1. [#7](../../issues/7) Prepare the database when the project is a Rails engine.
+1. [#9](../../issues/9) Add an `rspec_starter --init` command that installs an initial script.
+1. [#11](../../issues/11) Add `rubocop_plus` gem for internal code cleanup. **(Internal)**
+1. [#15](../../issues/15) Change the highlight color of the output from yellow to blue.
 
 ## 1.0.1 (May 10, 2017)
 
-1. Improve the logic for deciding when the database preparation step has successfully completed, and format the error output better.  (Issue #1)
+1. [#1](../../issues/1) Improve the logic for deciding when the database preparation step successfully completes.
 
 ## 1.0.0 (Apr 06, 2017)
 

data/README.md

@@ -1,23 +1,12 @@
 # rspec_starter
 
-rspec_starter is a Ruby gem that simplifies the process of running RSpec.  Large development teams often manage multiple projects.  Those projects tend to have subtle differences in how rspec should be invoked.  Hopefully someone took the time to explain how to do it in the README, but this frequently doesn't happen.
+rspec_starter is a Ruby gem that simplifies the process of running RSpec. Instead of running `bundle exec rspec`, developers run a script that includes predefined steps to execute while starting RSpec. The steps can be anything from removing the projects `tmp` folder to doing a full rebuild of the database prior to starting RSpec.
 
-With rspec_starter, a script is created which specifies how to run RSpec properly for the application.  Anyone can invoke the `bin/start_rspec` script to run the rspec test suite.  No confusion.  Self documenting.  Amazing.
+rspec_starter also helps eliminate differences between operating systems. For example, MacOS provides it's own display server for running feature tests while Linux operating systems may need to start a display sever, like XVFB. rspec_starter can inspect the OS and start the display server if necessary.
 
-rspec_starter also helps smooth out differences between operating systems.  For example, MacOS provides it's own display server for running feature tests whereas Linux operating systems may need to start a display sever, like XVFB, before feature tests will pass.  Once rspec_starter is setup, developers simply execute the script and rspec_starter does the rest.
+rspec_starter currently works natively for Rails applications, Rails Engines and raw ruby applications/gems that are not database dependent. However, rspec_starter is flexible and you can add your own tasks to support other types of projects.
 
-At the moment, rspec_starter works for Rails applications, Rails Engines and raw ruby applications/gems that are not database dependent.
-
-### Main Steps
-
-rspec_starter can currently perform the following steps (these steps can be toggled on or off)
-
-- Prepare a Rails database (or dummy database inside a Rails engine) by running `rake db:drop db:create db:migrate RAILS_ENV=test`
-- Remove the `tmp` folder if it exists
-- Verify XVFB is installed when running on a Linux box
-- Start RSpec with `bundle exec rspec` or `xvfb-run bundle exec rspec` (depending on the needs of the OS)
-
-## Version Policy
+## Version Strategy
 
 Releases are versioned using [semver 2.0.0](https://semver.org/spec/v2.0.0.html).
 
@@ -29,7 +18,7 @@ Releases are versioned using [semver 2.0.0](https://semver.org/spec/v2.0.0.html)
 
 ### Rails Applications & Rails Engines
 
-Add this line to your Gemfile of your Rails application or Rails Engine:
+Add this line to the `Gemfile` of your Rails application or Rails Engine:
 
 ```ruby
 group :development do
@@ -37,167 +26,208 @@ group :development do
 end
 ```
 
-And then execute:
+You do not need to add rspec_starter to the `:test` group since rspec_starter doesn't execute while RSpec runs. Its work is done once RSpec starts.
+
+Next, execute:
 
     $ bundle
 
-Run the installer
+Then run the installer
 
     $ rspec_starter --init
 
-The above command installs the script you will use to run rspec.  The file is named `start_rspec`, but you can rename it to anything you like.
+The installer creates a `bin/start_rspec` that you will use to start RSpec. You can rename the file to anything you want.
 
-## Usage
+## Basic Usage
 
-`cd` into the root of your application/project and invoke the script.  For these examples, it is assumed you placed the script in the `bin` folder of your app (but you could put it anywhere you like).
+`cd` into the root of your project and invoke the script.
 
     $ bin/start_rspec
 
-The above command will run the entire test suite.  You can pass options to the script as well.  Some of the options will be consumed by start_rspec and some will be forwarded on to rspec.  As a result, you could do something like
+The `bin/start_rspec` file executes a series of "steps" (more on this later) and eventually starts RSpec. Output from RSpec is displayed to the console as normal.
+
+You can pass command line arguments to rspec_starter. To see the full list, type `bin/start_rspec --help`.  When you pass arguments, rspec_starter first checks if any of them are specific to rspec_starter.  It processes those arguments and takes action.  Any remaining arguments are saved and passed to RSpec when RSpec is started. You can use all the normal RSpec command line options, except for `--help` and `-h` (rspec_starter assumes you want help for rspec_starter instead of rspec). rspec_starter will happily forward them on.  For example, if you only want to execute the feature specs in your project, simply do what you would normally do for RSpec:
 
     $ bin/start_rspec spec/features
 
-which tells start_rspec, to tell rspec, to only run the feature tests.  Run the following command to see other ways to use the script
+## Customizing the bin/start_rspec file
 
-    $ bin/start_rspec --help
+The `bin/start_rspec` file was made to be edited. When you ran the `rspec_starter --init` command, it installed a basic command for your project that looked something like this:
 
-## Custom Steps
+```ruby
+RspecStarter.start do
+  task :verify_display_server
+  task :remove_tmp_folder
+  task :rebuild_rails_app_database
+  task :start_rspec
+  command "echo 'Done Diggity Done!'"
+end
+```
 
-rspec_starter does not currently have support for creating custom steps.  However, there are some techniques that can achieve the same results.  rspec_starter currently implements 4 "steps" which can be turned on or off.  The steps are implemented by classes and are evaluated in this order:
+#### Steps
 
-1. `VerifyXvfbStep` - Ensures xvfb is installed on systems where it should be used (.i.e. Linux).
-1. `PrepareDatabaseStep` - Runs `rake db:drop db:create db:migrate RAILS_ENV=test`.
-1. `RemoveTmpFolderStep` - Deletes the `tmp` folder.
-1. `InvokeRspecStep` - Runs `bundle exec rspec`.
+At it's heart, rspec_starter is just a block that lists a series of "steps" that are executed in **top down order**. rspec_starter provides two kinds of steps:
 
-All steps implement an `execute` method that actually runs the step. You can inject custom code before or after any one of those steps.
+1. `command` - A "command" is the most basic kind of "step" in rspec_starter. It accepts a string and passes that string to the ruby `system` command. It can be used to run shell commands or scripts.
+1. `task` - A "task" is just a ruby class that implements an `execute` method. What you do in that `execute` method is up to you. rspec_starter provides a couple built-in tasks that perform various actions that are useful when running RSpec. The list of available task are defined below. You can also easily create your own.
 
-#### Using prepend to Inject a Custom Module
+#### Step Options
 
-One strategy is to open the `bin/start_rspec` file use `prepend` to inject a custom module into the class.
+Any options that you add to steps inside the block, become available to the task.
 
 ```ruby
-require "bundler/setup"
-require "rspec_starter"
-
-# The path to the application's root folder.
-APP_ROOT = Pathname.new File.expand_path('../../', __FILE__)
-
-module CustomStep
-  def execute
-    # Place code above the super call if you want it run before the targeted step
-    super # super needs to be called if you want the targeted step to execute
-    # Place code after the super call if you want it run after the targeted step
-  end
-end
-
-RspecStarter::PrepareDatabaseStep.prepend CustomStep
-
-Dir.chdir APP_ROOT do
-  RspecStarter.start(prepare_db: true, remove_tmp: true, allow_xvfb: true)
+RspecStarter.start do
+  task :verify_display_servr, foo: :bar
+  task :remove_tmp_folder
+  task :rebuild_rails_app_database, command: "rake db:drop db:create db:migrate", quiet: false
+  task :start_rspec, quiet: true
 end
 ```
 
-In the above example, the `PrepareDatabaseStep` is targeted.  By prepending the `CustomStep` module to `PrepareDatabaseStep`, it ensures  the `execute` in `CustomStep` is executed before the `execute` method in the targeted step..  At that point, you can execute any code you want, then call `super` to run targeted step, then run any code after the targeted step completes.
+Tasks ignore options unless they are specifically coded to look for them. For example, the `foo: :bar` in the above example has no affect on the `verify_display_server` task while the `command` option on the `rebuild_rails_app_database` changes the command that is executed.
 
-**Note:** If you're trying to run additional rake tasks on the database using this technique, it probably won't work.  Your custom rake task will execute in a different process from the rake tasks that rspec_starter runs.  This will prevent some changes from getting saved to the database.  The techniques described below can help in this situation.
+All steps allow you to specify these options when you call the `command` or `task` helpers:
 
-#### Customizing the Database Prep Step
+1. `quiet` - Direct the step to generate as little output as possible when it executes. It's up to the step to determine what this means for the step and the step may choose to ignore it. If you do not specify a value, a `command` or `task` will pick a default that it prefers. If the `command` or `task` triggers an error while it is running, it will dump the error output to the screen if it was running quietly.
+1. `stop_on_problem` - Direct rspec_stater to stop everything if a particular step fails. Some steps may only show information, and if they fail, you may not want to stop RSpec from running. If you want to ensure a step failure causes rspec_stater to stop, then set `stop_on_problem: true`. If you do not specify a value, steps will chose their preferred value.
 
-Database preparation is performed by `PrepareDatabaseStep`.  You can use the above `prepend` technique to add code before/after this step runs, but you can also customize the exact command that is run to prepare your db.  By default, `PrepareDatabaseStep` runs `rake db:drop db:create db:migrate RAILS_ENV=test` on your application (as seen [here](https://github.com/roberts1000/rspec_starter/blob/v1.4.0/lib/rspec_starter/steps/prepare_database_step.rb#L46)).  You can override that command with:
+## Commands
 
-```
-module CustomStep
-  def rebuild_command
-    "rake db:drop db:create db:migreate db:do_something_else RAILS_ENV=test"
-  end
-end
+Commands are steps that pass a string to the Ruby `system` method. Commands are defined in the following manner
 
-RspecStarter::PrepareDatabaseStep.prepend CustomStep
+```ruby
+RspecStarter.start do
+  command "echo 'This will execute, but not display output of the command"
+  command "echo 'This will execute, and display the output of the command", quiet: false
+end
 ```
 
-In this case, calling `super` isn't needed because we don't care about the default implementation.
+rspec_starter tries to keep output concise so command output is hidden by default. If you want to see the output of a command, add the `quiet: false` option.
 
-**Note:** When using this technique, any output written to the console by rake tasks will not be displayed because the `PrepareDatabaseStep` supresses the output.
+## Tasks
 
-#### Invoking Custom Rake Tasks
+#### Built-in Tasks
 
-There are several ways to invoke rake tasks in Ruby.  Backticks don't seem to work in `rspec_starter`, but calling `system` does work
+rspec_starter provides the following built-in tasks:
 
-```ruby
-module CustomStep
-  def execute
-    super
-    system("bundle exec rake do_something_else_after_db_is_prepped")
-  end
-end
+1. `verify_display_server` - Verify that Linux users have XVFB installed and Mac OS users do not.
+1. `remove_tmp_folder` - Delete the project's `tmp` folder.
+1. `rebuild_rails_app_database` - Rebuild the test database for a Ruby on Rails application. By default, the seed files are not loaded. The goal is to have a completely empty database.
+1. `start_rspec` - Run RSpec.
 
-RspecStarter::PrepareDatabaseStep.prepend CustomStep
-```
+You can find the code for rspec_starter's built-in `tasks` at ../../lib/rspec_starter/tasks.
+
+#### Custom Tasks
 
-You can also invoke the task without calling out to the system.  This should also be faster since the Kernel won't have to setup the process.
+The default tasks provided by rspec_starter are just subclasses of the `RspecStarterTask` class. You can define your own subclasses anywhere and load them. A simply way to get started is to define the classes in the `bin/start_rspec` file, before `RspecStarter.start` is called.
 
 ```ruby
-require 'rake'
-require File.expand_path('config/environment', APP_ROOT)
-ReplaceWithAppName::Application.load_tasks
+class MyTask < RspecStarterTask
+  # [OPTIONAL] This is an optional method. If you define it, you can add command line options to the
+  # root bin/start_rspec starter command and arguments to the task steps inside the
+  # 'RspecStarter.start' block. You can access the values at runtime by calling 'options'.
+  # Be careful not to add a switch that RSpec itself uses. rspec_starter will use it, but it will
+  # not forward it to RSpec.
+  def self.register_options
+    # The following registration lets users call
+    #
+    #   bin/start_rspec --skip-my-task
+    #
+    # and inside the start block they can do
+    #
+    #   RspecStarter.start do
+    #     task :my_task, skip_my_task: true/false
+    #   end
+    #
+    # register_option takes the following options
+    #
+    #   name        - The argument name for the task option'.
+    #   default     - The default value when the argument is not specified on the 'task' step.
+    #   switch      - The string the user specifies with the 'bin/start_rspec' command. Switches
+    #                 always return true or false.
+    #   description - The information to show when 'bin/start_rspec --help' is run.
+    #
+    # There are some rules that must be followed when registering the option:
+    #
+    #   1. You must specify either "name:", "switch:" or both.
+    #   2. If you specify both, "switch:" must be similiar to 'name:'. For example, if the name is
+    #      "skip_my_task", the switch must be --skip-my-task (-skip-my-task works too). Internally,
+    #      the hypens in the switch name are converted to underscores so you can access it as a
+    #      method on the options object inside the task.
+    #   3. Switch names must start with "--" or "-".
+    #   4. If "switch:" is specified, "default:" must be set to true or false. If the user does not
+    #      use the switch in the commandline, the default value is returned. If the user
+    #      specifies the switch, !default is returned.
+    #
+    register_option name: "skip_my_task", default: false, switch: '--skip-my-task',
+      description: "Skip the task"
+  end
 
-module CustomTask
-  def execute
-    super
-    Rake::Task["do_something_else_after_db_is_prepped"].invoke
+  # [OPTIONAL] This is an optional method. Let subsequent steps run if this task runs into a problem.
+  # This value can be overridden in the applications bin/start_rspec file if the user adds
+  # 'stop_on_problem: true' to the task line.
+  def self.default_stop_on_problem
+    false
   end
-end
 
-RspecStarter::PrepareDatabaseStep.prepend CustomTask
-```
+  # [OPTIONAL] This is an optional method. Specify if the task likes to run quietly or not. This will
+  # only set the 'quiet' flag on the task. It is up to you to check the quiet flag in the `execute`
+  # method and do something quietly or not.
+  def self.default_quiet
+    false
+  end
 
-In this technique, you must replace the `ReplaceWithAppName` with the name of your Rails application.  Open the `config/application.rb` file to find the correct name.
+  # [OPTIONAL] This is an optional method. If you want your task to be skipped under certain conditions,
+  # add the logic here. The task is fully initialized at this point and you have access to the
+  # 'options' object and any arguments that are added to the `task` helper inside the
+  # `RspecStarter.start` block.
+  def should_skip?
+    options.skip_my_task
+  end
 
-#### Appending to Existing Rake Tasks
+  # The string that is returned from this method is displayed just before your task starts to run. It
+  # should be brief and describe what the task is doing.
+  def starting_message
+    "Some string"
+  end
 
-You can also bypass rspec_starter completely and add additional logic to existing rake tasks.  For example, if you **always** want to peform an extra task after `db:migrate` is executed, you can add the following to your `lib/db_migrate.rake` folder:
+  # This is the main run method. Do whatever you want your task to do here.
+  def execute
+    # Call the 'problem' method if the command ran into an error.
+    problem if something_went_wrong
 
-```ruby
-namespace :db do
-  task :migrate do
-    # do something additional
+    # You can call the 'success' method if successful, but this is optional. rspec_starter will
+    # assume the task was successful if `problem` wasn't called.
+    success
   end
-end
-```
 
-or
-
-```ruby
-namespace :db do
-  task :migrate do
-    Rake::Task["another_task_name"].invoke
+  # [OPTIONAL] This is an optional method. When your task runs in quiet mode, it may not write error
+  # output to the screen if there's a problem. This method is called only when you call the `problem`
+  # method during execution (or if there's a general error raised). You can write any error/debug
+  # information that you find helpful.
+  def write_error_info
   end
 end
 ```
 
-When you redefine an existing rake task, rake actually apends your custom code to the existing rake task instead of overwriting it.  If needed, you can also add additional guards to conditionally add the custom logic:
-
+Once your custom task class is created, add it to the `RspecStarter.start` block:
 
 ```ruby
-if Rails.env == "development"
-  namespace :db do
-    task :migrate do
-      Rake::Task["another_task_name"].invoke
-    end
-  end
+RspecStarter.start do
+  #... tasks or commands above ...
+  task :my_task
+  # ... tasks or commands below ...
+  task :start_rspec
 end
 ```
 
-## Configuration
-
-The entire idea behind start_rspec is to standardize the process of starting RSpec for an application.  You can modify the `bin/start_rspec` file to do whatever you want.  If you open that file, you'll see that it does one thing - it calls the following command in the context of the root folder, of your project:
+When you add the `task` line, convert your class to lowercase and user underscores for word separators. In this example, the `MyTask` class became `:my_task` when it was used inside the start block.
 
-    RspecStarter.start(prepare_db: true, remove_tmp: true, allow_xvfb: true)
+That's it. rspec_starter will find your class, and call the `execute` at the appropriate time.
 
-The arguments passed to `start_rspec`, represent the defaults you consider important for achieving a clean RSpec run.  If your particular project doesn't have a DB, or you don't need it prepared before each Rspec run, you can turn that step off by passing `prepare_db: false`.
+## Command line options
 
-Be careful about the steps you enable/disable inside the script file.  **The goal is to define steps that help people, with limited knowledge of the project, successfully run RSpec.**  It's best to have `bin/start_rspec` define the best way to run RSpec for newbies, then disable specific steps by passing in command line options on a per-run basis.  Run `bin/start_rspec --help` to see a list of available options.
+Run `bin/start_rspec --help` to see a list of command line options. Command line options override settings that are present in the `bin/start_rspec` file, or hard-coded defaults inside the Task/Command code.
 
 ## Contributing