skywalker 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d19f8fad7236722932ae900e99b7c4aaf0b8a708
-  data.tar.gz: 1373707d67ae212131fa3f4ac95dda7d942831c1
+  metadata.gz: 2694a53679e9a4856529718e3d7a80108aa32273
+  data.tar.gz: 030762cf30ce2e24fef88a41098744ab65036965
 SHA512:
-  metadata.gz: f877c39807cb3b1b7948786d484e018b176ad6ffd036b2da28ffcc5dd2464fee06ee8c3635a133f0cf088d32eda857b2d0301545a9f7f13cbe99013c39eeaf56
-  data.tar.gz: 83eb7c4d081624d25378e2723595a62757b13642c7ef8b184b51a1a4885e4fc0d34409a36930caa6243b52e642a61e0def5fa03d2b3d7ca8dc2941a8471cc7ec
+  metadata.gz: ceed550cb8e32449ba3897c46a8b53ca4d89dc96874d66ebef9aa142227fddf928d8f2f4c6bfde3982239d348732035e31e90f472b6cb60a97b6d78b9ba422b5
+  data.tar.gz: 550fdeacbc19bebc36bab1eaf51c5171eb638f7a7364fa3d3d2079b9139e2244362fa1b8cc4b5ce4742c4010c63d9e8115d6e3526a8d58264dcfc4a75154e8f9

data/.gitignore

@@ -13,5 +13,7 @@
 *.a
 mkmf.log
 
+examples/vendor/gems
+
 vendor/bundle
 vendor/gems

data/README.md

@@ -190,18 +190,23 @@ class CreateGroupCommand < Skywalker::Command
   end
 
 
+  private def required_args
+    %w(group on_success on_failure)
+  end
+
+
   private def save_group!
     group.save!
   end
 
 
   private def send_notifications!
-    notifier.call(group).deliver
+    notifier.deliver
   end
 
 
   private def notifier
-    @notifier ||= NotificationsMailer.method(:group_created_notification)
+    @notifier ||= NotificationsMailer.group_created_notification(group)
   end
 end
 ```
@@ -242,6 +247,10 @@ The following methods are overridable for easy customization:
 
 - `execute!`
   - Define your operations here.
+- `required_args`
+  - An array of expected keys given to the command. Raises `ArgumentError` if keys are missing.
+- `validate_arguments!`
+  - Checks required args are present, but can be customized. All instance variables are set by this point.
 - `transaction(&block)`
   - Uses an `ActiveRecord::Base.transaction` by default, but can be customized. `execute!` runs inside of this.
 - `confirm_success`
@@ -255,9 +264,50 @@ The following methods are overridable for easy customization:
 
 For further reference, simply see the command file. It's less than 90 LOC and well-commented.
 
-## Testing
+## Testing (and TDD)
+
+Take a look at the `examples` directory, which uses example as above of a notifier, but makes it a bit more complicated: it assumes that we only send emails if the user (which we'll pass in) has a preference set to receive email.
+
+### Assumptions
+
+Here's what you can assume in your tests:
+
+1. Arguments that are present in the list of required_args will throw an error before the command executes if they are not passed.
+2. Operations that throw an error will abort the command and trigger its failure state.
+3. Calling `Command.new().call` is functionally equivalent to calling `Command.call()`
+
+### Strategy
+
+There are two tests that you need to write. First, you'll want to write a Command spec, which are very simplistic specs and should be used to verify the validity of the command in isolation from the rest of the system. (This is what the example shows.) You'll also want to write some high-level integration tests to make sure that the command is implemented correctly inside your controller, and has the expected system-wide results. You shouldn't need to write integration specs to test every path -- it should suffice to test a successful path and a failing path, though your situation may vary depending on the detail of error handling you perform.
+
+Here's one huge benefit: with a few small steps, you won't need to include `rails_helper` to boot up the entire environment. That means blazingly fast tests. All you need to do is stub `transaction` on your command, like so:
+
+```ruby
+RSpec.describe CreateGroupCommand do
+  describe "operations" do
+    let(:command) { CreateGroupCommand.new(group: double("group") }
+
+    before do
+      allow(command).to receive(:transaction).and_yield
+    end
+
+    # ...
+  end
+end
+```
+
+### Common Failures
+
+Your failures will initially look like this:
+
+```
+undefined method `call' for nil:NilClass
+  # .../lib/skywalker/command.rb:118:in `run_failure_callbacks'
+```
+
+This means that the command failed and you didn't specify an `on_failure` callback. You can stick a debugger
+inside of `run_failure_callbacks`, and get the failure exception as `self.error`. You can also reraise the exceptiong to achieve a better result summary, but this is not done by default, as you may also want to test error handling.
 
-To come.
 
 ## Contributing
 

data/examples/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gem 'rspec'
+gem 'pry'
+gem 'skywalker', path: '../'

data/examples/Gemfile.lock

@@ -0,0 +1,58 @@
+PATH
+  remote: ../
+  specs:
+    skywalker (1.1.1)
+      activerecord (~> 4.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (4.1.7)
+      activesupport (= 4.1.7)
+      builder (~> 3.1)
+    activerecord (4.1.7)
+      activemodel (= 4.1.7)
+      activesupport (= 4.1.7)
+      arel (~> 5.0.0)
+    activesupport (4.1.7)
+      i18n (~> 0.6, >= 0.6.9)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.1)
+      tzinfo (~> 1.1)
+    arel (5.0.1.20140414130214)
+    builder (3.2.2)
+    coderay (1.1.0)
+    diff-lcs (1.2.5)
+    i18n (0.6.11)
+    json (1.8.1)
+    method_source (0.8.2)
+    minitest (5.4.3)
+    pry (0.10.1)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rspec (3.1.0)
+      rspec-core (~> 3.1.0)
+      rspec-expectations (~> 3.1.0)
+      rspec-mocks (~> 3.1.0)
+    rspec-core (3.1.7)
+      rspec-support (~> 3.1.0)
+    rspec-expectations (3.1.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.1.0)
+    rspec-mocks (3.1.3)
+      rspec-support (~> 3.1.0)
+    rspec-support (3.1.2)
+    slop (3.6.0)
+    thread_safe (0.3.4)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  pry
+  rspec
+  skywalker!

data/examples/app/commands/create_group_command.rb

@@ -0,0 +1,46 @@
+require 'skywalker/command'
+
+class CreateGroupCommand < Skywalker::Command
+  def execute!
+    save_group!
+    send_notifications!
+  end
+
+
+  def required_args
+    %w(user group)
+  end
+
+  ################################################################################
+  # Operations
+  ################################################################################
+  private def save_group!
+    group.save!
+  end
+
+
+  private def send_notifications!
+    notifier.deliver if send_user_email?
+  end
+
+
+  ################################################################################
+  # Guards
+  ################################################################################
+  private def send_user_email?
+    user.receives_email?
+  end
+
+
+  ################################################################################
+  # Accessors
+  ################################################################################
+  private def notifier
+    @notifier ||= ::NotificationsMailer.group_created_notification(group)
+  end
+
+
+  # def run_failure_callbacks
+  #   require 'pry'; binding.pry
+  # end
+end

data/examples/spec/commands/create_group_command_spec.rb

@@ -0,0 +1,78 @@
+require 'tiny_spec_helper'
+require 'create_group_command'
+
+RSpec.describe CreateGroupCommand do
+  let(:notifier) { double("notifier") }
+  let(:command) { CreateGroupCommand.new(group: group, notifier: notifier, user: user) }
+  let(:group) { double("group") }
+  let(:user) { double("user") }
+
+  describe "operations" do
+    before do
+      allow(command).to receive(:transaction).and_yield
+      allow(command).to receive_message_chain("on_success.call") { true }
+    end
+
+    describe "save group" do
+      before do
+        allow(command).to receive(:send_notifications!)
+      end
+
+      it "saves" do
+        expect(group).to receive(:save!)
+        command.call
+      end
+    end
+
+    describe "send notification" do
+      before do
+        allow(command).to receive(:save_group!)
+      end
+
+      context "when user receives email" do
+        before do
+          allow(command).to receive(:send_user_email?).and_return(true)
+        end
+
+        it "sends" do
+          # NB: You'll want to set `raise_delivery_errors` for mail to work
+          # transactionally.
+          expect(notifier).to receive(:deliver)
+          command.call
+        end
+      end
+
+      context "when user does not receive email" do
+        before do
+          allow(command).to receive(:send_user_email?).and_return(false)
+        end
+
+        it "does not send" do
+          expect(notifier).not_to receive(:deliver)
+          command.call
+        end
+      end
+    end
+  end
+
+
+  describe "guards" do
+    describe "#send_user_email?" do
+      context "when user does not receive email" do
+        let(:user) { double("user", receives_email?: false) }
+
+        it "returns false" do
+          expect(command.send(:send_user_email?)).to eq(false)
+        end
+      end
+
+      context "when user receives email" do
+        let(:user) { double("user", receives_email?: true) }
+
+        it "returns true" do
+          expect(command.send(:send_user_email?)).to eq(true)
+        end
+      end
+    end
+  end
+end

data/examples/spec/spec_helper.rb

@@ -0,0 +1,61 @@
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  # These two settings work together to allow you to limit a spec run
+  # to individual examples or groups you care about by tagging them with
+  # `:focus` metadata. When nothing is tagged with `:focus`, all examples
+  # get run.
+
+  config.filter_run :focus
+  config.run_all_when_everything_filtered = true
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  if config.files_to_run.one?
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = 'doc'
+  end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  config.profile_examples = 2
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  Kernel.srand config.seed
+
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  # config.expect_with :rspec do |expectations|
+  #   # Enable only the newer, non-monkey-patching expect syntax.
+  #   # For more details, see:
+  #   #   - http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax
+  #   expectations.syntax = :expect
+  # end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  #
+  # config.mock_with :rspec do |mocks|
+  #   # Enable only the newer, non-monkey-patching expect syntax.
+  #   # For more details, see:
+  #   #   - http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+  #   mocks.syntax = :expect
+
+  #   # Prevents you from mocking or stubbing a method that does not exist on
+  #   # a real object. This is generally recommended.
+  #   mocks.verify_partial_doubles = true
+  # end
+end

data/examples/spec/tiny_spec_helper.rb

@@ -0,0 +1,6 @@
+require 'spec_helper'
+
+%w(commands).each do |pattern|
+  path = File.expand_path("../../app/#{pattern}", __FILE__)
+  $:.push path unless $:.include?(path)
+end

data/lib/skywalker/command.rb

@@ -14,6 +14,42 @@ module Skywalker
     # Instantiates command, setting all arguments.
     ################################################################################
     def initialize(**args)
+      self.args = args
+      self.args.freeze
+
+      parse_arguments
+      validate_arguments!
+
+    end
+
+
+    attr_accessor :on_success,
+                  :on_failure,
+                  :error,
+                  :args
+
+
+    ################################################################################
+    # Ensure required keys are present.
+    ################################################################################
+    private def validate_arguments!
+      missing_args = required_args.map(&:to_s) - args.keys.map(&:to_s)
+
+      raise ArgumentError, "#{missing_args.join(", ")} required but not given" \
+        if missing_args.any?
+    end
+
+
+    ################################################################################
+    # Any required keys should go here as either strings or symbols.
+    ################################################################################
+    private def required_args
+      []
+    end
+
+
+
+    private def parse_arguments
       args.each_pair do |reader_method, value|
         writer_method = "#{reader_method}="
 
@@ -27,11 +63,6 @@ module Skywalker
     end
 
 
-    attr_accessor :on_success,
-                  :on_failure,
-                  :error
-
-
     ################################################################################
     # Call: runs the transaction and all operations.
     ################################################################################

data/lib/skywalker/version.rb

@@ -1,3 +1,3 @@
 module Skywalker
-  VERSION = "1.1.1"
+  VERSION = "1.2.0"
 end

data/spec/lib/skywalker/command_spec.rb

@@ -12,6 +12,11 @@ module Skywalker
 
 
     describe "instantiation" do
+      it "freezes the arguments given to it" do
+        command = Command.new(a_symbol: :my_symbol)
+        expect(command.args).to be_frozen
+      end
+
       it "accepts a variable list of arguments" do
         expect { Command.new(a_symbol: :my_symbol, a_string: "my string") }.not_to raise_error
       end
@@ -30,6 +35,16 @@ module Skywalker
         command = Command.new(a_symbol: :my_symbol)
         expect(command.a_symbol).to eq(:my_symbol)
       end
+
+      it "raises an error if an argument in its required_args is not present" do
+        allow_any_instance_of(Command).to receive(:required_args).and_return([:required_arg])
+        expect { Command.new }.to raise_error
+      end
+
+      it "does not raise an error if an argument in its required_args is present" do
+        allow_any_instance_of(Command).to receive(:required_args).and_return([:required_arg])
+        expect { Command.new(required_arg: :blah) }.not_to raise_error
+      end
     end
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: skywalker
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Rob Yurkowski
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-14 00:00:00.000000000 Z
+date: 2014-11-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -108,6 +108,12 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/Gemfile
+- examples/Gemfile.lock
+- examples/app/commands/create_group_command.rb
+- examples/spec/commands/create_group_command_spec.rb
+- examples/spec/spec_helper.rb
+- examples/spec/tiny_spec_helper.rb
 - lib/skywalker.rb
 - lib/skywalker/command.rb
 - lib/skywalker/version.rb