@rvoh/psychic-workers 2.8.1 → 2.9.0

package/dist/cjs/src/background/BaseBackgroundedModel.js

@@ -36,13 +36,13 @@ export default class BaseBackgroundedModel extends Dream {
      * ```ts
      * await User.background('myMethod', 'abc', 123)
      * ```
-     * though calling background must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
+     * Outside automatic test invocation, awaiting `background` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`.
      *
      * @param methodName - the name of the static method you wish to run in the background
      * @param args - a variadic list of arguments to be sent to your method
@@ -71,12 +71,13 @@ export default class BaseBackgroundedModel extends Dream {
      * ```ts
      * await User.backgroundWithDelay({ minutes: 5 }, 'myMethod', 'abc', 123)
      * ```
-     * though calling backgroundWithDelay must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWithDelay` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
      *
@@ -110,12 +111,13 @@ export default class BaseBackgroundedModel extends Dream {
      * ```ts
      * await User.backgroundWith({ delay: { seconds: 30, jobId: 'my-unique-job-id' }, priority: 'urgent' }, 'myMethod', 'abc', 123)
      * ```
-     * though calling backgroundWith must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWith` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @param opts - options for backgrounding this job
      * @param opts.delay - (optional) how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run
@@ -150,13 +152,13 @@ export default class BaseBackgroundedModel extends Dream {
      * const user = await User.lastOrFail()
      * await user.background('myMethod', 'abc', 123)
      * ```
-     * though calling background must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
+     * Outside automatic test invocation, awaiting `background` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`.
      *
      * @param methodName - the name of the instance method you wish to run in the background
      * @param args - a variadic list of arguments to be sent to your method
@@ -185,12 +187,13 @@ export default class BaseBackgroundedModel extends Dream {
      * const user = await User.lastOrFail()
      * await user.backgroundWithDelay({ minutes: 5 }, 'myMethod', 'abc', 123)
      * ```
-     * though calling backgroundWithDelay must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWithDelay` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
      *
@@ -224,12 +227,13 @@ export default class BaseBackgroundedModel extends Dream {
      * const user = await User.lastOrFail()
      * await user.backgroundWith({ delay: { seconds: 30, jobId: 'my-unique-job-id' }, priority: 'urgent' }, 'myMethod', 'abc', 123)
      * ```
-     * though calling backgroundWith must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWith` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @param opts - options for backgrounding this job
      * @param opts.delay - (optional) how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run

package/dist/cjs/src/background/BaseBackgroundedService.js

@@ -47,13 +47,13 @@ export default class BaseBackgroundedService {
      * ```ts
      * await MyBackgroundableClass.background('myMethod', 'abc', 123)
      * ```
-     * though calling background must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
+     * Outside automatic test invocation, awaiting `background` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`.
      *
      * @param methodName - the name of the static method you wish to run in the background
      * @param args - a variadic list of arguments to be sent to your method
@@ -82,12 +82,13 @@ export default class BaseBackgroundedService {
      * ```ts
      * await MyBackgroundableClass.backgroundWithDelay({ minutes: 5 }, 'myMethod', 'abc', 123)
      * ```
-     * though calling backgroundWithDelay must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWithDelay` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
      *
@@ -126,12 +127,13 @@ export default class BaseBackgroundedService {
      *   123,
      * )
      * ```
-     * though calling backgroundWith must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWith` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @param opts - options for backgrounding this job
      * @param opts.delay - (optional) how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run

package/dist/cjs/src/background/BaseScheduledService.js

@@ -46,13 +46,15 @@ export default class BaseScheduledService {
      * ```ts
      * await MySchedulableClass.schedule('0 * * * *', 'myHourlyMethod', 'abc', 123)
      * ```
-     * though calling background must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
-     *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * Awaiting `schedule` confirms that the BullMQ job scheduler has been
+     * registered or updated in Redis. It does not invoke the method inline or
+     * wait for any scheduled run to complete. Independent queue workers may
+     * still execute scheduled runs asynchronously.
+     *
+     * In tests, this registration behavior is the same under both
+     * `testInvocation: 'automatic'` and `testInvocation: 'manual'`. To exercise
+     * the scheduled job, call `WorkerTestUtils.workScheduled()`, or invoke the
+     * method directly to test its body.
      *
      * @param pattern - A cron string representing the time interval you wish this to run on
      * @param methodName - the name of the static method you wish to run in the background

package/dist/cjs/src/psychic-app-workers/index.js

@@ -43,12 +43,18 @@ export default class PsychicAppWorkers {
     /**
      * Returns the testInvocation option provided by the user
      *
-     * when "automatic", any backgrounded job will be immediately
-     * invoked during tests. This is the default behavior
+     * With "automatic" (the default), one-off backgrounded jobs invoke their
+     * methods immediately during tests, ignoring delays. The backgrounding call
+     * awaits the method's completion.
      *
-     * when "manual", this will enable the dev to manually interact with
-     * queues, enabling them to target jobs and run them at specific
-     * code points.
+     * With "manual", one-off jobs are queued for explicit processing with
+     * `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` for delayed
+     * jobs, so tests can choose when to invoke them.
+     *
+     * Under either mode, `schedule()` registers or updates a scheduler in Redis
+     * without invoking the scheduled method inline. Use
+     * `WorkerTestUtils.workScheduled()` to exercise its dispatch, or invoke the
+     * method directly to test its body.
      */
     get testInvocation() {
         return this._testInvocation;

package/dist/esm/src/background/BaseBackgroundedModel.js

@@ -36,13 +36,13 @@ export default class BaseBackgroundedModel extends Dream {
      * ```ts
      * await User.background('myMethod', 'abc', 123)
      * ```
-     * though calling background must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
+     * Outside automatic test invocation, awaiting `background` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`.
      *
      * @param methodName - the name of the static method you wish to run in the background
      * @param args - a variadic list of arguments to be sent to your method
@@ -71,12 +71,13 @@ export default class BaseBackgroundedModel extends Dream {
      * ```ts
      * await User.backgroundWithDelay({ minutes: 5 }, 'myMethod', 'abc', 123)
      * ```
-     * though calling backgroundWithDelay must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWithDelay` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
      *
@@ -110,12 +111,13 @@ export default class BaseBackgroundedModel extends Dream {
      * ```ts
      * await User.backgroundWith({ delay: { seconds: 30, jobId: 'my-unique-job-id' }, priority: 'urgent' }, 'myMethod', 'abc', 123)
      * ```
-     * though calling backgroundWith must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWith` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @param opts - options for backgrounding this job
      * @param opts.delay - (optional) how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run
@@ -150,13 +152,13 @@ export default class BaseBackgroundedModel extends Dream {
      * const user = await User.lastOrFail()
      * await user.background('myMethod', 'abc', 123)
      * ```
-     * though calling background must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
+     * Outside automatic test invocation, awaiting `background` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`.
      *
      * @param methodName - the name of the instance method you wish to run in the background
      * @param args - a variadic list of arguments to be sent to your method
@@ -185,12 +187,13 @@ export default class BaseBackgroundedModel extends Dream {
      * const user = await User.lastOrFail()
      * await user.backgroundWithDelay({ minutes: 5 }, 'myMethod', 'abc', 123)
      * ```
-     * though calling backgroundWithDelay must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWithDelay` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
      *
@@ -224,12 +227,13 @@ export default class BaseBackgroundedModel extends Dream {
      * const user = await User.lastOrFail()
      * await user.backgroundWith({ delay: { seconds: 30, jobId: 'my-unique-job-id' }, priority: 'urgent' }, 'myMethod', 'abc', 123)
      * ```
-     * though calling backgroundWith must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWith` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @param opts - options for backgrounding this job
      * @param opts.delay - (optional) how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run

package/dist/esm/src/background/BaseBackgroundedService.js

@@ -47,13 +47,13 @@ export default class BaseBackgroundedService {
      * ```ts
      * await MyBackgroundableClass.background('myMethod', 'abc', 123)
      * ```
-     * though calling background must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
+     * Outside automatic test invocation, awaiting `background` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`.
      *
      * @param methodName - the name of the static method you wish to run in the background
      * @param args - a variadic list of arguments to be sent to your method
@@ -82,12 +82,13 @@ export default class BaseBackgroundedService {
      * ```ts
      * await MyBackgroundableClass.backgroundWithDelay({ minutes: 5 }, 'myMethod', 'abc', 123)
      * ```
-     * though calling backgroundWithDelay must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWithDelay` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
      *
@@ -126,12 +127,13 @@ export default class BaseBackgroundedService {
      *   123,
      * )
      * ```
-     * though calling backgroundWith must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWith` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @param opts - options for backgrounding this job
      * @param opts.delay - (optional) how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run

package/dist/esm/src/background/BaseScheduledService.js

@@ -46,13 +46,15 @@ export default class BaseScheduledService {
      * ```ts
      * await MySchedulableClass.schedule('0 * * * *', 'myHourlyMethod', 'abc', 123)
      * ```
-     * though calling background must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
-     *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * Awaiting `schedule` confirms that the BullMQ job scheduler has been
+     * registered or updated in Redis. It does not invoke the method inline or
+     * wait for any scheduled run to complete. Independent queue workers may
+     * still execute scheduled runs asynchronously.
+     *
+     * In tests, this registration behavior is the same under both
+     * `testInvocation: 'automatic'` and `testInvocation: 'manual'`. To exercise
+     * the scheduled job, call `WorkerTestUtils.workScheduled()`, or invoke the
+     * method directly to test its body.
      *
      * @param pattern - A cron string representing the time interval you wish this to run on
      * @param methodName - the name of the static method you wish to run in the background

package/dist/esm/src/psychic-app-workers/index.js

@@ -43,12 +43,18 @@ export default class PsychicAppWorkers {
     /**
      * Returns the testInvocation option provided by the user
      *
-     * when "automatic", any backgrounded job will be immediately
-     * invoked during tests. This is the default behavior
+     * With "automatic" (the default), one-off backgrounded jobs invoke their
+     * methods immediately during tests, ignoring delays. The backgrounding call
+     * awaits the method's completion.
      *
-     * when "manual", this will enable the dev to manually interact with
-     * queues, enabling them to target jobs and run them at specific
-     * code points.
+     * With "manual", one-off jobs are queued for explicit processing with
+     * `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` for delayed
+     * jobs, so tests can choose when to invoke them.
+     *
+     * Under either mode, `schedule()` registers or updates a scheduler in Redis
+     * without invoking the scheduled method inline. Use
+     * `WorkerTestUtils.workScheduled()` to exercise its dispatch, or invoke the
+     * method directly to test its body.
      */
     get testInvocation() {
         return this._testInvocation;

package/dist/types/src/background/BaseBackgroundedModel.d.ts

@@ -31,13 +31,13 @@ export default class BaseBackgroundedModel extends Dream {
      * ```ts
      * await User.background('myMethod', 'abc', 123)
      * ```
-     * though calling background must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
+     * Outside automatic test invocation, awaiting `background` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`.
      *
      * @param methodName - the name of the static method you wish to run in the background
      * @param args - a variadic list of arguments to be sent to your method
@@ -59,12 +59,13 @@ export default class BaseBackgroundedModel extends Dream {
      * ```ts
      * await User.backgroundWithDelay({ minutes: 5 }, 'myMethod', 'abc', 123)
      * ```
-     * though calling backgroundWithDelay must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWithDelay` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
      *
@@ -89,12 +90,13 @@ export default class BaseBackgroundedModel extends Dream {
      * ```ts
      * await User.backgroundWith({ delay: { seconds: 30, jobId: 'my-unique-job-id' }, priority: 'urgent' }, 'myMethod', 'abc', 123)
      * ```
-     * though calling backgroundWith must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWith` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @param opts - options for backgrounding this job
      * @param opts.delay - (optional) how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run
@@ -118,13 +120,13 @@ export default class BaseBackgroundedModel extends Dream {
      * const user = await User.lastOrFail()
      * await user.background('myMethod', 'abc', 123)
      * ```
-     * though calling background must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
+     * Outside automatic test invocation, awaiting `background` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`.
      *
      * @param methodName - the name of the instance method you wish to run in the background
      * @param args - a variadic list of arguments to be sent to your method
@@ -147,12 +149,13 @@ export default class BaseBackgroundedModel extends Dream {
      * const user = await User.lastOrFail()
      * await user.backgroundWithDelay({ minutes: 5 }, 'myMethod', 'abc', 123)
      * ```
-     * though calling backgroundWithDelay must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWithDelay` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
      *
@@ -178,12 +181,13 @@ export default class BaseBackgroundedModel extends Dream {
      * const user = await User.lastOrFail()
      * await user.backgroundWith({ delay: { seconds: 30, jobId: 'my-unique-job-id' }, priority: 'urgent' }, 'myMethod', 'abc', 123)
      * ```
-     * though calling backgroundWith must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWith` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @param opts - options for backgrounding this job
      * @param opts.delay - (optional) how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run

package/dist/types/src/background/BaseBackgroundedService.d.ts

@@ -39,13 +39,13 @@ export default class BaseBackgroundedService {
      * ```ts
      * await MyBackgroundableClass.background('myMethod', 'abc', 123)
      * ```
-     * though calling background must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
+     * Outside automatic test invocation, awaiting `background` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`.
      *
      * @param methodName - the name of the static method you wish to run in the background
      * @param args - a variadic list of arguments to be sent to your method
@@ -67,12 +67,13 @@ export default class BaseBackgroundedService {
      * ```ts
      * await MyBackgroundableClass.backgroundWithDelay({ minutes: 5 }, 'myMethod', 'abc', 123)
      * ```
-     * though calling backgroundWithDelay must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWithDelay` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @deprecated use `backgroundWith({ delay }, methodName, ...args)` instead. This method will be removed in a future major version.
      *
@@ -102,12 +103,13 @@ export default class BaseBackgroundedService {
      *   123,
      * )
      * ```
-     * though calling backgroundWith must be awaited, the resolution of the promise
-     * is an indication that a run is pending, not that it has completed.
+     * Outside automatic test invocation, awaiting `backgroundWith` confirms that
+     * a run is queued or pending, not that the method has completed.
      *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * In tests with `testInvocation: 'automatic'` (the default), Psychic invokes
+     * the method immediately and awaits its completion, ignoring the delay.
+     * With `testInvocation: 'manual'`, the job is queued for explicit processing
+     * with `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` when delayed.
      *
      * @param opts - options for backgrounding this job
      * @param opts.delay - (optional) how long you want to hold off before allowing the job to run, given as at least one of `seconds`, `minutes`, `hours` or `days`, plus an optional `jobId` (a deduplication key) which debounces repeated calls into a single run

package/dist/types/src/background/BaseScheduledService.d.ts

@@ -38,13 +38,15 @@ export default class BaseScheduledService {
      * ```ts
      * await MySchedulableClass.schedule('0 * * * *', 'myHourlyMethod', 'abc', 123)
      * ```
-     * though calling background must be awaited, the resolution of the promise
-     * is an indication that the job was put in the queue, not that it has
-     * completed.
-     *
-     * NOTE: in test environments, psychic will immediately invoke the underlying
-     * method, preventing you from needing to explicitly wait for queues to flush
-     * before making assertions.
+     * Awaiting `schedule` confirms that the BullMQ job scheduler has been
+     * registered or updated in Redis. It does not invoke the method inline or
+     * wait for any scheduled run to complete. Independent queue workers may
+     * still execute scheduled runs asynchronously.
+     *
+     * In tests, this registration behavior is the same under both
+     * `testInvocation: 'automatic'` and `testInvocation: 'manual'`. To exercise
+     * the scheduled job, call `WorkerTestUtils.workScheduled()`, or invoke the
+     * method directly to test its body.
      *
      * @param pattern - A cron string representing the time interval you wish this to run on
      * @param methodName - the name of the static method you wish to run in the background

package/dist/types/src/helpers/EnvInternal.d.ts

@@ -2,6 +2,5 @@ import { Env } from '@rvoh/dream';
 declare const EnvInternal: Env<{
     string: "NODE_ENV" | "PSYCHIC_CORE_DEVELOPMENT";
     integer: "VITEST_POOL_ID";
-    boolean: "REALLY_TEST_BACKGROUND_QUEUE";
-}, "NODE_ENV" | "PSYCHIC_CORE_DEVELOPMENT", "VITEST_POOL_ID", "REALLY_TEST_BACKGROUND_QUEUE">;
+}, "NODE_ENV" | "PSYCHIC_CORE_DEVELOPMENT", "VITEST_POOL_ID", never>;
 export default EnvInternal;

package/dist/types/src/psychic-app-workers/index.d.ts

@@ -21,12 +21,18 @@ export default class PsychicAppWorkers {
     /**
      * Returns the testInvocation option provided by the user
      *
-     * when "automatic", any backgrounded job will be immediately
-     * invoked during tests. This is the default behavior
+     * With "automatic" (the default), one-off backgrounded jobs invoke their
+     * methods immediately during tests, ignoring delays. The backgrounding call
+     * awaits the method's completion.
      *
-     * when "manual", this will enable the dev to manually interact with
-     * queues, enabling them to target jobs and run them at specific
-     * code points.
+     * With "manual", one-off jobs are queued for explicit processing with
+     * `WorkerTestUtils.work()`, or `WorkerTestUtils.workScheduled()` for delayed
+     * jobs, so tests can choose when to invoke them.
+     *
+     * Under either mode, `schedule()` registers or updates a scheduler in Redis
+     * without invoking the scheduled method inline. Use
+     * `WorkerTestUtils.workScheduled()` to exercise its dispatch, or invoke the
+     * method directly to test its body.
      */
     get testInvocation(): PsychicWorkersAppTestInvocationType;
     private _testInvocation;
@@ -53,7 +59,17 @@ export type PsychicWorkersHookEventType = 'workers:shutdown';
 export interface PsychicWorkersAppHooks {
     workerShutdown: (() => void | Promise<void>)[];
 }
-export interface BullMQNativeWorkerOptions extends WorkerOptions {
+/**
+ * Native worker options omit `connection`: Psychic supplies the resolved
+ * queue-side worker connection when constructing each worker. A `connection`
+ * previously supplied here was ignored; deleting it preserves runtime behavior.
+ *
+ * To deliberately configure a worker's Redis/Cluster instance, use
+ * `nativeBullMQ.defaultQueueOptions.workerConnection`,
+ * `nativeBullMQ.namedQueueOptions[name].workerConnection`, or the app-wide
+ * `defaultWorkerConnection`. See {@link QueueOptionsWithConnectionInstance}.
+ */
+export interface BullMQNativeWorkerOptions extends Omit<WorkerOptions, 'connection'> {
     group?: {
         id?: string;
         maxSize?: number;
@@ -91,6 +107,12 @@ export interface PsychicBackgroundNativeBullMQOptions extends PsychicBackgroundS
      * queue and worker connections.
      */
     defaultQueueConnection?: RedisOrRedisClusterConnection | undefined;
+    /**
+     * App-wide worker Redis/Cluster instance, used when
+     * `nativeBullMQ.defaultQueueOptions.workerConnection` is omitted. Named queues
+     * inherit that resolved default unless their own queue options provide a
+     * `workerConnection`. Worker-entry `connection` options are never used.
+     */
     defaultWorkerConnection?: RedisOrRedisClusterConnection | undefined;
     nativeBullMQ: {
         defaultQueueOptions?: QueueOptionsWithConnectionInstance;
@@ -141,6 +163,17 @@ export type QueueOptionsWithConnectionInstance = Omit<QueueOptions, 'connection'
      * queue and worker connections.
      */
     queueConnection?: RedisOrRedisClusterConnection | undefined;
+    /**
+     * Worker Redis/Cluster instance for this queue, not a plain BullMQ connection
+     * options object. In native mode a named queue's value takes precedence over
+     * `nativeBullMQ.defaultQueueOptions.workerConnection`, which takes precedence
+     * over the app-wide `defaultWorkerConnection`.
+     *
+     * This deliberately configures topology; do not move a formerly ignored
+     * worker-entry `connection` here just to migrate its literal. Delete that
+     * property to preserve behavior. Omit worker connections on producer-only
+     * processes; activating workers still requires a resolved instance.
+     */
     workerConnection?: RedisOrRedisClusterConnection | undefined;
 };
 export interface PsychicBackgroundSimpleOptions extends PsychicBackgroundSharedOptions {

package/package.json

@@ -2,7 +2,7 @@
   "type": "module",
   "name": "@rvoh/psychic-workers",
   "description": "Background job system for Psychic applications",
-  "version": "2.8.1",
+  "version": "2.9.0",
   "author": "RVO Health",
   "publishConfig": {
     "access": "public"
@@ -68,40 +68,41 @@
     "@koa/cors": "^5.0.0",
     "@koa/etag": "^5.0.2",
     "@koa/router": "^15.7.0",
-    "@rvoh/dream": "^2.33.0",
-    "@rvoh/dream-spec-helpers": "^2.3.0",
-    "@rvoh/psychic": "^3.15.2",
-    "@rvoh/psychic-spec-helpers": "^3.4.0",
+    "@rvoh/dream": "^2.41.0",
+    "@rvoh/dream-spec-helpers": "^2.4.0",
+    "@rvoh/psychic": "^3.18.1",
+    "@rvoh/psychic-spec-helpers": "^3.4.2",
     "@types/koa": "^3.0.3",
     "@types/koa-bodyparser": "^4.3.13",
     "@types/koa-conditional-get": "^2.0.4",
     "@types/koa-etag": "^3.0.4",
     "@types/koa__cors": "^5.0.1",
     "@types/koa__router": "^12.0.5",
-    "@types/node": "^26.6.3",
-    "@types/pg": "^8",
+    "@types/node": "^26.6.5",
+    "@types/pg": "^8.23.1",
     "@types/supertest": "^7.2.1",
-    "@typescript-eslint/parser": "^8.70.1",
-    "bullmq": "^5.64.0",
-    "eslint": "^10.11.0",
-    "ioredis": "^5.8.2",
+    "@typescript-eslint/parser": "^8.72.0",
+    "bullmq": "^5.81.5",
+    "eslint": "^10.13.0",
+    "ioredis": "^5.11.1",
     "koa": "^3.2.1",
     "koa-bodyparser": "^4.4.1",
     "koa-conditional-get": "^3.0.0",
-    "kysely": "^0.29.6",
+    "kysely": "^0.29.7",
     "kysely-codegen": "~0.20.0",
     "luxon-jest-matchers": "^0.1.14",
     "openapi-typescript": "^7.13.0",
-    "pg": "^8.23.0",
-    "prettier": "^3.9.9",
-    "supertest": "^7.3.0",
-    "tslib": "^2.7.0",
+    "pg": "^8.23.1",
+    "prettier": "^3.9.10",
+    "puppeteer": "^25.16.0",
+    "supertest": "^7.3.1",
+    "tslib": "^2.8.1",
     "tsx": "^4.23.15",
     "typedoc": "^0.28.20",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.70.1",
-    "vite": "^8.3.1",
-    "vitest": "^5.0.2"
+    "typescript-eslint": "^8.72.0",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
   },
   "packageManager": "pnpm@12.14.0+sha512.c18ba6d87993d3d164cb5e8948f32b2c06ee854487e06cd8d86781342fb3e5bb4634367034711e86802baa9c37bea906ce1929ad08d70884c97d801df13389a6",
   "dependencies": {