plan_my_stuff 0.1.0 → 1.0.0

data/lib/plan_my_stuff/test_helpers.rb

@@ -3,17 +3,25 @@
 require 'plan_my_stuff'
 
 module PlanMyStuff
-  # Test support for consuming apps. Provides:
+  # Test support for apps that *consume* PlanMyStuff. Provides:
   # - `PlanMyStuff.test_mode!` to stub all API calls
   # - Factory-style builders: `build_issue`, `build_comment`, `build_project`
   # - RSpec matchers: `expect_pms_issue_created`, `expect_pms_comment_created`, `expect_pms_item_moved`
   #
-  # Usage:
+  # Usage (in a consuming Rails app):
   #   require 'plan_my_stuff/test_helpers'
   #
   #   RSpec.configure do |config|
   #     config.include PlanMyStuff::TestHelpers
   #   end
+  #
+  # Not the harness for PlanMyStuff's own unit specs. Gem-internal specs go
+  # through VCR cassettes against a real GitHub sandbox (see `spec/support/vcr.rb`
+  # and the `:pms_vcr_configured` shared context). Calling `PlanMyStuff.test_mode!`
+  # inside the gem would monkey-patch the very class methods the cassettes were
+  # recorded against, defeating the VCR coverage. The builder utilities
+  # (`build_issue`, `build_comment`, `build_project`, `stub_approvals`) are safe
+  # to use inside the gem as plain factories - they don't replace any methods.
   module TestHelpers
     # Recorded actions during test mode, keyed by type:
     #   :issue_created, :comment_created, :item_moved
@@ -58,8 +66,8 @@ module PlanMyStuff
           custom_fields: {},
         }.merge(metadata))
 
-        issue.instance_variable_set(:@metadata, issue_metadata)
-        issue.instance_variable_set(:@persisted, true)
+        issue.metadata = issue_metadata
+        issue.__send__(:persisted!)
 
         body_comment = build_comment(
           body: body,
@@ -98,8 +106,8 @@ module PlanMyStuff
           custom_fields: {},
         }.merge(metadata))
 
-        comment.instance_variable_set(:@metadata, comment_metadata)
-        comment.instance_variable_set(:@persisted, true)
+        comment.metadata = comment_metadata
+        comment.__send__(:persisted!)
         comment
       end
 
@@ -124,7 +132,7 @@ module PlanMyStuff
           statuses: status_options,
           fields: [{ id: 'field_status', name: 'Status', options: status_options }],
         )
-        project.instance_variable_set(:@persisted, true)
+        project.__send__(:persisted!)
 
         project.items = items.map do |item_hash|
           PlanMyStuff::ProjectItem.build(
@@ -143,6 +151,54 @@ module PlanMyStuff
 
         project
       end
+
+      # Sets approvals on an in-memory +Issue+ without hitting the API.
+      # Accepts user objects or integer user_ids.
+      #
+      # @param issue [PlanMyStuff::Issue]
+      # @param approved [Array<Object, Integer>] approvers who have approved
+      # @param pending [Array<Object, Integer>] approvers who have not yet approved
+      #
+      # @return [Array<PlanMyStuff::Approval>] the records written to +issue.metadata.approvals+
+      #
+      def stub_approvals(issue, approved: [], pending: [])
+        records =
+          pending.map { |u| PlanMyStuff::Approval.new(user_id: extract_user_id(u), status: 'pending') } +
+          approved.map do |u|
+            PlanMyStuff::Approval.new(user_id: extract_user_id(u), status: 'approved', approved_at: Time.current)
+          end
+        issue.metadata.approvals = records
+        records
+      end
+
+      # @return [Integer]
+      def extract_user_id(user)
+        user.is_a?(Integer) ? user : PlanMyStuff::UserResolver.user_id(user)
+      end
+    end
+
+    # Captures +*.plan_my_stuff+ +ActiveSupport::Notifications+ events fired
+    # inside the given block. Lets consuming apps assert that their code
+    # triggers gem events without threading subscriptions through every spec.
+    #
+    # Usage:
+    #
+    #   events = PlanMyStuff::TestHelpers::Notifications.capture do
+    #     PlanMyStuff::Issue.create!(...)
+    #   end
+    #   events.first[:name]    # => "issue_created.plan_my_stuff"
+    #   events.first[:payload] # => { issue:, user:, timestamp:, ... }
+    #
+    module Notifications
+      module_function
+
+      # @return [Array<Hash>] events as +{ name: String, payload: Hash }+
+      def capture(&)
+        events = []
+        callback = -> (name, _start, _finish, _id, payload) { events << { name: name, payload: payload } }
+        ActiveSupport::Notifications.subscribed(callback, /\.plan_my_stuff\z/, &)
+        events
+      end
     end
 
     # RSpec matchers included when the module is included in a test config.
@@ -218,6 +274,36 @@ module PlanMyStuff
       expect_pms_action(:item_assigned, 'item to be assigned', **filters)
     end
 
+    # @param filters [Hash] attribute filters (e.g. item_id:)
+    def expect_pms_pipeline_taken(**filters)
+      expect_pms_action(:pipeline_started, 'pipeline item to be taken', **filters)
+    end
+
+    # @param filters [Hash] attribute filters (e.g. item_id:)
+    def expect_pms_pipeline_in_review(**filters)
+      expect_pms_action(:pipeline_in_review, 'pipeline item marked in review', **filters)
+    end
+
+    # @param filters [Hash] attribute filters (e.g. item_id:)
+    def expect_pms_pipeline_testing(**filters)
+      expect_pms_action(:pipeline_testing, 'pipeline item moved to testing', **filters)
+    end
+
+    # @param filters [Hash] attribute filters (e.g. item_id:)
+    def expect_pms_pipeline_ready_for_release(**filters)
+      expect_pms_action(:pipeline_ready_for_release, 'pipeline item marked ready for release', **filters)
+    end
+
+    # @param filters [Hash] attribute filters (e.g. project_number:, commit_sha:)
+    def expect_pms_pipeline_deployment_started(**filters)
+      expect_pms_action(:pipeline_deployment_started, 'pipeline deployment started', **filters)
+    end
+
+    # @param filters [Hash] attribute filters (e.g. item_id:, deployment_id:)
+    def expect_pms_pipeline_deployment_completed(**filters)
+      expect_pms_action(:pipeline_deployment_completed, 'pipeline deployment completed', **filters)
+    end
+
     private
 
       # @return [void]
@@ -228,7 +314,7 @@ module PlanMyStuff
 
         expect(match).to(
           be_truthy,
-          "Expected PMS #{description} with #{filters.inspect}, " \
+          "Expected PlanMyStuff #{description} with #{filters.inspect}, " \
             "but recorded actions were: #{format_actions(type)}",
         )
       end
@@ -257,7 +343,7 @@ module PlanMyStuff
     # @return [void]
     #
     def test_mode!
-      TestHelpers.recorded_actions = []
+      PlanMyStuff::TestHelpers.recorded_actions = []
       return if @_test_mode
 
       @_test_mode_originals = {}
@@ -265,10 +351,11 @@ module PlanMyStuff
       stub_comment_class_methods!
       stub_project_class_methods!
       stub_project_item_class_methods!
+      stub_pipeline_methods!
       @_test_mode = true
     end
 
-    # Restores original class methods overwritten by test_mode!
+    # Restores original class / instance methods overwritten by test_mode!
     #
     # @return [void]
     #
@@ -276,19 +363,24 @@ module PlanMyStuff
       return unless @_test_mode
 
       (@_test_mode_originals || {}).each do |klass, methods|
-        methods.each do |name, original|
-          klass.define_singleton_method(name, original)
+        methods.each do |key, original|
+          kind, name = key
+          if kind == :instance
+            klass.define_method(name, original)
+          else
+            klass.define_singleton_method(name, original)
+          end
         end
       end
 
       @_test_mode_originals = nil
       @_test_mode = false
-      TestHelpers.recorded_actions = []
+      PlanMyStuff::TestHelpers.recorded_actions = []
     end
 
     private
 
-      # Saves the original method so it can be restored by exit_test_mode!
+      # Saves the original class method so it can be restored by exit_test_mode!
       #
       # @param klass [Class]
       # @param method_name [Symbol]
@@ -297,13 +389,26 @@ module PlanMyStuff
       #
       def save_original(klass, method_name)
         @_test_mode_originals[klass] ||= {}
-        @_test_mode_originals[klass][method_name] = klass.method(method_name)
+        @_test_mode_originals[klass][[:class, method_name]] = klass.method(method_name)
+      end
+
+      # Saves the original instance method so it can be restored by exit_test_mode!
+      #
+      # @param klass [Class]
+      # @param method_name [Symbol]
+      #
+      # @return [void]
+      #
+      def save_instance_original(klass, method_name)
+        @_test_mode_originals[klass] ||= {}
+        @_test_mode_originals[klass][[:instance, method_name]] = klass.instance_method(method_name)
       end
 
       # @return [void]
       def stub_issue_class_methods!
         issue_mod = PlanMyStuff::Issue
-        %i[create! find list update! add_viewers remove_viewers].each { |m| save_original(issue_mod, m) }
+        %i[create! find list update!].each { |m| save_original(issue_mod, m) }
+        %i[add_viewers! remove_viewers!].each { |m| save_instance_original(issue_mod, m) }
 
         issue_mod.define_singleton_method(:create!) do |**params|
           PlanMyStuff::TestHelpers.recorded_actions << {
@@ -316,10 +421,17 @@ module PlanMyStuff
             },
           }
 
+          resolved_repo =
+            if params[:repo]
+              PlanMyStuff::Repo.resolve!(params[:repo]).full_name
+            else
+              'TestOrg/TestRepo'
+            end
+
           PlanMyStuff::TestHelpers.build_issue(
             title: params[:title],
             body: params[:body],
-            repo: params[:repo]&.to_s || 'TestOrg/TestRepo',
+            repo: resolved_repo,
             labels: params[:labels] || [],
           )
         end
@@ -330,7 +442,8 @@ module PlanMyStuff
             params: { number: number, repo: repo },
           }
 
-          PlanMyStuff::TestHelpers.build_issue(number: number, repo: repo&.to_s || 'TestOrg/TestRepo')
+          resolved_repo = repo ? PlanMyStuff::Repo.resolve!(repo).full_name : 'TestOrg/TestRepo'
+          PlanMyStuff::TestHelpers.build_issue(number: number, repo: resolved_repo)
         end
 
         issue_mod.define_singleton_method(:list) do |**params|
@@ -351,19 +464,19 @@ module PlanMyStuff
           nil
         end
 
-        issue_mod.define_singleton_method(:add_viewers) do |**params|
+        issue_mod.define_method(:add_viewers!) do |user_ids:, user: nil|
           PlanMyStuff::TestHelpers.recorded_actions << {
             type: :viewers_added,
-            params: params,
+            params: { number: number, repo: repo&.to_s, user_ids: Array.wrap(user_ids), user: user },
           }
 
           nil
         end
 
-        issue_mod.define_singleton_method(:remove_viewers) do |**params|
+        issue_mod.define_method(:remove_viewers!) do |user_ids:, user: nil|
           PlanMyStuff::TestHelpers.recorded_actions << {
             type: :viewers_removed,
-            params: params,
+            params: { number: number, repo: repo&.to_s, user_ids: Array.wrap(user_ids), user: user },
           }
 
           nil
@@ -443,9 +556,9 @@ module PlanMyStuff
       # @return [void]
       def stub_project_item_class_methods!
         item_mod = PlanMyStuff::ProjectItem
-        %i[move_item create! assign].each { |m| save_original(item_mod, m) }
+        %i[move_item! create! assign!].each { |m| save_original(item_mod, m) }
 
-        item_mod.define_singleton_method(:move_item) do |**params|
+        item_mod.define_singleton_method(:move_item!) do |**params|
           PlanMyStuff::TestHelpers.recorded_actions << {
             type: :item_moved,
             params: {
@@ -484,7 +597,7 @@ module PlanMyStuff
           )
         end
 
-        item_mod.define_singleton_method(:assign) do |**params|
+        item_mod.define_singleton_method(:assign!) do |**params|
           PlanMyStuff::TestHelpers.recorded_actions << {
             type: :item_assigned,
             params: {
@@ -497,5 +610,132 @@ module PlanMyStuff
           nil
         end
       end
+
+      # @return [void]
+      def stub_pipeline_methods!
+        pipeline_mod = PlanMyStuff::Pipeline
+        %i[
+          take! mark_in_review! request_testing! mark_ready_for_release! start_deployment! complete_deployment!
+        ].each { |m| save_original(pipeline_mod, m) }
+
+        pipeline_mod.define_singleton_method(:take!) do |project_item, user: nil|
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :pipeline_started,
+            params: {
+              item_id: project_item.respond_to?(:id) ? project_item.id : nil,
+              issue_number: project_item.respond_to?(:number) ? project_item.number : nil,
+              user: user,
+            },
+          }
+
+          nil
+        end
+
+        pipeline_mod.define_singleton_method(:mark_in_review!) do |project_item|
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :pipeline_in_review,
+            params: {
+              item_id: project_item.respond_to?(:id) ? project_item.id : nil,
+              issue_number: project_item.respond_to?(:number) ? project_item.number : nil,
+            },
+          }
+
+          nil
+        end
+
+        pipeline_mod.define_singleton_method(:request_testing!) do |project_item, user: nil|
+          field_name = PlanMyStuff.configuration.pipeline_testing_field_name
+          value = PlanMyStuff.configuration.pipeline_testing_values.fetch(:active)
+
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :pipeline_testing,
+            params: {
+              item_id: project_item.respond_to?(:id) ? project_item.id : nil,
+              issue_number: project_item.respond_to?(:number) ? project_item.number : nil,
+              field_name: field_name,
+              value: value,
+              user: user,
+            },
+          }
+
+          if project_item.respond_to?(:field_values) && project_item.field_values.is_a?(Hash)
+            project_item.field_values[field_name] = value
+          end
+
+          nil
+        end
+
+        pipeline_mod.define_singleton_method(:mark_ready_for_release!) do |project_item|
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :pipeline_ready_for_release,
+            params: {
+              item_id: project_item.respond_to?(:id) ? project_item.id : nil,
+              issue_number: project_item.respond_to?(:number) ? project_item.number : nil,
+            },
+          }
+
+          nil
+        end
+
+        pipeline_mod.define_singleton_method(:start_deployment!) do |project_number: nil, commit_sha: nil|
+          number =
+            project_number || PlanMyStuff.configuration.pipeline_project_number ||
+            PlanMyStuff.configuration.default_project_number
+
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :pipeline_deployment_started,
+            params: {
+              project_number: number,
+              commit_sha: commit_sha,
+            },
+          }
+
+          []
+        end
+
+        pipeline_mod.define_singleton_method(:complete_deployment!) do |project_item, deployment_id: nil|
+          PlanMyStuff::TestHelpers.recorded_actions << {
+            type: :pipeline_deployment_completed,
+            params: {
+              item_id: project_item.respond_to?(:id) ? project_item.id : nil,
+              issue_number: project_item.respond_to?(:number) ? project_item.number : nil,
+              deployment_id: deployment_id,
+            },
+          }
+
+          nil
+        end
+      end
+  end
+end
+
+if defined?(RSpec::Matchers)
+  # Asserts that a +<name>.plan_my_stuff+ event was fired inside the block.
+  # Chain +.with(key: value, ...)+ to match on a payload subset.
+  #
+  #   expect { Issue.create!(...) }.to(have_fired_event('issue_created.plan_my_stuff'))
+  #   expect { Issue.create!(...) }.to(have_fired_event('issue_created.plan_my_stuff').with(user: alice))
+  #
+  RSpec::Matchers.define(:have_fired_event) do |event_name|
+    supports_block_expectations
+
+    chain(:with) { |expected_payload| @expected_payload = expected_payload }
+
+    match do |block|
+      events = PlanMyStuff::TestHelpers::Notifications.capture(&block)
+      matching = events.select { |e| e[:name] == event_name }
+      @fired_events = events
+      next false if matching.empty?
+      next true if @expected_payload.nil?
+
+      matching.any? { |e| @expected_payload.all? { |k, v| e[:payload][k] == v } }
+    end
+
+    failure_message do
+      fired_names = @fired_events.pluck(:name)
+      base = "expected block to fire #{event_name.inspect}"
+      base += " with payload including #{@expected_payload.inspect}" if @expected_payload
+      "#{base}, but fired: #{fired_names.empty? ? '(none)' : fired_names.inspect}"
+    end
   end
 end