zeebe_bpmn_rspec 0.1.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21f042c1e3d81e8f0bc9096924685cdd8c436de1a5a68e1cef9857e3f4e87a58
-  data.tar.gz: fe32bf072bc3677667e1ed6ac49c92e2cd48647ad5adfabd546a7a94ea253eef
+  metadata.gz: a8ab5c676ef52ca21100add177726c7443298348603c89e8a53e1692b2876e21
+  data.tar.gz: a9a7acca330b1377991b524cb9e31d91ccd7599ef0391ca58aef6700dc7da168
 SHA512:
-  metadata.gz: 34a5334740649b53d9199e74009fb6e233ac34667b33c8e012f9c30fa168f470626c5d199a83f83032deae764a3408a33b6df3ce620ee427895d0d9bcc60f7c7
-  data.tar.gz: 1688746402718b8d1d38868f8271782af51be446bc3ba4d62b953ca9c049afa1933d4614ce9203294aa46286efaa74a54fd88b377c8df32f09e9c932acea8179
+  metadata.gz: aae2aa7d081b9dd5cc342f955f060b0a605f23c680b3a7b9368857fc08ada31a58fb047cdd41e419d8394127786b29b76486c8feb0ce5aef1925e9ee3f88237d
+  data.tar.gz: 5639b3ee712ea0af3b961e3402d5c606d3b26f55279785d844909030557fa8054c2ab344c62d10afcf020408055c58491eba9dcfc288eef673d37fd5d3eca799

data/CHANGELOG.md

@@ -1,4 +1,26 @@
 # zeebe_bpmn_rspec
 
+## 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`).
+
 ## v0.1.0
 - Initial version

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
@@ -118,7 +120,7 @@ activate_job("my_job").
 
 #### Complete Job
 
-Jobs can be completed by calling `and_complete`. Variables can optionally be returned with the
+Jobs can be completed by calling `and_complete` (also aliased as `complete`). Variables can optionally be returned with the
 completed job.
 
 ```ruby
@@ -134,7 +136,7 @@ project_job("my_job").
 
 #### Fail Job
 
-Jobs can be failed by calling `and_fail`. An optional message can be specified when failing a job.
+Jobs can be failed by calling `and_fail` (also aliased as `fail`). An optional message can be specified when failing a job.
 
 ```ruby
 # Failing a job can be chanined with expectations
@@ -147,9 +149,27 @@ activate_job("my_job").
   and_fail("something didn't go right")
 ```
 
+By default retries are set to zero when a job is failed but the remaining retries can optionally be specified:
+
+```ruby
+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` method can be used to throw an error for a job. The error code is required and an
+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
 optional message may be specified:
 
 ```ruby
@@ -165,7 +185,18 @@ activate_job("my_job").
 
 #### Activating Multiple Jobs
 
-TODO
+Multiple jobs can be activated using the `activate_jobs` method.
+
+```ruby
+activate_jobs("my_job")
+```
+
+The call to `activate_jobs` returns an Enumerator that returns `ActivatedJob` instance.
+The maximum number of jobs to return can be specified:
+
+```ruby
+jobs = activate_jobs("my_job", max_jobs: 2).to_a
+```
 
 ### Workflow Complete
 
@@ -198,6 +229,143 @@ 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
+
+When activating multiple jobs, call `to_a` on the result of `activate_jobs` to get
+an array of activated jobs objects.
+
+### Timer Duration
+
+Specify timer durations using a variable so that tests can easily set the variable
+to specify a short duration.
+
 ## Limitations
 
 The current gem and approach have some limitations:

data/docker-compose.yml

@@ -6,7 +6,7 @@ x-environment: &default-environment
   PRYRC: /usr/src/app/.docker-pryrc
   BUNDLE_IGNORE_CONFIG: 1
   BUNDLE_DISABLE_SHARED_GEMS: "true"
-  ZEEBE_ADDRESS: zeebe-bpmn-gateway:26500
+  ZEEBE_ADDRESS: zeebe:26500
 x-service: &default-service
   image: ruby:2.6.6
   volumes:
@@ -18,7 +18,7 @@ x-service: &default-service
   stdin_open: true
 services:
   zeebe:
-    image: camunda/zeebe:0.23.2
+    image: camunda/zeebe:${ZEEBE_VERSION:-0.24.1}
     environment:
       ZEEBE_LOG_LEVEL: debug
     volumes:
@@ -28,8 +28,8 @@ services:
   monitor:
     image: camunda/zeebe-simple-monitor:0.19.0
     environment:
-      - zeebe.client.broker.contactPoint=zeebe-bpmn-gateway:26500
-      - zeebe.client.worker.hazelcast.connection=zeebe-bpmn-gateway:5701
+      - zeebe.client.broker.contactPoint=zeebe:26500
+      - zeebe.client.worker.hazelcast.connection=zeebe:5701
     ports:
       - "8082:8082"
     depends_on:

data/lib/zeebe_bpmn_rspec.rb

@@ -4,11 +4,12 @@ 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 +24,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

@@ -8,27 +8,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
@@ -66,16 +89,18 @@ module ZeebeBpmnRspec
                            }.compact
                          ))
     end
+    alias throw_error and_throw_error
 
-    def and_fail(message = nil)
+    def and_fail(message = nil, retries: nil)
       client.fail_job(FailJobRequest.new(
                         {
                           jobKey: job.key,
-                          retries: 0,
+                          retries: retries || 0,
                           errorMessage: message,
                         }.compact
                       ))
     end
+    alias fail and_fail
 
     def and_complete(variables = {})
       client.complete_job(CompleteJobRequest.new(
@@ -83,6 +108,14 @@ module ZeebeBpmnRspec
                             variables: variables.to_json
                           ))
     end
+    alias complete and_complete
+
+    def update_retries(retries = 1)
+      client.update_job_retries(UpdateJobRetriesRequest.new(
+                                  jobKey: job.key,
+                                  retries: retries
+                                ))
+    end
 
     private
 

data/lib/zeebe_bpmn_rspec/helpers.rb

@@ -26,7 +26,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 +64,46 @@ 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}")
+      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 +113,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.1.0"
+  VERSION = "0.4.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeebe_bpmn_rspec
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.4.1
 platform: ruby
 authors:
 - ezCater, Inc
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-07-21 00:00:00.000000000 Z
+date: 2020-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -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
@@ -174,7 +177,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.0.3
 signing_key:
 specification_version: 4
 summary: Zeebe BPMN testing using RSpec