zeebe_bpmn_rspec 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ee557a1aed97212da2a198eafd8238859e12499f32e8ddf24d97d5240c83c36
-  data.tar.gz: 0105ee8a65e00fbab192cf6f76710e43973bec36324b3defcc4f83882db833ca
+  metadata.gz: 28a2727e47b273a44521d2f74ecf03c97ee84c22ccd9c2d16cd70eb97e2a2b3f
+  data.tar.gz: '065783a4f62345e2fa7b7a121d090153bdbf67e3b683c2156c40e74238e862b6'
 SHA512:
-  metadata.gz: 978a61f885179d519ede6340a283b93f9c36e1d712c1279629500732afe01a9f9ac7483a484c17d99356bcebb0258fb04f65771492a6d2b6774cd9be64454f1b
-  data.tar.gz: 6f235e5995f75fd04b7996708bb8a23d81cbb1b7bf1ecd8ebea46a5fba78fa1e5c60f8ab1e305e263d0e16e7ac2005dad78dfdf5e684528ff3cdf3343a2f9c2e
+  metadata.gz: 50711d2a17a5141d4734e5bcc40d10c73b7a43e369561ad74cbdb60de3d6631f804f175f777aed911a369d5aeaf4be619772d330d7c54ab26b8b24bc1d033f24
+  data.tar.gz: f81b79f8603d00b9c8714a85dd6d927e3e13c4b14d8f204e5dd0eeb172a4c04952e90f8d7419d20a788647125c9e362bb3ed81cd116cd6320414c2ebc2436503

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # zeebe_bpmn_rspec
 
+## v0.5.0
+- Require Ruby 2.6 or later.
+- Require `worker` to be specified when activating a job. This argument is
+  defaulted but can no longer be specified as blank.
+
+## v0.4.1
+- Allow `with_workflow_instance` to be called without a block.
+- Allow `worker` to be specified when activating a job.
+- Expose `workflow_instance_key` for activated jobs.
+
+## v0.4.0
+- Add `ttl_ms` option for `publish_message`.
+- Add `update_retries` method to `ActivatedJob` class.
+- Add `set_variables` helper.
+- Add support for `:fetch_variables` option when activating jobs.
+
+## v0.3.1
+- Use consistent activate request timeout.
+- Provide a better error when a job is not activated.
+
+## v0.3.0
+- Add custom matchers, `have_variables`, `have_headers`, and `have_activated`.
+
 ## v0.2.0
 - Add `retries` option to `ActivatedJob#and_fail`.
 - Add method aliases: `and_complete` (`complete`), `and_fail` (`fail`), `and_throw_error` (`throw_error`).

data/README.md

@@ -39,6 +39,8 @@ end
 
 The gem adds the following helper methods to RSpec.
 
+The gem also defines [Custom Matchers](#custom-matchers).
+
 ### Deploy Workflow
 
 The `deploy_workflow` method requires a path to a BPMN file and deploys it to Zeebe. There is no support for
@@ -155,6 +157,16 @@ job = activate_job("my_job")
 job.fail(retries: 1)
 ```
 
+#### Update Retries
+
+The retries for a job can also be modified using the `update_retries` method:
+
+```ruby
+job = activate_job("my_job")
+
+job.update_retries(3)
+```
+
 #### Throw Error
 
 The `and_throw_error` (also aliased as `throw_error`) method can be used to throw an error for a job. The error code is required and an
@@ -217,6 +229,131 @@ publish_message("message_name", correlation_key: expected_value,
                 variables: { foo: "bar" })
 ```
 
+The time-to-live (in milliseconds) cna also be specified for a message.
+It defaults to 5000 milliseconds if unspecified.
+
+```ruby
+publish_message("message_name", correlation_key: expected_value, ttl_ms: 1000)
+```
+
+### Set Variables
+
+The `set_variables` method can be used to set variables for a specified
+scope in Zeebe:
+
+```ruby
+# workflow_instance_key is a method that returns the key for the current workflow instance
+set_variables(workflow_instance_key, { foo: "bar" })
+```
+
+An activated job can be used to determine the key for the task that it is associated with:
+
+```ruby
+job = job_with_type("my_type")
+set_variables(job.task_key, { foo: "baz"})
+```
+
+Variables default to being local to the scope on which they are set. This
+can be overridden by specifying the `:local` option:
+
+```ruby
+set_variables(job.task_key, { foo: "baz"}, local: false)
+```
+
+### Custom Matchers
+
+In addition to the helpers documented above, this gem defines custom RSpec matchers to provide a more typical
+experience of expectations and matchers.
+
+#### expect_job_of_type
+
+The `expect_job_of_type` helper is a convenient wrapper to activate a job and set an expectation target.
+
+```ruby
+expect_job_of_type("my_type")
+```
+
+Similar to the `activate_job` helper, it activates a job and wraps the result in an `ActivatedJob` object.
+That object is then passed to `expect()`. Unlike `activate_job`, this helper does not raise if there is no job activated.
+
+This is equivalent to `expect(job_with_type("my_type")` or `expect(activate_job("my_type", validate: false))`.
+
+`expect_job_of_type` is expected to be used with the matchers below.
+
+#### have_activated
+
+The `have_activated` matcher checks that the target represents an activated job. It will raise an error if no job
+was activated.
+
+```ruby
+expect_job_of_type("my_type").to have_activated
+```
+
+Various additional methods can be chained on the `have_activated` matcher.
+
+The `with_variables` method can be used to check the input variables that the job was activated with:
+
+```ruby
+expect_job_of_type("my_type").to have_activated.with_variables(user_id: 123)
+```
+
+The `with_headers` method can be used to check the headers that the job was activated with:
+
+```ruby
+expect_job_of_type("my_type").to have_activated.with_headers(id_type: "user")
+```
+
+The `with_variables` and `with_headers` methods can be chained on the same expectation:
+
+```ruby
+expect_job_of_type("my_type").to have_activated.
+                                   with_variables(user_id: 123).
+                                   with_headers(id_type: "user")
+```
+
+The matcher also supports methods to complete, fail, or throw an error for a job:
+
+```ruby
+# Complete
+expect_job_of_type("my_type").to have_activated.and_complete
+
+# Complete with new variables
+expect_job_of_type("my_type").to have_activated.and_complete(result_code: 456)
+
+# Fail (sets retries to 0 by default)
+expect_job_of_type("my_type").to have_activated.and_fail
+
+# Fail and specify retries
+expect_job_of_type("my_type").to have_activated.and_fail(retries: 1)
+
+# Fail with an error message
+expect_job_of_type("my_type").to have_activated.and_fail("boom!")
+
+# Fail with an error message and specify retries
+expect_job_of_type("my_type").to have_activated.and_fail("boom!", retries: 2)
+
+# Throw an error (error code is required)
+expect_job_of_type("my_type").to have_activated.and_throw_error("MY_ERROR")
+
+# Throw an error with an error message
+expect_job_of_type("my_type").to have_activated.and_throw_error("MY_ERROR", "went horribly wrong")
+```
+
+Only one of `and_complete`, `and_fail`, or `and_throw_error` can be specified for a single expectation.
+
+#### have_variables and have_headers
+
+In addition to the `with_variables` and `with_headers` methods that can be chained onto the `have_activated`
+matcher, there are matchers that can be used directly to set expectations on the variables or
+headers for an `ActivatedJob`.
+
+```ruby
+job = activate_job("my_type")
+
+expect(job).to have_variables(user: 123)
+expect(job).to have_headers(id_type: "user")
+```
+
 ## Tips & Tricks
 
 ### Enumerator for Multiple Jobs

data/docker-compose.yml

@@ -8,7 +8,7 @@ x-environment: &default-environment
   BUNDLE_DISABLE_SHARED_GEMS: "true"
   ZEEBE_ADDRESS: zeebe:26500
 x-service: &default-service
-  image: ruby:2.6.6
+  image: ruby:2.7.2
   volumes:
     - .:/usr/src/gem
     - ./compose/entrypoint.sh:/tmp/entrypoint.sh
@@ -18,7 +18,7 @@ x-service: &default-service
   stdin_open: true
 services:
   zeebe:
-    image: camunda/zeebe:0.23.4
+    image: camunda/zeebe:${ZEEBE_VERSION:-0.26.1}
     environment:
       ZEEBE_LOG_LEVEL: debug
     volumes:
@@ -26,7 +26,7 @@ services:
       - ./compose/application.yml:/usr/local/zeebe/config/application.yaml
 
   monitor:
-    image: camunda/zeebe-simple-monitor:0.19.0
+    image: camunda/zeebe-simple-monitor:0.19.1
     environment:
       - zeebe.client.broker.contactPoint=zeebe:26500
       - zeebe.client.worker.hazelcast.connection=zeebe:5701

data/lib/zeebe_bpmn_rspec.rb

@@ -1,14 +1,16 @@
 # frozen_string_literal: true
 
+require "active_support"
 require "rspec"
 require "zeebe/client"
 require "zeebe_bpmn_rspec/helpers"
 require "zeebe_bpmn_rspec/version"
+require "zeebe_bpmn_rspec/matchers/have_activated"
 
 # Top-level gem module
 module ZeebeBpmnRspec
   class << self
-    attr_writer :client, :zeebe_address
+    attr_writer :client, :zeebe_address, :activate_request_timeout
 
     def configure
       yield(self)
@@ -23,6 +25,10 @@ module ZeebeBpmnRspec
     def zeebe_address
       @zeebe_address || ENV["ZEEBE_ADDRESS"] || (raise "zeebe_address must be set")
     end
+
+    def activate_request_timeout
+      @activate_request_timeout || 1000
+    end
   end
 end
 

data/lib/zeebe_bpmn_rspec/activated_job.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "active_support"
 require "active_support/core_ext/hash/keys"
 require "json"
 
@@ -8,27 +7,50 @@ module ZeebeBpmnRspec
   class ActivatedJob
     include ::Zeebe::Client::GatewayProtocol # for direct reference of request classes
 
-    attr_reader :job, :type, :workflow_instance_key
+    attr_reader :job, :type
 
-    def initialize(job, type:, workflow_instance_key:, client:, context:)
+    def initialize(job, type:, workflow_instance_key:, client:, context:, validate:) # rubocop:disable Metrics/ParameterLists
       @job = job
       @type = type
       @workflow_instance_key = workflow_instance_key
       @client = client
       @context = context
 
-      context.instance_eval do
-        aggregate_failures do
-          expect(job.workflowInstanceKey).to eq(workflow_instance_key)
-          expect(job.type).to eq(type)
+      if validate
+        context.instance_eval do
+          expect(job).not_to be_nil, "expected to receive job of type '#{type}' but received none"
+          aggregate_failures do
+            expect(job.workflowInstanceKey).to eq(workflow_instance_key)
+            expect(job.type).to eq(type)
+          end
         end
       end
     end
 
+    def raw
+      job
+    end
+
     def key
       job.key
     end
 
+    def workflow_instance_key
+      job.workflowInstanceKey
+    end
+
+    def retries
+      job.retries
+    end
+
+    def task_key
+      job.elementInstanceKey
+    end
+
+    def to_s
+      raw.to_s
+    end
+
     def variables
       @_variables ||= JSON.parse(job.variables)
     end
@@ -87,6 +109,13 @@ module ZeebeBpmnRspec
     end
     alias complete and_complete
 
+    def update_retries(retries = 1)
+      client.update_job_retries(UpdateJobRetriesRequest.new(
+                                  jobKey: job.key,
+                                  retries: retries
+                                ))
+    end
+
     private
 
     attr_reader :client, :context

data/lib/zeebe_bpmn_rspec/helpers.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "active_support/core_ext/object/blank"
 require "zeebe_bpmn_rspec/activated_job"
 
 module ZeebeBpmnRspec
@@ -26,7 +27,7 @@ module ZeebeBpmnRspec
                                                           variables: variables.to_json
                                                         ))
       @__workflow_instance_key = workflow.workflowInstanceKey
-      yield(workflow.workflowInstanceKey)
+      yield(workflow.workflowInstanceKey) if block_given?
     rescue Exception => e # rubocop:disable Lint/RescueException
       # exceptions are rescued to ensure that instances are cancelled
       # any error is re-raised below
@@ -64,37 +65,48 @@ module ZeebeBpmnRspec
       @__workflow_instance_key
     end
 
-    def activate_job(type)
-      stream = _zeebe_client.activate_jobs(ActivateJobsRequest.new(
-                                             type: type,
-                                             worker: "#{type}-#{SecureRandom.hex}",
-                                             maxJobsToActivate: 1,
-                                             timeout: 5000, # TODO: configure
-                                             requestTimeout: 5000
-                                           ))
+    def activate_job(type, fetch_variables: nil, validate: true, worker: "#{type}-#{SecureRandom.hex}")
+      raise ArgumentError.new("'worker' cannot be blank") if worker.blank?
+
+      stream = _zeebe_client.activate_jobs(ActivateJobsRequest.new({
+        type: type,
+        worker: worker,
+        maxJobsToActivate: 1,
+        timeout: 1000,
+        fetchVariable: fetch_variables&.then { |v| Array(v) },
+        requestTimeout: ZeebeBpmnRspec.activate_request_timeout,
+      }.compact))
 
       job = nil
       stream.find { |response| job = response.jobs.first }
-      raise "No job with type #{type.inspect} found" if job.nil?
-
       # puts job.inspect # support debug logging?
 
       ActivatedJob.new(job,
                        type: type,
                        workflow_instance_key: workflow_instance_key,
                        client: _zeebe_client,
-                       context: self)
+                       context: self,
+                       validate: validate)
     end
     alias process_job activate_job
     # TODO: deprecate process_job
 
-    def activate_jobs(type, max_jobs: nil)
+    def job_with_type(type, fetch_variables: nil)
+      activate_job(type, fetch_variables: fetch_variables, validate: false)
+    end
+
+    def expect_job_of_type(type, fetch_variables: nil)
+      expect(job_with_type(type, fetch_variables: fetch_variables))
+    end
+
+    def activate_jobs(type, max_jobs: nil, fetch_variables: nil)
       stream = _zeebe_client.activate_jobs(ActivateJobsRequest.new({
         type: type,
         worker: "#{type}-#{SecureRandom.hex}",
         maxJobsToActivate: max_jobs,
-        timeout: 5000, # TODO: configure
-        requestTimeout: 5000,
+        timeout: 1000,
+        fetchVariable: fetch_variables&.then { |v| Array(v) },
+        requestTimeout: ZeebeBpmnRspec.activate_request_timeout,
       }.compact))
 
       Enumerator.new do |yielder|
@@ -104,23 +116,32 @@ module ZeebeBpmnRspec
                                         type: type,
                                         workflow_instance_key: workflow_instance_key,
                                         client: _zeebe_client,
-                                        context: self)
+                                        context: self,
+                                        validate: true)
           end
         end
       end
     end
 
-    def publish_message(name, correlation_key:, variables: nil)
+    def publish_message(name, correlation_key:, variables: nil, ttl_ms: 5000)
       _zeebe_client.publish_message(PublishMessageRequest.new(
                                       {
                                         name: name,
                                         correlationKey: correlation_key,
-                                        timeToLive: 5000,
+                                        timeToLive: ttl_ms,
                                         variables: variables&.to_json,
                                       }.compact
                                     ))
     end
 
+    def set_variables(key, variables, local: true)
+      _zeebe_client.set_variables(SetVariablesRequest.new(
+                                    elementInstanceKey: key,
+                                    variables: variables.to_json,
+                                    local: local
+                                  ))
+    end
+
     def reset_zeebe!
       @__workflow_instance_key = nil
     end

data/lib/zeebe_bpmn_rspec/matchers/have_activated.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "zeebe_bpmn_rspec/matchers/have_variables"
+require "zeebe_bpmn_rspec/matchers/have_headers"
+
+module ZeebeBpmnRspec
+  class HaveActivatedMatcherError < StandardError
+    def initialize
+      super("Only one of complete, fail, and throw error can be specified")
+    end
+  end
+end
+
+# rubocop:disable Metrics/BlockLength
+RSpec::Matchers.define :have_activated do
+  match do |job|
+    @job = job
+
+    @matcher_error = nil
+    begin
+      aggregate_failures "activated job#{of_type(job)}" do
+        unless job.is_a?(ZeebeBpmnRspec::ActivatedJob)
+          raise ArgumentError.new("expectation target must be a "\
+                                  "#{ZeebeBpmnRspec::ActivatedJob.name}, got #{job.inspect}")
+        end
+
+        if job.raw.nil?
+          raise RSpec::Expectations::ExpectationNotMetError.new("expected activated job#{of_type(job)}, got nil")
+        end
+
+        expect(job).to have_variables(@variables) if @variables
+        expect(job).to have_headers(@headers) if @headers
+      end
+    rescue Exception => e # rubocop:disable Lint/RescueException
+      @matcher_error = e
+    end
+    return false if @matcher_error
+
+    if @complete
+      job.complete(@output || {})
+    elsif @fail
+      job.fail(@fail_message, retries: @retries)
+    elsif @throw
+      job.throw_error(@error_code, @throw_message)
+    end
+
+    true
+  end
+
+  def of_type(job)
+    job.respond_to?(:type) ? " of type #{job.type}" : nil
+  end
+
+  failure_message do |_job|
+    raise matcher_error
+  end
+
+  attr_reader :job, :matcher_error
+
+  def predestined?
+    @complete || @fail || @throw
+  end
+
+  def check_predestined!
+    raise ZeebeBpmnRspec::HaveActivatedMatcherError.new if predestined?
+  end
+
+  chain :with_variables do |variables|
+    @variables = variables.is_a?(Hash) ? variables.stringify_keys : variables
+  end
+
+  chain :with_headers do |headers|
+    @headers = headers.is_a?(Hash) ? headers.stringify_keys : headers
+  end
+
+  chain :and_complete do |output = nil|
+    check_predestined!
+
+    @output = output
+    @complete = true
+  end
+
+  chain :and_fail do |message = nil, retries: 0|
+    check_predestined!
+
+    @fail_message = message
+    @retries = retries
+    @fail = true
+  end
+
+  chain :and_throw_error do |error_code, message = nil|
+    check_predestined!
+
+    @error_code = error_code
+    @throw_message = message
+    @throw = true
+  end
+end
+# rubocop:enable Metrics/BlockLength

data/lib/zeebe_bpmn_rspec/matchers/have_headers.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+RSpec::Matchers.define :have_headers do
+  match do |actual|
+    @job = actual
+    @actual = @job.headers
+    values_match?(expected, @actual)
+  end
+
+  failure_message do |_actual|
+    "expected that job:\n  #{@job}\n\nwould have headers #{expected}"
+  end
+
+  diffable
+end

data/lib/zeebe_bpmn_rspec/matchers/have_variables.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+RSpec::Matchers.define :have_variables do |expected|
+  match do |actual|
+    @job = actual
+    @actual = @job.variables
+    values_match?(expected, @actual)
+  end
+
+  failure_message do |_actual|
+    "expected that job:\n  #{@job}\n\nwould have variables #{expected}"
+  end
+
+  diffable
+end

data/lib/zeebe_bpmn_rspec/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ZeebeBpmnRspec
-  VERSION = "0.2.0"
+  VERSION = "0.5.0"
 end

data/zeebe_bpmn_rspec.gemspec

@@ -41,7 +41,9 @@ Gem::Specification.new do |spec|
   spec.executables   = []
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.12"
+  spec.required_ruby_version = ">= 2.6"
+
+  spec.add_development_dependency "bundler", "~> 2.1"
   spec.add_development_dependency "ezcater_rubocop", "2.0.0"
   spec.add_development_dependency "overcommit"
   spec.add_development_dependency "rake", "~> 10.0"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeebe_bpmn_rspec
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.5.0
 platform: ruby
 authors:
 - ezCater, Inc
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-07-29 00:00:00.000000000 Z
+date: 2021-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '2.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '2.1'
 - !ruby/object:Gem::Dependency
   name: ezcater_rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -152,6 +152,9 @@ files:
 - lib/zeebe_bpmn_rspec.rb
 - lib/zeebe_bpmn_rspec/activated_job.rb
 - lib/zeebe_bpmn_rspec/helpers.rb
+- lib/zeebe_bpmn_rspec/matchers/have_activated.rb
+- lib/zeebe_bpmn_rspec/matchers/have_headers.rb
+- lib/zeebe_bpmn_rspec/matchers/have_variables.rb
 - lib/zeebe_bpmn_rspec/version.rb
 - zeebe_bpmn_rspec.gemspec
 homepage: https://github.com/ezcater/zeebe_bpmn_rspec
@@ -167,14 +170,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.4
 signing_key:
 specification_version: 4
 summary: Zeebe BPMN testing using RSpec