houston-core 0.7.0.beta3 → 0.7.0.beta4

data/templates/new-instance/config/main.rb

@@ -249,45 +249,18 @@ Houston.config do
   # ---------------------------------------------------------------------------
   #
   # Configure Houston to execute block of code when an event is triggered.
-  #
-  # Here is a list of many of Houston's events:
-  #
-  #   * antecedent:*:released   When a Ticket has been released, for each antecedent
-  #   * antecedent:*:resolved   When a Ticket has been resolved, for each antecedent
-  #   * antecedent:*:closed     When a Ticket has been closed, for each antecedent
-  #   * daemon:*:start          When a background thread (like the Scheduler or Slack) starts
-  #   * daemon:*:restart        When a background thread (like the Scheduler or Slack) is restarted
-  #   * daemon:*:stop           When a background thread (like the Scheduler or Slack) dies
-  #   * deploy:completed        When a deploy has been recorded
-  #   * hooks:*                 When a Web Hook as been triggered
-  #   * release:create          When a new Release has been created
-  #   * test_run:start          When the CI server has begun a build
-  #   * test_run:complete       When the CI server has completed a build
-  #   * testing_note:create     When a Testing Note has been created
-  #   * testing_note:update     When a Testing Note has been updated
-  #   * testing_note:save       When a Testing Note has been created or updated
-  #   * ticket:release          When a Ticket is mentioned in a Release
-  #   * task:released           When a commit mentioning a Task is released
-  #   * task:committed          When a commit mentioning a Task is pushed
-  #   * task:completed          When a Task is marked completed
-  #   * task:reopened           When a Task is marked reopened
-  #   * alert:create            When an Alert is created
-  #   * alert:*:create          When an Alert of a particular type is created
-  #   * alert:assign            When an Alert is assigned
-  #   * alert:*:assign          When an Alert of a particular type is assigned
-  #   * alert:deployed          When an Alert is deployed
-  #   * alert:*:deployed        When an Alert of a particular type is deployed
-
-  load "triggers/**/*"
-
-
-
-  # Background Jobs
+  # To see a complete list of events run `rake houston:events` at the command line.
+
+  load "events/**/*"
+
+
+
+  # Timers
   # ---------------------------------------------------------------------------
   #
   # Houston can be configured to run jobs at a variety of intervals.
 
-  load "jobs/**/*"
+  load "timers/**/*"
 
 
 

data/templates/new-module/lib/houston/%name%.rb

@@ -12,4 +12,17 @@ module Houston
     end
 
   end
+
+
+  # Register events that will be raised by this module
+  # register_events {{
+  #   "<%= name %>:create" => params("<%= name %>").desc("<%= camelized %> was created"),
+  #   "<%= name %>:update" => params("<%= name %>").desc("<%= camelized %> was updated")
+  # }}
+
+
+  # Add a link to Houston's global navigation
+  # add_navigation_renderer :<%= name %> do
+  #  render_nav_link "<%= camelized %>", Houston::<%= camelized %>::Engine.routes.url_helpers.<%= name %>_path, icon: "fa-thumbs-up"
+  # end
 end

data/test/integration/ci_integration_test.rb

@@ -8,7 +8,7 @@ class CIIntegrationTest < ActionDispatch::IntegrationTest
 
 
   context "Houston" do
-    should "trigger a build when the hooks:post_receive event is fired for a project that uses a CI server" do
+    should "trigger a build when the hooks:project:post_receive event is fired for a project that uses a CI server" do
       @project = create(:project, ci_server_name: "Mock")
 
       stub.instance_of(PostReceivePayload).commit { "63cd1ef" }
@@ -20,7 +20,7 @@ class CIIntegrationTest < ActionDispatch::IntegrationTest
       end
     end
 
-    should "do nothing when the hooks:post_receive event is fired for a project that does not use a CI server" do
+    should "do nothing when the hooks:project:post_receive event is fired for a project that does not use a CI server" do
       @project = create(:project, ci_server_name: "None")
 
       assert_no_difference "TestRun.count" do
@@ -127,7 +127,7 @@ class CIIntegrationTest < ActionDispatch::IntegrationTest
           stub(Object.new).success? { true }
         end
 
-        Houston.observer.fire "test_run:start", test_run
+        Houston.observer.fire "test_run:start", test_run: test_run
       end
 
       should "publish test results to GitHub" do
@@ -148,7 +148,7 @@ class CIIntegrationTest < ActionDispatch::IntegrationTest
           stub(Object.new).success? { true }
         end
 
-        Houston.observer.fire "test_run:complete", test_run
+        Houston.observer.fire "test_run:complete", test_run: test_run
       end
     end
 
@@ -162,7 +162,7 @@ class CIIntegrationTest < ActionDispatch::IntegrationTest
 
       mock(CodeClimate::CoverageReport).publish!(test_run)
 
-      Houston.observer.fire "test_run:complete", test_run
+      Houston.observer.fire "test_run:complete", test_run: test_run
     end
   end
 

data/test/integration/web_hook_test.rb

@@ -20,7 +20,7 @@ class WebHookTest < ActionDispatch::IntegrationTest
   end
 
   test "should trigger a project hook when it is defined" do
-    assert_triggered "hooks:whatever" do
+    assert_triggered "hooks:project:whatever" do
       post "/projects/#{project.slug}/hooks/whatever"
       assert_response :success
     end

data/test/test_helper.rb

@@ -85,6 +85,20 @@ class ActiveSupport::TestCase
 
 
 
+  def refute_raises(*exp)
+    msg = "#{exp.pop}.\n" if String === exp.last
+    exp << StandardError if exp.empty?
+
+    yield
+
+    pass
+  rescue *exp => e
+    exp = exp.first if exp.size == 1
+    flunk "#{msg}#{mu_pp(exp)} was not supposed to be raised"
+  end
+
+
+
   def assert_deep_equal(expected_value, actual_value)
     differences = differences_between_values(expected_value, actual_value)
     assert differences.none?, differences.join("\n")

data/test/unit/controllers/hooks_controller_test.rb

@@ -62,10 +62,10 @@ class HooksControllerTest < ActionController::TestCase
       assert_response :success
     end
 
-    should "trigger a `hooks:post_receive` event for the project" do
+    should "trigger a `hooks:project:post_receive` event for the project" do
       project = create(:project, slug: "public-repo")
       expected_payload = hash_including(github_push_event_payload.slice("before", "after"))
-      mock(Houston.observer).fire("hooks:post_receive", project, expected_payload)
+      mock(Houston.observer).fire("hooks:project:post_receive", project: project, params: expected_payload)
       post :github, hook: github_push_event_payload
     end
   end

data/test/unit/initializers/sync_commits_on_post_receive_test.rb

@@ -7,7 +7,7 @@ class SyncCommitsOnPostReceiveTest < ActiveSupport::TestCase
     should "sync commits for that project" do
       project = create(:project, version_control_name: "Mock")
       mock(project.commits).sync!
-      Houston.observer.fire "hooks:post_receive", project, {}
+      Houston.observer.fire "hooks:project:post_receive", project: project, params: {}
     end
   end
 

data/test/unit/models/actions_test.rb

@@ -0,0 +1,107 @@
+require "test_helper"
+
+class ActionsTest < ActiveSupport::TestCase
+
+  def setup
+    actions.define("test-action") { }
+    Action.delete_all
+  end
+
+
+  context "Actions#define" do
+    should "allow you to define the params an action requires" do
+      action = actions.redefine("test-action", %w{param1 param2}) { }
+      assert_equal "test-action", action.name
+      assert_equal %w{param1 param2}, action.required_params
+    end
+  end
+
+
+  context "Actions#run" do
+    should "raise if called with an argument that isn't a Hash" do
+      assert_raises ArgumentError do
+        run! 5
+      end
+    end
+
+    should "raise if any required params are absent" do
+      actions.redefine("test-action", %w{param1 param2}) { }
+      assert_raises Houston::Observer::MissingParamError do
+        run! param1: 1
+      end
+    end
+
+    should "allow unrequired params to be passed" do
+      actions.redefine("test-action", %w{param1}) { }
+      refute_raises Houston::Observer::MissingParamError do
+        run! param1: 1, param2: 2
+      end
+
+      assert_equal({param1: 1, param2: 2}, Action.last.params)
+    end
+
+    # We require that all params be serializable so that (1) actions can
+    # be recorded with all their state (and retried) and (2) the actions
+    # system can be "outsourced" to a background job system like Sidekiq
+    # if need be.
+    should "raise if any required param is unserializable" do
+      actions.redefine("test-action", %w{param1}) { }
+      unserializable_object = Class.new.new
+      assert_raises Houston::Serializer::UnserializableError do
+        run! param1: unserializable_object
+      end
+    end
+
+    should "record every invocation of the action" do
+      assert_difference "Action.count", +1 do
+        run!
+      end
+    end
+
+    should "record any exception raised by the action" do
+      actions.redefine("test-action") { raise "hell" }
+      run!
+      refute Action.last.succeeded?
+      error = Action.last.error
+      assert_kind_of Error, error
+      assert_equal "hell", error.message
+    end
+
+    should "record how an action was triggered" do
+      run!
+      assert_equal "manual", Action.first.trigger
+
+      run!({}, trigger: "at(5:00pm)")
+      assert_equal "at(5:00pm)", Action.first.trigger
+    end
+
+    should "record the params with which an action was triggered" do
+      run!
+      assert_equal({}, Action.first.params)
+
+      actions.redefine("test-action", [:example]) { }
+      run! example: 5
+      assert_equal({example: 5}, Action.first.params)
+    end
+
+    should "invoke actions in the context of their params" do
+      actions.redefine("test-action") do
+        assert respond_to?(:example)
+        assert_equal 5, example
+      end
+      run! example: 5
+    end
+  end
+
+
+private
+
+  def actions
+    @actions ||= Houston::Actions.new
+  end
+
+  def run!(params={}, options={})
+    actions.run "test-action", params, options.merge(async: false)
+  end
+
+end

data/test/unit/models/configuration_test.rb

@@ -0,0 +1,108 @@
+require "test_helper"
+
+class ConfigurationTest < ActiveSupport::TestCase
+
+
+  context "#action" do
+    should "define a new action" do
+      config.action("test-action") { }
+      assert config.actions.exists?("test-action")
+    end
+
+    should "raise if a block isn't given" do
+      assert_raises ArgumentError do
+        config.action("test-action")
+      end
+    end
+
+    should "raise if the action has already been defined" do
+      config.action("test-action") { }
+      assert_raises ArgumentError do
+        config.action("test-action") { }
+      end
+    end
+  end
+
+
+  context "#every" do
+    should "define an action and a timer that triggers it when you pass two arguments" do
+      assert_difference "config.triggers.count", +1 do
+        config.every("10m", "test-action") { }
+        assert config.actions.exists?("test-action")
+      end
+    end
+
+    should "define an action and a timer that triggers it when you pass a hash" do
+      assert_difference "config.triggers.count", +1 do
+        config.every("10m" => "test-action") { }
+        assert config.actions.exists?("test-action")
+      end
+    end
+
+    should "define an action with a made-up name (for now) when you don't specify an action" do
+      action = nil
+      assert_difference ["config.triggers.count", "config.actions.count"], +1 do
+        action = config.every("10m") { }
+      end
+      assert_match /10m:[a-f0-9]{8,}/, action.name
+    end
+
+    should "define a timer for an existing action" do
+      assert_difference "config.triggers.count", +1 do
+        config.action("test-action") { }
+        config.every "10m" => "test-action"
+      end
+    end
+
+    should "raise if the action requires any params" do
+      config.action("test-action", ["required_param"]) { }
+      assert_raises Houston::Observer::MissingParamError do
+        config.every "10m" => "test-action"
+      end
+    end
+  end
+
+
+  context "#on" do
+    should "define an action and an observer that triggers it when you pass two arguments" do
+      assert_difference "config.triggers.count", +1 do
+        config.on("hooks:example", "test-action") { }
+        assert config.actions.exists?("test-action")
+      end
+    end
+
+    should "define the action to require the params passed by the event" do
+      action = config.on("hooks:example", "test-action") { }
+      assert_equal %w{params}, action.required_params
+    end
+
+    should "define an action and an observer that triggers it when you pass a hash" do
+      assert_difference "config.triggers.count", +1 do
+        config.on("hooks:example" => "test-action") { }
+        assert config.actions.exists?("test-action")
+      end
+    end
+
+    should "define an observer for an existing action" do
+      assert_difference "config.triggers.count", +1 do
+        config.action("test-action") { }
+        config.on "hooks:example" => "test-action"
+      end
+    end
+
+    should "raise if the event doesn't supply the action's required params" do
+      config.action("test-action", ["required_param"]) { }
+      assert_raises Houston::Observer::MissingParamError do
+        config.on "hooks:example" => "test-action"
+      end
+    end
+  end
+
+
+private
+
+  def config
+    @config ||= Houston::Configuration.new
+  end
+
+end

data/test/unit/models/observer_test.rb

@@ -1,17 +1,101 @@
 require "test_helper"
 
+Houston.register_events {{
+  "test" => params("example").desc("For testing the observer"),
+  "test0" => desc("For testing the observer, takes 0 params")
+}}
+
 class ObserverTest < ActiveSupport::TestCase
 
 
   context "Houston.observer.once" do
     should "trigger a callback and then unregister it" do
       calls = 0
-      Houston.observer.once("test") { calls += 1 }
-      Houston.observer.fire "test"
-      Houston.observer.fire "test"
+      Houston.observer.once("test0") { calls += 1 }
+      Houston.observer.fire "test0"
+      Houston.observer.fire "test0"
       assert_equal 1, calls, "Expected the callback to be called only once"
     end
   end
 
 
+  context "Houston.observer.fire" do
+    should "raise if called with an argument that isn't a Hash" do
+      assert_raises ArgumentError do
+        Houston.observer.fire "test", 5
+      end
+    end
+
+    should "raise if called with more than one argument" do
+      assert_raises ArgumentError do
+        Houston.observer.fire "test", {}, 5
+      end
+    end
+
+    should "raise if the event isn't registered" do
+      assert_raises Houston::Observer::UnregisteredEventError do
+        Houston.observer.fire "test2"
+      end
+    end
+
+    should "raise if the event is triggered without a registered param" do
+      assert_raises Houston::Observer::MissingParamError do
+        Houston.observer.fire "test", {}
+      end
+    end
+
+    should "raise if the event is triggered with an unregistered param" do
+      assert_raises Houston::Observer::UnregisteredParamError do
+        Houston.observer.fire "test", {example: 5, counterexample: 1}
+      end
+    end
+
+    # We require that all params be serializable so that (1) actions can
+    # be recorded with all their state (and retried) and (2) the actions
+    # system can be "outsourced" to a background job system like Sidekiq
+    # if need be.
+    should "raise if the event is triggered with an unserializable param" do
+      unserializable_object = Class.new.new
+      assert_raises Houston::Serializer::UnserializableError do
+        Houston.observer.fire "test", {example: unserializable_object}
+      end
+    end
+
+    should "invoke callbacks with {} if called with no arguments" do
+      callback_args = :not_called
+      Houston.observer.on("test0") { |*args| callback_args = args }
+      Houston.observer.fire "test0"
+      assert_equal 1, callback_args.length
+      assert_equal [], callback_args[0].methods(false)
+    end
+
+    should "invoke callbacks with a copy of the params it was called with" do
+      params = {example: 5}
+      callback_params = :not_called
+      Houston.observer.on("test") { |params| callback_params = params }
+      Houston.observer.fire "test", params
+      assert_equal params, callback_params.to_h
+      refute_equal params.object_id, callback_params.to_h.object_id,
+        "Expected the observer to be invoked with a copy of the params; not the actual params itself"
+    end
+  end
+
+
+  context "callback params" do
+    should "be retrievable by array-style access" do
+      callback_params = :not_called
+      Houston.observer.on("test") { |params| callback_params = params }
+      Houston.observer.fire "test", example: 5
+      assert_equal 5, callback_params[:example]
+    end
+
+    should "be retrievable by method-style access" do
+      callback_params = :not_called
+      Houston.observer.on("test") { |params| callback_params = params }
+      Houston.observer.fire "test", example: 5
+      assert_equal 5, callback_params.example
+    end
+  end
+
+
 end

data/test/unit/models/persistent_trigger_test.rb

@@ -0,0 +1,94 @@
+require "test_helper"
+
+class PersistentTriggerTest < ActiveSupport::TestCase
+
+
+  context ".at" do
+    should "define a new trigger" do
+      trigger = PersistentTrigger.at("2:30pm", "test-action", example: 5)
+      assert_equal :at, trigger.type
+      assert_equal "2:30pm", trigger.value
+      assert_equal "test-action", trigger.action
+      assert_equal({example: 5}, trigger.params)
+    end
+  end
+
+
+  context "Validations:" do
+    should "require the action to exist" do
+      trigger = PersistentTrigger.new(action: "undefined-action").tap(&:validate)
+      assert_match /is not defined/, trigger.errors[:action].join
+    end
+
+    should "require the type to be one of :at, :every, or :on" do
+      trigger = PersistentTrigger.new
+
+      trigger.type = :at
+      refute trigger.tap(&:validate).errors[:type].any?
+
+      trigger.type = :every
+      refute trigger.tap(&:validate).errors[:type].any?
+
+      trigger.type = :on
+      refute trigger.tap(&:validate).errors[:type].any?
+
+      trigger.type = :nope
+      assert trigger.tap(&:validate).errors[:type].any?
+    end
+  end
+
+
+  context "#save!" do
+    setup do
+      Houston.config.actions.define("test-action") { }
+    end
+
+    teardown do
+      Houston.config.actions.undefine("test-action")
+    end
+
+    should "add the trigger to the database" do
+      assert_difference "PersistentTrigger.count", +1 do
+        PersistentTrigger.at("1:30pm", "test-action", example: 5).save!
+      end
+    end
+
+    should "register the trigger" do
+      assert_difference "Houston.config.triggers.count", +1 do
+        PersistentTrigger.at("2:30pm", "test-action", example: 5).save!
+      end
+    end
+  end
+
+
+  context ".load_all" do
+    setup do
+      PersistentTrigger.all.insert({
+        PersistentTrigger.column_for_attribute(:type) => "at",
+        PersistentTrigger.column_for_attribute(:value) => "9:00am",
+        PersistentTrigger.column_for_attribute(:action) => "test-action",
+        PersistentTrigger.column_for_attribute(:params) => {example: 5}
+      })
+    end
+
+    teardown do
+      Houston.config.triggers.clear
+    end
+
+    should "load all persisted triggers and register them" do
+    assert_equal 1, PersistentTrigger.count
+      assert_difference "Houston.config.triggers.count", +1 do
+        PersistentTrigger.load_all
+      end
+    end
+
+    should "be idempotent" do
+      PersistentTrigger.load_all
+      assert_no_difference "Houston.config.triggers.count" do
+        PersistentTrigger.load_all
+      end
+    end
+  end
+
+
+end

data/test/unit/models/serializer_test.rb

@@ -0,0 +1,80 @@
+require "test_helper"
+
+class SerializerTest < ActiveSupport::TestCase
+
+
+  should "serialize JSON literals conventionally" do
+    assert_serializes(5, to: '5')
+    assert_serializes("five", to: '"five"')
+    assert_serializes(false, to: 'false')
+    assert_serializes(nil, to: 'null')
+  end
+
+  should "let Oj serialize dates via iso8601" do
+    assert_equal '{"^O":"Date","iso8601":"2016-07-15"}',
+      dump(Date.new(2016, 7, 15))
+
+    assert_equal '{"^O":"DateTime","iso8601":"2016-07-15T01:30:59+00:00"}',
+      dump(DateTime.new(2016, 7, 15, 1, 30, 59.457))
+  end
+
+  should "let Oj serialize times" do
+    assert_equal '{"^t":1468587630.542999999e59}',
+      dump(Time.new(2016, 7, 15, 13, 1, 30, 59.457))
+  end
+
+  should "serialize Houston::ReadonlyHash like a hash" do
+    assert_equal '{":x":5}', dump(Houston::ReadonlyHash.new(x: 5))
+  end
+
+  should "serialize ActiveSupport::TimeWithZone like a DateTime" do
+    time = ActiveSupport::TimeZone["Mountain Time (US & Canada)"].now
+    assert_equal '{"^O":"DateTime","iso8601":"' + time.iso8601 + '"}', dump(time)
+  end
+
+  should "serialize ActiveRecord objects by their raw attributes" do
+    project = Project.create!(name: "Test", slug: "test")
+    assert_serializes(project,
+      like: /"class":"Project","attributes":{.*},"\^S":"Houston::ActiveRecordSerializer"/)
+  end
+
+  should "serialize objects that refer to ActiveRecord objects" do
+    project = Project.create!(name: "Test", slug: "test")
+    commit = Commit.new(project: project, message: "Commit Message")
+    antecedent = TicketAntecedent.new(commit, "Err", 45)
+    assert_serializes(antecedent,
+      like: /"ticket_or_commit":{"class":"Commit".*},"kind":"Err","id":45,"\^S":"Houston::TicketAntecedentSerializer"/)
+  end
+
+  should "work even when you set a value" do
+    project = Project.create!(name: "Test", slug: "test")
+    project.updated_at = 1.week.after(project.updated_at) # ActiveSupport::TimeWithZone
+    refute_match /"^o":"ActiveSupport::TimeWithZone"/, dump(x: project)
+  end
+
+
+private
+
+  def assert_serializes(object, options={})
+    serialized = dump(object)
+
+    if expectation = options[:to]
+      assert_equal expectation, serialized, "The object wasn't serialized as expected"
+    end
+
+    if expectation = options[:like]
+      assert_match expectation, serialized, "The object wasn't serialized as expected"
+    end
+
+    assert_equal object, load(serialized), "The object wasn't deserialized as expected"
+  end
+
+  def load(string)
+    Houston::Serializer.new.load(string)
+  end
+
+  def dump(object)
+    Houston::Serializer.new.dump(object)
+  end
+
+end