Summary
Add a new QueueTrait for managing and asserting Drupal core queue state
during BDD tests.
Motivation
Queue-driven processing is common in Drupal: batch operations, email
sending, search indexing, data sync, webhook processing. Drupal core's
Queue API (\Drupal\Core\Queue\QueueInterface) provides the foundation,
and contrib modules like AdvancedQueue build on top of it.
DrupalExtension provides no queue steps.
Proposed steps
Given the "my_queue" queue is empty
When I process 5 items from the "my_queue" queue
When I process all items from the "my_queue" queue
Then the "my_queue" queue should have 3 items
Then the "my_queue" queue should be empty
Implementation notes
- New file:
src/Drupal/QueueTrait.php.
- Use
\Drupal::queue($queue_name) to get QueueInterface instances.
Given queue is empty: call $queue->deleteQueue() then
$queue->createQueue() to reset.
When I process N items: get queue worker via
\Drupal::service('plugin.manager.queue_worker')->createInstance($queue_name)
and call $worker->processItem($item->data) in a loop with
$queue->claimItem() / $queue->deleteItem().
When I process all items: same loop until $queue->numberOfItems() === 0
or claimItem() returns FALSE, with a safety limit to prevent infinite
loops.
Then queue should have N items: call $queue->numberOfItems() and
compare.
- Method naming:
queueEmpty, queueProcessItems, queueProcessAll,
queueAssertItemCount, queueAssertEmpty.
- Add
@AfterScenario hook (tagged @queue) to clean up queues created
during the scenario.
Configurable defaults (protected methods)
All limits and settings should be exposed as protected methods so that
consumer FeatureContext classes can override them:
// Maximum items to process in "process all" to prevent infinite loops.
protected function queueGetProcessLimit(): int {
return 1000;
}
// Lease time in seconds when claiming queue items.
protected function queueGetLeaseTime(): int {
return 30;
}
Scope boundaries
- This trait targets Drupal core Queue API (
DatabaseQueue, Batch,
Memory).
- AdvancedQueue has a fundamentally different API (entity-based jobs with
states, not claim/release). If needed, it should be a separate
AdvancedQueueTrait in a future issue.
- No queue creation steps — queues are created by modules, not by tests.
Acceptance criteria
Summary
Add a new
QueueTraitfor managing and asserting Drupal core queue stateduring BDD tests.
Motivation
Queue-driven processing is common in Drupal: batch operations, email
sending, search indexing, data sync, webhook processing. Drupal core's
Queue API (
\Drupal\Core\Queue\QueueInterface) provides the foundation,and contrib modules like AdvancedQueue build on top of it.
DrupalExtension provides no queue steps.
Proposed steps
Implementation notes
src/Drupal/QueueTrait.php.\Drupal::queue($queue_name)to getQueueInterfaceinstances.Given queue is empty: call$queue->deleteQueue()then$queue->createQueue()to reset.When I process N items: get queue worker via\Drupal::service('plugin.manager.queue_worker')->createInstance($queue_name)and call
$worker->processItem($item->data)in a loop with$queue->claimItem()/$queue->deleteItem().When I process all items: same loop until$queue->numberOfItems() === 0or
claimItem()returnsFALSE, with a safety limit to prevent infiniteloops.
Then queue should have N items: call$queue->numberOfItems()andcompare.
queueEmpty,queueProcessItems,queueProcessAll,queueAssertItemCount,queueAssertEmpty.@AfterScenariohook (tagged@queue) to clean up queues createdduring the scenario.
Configurable defaults (protected methods)
All limits and settings should be exposed as protected methods so that
consumer
FeatureContextclasses can override them:Scope boundaries
DatabaseQueue,Batch,Memory).states, not claim/release). If needed, it should be a separate
AdvancedQueueTraitin a future issue.Acceptance criteria
src/Drupal/QueueTrait.php.#[Given(...)]/#[When(...)]/#[Then(...)]tuple annotations.tests/behat/features/queue.feature.@trait:QueueTraitnegative tests.processAllto prevent infinite loops.@AfterScenariocleanup hook for@queue-tagged scenarios.ahoy update-docsrun to regenerateSTEPS.md.ahoy lintpasses.use QueueTrait;toFeatureContext.php.