zeebe_bpmn_rspec 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ee557a1aed97212da2a198eafd8238859e12499f32e8ddf24d97d5240c83c36
-  data.tar.gz: 0105ee8a65e00fbab192cf6f76710e43973bec36324b3defcc4f83882db833ca
+  metadata.gz: 6bf6a270631bb041c26a38ccfacf5e57e6cbb8b91601f13e8bab26257151a4f8
+  data.tar.gz: 1e5e28c05d63f1317fc62ccf18b741e60ce9263b085d6e8a1da3232ec0bfeaf8
 SHA512:
-  metadata.gz: 978a61f885179d519ede6340a283b93f9c36e1d712c1279629500732afe01a9f9ac7483a484c17d99356bcebb0258fb04f65771492a6d2b6774cd9be64454f1b
-  data.tar.gz: 6f235e5995f75fd04b7996708bb8a23d81cbb1b7bf1ecd8ebea46a5fba78fa1e5c60f8ab1e305e263d0e16e7ac2005dad78dfdf5e684528ff3cdf3343a2f9c2e
+  metadata.gz: 959b2bbb2c51a68bb7d7559aeffed2b475d660329ad33b7f87feba10e93af476ffd996dcfef7f81634c553423c8cb6dd2e82d0c0e1b280f5d072cb634880d4f8
+  data.tar.gz: 58ccf62381772827998bf76cc5ec18961d90fef06194d082848c4738b36fe4420a91c4f7d9f9f15f8fa8739395479566203337dbc412f802f0d35993644b77e1

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 # zeebe_bpmn_rspec
 
+## 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
@@ -217,6 +219,100 @@ publish_message("message_name", correlation_key: expected_value,
                 variables: { foo: "bar" })
 ```
 
+### 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

@@ -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.24.1}
     environment:
       ZEEBE_LOG_LEVEL: debug
     volumes:

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

@@ -10,25 +10,35 @@ module ZeebeBpmnRspec
 
     attr_reader :job, :type, :workflow_instance_key
 
-    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
+          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 to_s
+      raw.to_s
+    end
+
     def variables
       @_variables ||= JSON.parse(job.variables)
     end

data/lib/zeebe_bpmn_rspec/helpers.rb

@@ -64,7 +64,7 @@ module ZeebeBpmnRspec
       @__workflow_instance_key
     end
 
-    def activate_job(type)
+    def activate_job(type, validate: true)
       stream = _zeebe_client.activate_jobs(ActivateJobsRequest.new(
                                              type: type,
                                              worker: "#{type}-#{SecureRandom.hex}",
@@ -75,26 +75,33 @@ module ZeebeBpmnRspec
 
       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 job_with_type(type)
+      activate_job(type, validate: false)
+    end
+
+    def expect_job_of_type(type)
+      expect(job_with_type(type))
+    end
+
     def activate_jobs(type, max_jobs: 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,
+        requestTimeout: ZeebeBpmnRspec.activate_request_timeout,
       }.compact))
 
       Enumerator.new do |yielder|
@@ -104,7 +111,8 @@ module ZeebeBpmnRspec
                                         type: type,
                                         workflow_instance_key: workflow_instance_key,
                                         client: _zeebe_client,
-                                        context: self)
+                                        context: self,
+                                        validate: true)
           end
         end
       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.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeebe_bpmn_rspec
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - ezCater, Inc
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-07-29 00:00:00.000000000 Z
+date: 2020-08-20 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.0.3
+rubygems_version: 3.1.4
 signing_key:
 specification_version: 4
 summary: Zeebe BPMN testing using RSpec