busybee 0.1.0 → 0.3.0

data/lib/busybee/testing/helpers.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
-require "securerandom"
+require "active_support"
+require "active_support/duration"
 require "base64"
-require "json"
+require "securerandom"
 require "busybee/grpc"
-require_relative "activated_job"
+require "busybee/serialization"
+require "busybee/testing/activated_job"
+require "busybee/testing/helpers/support"
+require "busybee/testing/helpers/execution"
 
 module Busybee
   module Testing
@@ -13,6 +17,9 @@ module Busybee
 
     # RSpec helper methods for testing BPMN workflows against Zeebe.
     module Helpers
+      extend Support
+      include Execution
+
       # Deploy a BPMN process file to Zeebe.
       #
       # By default, deploys the BPMN file as-is using its original process ID.
@@ -40,11 +47,11 @@ module Busybee
       #   result[:process_id] #=> "my-test-process"
       def deploy_process(path, uniquify: nil)
         if uniquify
-          process_id = uniquify == true ? unique_process_id : uniquify
-          bpmn_content = bpmn_with_unique_id(path, process_id)
+          process_id = uniquify == true ? Busybee::Testing::Helpers.unique_process_id : uniquify
+          bpmn_content = Busybee::Testing::Helpers.bpmn_with_unique_id(path, process_id)
         else
           bpmn_content = File.read(path)
-          process_id = extract_process_id(bpmn_content)
+          process_id = Busybee::Testing::Helpers.extract_process_id(bpmn_content)
         end
 
         resource = Busybee::GRPC::Resource.new(
@@ -73,7 +80,7 @@ module Busybee
         request = Busybee::GRPC::CreateProcessInstanceRequest.new(
           bpmnProcessId: process_name,
           version: -1,
-          variables: JSON.generate(variables)
+          variables: Busybee::Serialization.to_json(variables)
         )
 
         response = grpc_client.create_process_instance(request)
@@ -82,7 +89,7 @@ module Busybee
         yield @current_process_instance_key
       ensure
         if @current_process_instance_key
-          cancel_process_instance(@current_process_instance_key)
+          Busybee::Testing::Helpers.cancel_process_instance(@current_process_instance_key)
           @last_process_instance_key = @current_process_instance_key
           @current_process_instance_key = nil
         end
@@ -103,6 +110,31 @@ module Busybee
         @last_process_instance_key
       end
 
+      # Activate a job, yield it, and complete it on block exit.
+      # Must be called within a with_process_instance block.
+      #
+      # @param job_type [String] job type to activate
+      # @yield [ActivatedJob] the activated job
+      def with_activated_job_instance(job_type)
+        job = activate_job(job_type)
+        @current_job_key = job.key
+        yield job
+      ensure
+        if @current_job_key
+          begin
+            request = Busybee::GRPC::CompleteJobRequest.new(
+              jobKey: @current_job_key,
+              variables: "{}"
+            )
+            grpc_client.complete_job(request)
+          rescue ::GRPC::BadStatus
+            # Job may have already been completed/failed in the test block - ignore
+          ensure
+            @current_job_key = nil
+          end
+        end
+      end
+
       # Checks if Zeebe is available and responsive.
       #
       # This method attempts to connect to Zeebe and call the topology endpoint
@@ -114,17 +146,18 @@ module Busybee
         request = Busybee::GRPC::TopologyRequest.new
         grpc_client.topology(request, deadline: Time.now + timeout)
         true
-      rescue GRPC::Unavailable, GRPC::DeadlineExceeded, GRPC::Core::CallError, GRPC::Unauthenticated
+      rescue ::GRPC::Unavailable, ::GRPC::DeadlineExceeded, ::GRPC::Core::CallError, ::GRPC::Unauthenticated
         false
       end
 
       # Activate a single job of the given type.
       #
       # @param type [String] job type
+      # @param timeout [Integer, nil] request timeout in milliseconds (defaults to Busybee.default_job_request_timeout)
       # @return [ActivatedJob]
       # @raise [NoJobAvailable] if no job is available
-      def activate_job(type)
-        jobs = activate_jobs_raw(type, max_jobs: 1)
+      def activate_job(type, timeout: nil)
+        jobs = Busybee::Testing::Helpers.activate_jobs_raw(type, max_jobs: 1, timeout: timeout)
         raise NoJobAvailable, "No job of type '#{type}' available" if jobs.empty?
 
         ActivatedJob.new(jobs.first, client: grpc_client)
@@ -134,10 +167,11 @@ module Busybee
       #
       # @param type [String] job type
       # @param max_jobs [Integer] maximum number of jobs to activate
+      # @param timeout [Integer, nil] request timeout in milliseconds (defaults to Busybee.default_job_request_timeout)
       # @return [Enumerator<ActivatedJob>]
-      def activate_jobs(type, max_jobs:)
+      def activate_jobs(type, max_jobs:, timeout: nil)
         Enumerator.new do |yielder|
-          activate_jobs_raw(type, max_jobs: max_jobs).each do |raw_job|
+          Busybee::Testing::Helpers.activate_jobs_raw(type, max_jobs: max_jobs, timeout: timeout).each do |raw_job|
             yielder << ActivatedJob.new(raw_job, client: grpc_client)
           end
         end
@@ -153,7 +187,7 @@ module Busybee
         request = Busybee::GRPC::PublishMessageRequest.new(
           name: name,
           correlationKey: correlation_key,
-          variables: JSON.generate(variables),
+          variables: Busybee::Serialization.to_json(variables),
           timeToLive: ttl_ms
         )
         grpc_client.publish_message(request)
@@ -167,7 +201,7 @@ module Busybee
       def set_variables(scope_key, variables, local: true)
         request = Busybee::GRPC::SetVariablesRequest.new(
           elementInstanceKey: scope_key,
-          variables: JSON.generate(variables),
+          variables: Busybee::Serialization.to_json(variables),
           local: local
         )
         grpc_client.set_variables(request)
@@ -193,58 +227,14 @@ module Busybee
         end
       end
 
-      private
-
-      def unique_process_id
-        "test-process-#{SecureRandom.hex(6)}"
-      end
-
-      def extract_process_id(bpmn_content)
-        match = bpmn_content.match(/<bpmn:process id="([^"]+)"/)
-        match ? match[1] : nil
-      end
-
-      def bpmn_with_unique_id(bpmn_path, process_id)
-        bpmn_content = File.read(bpmn_path)
-        bpmn_content
-          .gsub(/(<bpmn:process id=")[^"]+/, "\\1#{process_id}")
-          # Possessive quantifiers (++, *+) prevent polynomial backtracking
-          .gsub(/(<bpmndi:BPMNPlane\s++[^>]*+bpmnElement=")[^"]++/, "\\1#{process_id}")
-      end
-
-      def cancel_process_instance(key)
-        request = Busybee::GRPC::CancelProcessInstanceRequest.new(
-          processInstanceKey: key
-        )
-        grpc_client.cancel_process_instance(request)
-        true
-      rescue ::GRPC::NotFound
-        # Process already completed, ignore
-        false
-      end
-
-      def activate_jobs_raw(type, max_jobs:)
-        worker = "#{type}-#{SecureRandom.hex(4)}"
-        request = Busybee::GRPC::ActivateJobsRequest.new(
-          type: type,
-          worker: worker,
-          timeout: 30_000,
-          maxJobsToActivate: max_jobs,
-          requestTimeout: Busybee::Testing.activate_request_timeout
-        )
-
-        jobs = []
-        grpc_client.activate_jobs(request).each do |response|
-          jobs.concat(response.jobs.to_a)
-        end
-        jobs
-      end
-
+      # Returns a GRPC client stub for direct Zeebe access.
+      # Uses Busybee.credential_type if set, autodetects from env vars otherwise.
+      #
+      # This is a public instance method that delegates to the module-level implementation.
+      #
+      # @return [Busybee::GRPC::Gateway::Stub]
       def grpc_client
-        @grpc_client ||= Busybee::GRPC::Gateway::Stub.new(
-          Busybee::Testing.address,
-          :this_channel_is_insecure
-        )
+        Busybee::Testing::Helpers.grpc_client
       end
     end
   end

data/lib/busybee/testing/matchers/complete_job.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+
+# Asserts that a worker completes the job successfully.
+#
+# Checks that the job ends in +:complete+ status. Optionally checks
+# the return value of +perform+ for expected variables via +with_vars+.
+#
+# @example Basic usage
+#   job = build_test_job(variables: { order_id: 1 })
+#   expect(MyWorker).to complete_job(job)
+#
+# @example With expected return variables
+#   expect(MyWorker).to complete_job(job).with_vars(status: "done")
+#
+RSpec::Matchers.define :complete_job do |job|
+  match do |worker_class|
+    @result = execute_worker(worker_class, job: job)
+    return false unless job.complete?
+
+    if @expected_vars
+      if @result.is_a?(Hash)
+        values_match?(@expected_vars, @result)
+      else
+        @expected_vars == {}
+      end
+    else
+      true
+    end
+  rescue StandardError => e
+    @raised_error = e
+    false
+  end
+
+  chain :with_vars do |expected|
+    @expected_vars = expected
+  end
+
+  chain :with_no_vars do
+    @expected_vars = {}
+  end
+
+  failure_message do
+    if @raised_error
+      "expected #{actual} to complete the job, but it raised " \
+        "#{@raised_error.class}: #{@raised_error.message}"
+    elsif !job.complete?
+      "expected job to be complete, but was #{job.status}"
+    else
+      "expected result to match #{@expected_vars.inspect}, " \
+        "got #{@result.inspect}"
+    end
+  end
+end

data/lib/busybee/testing/matchers/fail_job.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+
+# Asserts that a worker fails the job with an optional error match.
+#
+# Accepts the same argument forms as RSpec's +raise_error+:
+#   with_error(ErrorClass)
+#   with_error(ErrorClass, "exact message")
+#   with_error(ErrorClass, /message pattern/)
+#   with_error("exact message")
+#   with_error(/message pattern/)
+#
+# @example Basic usage
+#   job = build_test_job(variables: { order_id: 999 })
+#   expect(MyWorker).to fail_job(job)
+#
+# @example With error class
+#   expect(MyWorker).to fail_job(job).with_error(ActiveRecord::RecordNotFound)
+#
+# @example With error class and message
+#   expect(MyWorker).to fail_job(job).with_error(ArgumentError, /invalid/)
+#
+RSpec::Matchers.define :fail_job do |job|
+  match do |worker_class|
+    execute_worker(worker_class, job: job)
+    @no_error = true
+    false
+  rescue StandardError => e
+    @raised_error = e
+    job.failed? && error_matches?(e)
+  end
+
+  chain :with_error do |expected_error_or_message, expected_message = nil|
+    case expected_error_or_message
+    when String, Regexp
+      @expected_error = StandardError
+      @expected_message = expected_error_or_message
+    else
+      @expected_error = expected_error_or_message
+      @expected_message = expected_message
+    end
+  end
+
+  def error_matches?(error)
+    return true unless @expected_error
+
+    class_matches = @expected_error === error # rubocop:disable Style/CaseEquality
+    return false unless class_matches
+    return true unless @expected_message
+
+    case @expected_message
+    when Regexp then error.message.match?(@expected_message)
+    else error.message == @expected_message.to_s
+    end
+  end
+
+  failure_message do
+    if @no_error
+      "expected #{actual} to fail the job, but it completed successfully"
+    elsif !job.failed?
+      "expected job to be failed, but was #{job.status}"
+    else
+      "expected error matching #{expected_description}, " \
+        "got #{@raised_error.class}: #{@raised_error.message}"
+    end
+  end
+
+  def expected_description
+    parts = []
+    parts << @expected_error.inspect if @expected_error
+    parts << @expected_message.inspect if @expected_message
+    parts.join(" with message ")
+  end
+end

data/lib/busybee/testing/matchers/have_activated.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require "rspec/expectations"
-require_relative "../activated_job"
+require "busybee/testing/activated_job"
 
 RSpec::Matchers.define :have_activated do |job_type|
   match do |helper|

data/lib/busybee/testing/matchers/have_available_jobs.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+
+# Matcher to check if jobs are available for activation.
+#
+# This matcher is designed to work with blocks that call `activate_job` or similar methods
+# that raise `Busybee::Testing::NoJobAvailable` when no jobs are found.
+#
+# @example Check that jobs are available
+#   expect { activate_job("process-order") }.to have_available_jobs
+#
+# @example Check that NO jobs are available (most common usage)
+#   expect { activate_job("process-order") }.not_to have_available_jobs
+#
+RSpec::Matchers.define :have_available_jobs do
+  supports_block_expectations
+
+  match do |block|
+    block.call
+    @job_found = true
+    true
+  rescue Busybee::Testing::NoJobAvailable
+    @job_found = false
+    false
+  rescue StandardError => e
+    @unexpected_error = e
+    false
+  end
+
+  failure_message do
+    if @unexpected_error
+      "expected jobs to be available, but got #{@unexpected_error.class}: #{@unexpected_error.message}"
+    else
+      "expected jobs to be available, but no jobs were found (Busybee::Testing::NoJobAvailable raised)"
+    end
+  end
+
+  failure_message_when_negated do
+    "expected no jobs to be available, but a job was activated"
+  end
+end
+
+RSpec::Matchers.alias_matcher :have_an_available_job, :have_available_jobs

data/lib/busybee/testing/matchers/throw_bpmn_error_on.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+
+# Asserts that a worker throws a BPMN error on the job.
+#
+# Captures the error code and message passed to the stub client's
+# +throw_bpmn_error+ call for optional verification via +with_code+.
+#
+# @example Basic usage
+#   job = build_test_job(variables: { order_id: 999 })
+#   expect(MyWorker).to throw_bpmn_error_on(job)
+#
+# @example With error code
+#   expect(MyWorker).to throw_bpmn_error_on(job).with_code(:not_found)
+#
+# @example With error code and message
+#   expect(MyWorker).to throw_bpmn_error_on(job).with_code(:not_found, message: /missing/)
+#
+RSpec::Matchers.define :throw_bpmn_error_on do |job|
+  match do |worker_class|
+    client = job.instance_variable_get(:@client)
+    allow(client).to receive(:throw_bpmn_error) do |_key, code, message:|
+      @actual_code = code
+      @actual_message = message
+    end
+
+    execute_worker(worker_class, job: job)
+    return false unless job.error?
+
+    code_matches? && message_matches?
+  rescue StandardError => e
+    @raised_error = e
+    false
+  end
+
+  chain :with_code do |expected_code, opts = {}|
+    @expected_code = case expected_code
+                     when Symbol then expected_code.to_s.upcase
+                     when Class then expected_code.name.gsub("::", "_").underscore.upcase
+                     else expected_code
+                     end
+    @expected_message = opts[:message]
+  end
+
+  def code_matches?
+    return true unless @expected_code
+
+    values_match?(@expected_code, @actual_code)
+  end
+
+  def message_matches?
+    return true unless @expected_message
+
+    values_match?(@expected_message, @actual_message)
+  end
+
+  failure_message do
+    if @raised_error
+      "expected #{actual} to throw a BPMN error, but it raised " \
+        "#{@raised_error.class}: #{@raised_error.message}"
+    elsif !job.error?
+      "expected job to be error, but was #{job.status}"
+    elsif @expected_code && !code_matches?
+      "expected BPMN error code #{@expected_code.inspect}, " \
+        "got #{@actual_code.inspect}"
+    else
+      "expected BPMN error message #{@expected_message.inspect}, " \
+        "got #{@actual_message.inspect}"
+    end
+  end
+end

data/lib/busybee/testing.rb

@@ -3,40 +3,8 @@
 require "busybee/grpc"
 
 module Busybee
-  # Testing support for BPMN workflows with RSpec.
-  #
-  # @example Configuration
-  #   Busybee::Testing.configure do |config|
-  #     config.address = "localhost:26500"
-  #     config.username = "demo"
-  #     config.password = "demo"
-  #     config.activate_request_timeout = 2000
-  #   end
-  #
+  # Testing support for BPMN workflows and workers with RSpec.
   module Testing
-    class << self
-      attr_writer :address, :username, :password, :activate_request_timeout
-
-      def configure
-        yield self
-      end
-
-      def address
-        @address || ENV["ZEEBE_ADDRESS"] || "localhost:26500"
-      end
-
-      def username
-        @username || ENV["ZEEBE_USERNAME"] || "demo"
-      end
-
-      def password
-        @password || ENV["ZEEBE_PASSWORD"] || "demo"
-      end
-
-      def activate_request_timeout
-        @activate_request_timeout || 1000
-      end
-    end
   end
 end
 
@@ -47,6 +15,10 @@ if defined?(RSpec)
   require "busybee/testing/matchers/have_received_variables"
   require "busybee/testing/matchers/have_received_headers"
   require "busybee/testing/matchers/have_activated"
+  require "busybee/testing/matchers/have_available_jobs"
+  require "busybee/testing/matchers/fail_job"
+  require "busybee/testing/matchers/complete_job"
+  require "busybee/testing/matchers/throw_bpmn_error_on"
 
   RSpec.configure do |config|
     config.include Busybee::Testing::Helpers

data/lib/busybee/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Busybee
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end