zizq 0.3.4 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99a09e939c3261e843c176cd936a29e4e6f6a725ac802d93273a2608692b9616
-  data.tar.gz: ef6a5a3af87980b71a68a10a16969c29f572ef55d4b628de89bde210f0949f69
+  metadata.gz: a95c96d7b844064db29aea81935d6ec6e3c6953fc47459fcfd6253b6b44aa1e7
+  data.tar.gz: 19a8e38ef04716ba02b21bb4ce1f8f2b3e597b1f9845ada71dde5ae7d31fecd3
 SHA512:
-  metadata.gz: 4eae14c105f51ca5d3b8f8fbf51e635bee289d81a2d81603ba47ee85c29493daa67eee2d3fa07246ba91a2d98381f9e2f7db46ad23e13d191228df9c48043fd7
-  data.tar.gz: 78382c2d8062b3b51a76fd44760b9116fe71b5f273b5d3ec8d458e6e8609fd6d8a22f5f54717920dc6197393f5ba56e05298ccf51fd5a5beefc1d52ee838a65d
+  metadata.gz: d4158e9e2b3f58e2c1b823b26f8c81a9ee5ab347d72683377909fed7b4d0d163caf3e27708d3e1f3cbd1af3018068fda34d97405ec6095732b0cda57909a82fc
+  data.tar.gz: 95c1453a0af6a82e8ad0abd5e2a8085550ce4cf5ef6b2871cb653fdd1068994f69b36bb04a5e30d2ec76c1ccc02a1e142621a5c5bde7de9bab84517917b90fef

data/README.md

@@ -12,7 +12,7 @@ API.
 ## Features
 
 * Multi-thread and/or multi-fiber concurrent worker (via [`async`](https://github.com/socketry/async))
-* `Zizq::Job` based job classes, Active Job support, or completely custom
+* `Zizq::Job` based job classes, Active Job support, or low-level/custom
 * Enqueue and process jobs from one language to another
 * Arbitrary named queues
 * Granular job priorities
@@ -22,6 +22,7 @@ API.
 * Recurring jobs (cron)
 * Job introspection and management APIs, with support for `jq` query filters
 * Unique jobs
+* Testing helpers
 
 ## Installation
 
@@ -32,13 +33,13 @@ API.
 Add it to your application's `Gemfile`:
 
 ```ruby
-gem 'zizq', '~> 0.3.4'
+gem 'zizq', '~> 0.3.6'
 ```
 
 Or install it manually:
 
 ```shell
-$ gem install zizq -v 0.3.4
+$ gem install zizq -v 0.3.6
 ```
 
 Ruby **3.2.8 or newer** is required. Client and server share version
@@ -62,7 +63,7 @@ Zizq.configure do |c|
   # Optional worker defaults — applied to every Zizq::Worker
   # instance and to runs of the `zizq-worker` executable. Explicit
   # kwargs or CLI flags override these.
-  c.worker.queues       = ['emails', 'payments']
+  c.worker.queues = ['emails', 'payments']
   c.worker.fiber_count  = 25
 end
 ```
@@ -148,10 +149,42 @@ Zizq.enqueue_bulk do |b|
 end
 ```
 
-> [!NOTE]
-> Jobs can also be enqueued without `Zizq::Job` via `Zizq.enqueue_raw` —
-> designed for cross-language workflows where, for example, a Ruby app
-> enqueues jobs consumed by a Go service.
+Jobs can also be enqueued without `Zizq::Job` via `Zizq.enqueue_raw` —
+designed for lower-level code style, and for cross-language workflows where,
+for example, a Ruby app enqueues jobs consumed by a Go service.
+
+```ruby
+Zizq.enqueue_raw(
+  type: "send_email",
+  queue: "comms",
+  payload: { user_id: 42, template: "welcome" }
+)
+```
+
+### Cross-language and low-level dispatch { #router }
+
+When a Ruby app needs to *process* jobs enqueued by another language
+(or by `Zizq.enqueue_raw`), `Zizq::Router` maps `type` strings to
+handler blocks operating on plain JSON payloads:
+
+```ruby
+Zizq.configure do |c|
+  c.dispatcher = Zizq::Router.new do
+    route('send_email') do |payload|
+      Mailer.deliver(payload['user_id'], payload['template'])
+    end
+
+    # Apps that mix the two styles can fall back to Zizq::Job
+    # for anything not handled by an explicit route.
+    fallback { |job| Zizq::Job.call(job) }
+  end
+end
+```
+
+See [Custom Dispatchers](https://zizq.io/docs/clients/ruby/dispatchers.html)
+for full details. Dispatchers in Zizq are just objects that implement `#call`
+with a single `Zizq::Resources::Job` argument, and `Zizq::Router` is just a
+dispatcher itself.
 
 ### Running a worker
 
@@ -221,6 +254,38 @@ Once defined, schedules can be inspected and managed via
 `Zizq.crontab('maintenance')` — paused/resumed at the schedule level or per
 entry, and deleted entirely when no longer needed.
 
+### Testing
+
+Set `c.test_mode = true` in your test helper and Zizq swaps the real
+client out for an in-memory `Zizq::Test::Client` that buffers enqueues
+instead of dispatching them. Tests can then assert on what was
+enqueued and drain the buffer through the configured dispatcher —
+no running server required.
+
+```ruby
+# test/test_helper.rb (or spec/spec_helper.rb)
+Zizq::Test.enable!
+
+class ActiveSupport::TestCase
+  setup { Zizq::Test.reset! }
+end
+
+# In a test
+def test_signup_fans_out
+  SignupService.new.run
+
+  assert Zizq::Test.enqueued?(SendWelcomeEmailJob, user_id: 42)
+  assert_equal 2, Zizq::Test.pending_jobs(only_queues: 'emails').size
+
+  # Drain the buffer through Zizq.configuration.dequeue_middleware
+  # (same path the real worker takes — registered middleware runs too).
+  Zizq::Test.dispatch_enqueued_jobs
+end
+```
+
+See [Testing](https://zizq.io/docs/clients/ruby/testing.html) for
+full details.
+
 ## Resources
 
 * [Ruby Client Docs](https://zizq.io/docs/clients/ruby/)

data/lib/zizq/configuration.rb

@@ -59,6 +59,16 @@ module Zizq
     # a `Resources::Job` and a chain to continue.
     attr_reader :dequeue_middleware #: Middleware::Chain[Resources::Job, void]
 
+    # When truthy, `Zizq.client` lazily resolves to a
+    # `Zizq::Test::Client` that buffers enqueues in memory rather than
+    # dispatching to a real server. Useful inside test suites — set it
+    # once in your test helper and the rest of the app's code uses
+    # `Zizq.enqueue` / `Zizq.enqueue_bulk` unchanged. Read operations
+    # (`Zizq.query`, `Zizq.queues`, `Client#get_job`, etc.) raise
+    # rather than silently returning empty results, so missing test
+    # setup is obvious.
+    attr_accessor :test_mode #: bool
+
     def initialize #: () -> void
       @url = "http://localhost:7890"
       @format = :msgpack
@@ -67,6 +77,7 @@ module Zizq
       @worker = nil
       @read_timeout = 30
       @stream_idle_timeout = 30
+      @test_mode = false
       @enqueue_middleware = Middleware::Chain.new(Identity.new)
       @dequeue_middleware = Middleware::Chain.new(Zizq::Job)
     end

data/lib/zizq/router.rb

@@ -0,0 +1,100 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Zizq
+  # Dispatch jobs by `type` string, mapping each to a handler block.
+  #
+  # Designed for cross-language workflows: payloads are plain JSON
+  # values (Hashes / Arrays / strings / numbers), `type` is a String
+  # the producer agrees on with the consumer, and routes are
+  # registered explicitly — no `Zizq::Job` mixin involved.
+  #
+  #   Zizq.configure do |c|
+  #     c.dispatcher = Zizq::Router.new do
+  #       route("send_email") do |payload|
+  #         Mailer.deliver(payload["user_id"], payload["template"])
+  #       end
+  #
+  #       route("expire_tokens") do
+  #         TokenSweeper.run
+  #       end
+  #
+  #       route("generate_report") do |payload, job|
+  #         Reports.generate(payload["id"], attempts: job.attempts)
+  #       end
+  #
+  #       # `def` inside the block defines singleton methods on the
+  #       # router. Route blocks captured *inside* the constructor
+  #       # have lexical `self == router`, so they can call these
+  #       # helpers; routes added outside (`router.route("…") { … }`)
+  #       # keep their own lexical `self` and would need to go through
+  #       # the router explicitly (`router.logger`).
+  #       def logger
+  #         Zizq.configuration.logger
+  #       end
+  #
+  #       # Anything else falls back. A common pattern is delegating
+  #       # to `Zizq::Job` for the apps that mix the two styles.
+  #       fallback { |job| Zizq::Job.call(job) }
+  #     end
+  #   end
+  #
+  # Routes can also be registered outside the constructor block:
+  #
+  #   router = Zizq::Router.new
+  #   router.route("send_email") { |payload| ... }
+  #
+  # Handlers are called as `handler.call(payload, job)`. Block-arity
+  # rules let `{ |payload| }` or `{ }` ignore either argument.
+  # Strict-arity lambdas need to declare both.
+  class Router
+    # Raised when a job arrives with a type that has no registered
+    # route and no fallback. Caught by Zizq's normal worker error
+    # path, which nacks the job for retry (or dead-letters it once
+    # the retry limit is hit).
+    class UnknownJobType < Zizq::Error; end
+
+    # @rbs &block: ?(self) [self: Router] -> void
+    def initialize(&block)
+      @routes = {} #: Hash[String, ^(untyped, Resources::Job) -> void]
+      @fallback = nil #: (^(Resources::Job) -> void)?
+      instance_eval(&block) if block
+    end
+
+    # Register `handler` for jobs whose `type` matches.
+    #
+    # @rbs type: String | Symbol
+    # @rbs &handler: (untyped, Resources::Job) -> void
+    def route(type, &handler)
+      @routes[type.to_s] = handler
+    end
+
+    # Register a fallback handler invoked when no route matches.
+    # Receives the full `Resources::Job` (not split into payload /
+    # job pair), since the canonical use is delegation to another
+    # dispatcher:
+    #
+    #   fallback { |job| Zizq::Job.call(job) }
+    #
+    # @rbs &handler: (Resources::Job) -> void
+    def fallback(&handler)
+      @fallback = handler
+    end
+
+    # Dispatch a single job. Looks up the handler by `job.type`,
+    # falls back to the registered fallback if any, otherwise
+    # raises `UnknownJobType`.
+    def call(job) #: (Resources::Job) -> void
+      handler = @routes[job.type]
+
+      return handler.call(job.payload, job) if handler
+      return @fallback.call(job) if @fallback
+
+      raise UnknownJobType,
+        "no handler registered for job type #{job.type.inspect}"
+    end
+  end
+end

data/lib/zizq/test/client.rb

@@ -0,0 +1,332 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Zizq
+  module Test
+    # A `Zizq::Client` stand-in for use in test suites.
+    #
+    # Buffers `enqueue` / `enqueue_bulk` calls in memory and returns
+    # synthetic `Resources::Job` instances (with generated ids) so that
+    # callers depending on the regular client's return contract don't
+    # need to special-case test mode.
+    #
+    # Read operations (`get_queues`, `list_jobs`, `count_jobs`, …) are
+    # explicitly not supported in test mode and raise `NotSupported`.
+    # Tests that need those should either run against a real server or
+    # stub at a higher level.
+    #
+    # Activated indirectly via `Zizq.configuration.test_mode = true` —
+    # `Zizq.client` then lazily builds a `Test::Client` instead of a
+    # real `Client`.
+    class Client < Zizq::Client
+      # Raised when test-mode code reaches an operation that isn't
+      # supported (queries, queue listing, worker streams, etc.).
+      class NotSupported < Zizq::Error; end
+
+      # Length of a real scru128 id in its base-32 representation.
+      # Synthetic test ids are sized to match (`test` prefix + zero
+      # padded counter) so they fit anywhere a real id would.
+      ID_LENGTH = 25
+      ID_PREFIX = "test"
+
+      # The canonical Zizq lifecycle states. We mirror these so the
+      # `status` on a buffered job reflects what the real server would
+      # report. Test mode never retries — `in_flight` only ever
+      # transitions to `completed` or `dead`.
+      STATUS_SCHEDULED = "scheduled"
+      STATUS_READY     = "ready"
+      STATUS_IN_FLIGHT = "in_flight"
+      STATUS_COMPLETED = "completed"
+      STATUS_DEAD      = "dead"
+
+      # Default `filter:` lambda — passes every job. Named so the
+      # filter pipeline is always callable without nil-checking.
+      PASS_ALL_FILTER = ->(_job) { true } #: ^(Resources::Job) -> bool
+
+      # Paired view of a single enqueue: the original `EnqueueRequest`
+      # (with full submission metadata — `unique_key`, `unique_while`,
+      # retry config, etc.), the synthetic `Resources::Job` returned
+      # to callers, and the data hash that backs the job (so we can
+      # mutate its status through the lifecycle).
+      Entry = Struct.new(:request, :job, :data, keyword_init: true)
+
+      def initialize #: () -> void
+        # Skip the parent's HTTP setup — we don't open connections in
+        # test mode. The parent's @http and friends stay nil; methods
+        # that would touch them are overridden below.
+
+        @entries = [] #: Array[Entry]
+        @mutex = Mutex.new
+      end
+
+      # All buffered jobs, in submission order, optionally filtered.
+      # See `apply_filters` for the filter kwargs.
+      def enqueued_jobs(**filters) #: (**untyped) -> Array[Resources::Job]
+        @mutex.synchronize { apply_filters(@entries, **filters).map(&:job) }
+      end
+
+      # Original `EnqueueRequest`s in submission order. Useful when a
+      # test needs metadata that doesn't survive onto `Resources::Job`
+      # (`unique_key`, `unique_while`, `delay` before `ready_at`
+      # resolution, etc.). Same filter kwargs as `enqueued_jobs`.
+      def enqueued_requests(**filters) #: (**untyped) -> Array[EnqueueRequest]
+        @mutex.synchronize { apply_filters(@entries, **filters).map(&:request) }
+      end
+
+      # Jobs awaiting dispatch — `ready` and `scheduled` entries.
+      # `pending_jobs` is the set `drain` would attempt to run on its
+      # next call (modulo `ready_at` for `scheduled` entries).
+      def pending_jobs(**filters) #: (**untyped) -> Array[Resources::Job]
+        filter_by_status([STATUS_READY, STATUS_SCHEDULED], **filters)
+      end
+
+      def in_flight_jobs(**filters) #: (**untyped) -> Array[Resources::Job]
+        filter_by_status([STATUS_IN_FLIGHT], **filters)
+      end
+
+      def completed_jobs(**filters) #: (**untyped) -> Array[Resources::Job]
+        filter_by_status([STATUS_COMPLETED], **filters)
+      end
+
+      def dead_jobs(**filters) #: (**untyped) -> Array[Resources::Job]
+        filter_by_status([STATUS_DEAD], **filters)
+      end
+
+      # Reset the buffer. Called between tests via `Zizq::Test.reset!`.
+      def clear! #: () -> void
+        @mutex.synchronize { @entries.clear }
+      end
+
+      def close #: () -> void
+      end
+
+      # Dispatch every runnable entry (status `ready`, or `scheduled`
+      # with `ready_at` already elapsed) through the configured
+      # dequeue middleware chain (same path the real worker uses, so
+      # any registered middlewares run in tests too), looping until no
+      # more match the filters. Re-enqueues during dispatch fall
+      # through the loop naturally — they get drained too unless they
+      # fall outside the filter set.
+      #
+      # The per-iteration snapshot is taken under the mutex and marked
+      # `in_flight` atomically. Dispatch happens outside the mutex so
+      # handlers can re-enter the client without deadlocking. On
+      # success the entry moves to `completed`; on a raised exception
+      # it moves to `dead` and the exception re-raises (matching
+      # ActiveJob's `perform_enqueued_jobs` + Sidekiq's `drain`).
+      def drain(**filters) #: (**untyped) -> Integer
+        total = 0
+        loop do
+          snapshot = take_runnable_snapshot(**filters)
+          break if snapshot.empty?
+
+          snapshot.each { |entry| dispatch_entry(entry) }
+          total += snapshot.size
+        end
+        total
+      end
+
+      # @rbs override
+      def enqueue(queue:,
+                  type:,
+                  payload:,
+                  priority: nil,
+                  ready_at: nil,
+                  retry_limit: nil,
+                  backoff: nil,
+                  retention: nil,
+                  unique_key: nil,
+                  unique_while: nil)
+        req = EnqueueRequest.new(
+          queue:,
+          type:,
+          payload:,
+          priority:,
+          ready_at:,
+          retry_limit:,
+          backoff:,
+          retention:,
+          unique_key:,
+          unique_while:,
+        )
+        @mutex.synchronize { record_unsynchronized(req) }.job
+      end
+
+      # @rbs override
+      def enqueue_bulk(jobs:)
+        @mutex.synchronize do
+          jobs.map do |params|
+            req = EnqueueRequest.new(
+              queue:        params[:queue],
+              type:         params[:type],
+              payload:      params[:payload],
+              priority:     params[:priority],
+              ready_at:     params[:ready_at],
+              retry_limit:  params[:retry_limit],
+              backoff:      params[:backoff],
+              retention:    params[:retention],
+              unique_key:   params[:unique_key],
+              unique_while: params[:unique_while],
+            )
+            record_unsynchronized(req).job
+          end
+        end
+      end
+
+      # All read / mutation / streaming operations are deliberately
+      # unimplemented.
+      #
+      # Raising loudly beats silently returning empty results that
+      # hide missing test setup.
+      %i[
+        get_queues
+        list_jobs
+        count_jobs
+        get_job
+        delete_job
+        delete_all_jobs
+        update_job
+        update_all_jobs
+        take_jobs
+        get_error
+        list_errors
+        health
+        server_version
+      ].each do |method_name|
+        define_method(method_name) do |*, **, &_|
+          Kernel.raise(
+            NotSupported,
+            "Zizq::Test::Client##{method_name} is not supported in test mode. " \
+            "Test mode buffers enqueues only — point at a real server, or stub the call."
+          )
+        end
+      end
+
+      private
+
+      def record_unsynchronized(req) #: (EnqueueRequest) -> Entry
+        # Serialized format: ready_at is integer milliseconds.
+        # `req.ready_at` (from `to_enqueue_params`) is fractional
+        # seconds; convert here so `Resources::Job#ready_at`'s
+        # ms -> seconds round-trip produces the same value the
+        # caller passed in. When the client omits ready_at the server
+        # assigns `now`, so we do the same.
+        now_ms = (Time.now.to_f * 1000).to_i
+        ready_at_ms = req.ready_at ? (req.ready_at.to_f * 1000).to_i : now_ms
+
+        data = {
+          "id" => synthetic_id(@entries.size + 1),
+          "queue" => req.queue,
+          "type" => req.type,
+          "payload" => req.payload,
+          "priority" => req.priority,
+          "ready_at" => ready_at_ms,
+          "retry_limit" => req.retry_limit,
+          "status" => ready_at_ms > now_ms ? STATUS_SCHEDULED : STATUS_READY,
+        }
+        entry = Entry.new(request: req, job: Resources::Job.new(self, data), data: data)
+        @entries << entry
+        entry
+      end
+
+      def synthetic_id(counter) #: (Integer) -> String
+        "#{ID_PREFIX}#{counter.to_s.rjust(ID_LENGTH - ID_PREFIX.length, '0')}"
+      end
+
+      # Returns entries matching every named filter AND the predicate.
+      # All filter kwargs are optional; unset means "don't filter on
+      # this axis." Callers must hold `@mutex` — public accessors do
+      # so via `synchronize` before calling.
+      #
+      # * `only_queues:`  / `except_queues:` — String, Array of Strings.
+      # * `only_types:`   / `except_types:`  — String, Class, or Array
+      #   of those. Class names are matched against the wire-format
+      #   `type` string via `.to_s`.
+      # * `filter:` — a lambda receiving a `Resources::Job`, returning
+      #   truthy to keep. Defaults to `PASS_ALL_FILTER`.
+      #
+      # `only_*` and `except_*` AND together with the predicate.
+      def apply_filters(entries,
+                        only_queues: nil,
+                        except_queues: nil,
+                        only_types: nil,
+                        except_types: nil,
+                        filter: PASS_ALL_FILTER) #: (Array[Entry], **untyped) -> Array[Entry]
+        only_queues   = normalize_filter(only_queues)
+        except_queues = normalize_filter(except_queues)
+        only_types    = normalize_filter(only_types)
+        except_types  = normalize_filter(except_types)
+
+        entries.select do |entry|
+          queue = entry.data["queue"] #: String
+          type  = entry.data["type"]  #: String
+
+          (only_queues.empty? || only_queues.include?(queue)) &&
+            (except_queues.empty? || !except_queues.include?(queue)) &&
+            (only_types.empty? || only_types.include?(type)) &&
+            (except_types.empty? || !except_types.include?(type)) &&
+            filter.call(entry.job)
+        end
+      end
+
+      def filter_by_status(statuses, **filters) #: (Array[String], **untyped) -> Array[Resources::Job]
+        @mutex.synchronize do
+          apply_filters(@entries, **filters)
+            .select { |e| statuses.include?(e.data["status"]) }
+            .map(&:job)
+        end
+      end
+
+      # Lock, find runnable entries matching the filters, flip each
+      # to in_flight, return the snapshot. Holding the mutex through
+      # this is fine because we don't call user code — dispatch
+      # happens outside.
+      def take_runnable_snapshot(**filters) #: (**untyped) -> Array[Entry]
+        now_ms = (Time.now.to_f * 1000).to_i
+        @mutex.synchronize do
+          apply_filters(@entries, **filters)
+            .select { |e| runnable?(e, now_ms) }
+            .each { |entry| entry.data["status"] = STATUS_IN_FLIGHT }
+        end
+      end
+
+      def runnable?(entry, now_ms) #: (Entry, Integer) -> bool
+        case entry.data["status"]
+        when STATUS_READY     then true
+        when STATUS_SCHEDULED then entry.data["ready_at"] <= now_ms
+        else false
+        end
+      end
+
+      # Accept a Class, String, or Array of those; emit an Array of
+      # Strings. Class names match the API's `type` string.
+      def normalize_filter(value) #: ((String | Class | Array[String | Class])?) -> Array[String]
+        case value
+        when nil then []
+        when Array then value.map { |x| x.to_s }
+        else [value.to_s]
+        end
+      end
+
+      # Mark the entry in_flight, dispatch through the full dequeue
+      # middleware chain (same path the real worker uses, so any
+      # registered middlewares run in tests too), settle to
+      # completed or dead. A raised exception re-raises after
+      # recording — same observable behaviour as Rails'
+      # `perform_enqueued_jobs`.
+      def dispatch_entry(entry) #: (Entry) -> void
+        entry.data["status"] = STATUS_IN_FLIGHT
+        begin
+          Zizq.configuration.dequeue_middleware.call(entry.job)
+          entry.data["status"] = STATUS_COMPLETED
+        rescue
+          entry.data["status"] = STATUS_DEAD
+          raise
+        end
+      end
+    end
+  end
+end

data/lib/zizq/test.rb

@@ -0,0 +1,190 @@
+# Copyright (c) 2026 Chris Corbyn <chris@zizq.io>
+# Licensed under the MIT License. See LICENSE file for details.
+
+# rbs_inline: enabled
+# frozen_string_literal: true
+
+module Zizq
+  # Test-mode helpers. Activated by setting `c.test_mode = true` in a
+  # `Zizq.configure` block; `Zizq.client` then lazily resolves to a
+  # `Zizq::Test::Client` that buffers enqueues instead of dispatching.
+  #
+  # Typical use in a test helper:
+  #
+  #   Zizq.configure do |c|
+  #     c.test_mode = true
+  #   end
+  #
+  #   class MyTestCase
+  #     setup { Zizq::Test.reset! }
+  #   end
+  #
+  # In a test:
+  #
+  #   def test_signup_fans_out
+  #     # Default buffered mode — assert what was enqueued.
+  #     SignupService.new.run
+  #     assert_equal 2, Zizq::Test.client.pending_jobs.size
+  #
+  #     # Drain whatever's pending (handler re-enqueues fall through
+  #     # naturally — drain loops until pending is empty).
+  #     Zizq::Test.dispatch_enqueued_jobs
+  #
+  #     # Block form: run the work, then drain. Matches ActiveJob's
+  #     # `perform_enqueued_jobs do ... end`.
+  #     Zizq::Test.dispatch_enqueued_jobs { SignupService.new.run }
+  #
+  #     # Filter by queue and/or type when only a subset should fire.
+  #     Zizq::Test.dispatch_enqueued_jobs(queue: "emails")
+  #     Zizq::Test.dispatch_enqueued_jobs(type: SendEmailJob)
+  #   end
+  module Test
+    autoload :Client, "zizq/test/client"
+
+    # Switch Zizq into test mode. After this, `Zizq.client` resolves
+    # to a `Zizq::Test::Client` that buffers enqueues in memory.
+    # Typically called once in a test helper.
+    def self.enable! #: () -> void
+      Zizq.configure { |c| c.test_mode = true }
+    end
+
+    # Switch back to the real client. The buffered state is dropped
+    # along with the test client (the next `Zizq.client` access
+    # builds a fresh `Zizq::Client`).
+    def self.disable! #: () -> void
+      Zizq.configure { |c| c.test_mode = false }
+    end
+
+    # The active test client. Raises if test mode is not enabled —
+    # better to fail loudly than return a stale or wrong client.
+    def self.client #: () -> Client
+      unless Zizq.configuration.test_mode
+        raise Client::NotSupported,
+          "Zizq.configuration.test_mode is not enabled; Zizq::Test.client has nothing to manage."
+      end
+      Zizq.client #: Client
+    end
+
+    # Reset buffered state between tests. Keeps the configured
+    # `test_mode` flag.
+    def self.reset! #: () -> void
+      client.clear!
+    end
+
+    # Dispatch pending jobs through the configured dequeue middleware
+    # chain (`Zizq.configuration.dequeue_middleware` — same path the
+    # real worker uses, so any registered middlewares run in tests
+    # too), looping until no more pending entries match the filters.
+    #
+    # * No block: drain whatever's pending now.
+    # * With block: yield first (test code enqueues), then drain.
+    # * `only_queues:` / `except_queues:` — String or Array of Strings.
+    # * `only_types:`  / `except_types:`  — String, Class, or Array of
+    #   those (Class names match the serialized-format `type` via `.to_s`,
+    #   so passing an ActiveJob class works directly).
+    # * `filter:` — a lambda `->(job)` returning truthy to keep an
+    #   entry. Defaults to "pass all". Combines with the named
+    #   filters via AND.
+    #
+    # Returns the number of jobs dispatched. A block exception
+    # propagates without draining; a handler exception during drain
+    # transitions that entry to `dead` and re-raises.
+    def self.dispatch_enqueued_jobs(**filters, &block) #: (**untyped) ?{ () -> void } -> Integer
+      yield if block
+      client.drain(**filters)
+    end
+
+    # Convenience proxies onto the active test client, so test code
+    # can read `Zizq::Test.pending_jobs(only_queues: "emails")`
+    # instead of routing through `Zizq::Test.client.pending_jobs(...)`.
+    # Each forwards `**filters` to the corresponding Client accessor;
+    # see `Test::Client` for the supported filter kwargs.
+    #
+    # All accept the same filter kwargs as `#dispatch_enqueued_jobs`.
+    %i[
+      enqueued_jobs
+      enqueued_requests
+      pending_jobs
+      in_flight_jobs
+      completed_jobs
+      dead_jobs
+    ].each do |name|
+      define_singleton_method(name) do |**filters|
+        client.public_send(name, **filters)
+      end
+    end
+
+    # Was a job of `job_class` enqueued (optionally with matching
+    # args)?
+    #
+    #   Zizq::Test.enqueued?(SendEmailJob)                            # any args
+    #   Zizq::Test.enqueued?(SendEmailJob, 42, template: "welcome")   # exact args
+    #
+    # With no args, matches by class/type only. With args/kwargs,
+    # uses the class's own `zizq_serialize` to compute the expected
+    # payload — so it works for both `Zizq::Job` and AJ classes
+    # (AJ's volatile fields like `job_id` are ignored, only the
+    # `arguments` subset is compared).
+    #
+    # For anything fuzzier (matchers, subset matching, custom
+    # predicates), drop down to
+    # `client.enqueued_jobs(only_types: ..., filter: ->(job) { ... })`.
+    def self.enqueued?(job_class, *args, **kwargs) #: (Class, *untyped, **untyped) -> bool
+      enqueued_count(job_class, *args, **kwargs) > 0
+    end
+
+    # How many times was a job of `job_class` enqueued (optionally
+    # with matching args)? Same argument semantics as `#enqueued?`.
+    def self.enqueued_count(job_class, *args, **kwargs) #: (Class, *untyped, **untyped) -> Integer
+      type = job_class.to_s
+      return enqueued_raw_count(type: type) if args.empty? && kwargs.empty?
+
+      unless job_class.respond_to?(:zizq_serialize)
+        raise ArgumentError,
+          "#{job_class} doesn't implement zizq_serialize — " \
+          "include Zizq::Job or extend Zizq::ActiveJobConfig, " \
+          "or use Zizq::Test.enqueued_raw? for raw enqueues."
+      end
+
+      expected = job_class.zizq_serialize(*args, **kwargs)
+      client.enqueued_jobs(only_types: type).count do |job|
+        payloads_equivalent?(expected, job.payload)
+      end
+    end
+
+    # Was a raw job (queue + type + payload) enqueued? Each kwarg is
+    # optional; unspecified means "don't filter on this axis."
+    #
+    #   Zizq::Test.enqueued_raw?(type: "send_email")
+    #   Zizq::Test.enqueued_raw?(type: "send_email", payload: { user_id: 42 })
+    #   Zizq::Test.enqueued_raw?(queue: "emails", type: "send_email")
+    def self.enqueued_raw?(queue: nil, type: nil, payload: nil) #: (?queue: String?, ?type: String?, ?payload: untyped) -> bool
+      enqueued_raw_count(queue: queue, type: type, payload: payload) > 0
+    end
+
+    # How many raw jobs match (queue + type + payload)? Same
+    # argument semantics as `#enqueued_raw?`.
+    def self.enqueued_raw_count(queue: nil, type: nil, payload: nil) #: (?queue: String?, ?type: String?, ?payload: untyped) -> Integer
+      filters = {}
+      filters[:only_queues] = queue if queue
+      filters[:only_types]  = type  if type
+      filters[:filter]      = ->(job) { job.payload == payload } unless payload.nil?
+      client.enqueued_jobs(**filters).size
+    end
+
+    # Heuristic payload comparison that handles both `Zizq::Job`'s
+    # serialized format (`{"args" => [...], "kwargs" => {...}}`) and
+    # ActiveJob's (`{"job_class" => ..., "arguments" => [...],
+    # "job_id" => ..., "enqueued_at" => ..., ...}`). The AJ shape
+    # always has an `"arguments"` key while `Zizq::Job`'s doesn't, so
+    # we use that to pick whether to compare the full hash or only the
+    # `arguments` subset (dropping AJ's volatile per-enqueue fields).
+    def self.payloads_equivalent?(expected, actual) #: (untyped, untyped) -> bool
+      if expected.is_a?(Hash) && expected.key?("arguments")
+        actual.is_a?(Hash) && actual["arguments"] == expected["arguments"]
+      else
+        actual == expected
+      end
+    end
+  end
+end

data/lib/zizq/version.rb

@@ -5,5 +5,5 @@
 # frozen_string_literal: true
 
 module Zizq
-  VERSION = "0.3.4" #: String
+  VERSION = "0.3.6" #: String
 end

data/lib/zizq.rb

@@ -29,6 +29,8 @@ module Zizq
   autoload :Lifecycle,           "zizq/lifecycle"
   autoload :Query,               "zizq/query"
   autoload :Resources,           "zizq/resources"
+  autoload :Router,              "zizq/router"
+  autoload :Test,                "zizq/test"
   autoload :TlsConfiguration,    "zizq/tls_configuration"
   autoload :Worker,              "zizq/worker"
   autoload :WorkerConfiguration, "zizq/worker_configuration"
@@ -74,19 +76,27 @@ module Zizq
     #
     # The client is memoized so that persistent HTTP connections are reused
     # across calls, reducing TCP connection overhead.
+    #
+    # When `configuration.test_mode` is set, a `Zizq::Test::Client` is
+    # returned instead — buffering enqueues in memory rather than
+    # talking to a real server.
     def client #: () -> Client
       @client ||= begin
         @client_mutex.synchronize do
           break @client if @client
 
           configuration.validate!
-          @client = Client.new(
-            url: configuration.url,
-            format: configuration.format,
-            ssl_context: configuration.ssl_context,
-            read_timeout: configuration.read_timeout,
-            stream_idle_timeout: configuration.stream_idle_timeout
-          )
+          @client = if configuration.test_mode
+            Test::Client.new
+          else
+            Client.new(
+              url: configuration.url,
+              format: configuration.format,
+              ssl_context: configuration.ssl_context,
+              read_timeout: configuration.read_timeout,
+              stream_idle_timeout: configuration.stream_idle_timeout
+            )
+          end
         end
       end
     end

data/sig/generated/zizq/configuration.rbs

@@ -51,6 +51,16 @@ module Zizq
     # a `Resources::Job` and a chain to continue.
     attr_reader dequeue_middleware: Middleware::Chain[Resources::Job, void]
 
+    # When truthy, `Zizq.client` lazily resolves to a
+    # `Zizq::Test::Client` that buffers enqueues in memory rather than
+    # dispatching to a real server. Useful inside test suites — set it
+    # once in your test helper and the rest of the app's code uses
+    # `Zizq.enqueue` / `Zizq.enqueue_bulk` unchanged. Read operations
+    # (`Zizq.query`, `Zizq.queues`, `Client#get_job`, etc.) raise
+    # rather than silently returning empty results, so missing test
+    # setup is obvious.
+    attr_accessor test_mode: bool
+
     def initialize: () -> untyped
 
     # TLS settings for connecting to the server over HTTPS.

data/sig/generated/zizq/router.rbs

@@ -0,0 +1,81 @@
+# Generated from lib/zizq/router.rb with RBS::Inline
+
+module Zizq
+  # Dispatch jobs by `type` string, mapping each to a handler block.
+  #
+  # Designed for cross-language workflows: payloads are plain JSON
+  # values (Hashes / Arrays / strings / numbers), `type` is a String
+  # the producer agrees on with the consumer, and routes are
+  # registered explicitly — no `Zizq::Job` mixin involved.
+  #
+  #   Zizq.configure do |c|
+  #     c.dispatcher = Zizq::Router.new do
+  #       route("send_email") do |payload|
+  #         Mailer.deliver(payload["user_id"], payload["template"])
+  #       end
+  #
+  #       route("expire_tokens") do
+  #         TokenSweeper.run
+  #       end
+  #
+  #       route("generate_report") do |payload, job|
+  #         Reports.generate(payload["id"], attempts: job.attempts)
+  #       end
+  #
+  #       # `def` inside the block defines singleton methods on the
+  #       # router. Route blocks captured *inside* the constructor
+  #       # have lexical `self == router`, so they can call these
+  #       # helpers; routes added outside (`router.route("…") { … }`)
+  #       # keep their own lexical `self` and would need to go through
+  #       # the router explicitly (`router.logger`).
+  #       def logger
+  #         Zizq.configuration.logger
+  #       end
+  #
+  #       # Anything else falls back. A common pattern is delegating
+  #       # to `Zizq::Job` for the apps that mix the two styles.
+  #       fallback { |job| Zizq::Job.call(job) }
+  #     end
+  #   end
+  #
+  # Routes can also be registered outside the constructor block:
+  #
+  #   router = Zizq::Router.new
+  #   router.route("send_email") { |payload| ... }
+  #
+  # Handlers are called as `handler.call(payload, job)`. Block-arity
+  # rules let `{ |payload| }` or `{ }` ignore either argument.
+  # Strict-arity lambdas need to declare both.
+  class Router
+    # Raised when a job arrives with a type that has no registered
+    # route and no fallback. Caught by Zizq's normal worker error
+    # path, which nacks the job for retry (or dead-letters it once
+    # the retry limit is hit).
+    class UnknownJobType < Zizq::Error
+    end
+
+    # @rbs &block: ?(self) [self: Router] -> void
+    def initialize: () ?{ (self) [self: Router] -> void } -> untyped
+
+    # Register `handler` for jobs whose `type` matches.
+    #
+    # @rbs type: String | Symbol
+    # @rbs &handler: (untyped, Resources::Job) -> void
+    def route: (String | Symbol type) { (untyped, Resources::Job) -> void } -> untyped
+
+    # Register a fallback handler invoked when no route matches.
+    # Receives the full `Resources::Job` (not split into payload /
+    # job pair), since the canonical use is delegation to another
+    # dispatcher:
+    #
+    #   fallback { |job| Zizq::Job.call(job) }
+    #
+    # @rbs &handler: (Resources::Job) -> void
+    def fallback: () { (Resources::Job) -> void } -> untyped
+
+    # Dispatch a single job. Looks up the handler by `job.type`,
+    # falls back to the registered fallback if any, otherwise
+    # raises `UnknownJobType`.
+    def call: (untyped job) -> untyped
+  end
+end

data/sig/generated/zizq/test/client.rbs

@@ -0,0 +1,161 @@
+# Generated from lib/zizq/test/client.rb with RBS::Inline
+
+module Zizq
+  module Test
+    # A `Zizq::Client` stand-in for use in test suites.
+    #
+    # Buffers `enqueue` / `enqueue_bulk` calls in memory and returns
+    # synthetic `Resources::Job` instances (with generated ids) so that
+    # callers depending on the regular client's return contract don't
+    # need to special-case test mode.
+    #
+    # Read operations (`get_queues`, `list_jobs`, `count_jobs`, …) are
+    # explicitly not supported in test mode and raise `NotSupported`.
+    # Tests that need those should either run against a real server or
+    # stub at a higher level.
+    #
+    # Activated indirectly via `Zizq.configuration.test_mode = true` —
+    # `Zizq.client` then lazily builds a `Test::Client` instead of a
+    # real `Client`.
+    class Client < Zizq::Client
+      # Raised when test-mode code reaches an operation that isn't
+      # supported (queries, queue listing, worker streams, etc.).
+      class NotSupported < Zizq::Error
+      end
+
+      # Length of a real scru128 id in its base-32 representation.
+      # Synthetic test ids are sized to match (`test` prefix + zero
+      # padded counter) so they fit anywhere a real id would.
+      ID_LENGTH: ::Integer
+
+      ID_PREFIX: ::String
+
+      # The canonical Zizq lifecycle states. We mirror these so the
+      # `status` on a buffered job reflects what the real server would
+      # report. Test mode never retries — `in_flight` only ever
+      # transitions to `completed` or `dead`.
+      STATUS_SCHEDULED: ::String
+
+      STATUS_READY: ::String
+
+      STATUS_IN_FLIGHT: ::String
+
+      STATUS_COMPLETED: ::String
+
+      STATUS_DEAD: ::String
+
+      # Default `filter:` lambda — passes every job. Named so the
+      # filter pipeline is always callable without nil-checking.
+      PASS_ALL_FILTER: ^(Resources::Job) -> bool
+
+      # Paired view of a single enqueue: the original `EnqueueRequest`
+      # (with full submission metadata — `unique_key`, `unique_while`,
+      # retry config, etc.), the synthetic `Resources::Job` returned
+      # to callers, and the data hash that backs the job (so we can
+      # mutate its status through the lifecycle).
+      class Entry < Struct[untyped]
+        attr_accessor request(): untyped
+
+        attr_accessor job(): untyped
+
+        attr_accessor data(): untyped
+
+        def self.new: (?request: untyped, ?job: untyped, ?data: untyped) -> instance
+                    | ({ ?request: untyped, ?job: untyped, ?data: untyped }) -> instance
+      end
+
+      def initialize: () -> untyped
+
+      # All buffered jobs, in submission order, optionally filtered.
+      # See `apply_filters` for the filter kwargs.
+      def enqueued_jobs: (**untyped filters) -> untyped
+
+      # Original `EnqueueRequest`s in submission order. Useful when a
+      # test needs metadata that doesn't survive onto `Resources::Job`
+      # (`unique_key`, `unique_while`, `delay` before `ready_at`
+      # resolution, etc.). Same filter kwargs as `enqueued_jobs`.
+      def enqueued_requests: (**untyped filters) -> untyped
+
+      # Jobs awaiting dispatch — `ready` and `scheduled` entries.
+      # `pending_jobs` is the set `drain` would attempt to run on its
+      # next call (modulo `ready_at` for `scheduled` entries).
+      def pending_jobs: (**untyped filters) -> untyped
+
+      def in_flight_jobs: (**untyped filters) -> untyped
+
+      def completed_jobs: (**untyped filters) -> untyped
+
+      def dead_jobs: (**untyped filters) -> untyped
+
+      # Reset the buffer. Called between tests via `Zizq::Test.reset!`.
+      def clear!: () -> untyped
+
+      def close: () -> untyped
+
+      # Dispatch every runnable entry (status `ready`, or `scheduled`
+      # with `ready_at` already elapsed) through the configured
+      # dequeue middleware chain (same path the real worker uses, so
+      # any registered middlewares run in tests too), looping until no
+      # more match the filters. Re-enqueues during dispatch fall
+      # through the loop naturally — they get drained too unless they
+      # fall outside the filter set.
+      #
+      # The per-iteration snapshot is taken under the mutex and marked
+      # `in_flight` atomically. Dispatch happens outside the mutex so
+      # handlers can re-enter the client without deadlocking. On
+      # success the entry moves to `completed`; on a raised exception
+      # it moves to `dead` and the exception re-raises (matching
+      # ActiveJob's `perform_enqueued_jobs` + Sidekiq's `drain`).
+      def drain: (**untyped filters) -> untyped
+
+      # @rbs override
+      def enqueue: ...
+
+      # @rbs override
+      def enqueue_bulk: ...
+
+      private
+
+      def record_unsynchronized: (untyped req) -> untyped
+
+      def synthetic_id: (untyped counter) -> untyped
+
+      # Returns entries matching every named filter AND the predicate.
+      # All filter kwargs are optional; unset means "don't filter on
+      # this axis." Callers must hold `@mutex` — public accessors do
+      # so via `synchronize` before calling.
+      #
+      # * `only_queues:`  / `except_queues:` — String, Array of Strings.
+      # * `only_types:`   / `except_types:`  — String, Class, or Array
+      #   of those. Class names are matched against the wire-format
+      #   `type` string via `.to_s`.
+      # * `filter:` — a lambda receiving a `Resources::Job`, returning
+      #   truthy to keep. Defaults to `PASS_ALL_FILTER`.
+      #
+      # `only_*` and `except_*` AND together with the predicate.
+      def apply_filters: (untyped entries, ?only_queues: untyped, ?except_queues: untyped, ?only_types: untyped, ?except_types: untyped, ?filter: untyped) -> untyped
+
+      def filter_by_status: (untyped statuses, **untyped filters) -> untyped
+
+      # Lock, find runnable entries matching the filters, flip each
+      # to in_flight, return the snapshot. Holding the mutex through
+      # this is fine because we don't call user code — dispatch
+      # happens outside.
+      def take_runnable_snapshot: (**untyped filters) -> untyped
+
+      def runnable?: (untyped entry, untyped now_ms) -> untyped
+
+      # Accept a Class, String, or Array of those; emit an Array of
+      # Strings. Class names match the API's `type` string.
+      def normalize_filter: (untyped value) -> untyped
+
+      # Mark the entry in_flight, dispatch through the full dequeue
+      # middleware chain (same path the real worker uses, so any
+      # registered middlewares run in tests too), settle to
+      # completed or dead. A raised exception re-raises after
+      # recording — same observable behaviour as Rails'
+      # `perform_enqueued_jobs`.
+      def dispatch_entry: (untyped entry) -> untyped
+    end
+  end
+end

data/sig/generated/zizq/test.rbs

@@ -0,0 +1,118 @@
+# Generated from lib/zizq/test.rb with RBS::Inline
+
+module Zizq
+  # Test-mode helpers. Activated by setting `c.test_mode = true` in a
+  # `Zizq.configure` block; `Zizq.client` then lazily resolves to a
+  # `Zizq::Test::Client` that buffers enqueues instead of dispatching.
+  #
+  # Typical use in a test helper:
+  #
+  #   Zizq.configure do |c|
+  #     c.test_mode = true
+  #   end
+  #
+  #   class MyTestCase
+  #     setup { Zizq::Test.reset! }
+  #   end
+  #
+  # In a test:
+  #
+  #   def test_signup_fans_out
+  #     # Default buffered mode — assert what was enqueued.
+  #     SignupService.new.run
+  #     assert_equal 2, Zizq::Test.client.pending_jobs.size
+  #
+  #     # Drain whatever's pending (handler re-enqueues fall through
+  #     # naturally — drain loops until pending is empty).
+  #     Zizq::Test.dispatch_enqueued_jobs
+  #
+  #     # Block form: run the work, then drain. Matches ActiveJob's
+  #     # `perform_enqueued_jobs do ... end`.
+  #     Zizq::Test.dispatch_enqueued_jobs { SignupService.new.run }
+  #
+  #     # Filter by queue and/or type when only a subset should fire.
+  #     Zizq::Test.dispatch_enqueued_jobs(queue: "emails")
+  #     Zizq::Test.dispatch_enqueued_jobs(type: SendEmailJob)
+  #   end
+  module Test
+    # Switch Zizq into test mode. After this, `Zizq.client` resolves
+    # to a `Zizq::Test::Client` that buffers enqueues in memory.
+    # Typically called once in a test helper.
+    def self.enable!: () -> untyped
+
+    # Switch back to the real client. The buffered state is dropped
+    # along with the test client (the next `Zizq.client` access
+    # builds a fresh `Zizq::Client`).
+    def self.disable!: () -> untyped
+
+    # The active test client. Raises if test mode is not enabled —
+    # better to fail loudly than return a stale or wrong client.
+    def self.client: () -> untyped
+
+    # Reset buffered state between tests. Keeps the configured
+    # `test_mode` flag.
+    def self.reset!: () -> untyped
+
+    # Dispatch pending jobs through the configured dequeue middleware
+    # chain (`Zizq.configuration.dequeue_middleware` — same path the
+    # real worker uses, so any registered middlewares run in tests
+    # too), looping until no more pending entries match the filters.
+    #
+    # * No block: drain whatever's pending now.
+    # * With block: yield first (test code enqueues), then drain.
+    # * `only_queues:` / `except_queues:` — String or Array of Strings.
+    # * `only_types:`  / `except_types:`  — String, Class, or Array of
+    #   those (Class names match the serialized-format `type` via `.to_s`,
+    #   so passing an ActiveJob class works directly).
+    # * `filter:` — a lambda `->(job)` returning truthy to keep an
+    #   entry. Defaults to "pass all". Combines with the named
+    #   filters via AND.
+    #
+    # Returns the number of jobs dispatched. A block exception
+    # propagates without draining; a handler exception during drain
+    # transitions that entry to `dead` and re-raises.
+    def self.dispatch_enqueued_jobs: (**untyped filters) ?{ (?) -> untyped } -> untyped
+
+    # Was a job of `job_class` enqueued (optionally with matching
+    # args)?
+    #
+    #   Zizq::Test.enqueued?(SendEmailJob)                            # any args
+    #   Zizq::Test.enqueued?(SendEmailJob, 42, template: "welcome")   # exact args
+    #
+    # With no args, matches by class/type only. With args/kwargs,
+    # uses the class's own `zizq_serialize` to compute the expected
+    # payload — so it works for both `Zizq::Job` and AJ classes
+    # (AJ's volatile fields like `job_id` are ignored, only the
+    # `arguments` subset is compared).
+    #
+    # For anything fuzzier (matchers, subset matching, custom
+    # predicates), drop down to
+    # `client.enqueued_jobs(only_types: ..., filter: ->(job) { ... })`.
+    def self.enqueued?: (untyped job_class, *untyped args, **untyped kwargs) -> untyped
+
+    # How many times was a job of `job_class` enqueued (optionally
+    # with matching args)? Same argument semantics as `#enqueued?`.
+    def self.enqueued_count: (untyped job_class, *untyped args, **untyped kwargs) -> untyped
+
+    # Was a raw job (queue + type + payload) enqueued? Each kwarg is
+    # optional; unspecified means "don't filter on this axis."
+    #
+    #   Zizq::Test.enqueued_raw?(type: "send_email")
+    #   Zizq::Test.enqueued_raw?(type: "send_email", payload: { user_id: 42 })
+    #   Zizq::Test.enqueued_raw?(queue: "emails", type: "send_email")
+    def self.enqueued_raw?: (?queue: untyped, ?type: untyped, ?payload: untyped) -> untyped
+
+    # How many raw jobs match (queue + type + payload)? Same
+    # argument semantics as `#enqueued_raw?`.
+    def self.enqueued_raw_count: (?queue: untyped, ?type: untyped, ?payload: untyped) -> untyped
+
+    # Heuristic payload comparison that handles both `Zizq::Job`'s
+    # serialized format (`{"args" => [...], "kwargs" => {...}}`) and
+    # ActiveJob's (`{"job_class" => ..., "arguments" => [...],
+    # "job_id" => ..., "enqueued_at" => ..., ...}`). The AJ shape
+    # always has an `"arguments"` key while `Zizq::Job`'s doesn't, so
+    # we use that to pick whether to compare the full hash or only the
+    # `arguments` subset (dropping AJ's volatile per-enqueue fields).
+    def self.payloads_equivalent?: (untyped expected, untyped actual) -> untyped
+  end
+end

data/sig/generated/zizq.rbs

@@ -33,6 +33,10 @@ module Zizq
   #
   # The client is memoized so that persistent HTTP connections are reused
   # across calls, reducing TCP connection overhead.
+  #
+  # When `configuration.test_mode` is set, a `Zizq::Test::Client` is
+  # returned instead — buffering enqueues in memory rather than
+  # talking to a real server.
   def self.client: () -> untyped
 
   # Resets all global state: configuration and shared client.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zizq
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.6
 platform: ruby
 authors:
 - Chris Corbyn <chris@zizq.io>
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-25 00:00:00.000000000 Z
+date: 2026-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-http
@@ -100,6 +100,9 @@ files:
 - lib/zizq/resources/job_template.rb
 - lib/zizq/resources/page.rb
 - lib/zizq/resources/resource.rb
+- lib/zizq/router.rb
+- lib/zizq/test.rb
+- lib/zizq/test/client.rb
 - lib/zizq/tls_configuration.rb
 - lib/zizq/version.rb
 - lib/zizq/worker.rb
@@ -133,6 +136,9 @@ files:
 - sig/generated/zizq/resources/job_template.rbs
 - sig/generated/zizq/resources/page.rbs
 - sig/generated/zizq/resources/resource.rbs
+- sig/generated/zizq/router.rbs
+- sig/generated/zizq/test.rbs
+- sig/generated/zizq/test/client.rbs
 - sig/generated/zizq/tls_configuration.rbs
 - sig/generated/zizq/version.rbs
 - sig/generated/zizq/worker.rbs