zizq 0.3.3 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ab68c867c5342352c99cccc1c244215a12256c8957be422c38c1446fbcc317e
-  data.tar.gz: 58651399c191747b0e1fab0b0751e53de4eb415dcb0ae5845b76eb35590cb5eb
+  metadata.gz: 3d7eb0e9668c055e6f5b6b8ec6aacb5c09f8df5eedcea038acdb14d164a58acf
+  data.tar.gz: d30b95be8bab2eae5100b89fa7957278a20c301538e5630156bf9892739864a3
 SHA512:
-  metadata.gz: 4b35bd73a1e4c8c66113b7f1b0c4efbb1eef97e0b304730510a76a35498e6fcc38c15016b53b7507206e558535d07b1a0dbd377d7e5472247f9fffd5ac5a79ec
-  data.tar.gz: 6fbdbe994579189e68bd37e5ce4167a4c074593609cb7938f411e956c073b11d43c0863e8c8038bb2e77cfe0246263e3c7b55e83d3961f5da99e133164da766a
+  metadata.gz: dbe8d111b4083de907b4522ae4f0c110554a0ab5821a544d808c363868602178c15f983140436da6525b96ab30be159ac52309adfb05cb271739a7aee73174cc
+  data.tar.gz: 39606af98c372c50147922ba7640dcd9e58d449c63927008abbcc03ac2b926e68d4856764152f51f16fb26554241e801df1fb862542e405a1087bd2213d4eaab

data/README.md

@@ -32,13 +32,13 @@ API.
 Add it to your application's `Gemfile`:
 
 ```ruby
-gem 'zizq', '~> 0.3.3'
+gem 'zizq', '~> 0.3.5'
 ```
 
 Or install it manually:
 
 ```shell
-$ gem install zizq -v 0.3.3
+$ gem install zizq -v 0.3.5
 ```
 
 Ruby **3.2.8 or newer** is required. Client and server share version
@@ -221,6 +221,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/enqueue_request.rb

@@ -157,8 +157,8 @@ module Zizq
       if backoff
         params[:backoff] = {
           exponent: backoff[:exponent].to_f,
-          base_ms: (backoff[:base].to_f * 1000).to_f,
-          jitter_ms: (backoff[:jitter].to_f * 1000).to_f
+          base_ms: (backoff[:base].to_f * 1000).to_i,
+          jitter_ms: (backoff[:jitter].to_f * 1000).to_i
         }
       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.3" #: String
+  VERSION = "0.3.5" #: String
 end

data/lib/zizq.rb

@@ -29,6 +29,7 @@ module Zizq
   autoload :Lifecycle,           "zizq/lifecycle"
   autoload :Query,               "zizq/query"
   autoload :Resources,           "zizq/resources"
+  autoload :Test,                "zizq/test"
   autoload :TlsConfiguration,    "zizq/tls_configuration"
   autoload :Worker,              "zizq/worker"
   autoload :WorkerConfiguration, "zizq/worker_configuration"
@@ -74,19 +75,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/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.3
+  version: 0.3.5
 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,8 @@ files:
 - lib/zizq/resources/job_template.rb
 - lib/zizq/resources/page.rb
 - lib/zizq/resources/resource.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 +135,8 @@ files:
 - sig/generated/zizq/resources/job_template.rbs
 - sig/generated/zizq/resources/page.rbs
 - sig/generated/zizq/resources/resource.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