postburner 1.0.0.rc.7 → 1.0.0.rc.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41b3c95f8abde17bb19b725dd0c39ce65b97a53e73afb77c7237e2e51f37d7e9
-  data.tar.gz: 7e5de5424a027d59c9552624bd555ae38da4f30823f3ffc28ef86601c96301e0
+  metadata.gz: 9e547f2f387408e6f3abed4bafba9f6c737c49ec3d7cbc65bfd80dd2ba509451
+  data.tar.gz: 7aa5b40f8224bc79abcba8d63f423410ed86cb74c9db9a47a47c83027744a667
 SHA512:
-  metadata.gz: d2f90b3d590adfc16247f285f8ea27cef03d9dd72af5671bc92117d2418442dcf6f331c68d5380a2917687ea2353524f972fdd7edeca4fe9a8e1b6b965dff9ef
-  data.tar.gz: 06accd7ecd5c01aa83532e7f8cd69e2aca53459e7b8f8f8c0a290163555a2f24f47df8ecb4407e39d7401680547b7f016b9111221688e5dc10c2fea43eb49ba6
+  metadata.gz: 24aa9c290a6f34ea9630823da4849a96d28cf786bbfdac43e8e2ba45fc79d04fa49d2d99ef1917740baca2e282693ce80e928a010df653cb55b78f9f19d15f39
+  data.tar.gz: e39b5f65a04804282d5050115111c1906377ad9da2cc169c805235a43d6933687e01ecc2619c2869fb99cb004e6b7d6fed3009ccd2b720a4e13e9998eb83eae6

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## Unreleased
+
+## v1.0.0.rc.8 - 2026-10-05
+
+### Fixed
+
+- **A testing strategy no longer drops ActiveJob enqueues outside the test environment.** `NullQueue`, `InlineTestQueue`, and `TimeTravelTestQueue` still keep `Postburner::Job` off Beanstalkd in every environment. `perform_later`, `deliver_later`, and `broadcast_*_later` skip the put only when `Rails.env.test?` and the strategy is a testing strategy. In production the adapter always puts, including after `Postburner.null_strategy!`.
+- **The test strategy is chosen at boot.** The engine reads `config.active_job.queue_adapter` from `after_initialize`, so the choice is in place before the first test and does not wait for `ActiveJob::Base` to load. A strategy assigned in an initializer, or later in `test_helper.rb`, is kept. `:test` selects `InlineTestQueue`. `:postburner` selects `NullQueue`.
+- **Boot no longer reads `config.active_job` unless the test environment has that railtie.** An application that requires Active Record, Action Controller, and Action View without the ActiveJob railtie has no `config.active_job`. The test-strategy hook returns before touching it outside test, and when `config` does not respond to `active_job`.
+
+### Changed
+
+- **`perform_later` waits for the surrounding transaction to commit.** Selecting the Postburner adapter sets `ActiveJob::Base.enqueue_after_transaction_commit = true`. A job enqueued inside a joinable transaction is put after commit and dropped on rollback. A Beanstalkd error on that put is raised after the data is committed. The flag lives on `ActiveJob::Base`, so a job class that uses another adapter in the same process inherits the same deferral.
+- **In the test environment, `:postburner` does not write to Beanstalkd.** `Postburner::Job#queue!` keeps the row (`NullQueue`). ActiveJob enqueues still write a tracked row when the job is tracked, still emit the enqueue notification, and do not put. `Postburner.default_strategy!` or `Postburner.strict_strategy!` is the opt-in that puts.
+
+### Upgrade notes
+
+- A test that asserts a real tube job after `perform_later` or `queue!` calls `Postburner.default_strategy!` or `Postburner.strict_strategy!`.
+- `Postburner.null_strategy!` in production still skips the tube for `Postburner::Job` only. ActiveJob continues to put.
+
 ## v1.0.0.rc.7 - 2026-08-03
 
 ### Fixed

data/README.md

@@ -919,15 +919,15 @@ Pay attention to the following when writing jobs:
 
 ## Queue Strategies
 
-Postburner uses different strategies to control job execution. These affect `Postburner::Job` subclasses (not ActiveJob classes).
+Postburner uses different strategies to control `Postburner::Job` execution. In the test environment a testing strategy also tells the ActiveJob adapter not to put to Beanstalkd. Outside test the adapter always puts. `DefaultQueue` and `StrictQueue` put in every environment.
 
 | Strategy | When to Use | Behavior | Requires Beanstalkd |
 |----------|-------------|----------|---------------------|
-| **DefaultQueue** | Production | Async, gracefully requeues premature jobs | Yes |
-| **StrictQueue** | Production | Async via Beanstalkd, raises error on premature execution | Yes |
-| **NullQueue** | Test (usually) | Jobs created but not inserted into Beanstalkd, manual execution | No |
-| **InlineTestQueue** | Test | Inline execution (error raised for delayed jobs) | No |
-| **TimeTravelTestQueue** | Test | Inline execution, (auto time-travels for delayed jobs) | No |
+| **DefaultQueue** | Production, or a test that needs a real tube | Async, gracefully requeues premature jobs. The ActiveJob adapter puts. | Yes |
+| **StrictQueue** | Production, or a test that needs a real tube | Async via Beanstalkd, raises error on premature execution. The ActiveJob adapter puts. | Yes |
+| **NullQueue** | Test default when the adapter is `:postburner`. Also deferred or manual `Postburner::Job` execution | Jobs created but not inserted into Beanstalkd. In test, the ActiveJob adapter does not put. Outside test, the adapter still puts. | No |
+| **InlineTestQueue** | Test default when the adapter is `:test` | Inline execution (error raised for delayed jobs). In test, the ActiveJob adapter does not put. | No |
+| **TimeTravelTestQueue** | Test | Inline execution, (auto time-travels for delayed jobs). In test, the ActiveJob adapter does not put. | No |
 
 ```ruby
 # Switch strategies
@@ -950,45 +950,33 @@ There are 4 hook methods that are used with inheritance:
 
 ### Automatic Test Mode
 
-In Rails test environments, Postburner automatically uses inline execution via the `InlineTestQueue` strategy:
+`config.active_job.queue_adapter` is the only setup. At the end of boot the test environment selects a strategy that does not write to Beanstalkd. A strategy assigned in an initializer is already set by then and is kept. A strategy assigned in `test_helper.rb` runs after boot and is kept:
+
+| `queue_adapter` | `Postburner::Job#queue!` | ActiveJob `perform_later` |
+|-----------------|--------------------------|---------------------------|
+| `:test` | `InlineTestQueue` (runs in process) | Rails keeps the job in memory |
+| `:postburner` | `NullQueue` (row kept, run it with `Postburner::Job.perform`) | Tracked jobs still write their row. Nothing is put. |
 
 ```ruby
-# test/test_helper.rb - automatic!
-Postburner.testing?  # => true in tests
+Postburner.default_strategy!   # this example needs a real tube
+SendEmail.perform_later(123)   # now the adapter puts
 ```
 
-Postburner provides test-friendly execution modes that don't require Beanstalkd.
-
-### Testing Default Jobs (ActiveJob)
-
-Use standard ActiveJob test helpers:
-
-```ruby
-class MyTest < ActiveSupport::TestCase
-  test "job executes" do
-    SendEmail.perform_later(123)
-    # Job executes immediately in test mode
-  end
+`Postburner.strict_strategy!` is the same opt-in with strict premature handling. `assert_enqueued_jobs` still needs the `:test` adapter, via `config/environments/test.rb` or `queue_adapter_for_test`.
 
-  test "job with delay" do
-    travel 1.hour do
-      SendEmail.set(wait: 1.hour).perform_later(123)
-    end
-  end
-end
-```
+An application that does not load the ActiveJob railtie has no `config.active_job`, so test boot leaves `DefaultQueue` in place and `Postburner::Job#queue!` puts. Call `Postburner.null_strategy!` in that app. `:inline` and `:async` leave `DefaultQueue` for the same reason: only `:test` and `:postburner` select a strategy that does not put.
 
 ### Testing Tracked Jobs
 
-Tracked jobs create database records you can inspect:
+With the `:postburner` adapter in test, `perform_later` writes the `TrackedJob` row and leaves `bkid` nil:
 
 ```ruby
-test "tracked job logs execution" do
+test "tracked job records the enqueue" do
   ProcessPayment.perform_later(456)
 
   job = Postburner::TrackedJob.last
-  assert job.processed_at.present?
-  assert_includes job.logs.map { |l| l[1]['message'] }, "Processing payment 456"
+  assert job.queued_at.present?
+  assert_nil job.bkid
 end
 ```
 
@@ -1014,16 +1002,16 @@ class EmailTest < ActiveSupport::TestCase
 end
 ```
 
-**How this works:** `assert_enqueued_emails` and `assert_enqueued_jobs` are powered by Rails' `:test` ActiveJob adapter, which tracks enqueued jobs in an in-memory array. Postburner's queue strategies (`InlineTestQueue`, etc.) control `Postburner::Job` subclasses separately. The two systems coexist — ActiveJob assertions use the `:test` adapter, `Postburner::Job` assertions use database queries.
+**How this works:** `assert_enqueued_emails` and `assert_enqueued_jobs` read Rails' `:test` adapter. They do not see jobs enqueued through `:postburner`. Set the test adapter when a test needs those assertions. With `:postburner` left in place, test enqueues stay out of Beanstalkd until the test calls `Postburner.default_strategy!` or `Postburner.strict_strategy!`.
 
-By default, Rails uses the `:test` adapter in test mode unless you override it. Since you set `:postburner` as your adapter in `config/application.rb`, you should set it back to `:test` for your test environment:
+Rails uses the `:test` adapter in the test environment unless the application sets another one:
 
 ```ruby
 # config/environments/test.rb
 config.active_job.queue_adapter = :test
 ```
 
-This is standard practice for any ActiveJob adapter (Sidekiq, SolidQueue, etc.) — the production adapter handles real execution, and the `:test` adapter enables Rails' built-in assertion helpers. Without this, `assert_enqueued_emails` will not work because Postburner's adapter executes jobs rather than tracking them in an array.
+Without the `:test` adapter, `assert_enqueued_emails` does not see the enqueue. Postburner does not run the job in its place, and it does not put one on a tube either.
 
 **`Postburner::Mailer`** bypasses ActiveJob entirely, so `assert_enqueued_emails` cannot see these jobs regardless of adapter. Assert on side effects instead:
 

data/app/models/postburner/schedule_execution.rb

@@ -144,7 +144,9 @@ module Postburner
       # BOTH enqueue paths defer the actual Beanstalkd insertion until this
       # transaction commits:
       #  - Postburner::Job#queue! inserts via an after-commit hook;
-      #  - the ActiveJob adapter declares enqueue_after_transaction_commit?.
+      #  - selecting the Postburner adapter sets
+      #    ActiveJob::Base.enqueue_after_transaction_commit, so Rails holds
+      #    the adapter enqueue until this transaction commits.
       # So the real Beanstalkd id (and, for tracked ActiveJobs, the TrackedJob
       # row) only exists AFTER the transaction below. We capture the job here and
       # link/record the Beanstalkd id afterward.
@@ -378,11 +380,12 @@ module Postburner
     # Creates and enqueues an ActiveJob instance with the scheduled run_at time.
     # Handles both Hash args (passed as keyword arguments) and Array args (splatted).
     #
-    # IMPORTANT: the Postburner ActiveJob adapter declares
-    # enqueue_after_transaction_commit?, so the actual Beanstalkd put is deferred
-    # until the surrounding transaction commits. This method therefore only
-    # *registers* the enqueue; the resulting beanstalk_job_id (and, for tracked
-    # ActiveJobs, the TrackedJob record) are not available until after commit.
+    # IMPORTANT: selecting the Postburner adapter sets
+    # ActiveJob::Base.enqueue_after_transaction_commit, so Rails defers the
+    # actual Beanstalkd put until the surrounding transaction commits. This
+    # method therefore only *registers* the enqueue; the resulting
+    # beanstalk_job_id (and, for tracked ActiveJobs, the TrackedJob record)
+    # are not available until after commit.
     # Linking is the caller's responsibility via {#link_activejob!}.
     #
     # @return [ActiveJob::Base] the enqueued job, to be linked after commit

data/lib/postburner/active_job/adapter.rb

@@ -53,6 +53,17 @@ module ActiveJob
     #   end
     #
     class PostburnerAdapter
+      # Rails 8 reads `ActiveJob::Base.enqueue_after_transaction_commit` and
+      # never calls {#enqueue_after_transaction_commit?}. Setting it here, when
+      # the adapter is selected, covers jobs that inherit `ActiveJob::Base`
+      # directly (Turbo broadcasts, Action Mailer). A job class that uses a
+      # different adapter in the same process inherits the same deferral.
+      # The put then runs after commit, so a Beanstalkd failure raises after
+      # the surrounding data is committed and the enqueue is dropped on rollback.
+      def initialize(*)
+        ActiveJob::Base.enqueue_after_transaction_commit = true
+      end
+
       # Enqueues a job for immediate execution.
       #
       # @param job [ActiveJob::Base] The job to enqueue
@@ -71,19 +82,17 @@ module ActiveJob
       # @return [void]
       #
       def enqueue_at(job, timestamp)
-        if tracked?(job)
+        if Postburner.suppress_active_job_enqueue?
+          enqueue_for_test(job, timestamp)
+        elsif tracked?(job)
           enqueue_tracked(job, timestamp)
         else
           enqueue_default(job, timestamp)
         end
       end
 
-      # Indicates whether the adapter supports enqueuing after transaction commit.
-      #
-      # Returns true because Postburner uses Beanstalkd (external queue),
-      # which means jobs are safely enqueued outside the database transaction.
-      # This allows Rails to automatically defer job enqueuing until after
-      # the current database transaction commits.
+      # @deprecated Rails 8 does not call this. {#initialize} sets
+      #   `ActiveJob::Base.enqueue_after_transaction_commit` instead.
       #
       # @return [Boolean] Always returns true
       #
@@ -147,6 +156,32 @@ module ActiveJob
         hook.call(job) || {}
       end
 
+      # Test enqueue. Writes a tracked row when the job is tracked, emits the
+      # enqueue notification, and does not put to Beanstalkd.
+      #
+      # Reached only from {Postburner.suppress_active_job_enqueue?}, which is
+      # true in the test environment while a testing strategy is active.
+      # Outside test the adapter puts even when the strategy is {Postburner::NullQueue}.
+      # {Postburner.default_strategy!} and {Postburner.strict_strategy!} are
+      # the opt-in that puts in test.
+      #
+      # @param job [ActiveJob::Base] The job instance
+      # @param timestamp [Time, nil] When to execute the job
+      #
+      # @return [void]
+      #
+      def enqueue_for_test(job, timestamp)
+        tracked_job = tracked?(job) ? create_tracked_record(job, timestamp) : nil
+        job.provider_job_id = nil
+        instrument_enqueue(
+          job,
+          timestamp,
+          tracked: !tracked_job.nil?,
+          postburner_job_id: tracked_job&.id,
+          beanstalk_job_id: nil
+        )
+      end
+
       # Enqueues a tracked job (with PostgreSQL audit trail).
       #
       # Creates a Postburner::TrackedJob record, then queues minimal payload
@@ -162,12 +197,7 @@ module ActiveJob
       # @return [void]
       #
       def enqueue_tracked(job, timestamp)
-        # Create Postburner::TrackedJob record
-        tracked_job = Postburner::TrackedJob.create!(
-          args: Postburner::ActiveJob::Payload.serialize_for_tracked(job),
-          run_at: timestamp ? Time.zone.at(timestamp) : nil,
-          queued_at: Time.current
-        )
+        tracked_job = create_tracked_record(job, timestamp)
 
         # Calculate delay for Beanstalkd
         # ceil so the job is never released before its timestamp; see
@@ -198,25 +228,13 @@ module ActiveJob
         # callers (e.g. ScheduleExecution) can capture it after enqueue.
         job.provider_job_id = bkid
 
-        # Instrument enqueue event
-        job_payload = Postburner::Instrumentation.job_payload_from_activejob(
+        instrument_enqueue(
           job,
+          timestamp,
           tracked: true,
           postburner_job_id: tracked_job.id,
           beanstalk_job_id: bkid
         )
-        scheduled_at = timestamp ? Time.zone.at(timestamp) : nil
-
-        if scheduled_at && scheduled_at > Time.current
-          ActiveSupport::Notifications.instrument('enqueue_at.job.postburner', {
-            job: job_payload,
-            scheduled_at: scheduled_at
-          })
-        else
-          ActiveSupport::Notifications.instrument('enqueue.job.postburner', {
-            job: job_payload
-          })
-        end
       end
 
       # Enqueues a default job (Beanstalkd only, no PostgreSQL).
@@ -258,13 +276,47 @@ module ActiveJob
         # callers (e.g. ScheduleExecution) can capture it after enqueue.
         job.provider_job_id = bkid
 
-        # Instrument enqueue event
-        job_payload = Postburner::Instrumentation.job_payload_from_activejob(
+        instrument_enqueue(
           job,
+          timestamp,
           tracked: false,
           postburner_job_id: nil,
           beanstalk_job_id: bkid
         )
+      end
+
+      # Creates the PostgreSQL row for a tracked ActiveJob.
+      #
+      # @param job [ActiveJob::Base] The job instance
+      # @param timestamp [Numeric, nil] Scheduled time as a unix timestamp
+      #
+      # @return [Postburner::TrackedJob]
+      #
+      def create_tracked_record(job, timestamp)
+        Postburner::TrackedJob.create!(
+          args: Postburner::ActiveJob::Payload.serialize_for_tracked(job),
+          run_at: timestamp ? Time.zone.at(timestamp) : nil,
+          queued_at: Time.current
+        )
+      end
+
+      # Emits enqueue or enqueue_at for an ActiveJob.
+      #
+      # @param job [ActiveJob::Base]
+      # @param timestamp [Numeric, nil]
+      # @param tracked [Boolean]
+      # @param postburner_job_id [Integer, nil]
+      # @param beanstalk_job_id [Integer, nil]
+      #
+      # @return [void]
+      #
+      def instrument_enqueue(job, timestamp, tracked:, postburner_job_id:, beanstalk_job_id:)
+        job_payload = Postburner::Instrumentation.job_payload_from_activejob(
+          job,
+          tracked: tracked,
+          postburner_job_id: postburner_job_id,
+          beanstalk_job_id: beanstalk_job_id
+        )
         scheduled_at = timestamp ? Time.zone.at(timestamp) : nil
 
         if scheduled_at && scheduled_at > Time.current

data/lib/postburner/engine.rb

@@ -13,5 +13,21 @@ module Postburner
       g.skip_routes true
     end
 
+    # Choose the test strategy once boot has finished applying configuration.
+    # after_initialize runs after config/initializers and before a test helper
+    # continues. The configured adapter is already a name here, so this does
+    # not load ActiveJob::Base. An application that already assigned a
+    # strategy keeps that choice.
+    #
+    # The hook runs in every environment. {Postburner.install_test_queue_strategy_for}
+    # returns before reading +config.active_job+ outside test, and when the
+    # app did not load the ActiveJob railtie. That config namespace does not
+    # exist unless the railtie is required.
+    initializer "postburner.active_job_test_strategy", after: "active_job.set_configs" do |app|
+      app.config.after_initialize do
+        Postburner.install_test_queue_strategy_for(app)
+      end
+    end
+
   end
 end

data/lib/postburner/strategies/inline_test_queue.rb

@@ -7,7 +7,7 @@ module Postburner
   # tests fast and predictable. It raises {Postburner::Job::PrematurePerform} if
   # a job has a future run_at, forcing you to use explicit time travel in tests.
   #
-  # @note Auto-detected when Rails.env.test? and ActiveJob adapter is :test
+  # @note Selected in the Rails test environment when the ActiveJob adapter is `:test`
   #
   # ## When to Use InlineTestQueue
   #

data/lib/postburner/strategies/null_queue.rb

@@ -9,7 +9,10 @@ module Postburner
   # to Beanstalkd. Jobs can be manually executed later using {.handle_perform!},
   # which includes automatic time travel for scheduled jobs.
   #
-  # @note This is a test-mode strategy (returns true for testing)
+  # @note This is a test-mode strategy (returns true for testing).
+  #   Selected in the Rails test environment when the ActiveJob adapter is `:postburner`.
+  #   Outside the test environment it still keeps {Postburner::Job} off
+  #   Beanstalkd. ActiveJob `perform_later` continues to put.
   #
   # ## When to Use NullQueue
   #

data/lib/postburner/version.rb

@@ -1,3 +1,3 @@
 module Postburner
-  VERSION = '1.0.0.rc.7'
+  VERSION = '1.0.0.rc.8'
 end

data/lib/postburner.rb

@@ -45,9 +45,19 @@ require "postburner/test_helpers"
 #
 # ## Auto-Detection
 #
-# Postburner automatically detects Rails test mode and switches to {InlineTestQueue} when:
-# - `Rails.env.test?` is true
-# - `ActiveJob::Base.queue_adapter_name == :test`
+# During `after_initialize`, {#install_test_queue_strategy!} reads
+# `config.active_job.queue_adapter` and selects the test strategy. It does
+# not wait for `ActiveJob::Base` to load, and it leaves a strategy the
+# application already assigned in place.
+#
+# - `:test` → {InlineTestQueue}. `Postburner::Job#queue!` runs in process.
+# - `:postburner` → {NullQueue}. The row is kept. In the test environment
+#   the ActiveJob adapter does not put. {#default_strategy!} or
+#   {#strict_strategy!} is the opt-in that writes to Beanstalkd.
+# - Any other adapter leaves the current strategy unchanged.
+#
+# Outside the test environment the adapter always puts. A testing strategy
+# still keeps {Postburner::Job} off Beanstalkd.
 #
 # ## Usage
 #
@@ -67,17 +77,17 @@ require "postburner/test_helpers"
 #   job.queue!(delay: 1.hour)
 #
 # @example Switching queue strategies
-#   # Production with graceful premature handling (default)
-#   Postburner.nice_async_strategy!
+#   # Production default. Premature jobs are re-inserted with a delay.
+#   Postburner.default_strategy!
 #
 #   # Production with strict premature errors
-#   Postburner.async_strategy!
+#   Postburner.strict_strategy!
 #
 #   # Test mode with explicit time control
 #   Postburner.inline_test_strategy!
 #
 #   # Test mode with automatic time travel
-#   Postburner.inline_immediate_test_strategy!
+#   Postburner.time_travel_test_strategy!
 #
 # @example Using Beanstalkd connection
 #   Postburner.connected do |conn|
@@ -87,7 +97,8 @@ require "postburner/test_helpers"
 #
 # @example Checking if in test mode
 #   if Postburner.testing?
-#     # Jobs execute inline
+#     # Postburner::Job stays off Beanstalkd. In the test environment the
+#     # ActiveJob adapter does not put either.
 #   else
 #     # Jobs queued to Beanstalkd
 #   end
@@ -99,13 +110,15 @@ require "postburner/test_helpers"
 # @see TimeTravelTestQueue
 #
 module Postburner
-  # @!attribute [rw] queue_strategy
+  # @!attribute [r] queue_strategy
   #   The current queue strategy class used for job execution.
   #
-  #   Defaults to {DefaultQueue} for production, auto-switches to {InlineTestQueue}
-  #   in Rails test environment.
+  #   Defaults to {DefaultQueue}. In the Rails test environment,
+  #   {#install_test_queue_strategy!} switches to {InlineTestQueue} when the
+  #   ActiveJob adapter is `:test`, and to {NullQueue} when it is `:postburner`,
+  #   unless the application has already assigned a strategy.
   #
-  #   @return [Class] One of StrictQueue, DefaultQueue, InlineTestQueue, or TimeTravelTestQueue
+  #   @return [Class] One of StrictQueue, DefaultQueue, InlineTestQueue, TimeTravelTestQueue, or NullQueue
   #
   #   @example
   #     Postburner.queue_strategy
@@ -116,18 +129,143 @@ module Postburner
   #   @see #inline_test_strategy!
   #   @see #time_travel_test_strategy!
   #
-  mattr_accessor :queue_strategy
+  mattr_reader :queue_strategy
+
+  # Assigns the queue strategy and records it as the application's choice.
+  #
+  # {#install_test_queue_strategy!} will not replace a strategy assigned
+  # through this writer or through a `*_strategy!` setter. The load-time
+  # default is applied without marking that choice.
+  #
+  # @param strategy [Class] A queue strategy class
+  # @return [Class]
+  #
+  def self.queue_strategy=(strategy)
+    @queue_strategy_explicit = true unless @applying_queue_strategy
+    @@queue_strategy = strategy
+  end
+
+  # True when application code assigned {#queue_strategy}, rather than the
+  # load-time default or {#install_test_queue_strategy!}.
+  #
+  # @return [Boolean]
+  #
+  def self.queue_strategy_explicit?
+    @queue_strategy_explicit == true
+  end
+
+  # Selects the queue strategy for the Rails test environment from the
+  # configured ActiveJob adapter. See the Auto-Detection section above.
+  #
+  # Called from {#install_test_queue_strategy_for} during `after_initialize`,
+  # which runs after `config/initializers` and before a test helper continues.
+  # The argument is `config.active_job.queue_adapter`. This method does not
+  # read `ActiveJob::Base.queue_adapter_name`, because that loads ActiveJob
+  # and forces `:async` when the adapter is still unset.
+  #
+  # No-op outside the test environment. No-op when {#queue_strategy_explicit?}
+  # is true. An adapter other than `:test` or `:postburner` leaves the
+  # current strategy unchanged.
+  #
+  # @param adapter [Symbol, String, Object, nil] Adapter name or instance.
+  #   `nil` reads `Rails.application.config.active_job.queue_adapter`.
+  # @return [void]
+  #
+  def self.install_test_queue_strategy!(adapter = nil)
+    return unless defined?(Rails) && Rails.env.test?
+    return if queue_strategy_explicit?
+
+    case adapter_name_for_install(adapter)
+    when "test"
+      apply_queue_strategy(InlineTestQueue)
+    when "postburner"
+      apply_queue_strategy(NullQueue)
+    end
+  end
+
+  # Engine entry point for {#install_test_queue_strategy!}.
+  #
+  # Returns before reading +config.active_job+ unless this is the test
+  # environment and the application loaded the ActiveJob railtie. Without
+  # that railtie, +Rails::Application::Configuration+ has no +active_job+
+  # method, and reading it raises during boot.
+  #
+  # @param app [Rails::Application]
+  # @return [void]
+  #
+  def self.install_test_queue_strategy_for(app)
+    return unless defined?(Rails) && Rails.env.test?
+    return unless app.config.respond_to?(:active_job)
+
+    install_test_queue_strategy!(app.config.active_job.queue_adapter)
+  end
+
+  # True when the ActiveJob adapter should record the enqueue and skip the
+  # Beanstalkd put.
+  #
+  # Limited to the test environment. A testing strategy in production still
+  # only governs {Postburner::Job}: `perform_later`, `deliver_later`, and
+  # `broadcast_*_later` keep writing to the tube.
+  #
+  # @return [Boolean]
+  #
+  def self.suppress_active_job_enqueue?
+    return false unless defined?(Rails) && Rails.env.test?
+    testing?
+  end
+
+  # Assigns a strategy without recording an application choice.
+  #
+  # @param strategy [Class]
+  # @return [Class]
+  # @api private
+  #
+  def self.apply_queue_strategy(strategy)
+    previous = @applying_queue_strategy
+    @applying_queue_strategy = true
+    self.queue_strategy = strategy
+  ensure
+    @applying_queue_strategy = previous
+  end
+  private_class_method :apply_queue_strategy
+
+  # @param adapter [Symbol, String, Object, nil]
+  # @return [String, nil]
+  # @api private
+  #
+  def self.adapter_name_for_install(adapter)
+    adapter = configured_active_job_adapter if adapter.nil?
+    return if adapter.nil?
 
-  # Initialize with DefaultQueue (production) by default
-  # DefaultQueue re-inserts premature jobs with appropriate delay
-  self.queue_strategy = Postburner::DefaultQueue
+    case adapter
+    when Symbol, String
+      adapter.to_s
+    else
+      return unless defined?(::ActiveJob) && ::ActiveJob.respond_to?(:adapter_name)
 
-  # Auto-detect Rails test mode and switch to InlineTestQueue
-  if defined?(Rails) && Rails.env.test? && defined?(::ActiveJob::Base)
-    if ::ActiveJob::Base.queue_adapter_name == :test
-      self.queue_strategy = Postburner::InlineTestQueue
+      ::ActiveJob.adapter_name(adapter).to_s.underscore
     end
   end
+  private_class_method :adapter_name_for_install
+
+  # @return [Object, nil]
+  # @api private
+  #
+  def self.configured_active_job_adapter
+    return unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+
+    config = Rails.application.config
+    return unless config.respond_to?(:active_job)
+
+    config.active_job.queue_adapter
+  end
+  private_class_method :configured_active_job_adapter
+
+  # DefaultQueue re-inserts premature jobs with a delay. The test strategy is
+  # applied later by {#install_test_queue_strategy!}. Assigning it here does
+  # not count as an application choice. Reading the adapter name at require
+  # time would force :async before the application sets it.
+  apply_queue_strategy(Postburner::DefaultQueue)
 
   # Activates strict test mode with inline job execution.
   #
@@ -154,7 +292,7 @@ module Postburner
   #   # Raises PrematurePerform - use travel_to instead
   #
   # @see InlineTestQueue
-  # @see #inline_immediate_test_strategy!
+  # @see #time_travel_test_strategy!
   #
   def self.inline_test_strategy!
     self.queue_strategy = Postburner::InlineTestQueue
@@ -282,16 +420,18 @@ module Postburner
     self.queue_strategy = Postburner::NullQueue
   end
 
-  # Checks if currently using a test queue strategy.
+  # Checks if the current queue strategy is a testing strategy.
   #
-  # Returns true if the current queue strategy is {InlineTestQueue} or
-  # {TimeTravelTestQueue}, indicating that jobs execute inline/synchronously
-  # without Beanstalkd.
+  # True for {NullQueue}, {InlineTestQueue}, and {TimeTravelTestQueue}.
+  # Those strategies keep {Postburner::Job} off Beanstalkd. In the test
+  # environment they also tell the ActiveJob adapter not to put. Outside
+  # test, the adapter puts even when this is true. {DefaultQueue} and
+  # {StrictQueue} put in every environment.
   #
-  # @return [Boolean] true if using test strategy, false if using production strategy
+  # @return [Boolean] true if using a testing strategy
   #
   # @example
-  #   Postburner.nice_async_strategy!
+  #   Postburner.default_strategy!
   #   Postburner.testing?  # => false
   #
   #   Postburner.inline_test_strategy!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: postburner
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc.7
+  version: 1.0.0.rc.8
 platform: ruby
 authors:
 - Matt Smith