busybee 0.1.0 → 0.3.0

data/docs/testing.md

@@ -1,6 +1,8 @@
-# Testing BPMN Workflows with Busybee
+# Testing BPMN Workflows
 
-Busybee provides RSpec helpers and matchers for testing BPMN workflows against Zeebe. This testing module makes it easy to write integration tests that deploy processes, create instances, activate jobs, and verify workflow behavior.
+Busybee provides RSpec helpers and matchers for testing BPMN workflows against a running Zeebe instance. This testing module lets you deploy processes, create instances, activate jobs, and verify that your workflow definitions route work correctly.
+
+This document covers **workflow-level testing** — verifying that your BPMN process definitions behave as expected. If you're looking to **unit test your worker classes** (the Ruby code that handles individual jobs), see [Workers: Testing Workers](workers.md#testing-workers). The two complement each other: workflow tests verify the orchestration, worker tests verify the business logic.
 
 ## Installation
 
@@ -35,27 +37,28 @@ Configure the Zeebe connection. Busybee reads from environment variables by defa
 
 ```ruby
 # Use environment variables (recommended)
-# ZEEBE_ADDRESS=localhost:26500
-# ZEEBE_USERNAME=demo
-# ZEEBE_PASSWORD=demo
+# CLUSTER_ADDRESS=localhost:26500
 
 # Or configure explicitly
-Busybee::Testing.configure do |config|
-  config.address = "localhost:26500"
-  config.username = "demo"
-  config.password = "demo"
-  config.activate_request_timeout = 2000 # milliseconds, default: 1000
+Busybee.configure do |config|
+  config.cluster_address = "localhost:26500"
 end
 ```
 
-### Configuration Options
+Job activation timeouts used by the testing helpers default to `Busybee.default_job_request_timeout` (see [Configuration](configuration.md)). You can override per-call or globally:
+
+```ruby
+# Per-call: pass timeout directly to the helper
+job = activate_job("my-task", timeout: 2000)
+jobs = activate_jobs("my-task", max_jobs: 5, timeout: 2000)
+
+# Globally: configure a shorter default for your test environment
+Busybee.configure do |config|
+  config.default_job_request_timeout = 2000 # milliseconds, default: 60_000
+end
+```
 
-| Option | Environment Variable | Default | Description |
-|--------|---------------------|---------|-------------|
-| `address` | `ZEEBE_ADDRESS` | `"localhost:26500"` | Zeebe gateway gRPC address |
-| `username` | `ZEEBE_USERNAME` | `"demo"` | Zeebe authentication username |
-| `password` | `ZEEBE_PASSWORD` | `"demo"` | Zeebe authentication password |
-| `activate_request_timeout` | - | `1000` | Timeout in milliseconds for job activation requests |
+For authenticated cluster connections (TLS, OAuth, Camunda Cloud), configure credentials via `Busybee.configure` in your Rails `config/environments/test.rb` or equivalent. See [Providing Credentials](client.md#providing-credentials) for details.
 
 ## Helper Methods
 
@@ -145,14 +148,47 @@ after do
 end
 ```
 
+#### `with_activated_job_instance(job_type)`
+
+Activates a job, yields it, and automatically completes it when the block exits. Must be called within a `with_process_instance` block. This ensures cleanup even if tests fail.
+
+**Parameters:**
+- `job_type` (String) - Job type to activate
+
+**Yields:** `ActivatedJob` instance
+
+**Note:** If the job is already completed or failed within the block, the cleanup completion is silently ignored.
+
+**Examples:**
+
+```ruby
+with_process_instance("order-fulfillment") do
+  with_activated_job_instance("process-order") do |job|
+    # Test job without worrying about cleanup
+    expect(job.variables["order_id"]).to eq("123")
+    client.update_job_retries(job.key, 5)
+    # Job is automatically completed after block
+  end
+end
+
+# Test that completes the job explicitly
+with_process_instance("order-fulfillment") do
+  with_activated_job_instance("process-order") do |job|
+    job.mark_completed(result: "success")
+    # Cleanup completion is safely ignored since job already completed
+  end
+end
+```
+
 ### Job Activation
 
-#### `activate_job(type)`
+#### `activate_job(type, timeout: nil)`
 
 Activates a single job of the specified type. Raises `Busybee::Testing::NoJobAvailable` if no job is available.
 
 **Parameters:**
 - `type` (String) - Job type to activate
+- `timeout` (Integer, ActiveSupport::Duration, optional) - Request timeout in milliseconds. Defaults to `Busybee.default_job_request_timeout` (60,000ms)
 
 **Returns:** `ActivatedJob` instance
 
@@ -164,15 +200,19 @@ Activates a single job of the specified type. Raises `Busybee::Testing::NoJobAva
 job = activate_job("process-payment")
 expect(job.variables["amount"]).to eq(99.99)
 job.mark_completed(payment_status: "success")
+
+# With custom timeout for faster cleanup loops
+job = activate_job("process-order", timeout: 100)
 ```
 
-#### `activate_jobs(type, max_jobs:)`
+#### `activate_jobs(type, max_jobs:, timeout: nil)`
 
 Activates multiple jobs of the specified type.
 
 **Parameters:**
 - `type` (String) - Job type to activate
 - `max_jobs` (Integer) - Maximum number of jobs to activate
+- `timeout` (Integer, ActiveSupport::Duration, optional) - Request timeout in milliseconds. Defaults to `Busybee.default_job_request_timeout` (60,000ms)
 
 **Returns:** Enumerator of `ActivatedJob` instances
 
@@ -292,6 +332,34 @@ job.headers                #=> {"priority" => "high"}
 job.retries                #=> 3
 ```
 
+#### Variables and Headers
+
+The `variables` and `headers` accessors return frozen `HashWithIndifferentAccess` objects with method-style access:
+
+```ruby
+job = activate_job("my-task")
+
+# Indifferent access - use symbol or string keys interchangeably
+job.variables[:order_id]     #=> "123"
+job.variables["order_id"]    #=> "123"
+
+# Method-style access - access keys as methods
+job.variables.order_id       #=> "123"
+job.variables.total          #=> 99.99
+
+# Works with camelCase keys from Zeebe (snake_case methods)
+# If Zeebe sends {"customerId": "abc"}, access via:
+job.variables.customer_id    #=> "abc"
+
+# Nested hashes also support method access
+job.variables.order.line_items.first.product_name
+
+# Variables are frozen (immutable) to prevent accidental modification
+job.variables[:foo] = "bar"  #=> raises FrozenError
+```
+
+This matches the behavior of `Busybee::Job` used in production code, making it easy to write tests that mirror real job handling.
+
 ### Expectation Methods
 
 These methods verify job state and return `self` for chaining:
@@ -460,6 +528,26 @@ expect(activate_job("process-order"))
   .and_complete(processed: true, processed_at: Time.now.iso8601)
 ```
 
+### `have_available_jobs`
+
+Matcher to check if jobs are available for activation. Primarily used in negated form to verify that no jobs exist.
+
+**Aliases:** `have_an_available_job`
+
+**Example:**
+
+```ruby
+# Verify jobs are available
+expect { activate_job("process-order") }.to have_available_jobs
+
+# More commonly: verify NO jobs are available (most common usage)
+expect { activate_job("process-order") }.not_to have_available_jobs
+
+# Use case: verify signal didn't create instances
+client.broadcast_signal("non-existent-signal")
+expect { activate_job("process-order") }.not_to have_an_available_job
+```
+
 ## Complete Workflow Example
 
 Here's a complete example testing an order fulfillment workflow:
@@ -634,18 +722,20 @@ cancel_instance(key) # Easy to forget in error paths
 Assert expected inputs before completing jobs:
 
 ```ruby
-# Good: Verify then complete
-job = activate_job("send-email")
-expect(job).to have_received_variables(
-  recipient: "user@example.com",
-  template: "order_confirmation"
-)
-job.mark_completed(sent_at: Time.now.iso8601)
-
-# Also Good: fluent style
+# Good: fluent style — verify and complete in one chain
 activate_job("send-email")
   .expect_variables(recipient: "user@example.com")
   .and_complete(sent_at: Time.now.iso8601)
+
+# Also Good: separate verification and completion — useful when you need to
+# activate multiple jobs of the same type and distinguish between them
+jobs = activate_jobs("send-comms", max_jobs: 2)
+  .group_by { |j| j.headers["medium"] }
+  .transform_values(&:first)
+
+expect(jobs["sms"]).to have_received_variables(template: "order_sms")
+expect(jobs["email"]).to have_received_variables(template: "order_confirmation")
+jobs.each_value(&:mark_completed)
 ```
 
 ## Troubleshooting