Documentation

QueueTest extends Api4TestBase
in package

CRM

uses QueueTestTrait

Properties

$testRecords : array<string|int, mixed>: Records created which will be deleted during tearDown

Methods

__construct() : mixed
assertArrayKeyExists() : mixed
assertArrayValuesEqual() : mixed: Assert the 2 arrays have the same values.
assertAttributesEquals() : mixed: Assert attributes are equal.
assertTreeEquals() : mixed: Assert that two array-trees are exactly equal.
cleanup() : void: Quick clean by emptying tables created for the test.
createLoggedInUser() : int: Emulate a logged in user since certain functions use that.
createTestRecord() : array<string|int, mixed>|null: Inserts a test record, supplying all required values if not provided.
doSomething() : mixed
dummyTask() : bool
getDelayableDrivers() : array<string|int, mixed>
getErrorModes() : array<string|int, mixed>
getTestRecord() : array<string|int, mixed>
onHookQueueRun() : void
registerTestRecord() : void: Register a record to be automatically cleaned up during tearDown
saveTestRecords() : Result: Saves one or more test records, supplying default values.
setUpHeadless() : CiviEnvBuilder: The setupHeadless function runs at the start of each test case, right before the headless environment reboots.
tearDown() : void: Post test cleanup.
testBasicLinearPolling() : void: Setup a queue with a line of back-to-back tasks.
testBasicParallelPolling() : void
testBatchParallelPolling() : void: Create a parallel queue. Claim and execute tasks as batches.
testBatchParallelPolling_WithBasicHandler() : void: Similar to testBatchParallelPolling(). But the hook-listener doesn't directly manipulate queue-items. Instead, it uses the BasicHandlerTrait.
testDelayedStart() : mixed
testEmptyPoll() : void
testQueueItem() : void: Test that queue item permits updates to other fields, but not data.
testReset() : mixed
testRetryWithDelinquencyAndSuccess() : void: Add a task. The task-running agent is a bit delinquent... so it forgets the first few tasks. But the third one works!
testRetryWithEventualFailure() : mixed: Add a task which is never going to succeed. The task fails every time, and eventually we either delete it or abort the queue.
testRetryWithPoliteExhaustion() : mixed: Add a task which is never going to succeed. Try it multiple times (until we run out of retries).
testRunLoop() : mixed
testRunLoop_abort() : mixed
testSelect() : void
testSelectRunAs() : void
testServiceQueue_NeverComplete() : void: If a queue is created as a long-term service, then its work is never complete.
testUserJobQueue_Completion() : void: If a queue is created as part of a user-job, then it has a fixed scope-of-work. The status should flip after completing its work.
userLogout() : mixed
assertCallback() : mixed
assertLike() : void: Assert 2 sql strings are the same, ignoring double spaces.
assertQueueStats() : mixed
conditionallyDeleteTestRecords() : void
deleteTestRecords() : void: Delete records previously created by the `saveTestRecords` function.
getRequiredValuesToCreate() : array<string|int, mixed>: Get the required fields for the api entity + action.
setUp() : void
waitFor() : int: Repeatedly check $condition until it returns true (or until we exhaust timeout).
waitForClaim() : array<string|int, mixed>|null
createOptionValue() : mixed|null: Creates a dummy option value when one is required but the option list is empty
getFkID() : int: Get an ID for the appropriate entity.
getRandomValue() : int|null|string
getRequiredValue() : mixed: Attempt to get a value using field option, defaults, FKEntity, or a random value based on the data type.
isMissingValue() : bool
randomLetters() : string: Generate some random lowercase letters.

$testRecords

Records created which will be deleted during tearDown


        protected
            array<string|int, mixed>
    $testRecords
     = []

__construct()


    public
                    __construct([string $name = null ][, array<string|int, mixed> $data = [] ][, string $dataName = '' ]) : mixed

Parameters

$name : string = null
$data : array<string|int, mixed> = []
$dataName : string = ''

assertArrayKeyExists()


    public
                    assertArrayKeyExists(string|int $key, array<string|int, mixed> &$list) : mixed

Parameters

$key : string|int
$list : array<string|int, mixed>

assertArrayValuesEqual()

Assert the 2 arrays have the same values.


    public
                    assertArrayValuesEqual(array<string|int, mixed> $array1, array<string|int, mixed> $array2) : mixed

The order of arrays, and keys of the arrays, do not affect the outcome.

Parameters

$array1 : array<string|int, mixed>
$array2 : array<string|int, mixed>

assertAttributesEquals()

Assert attributes are equal.


    public
                    assertAttributesEquals(array<string|int, mixed> $expectedValues, array<string|int, mixed> $actualValues[, string $message = null ]) : mixed

Parameters

$expectedValues : array<string|int, mixed>
$actualValues : array<string|int, mixed>
$message : string = null

assertTreeEquals()

Assert that two array-trees are exactly equal.


    public
                    assertTreeEquals(array<string|int, mixed> $expected, array<string|int, mixed> $actual) : mixed

The ordering of keys do not affect the outcome (within either the roots or in any child elements).

Error messages will reveal a readable -path-, regardless of how many levels of nesting are present.

Parameters

$expected : array<string|int, mixed>
$actual : array<string|int, mixed>

cleanup()

Quick clean by emptying tables created for the test.


    public
                    cleanup(array{tablesToTruncate: array} $params) : void

Parameters

$params : array{tablesToTruncate: array}

createLoggedInUser()

Emulate a logged in user since certain functions use that.


    public
                    createLoggedInUser() : int

value to store a record in the DB (like activity)

Return values

int —

Contact ID of the created user.

createTestRecord()

Inserts a test record, supplying all required values if not provided.


    public
                    createTestRecord(string $entityName[, array<string|int, mixed> $values = [] ]) : array<string|int, mixed>|null

Test records will be automatically deleted if deleteTestRecords is called.

This is a convenience helper for saveTestRecords when working with a single entity.

Parameters

$entityName : string
$values : array<string|int, mixed> = []

Return values

array<string|int, mixed>|null

doSomething()


    public
            static        doSomething(CRM_Queue_TaskContext $ctx, string $something) : mixed

Parameters

$ctx : CRM_Queue_TaskContext
$something : string

dummyTask()


    public
            static        dummyTask(CRM_Queue_TaskContext $ctx, string $outcome) : bool

Parameters

$ctx : CRM_Queue_TaskContext
$outcome : string

Return values

bool

getDelayableDrivers()


    public
            static        getDelayableDrivers() : array<string|int, mixed>

Return values

array<string|int, mixed>

getErrorModes()


    public
            static        getErrorModes() : array<string|int, mixed>

Return values

array<string|int, mixed>

getTestRecord()


    public
                    getTestRecord(string $entityName, array<string|int, mixed>|string|int $idOrFilters[, array<string|int, mixed> $select = [] ]) : array<string|int, mixed>

Parameters

$entityName : string
$idOrFilters : array<string|int, mixed>|string|int: Either the entity id or filters like ['name' => 'foo']
$select : array<string|int, mixed> = []

Return values

array<string|int, mixed>

onHookQueueRun()


    public
                    onHookQueueRun(GenericHookEvent $e) : void

Parameters

$e : GenericHookEvent

registerTestRecord()


    public
                    registerTestRecord(string $entityName, string|int|array<string|int, mixed> $where) : void

Parameters

$entityName : string
$where : string|int|array<string|int, mixed>: Where clause (or for short, just the ID)

saveTestRecords()

Saves one or more test records, supplying default values.


    public
                    saveTestRecords(string $entityName, array<string|int, mixed> $saveParams) : Result

Test records will be deleted when the deleteTestRecords function is called, usually in tearDown.

If the transactional method is in use (and nothing is down to cause the transaction to commit, such as creating custom fields) then the deleteTestRecords function does not need to be called.

Parameters

$entityName : string
$saveParams : array<string|int, mixed>

Return values

Result

setUpHeadless()

The setupHeadless function runs at the start of each test case, right before the headless environment reboots.


    public
                    setUpHeadless() : CiviEnvBuilder

It should perform any necessary steps required for putting the database in a consistent baseline -- such as loading schema and extensions.

The utility \Civi\Test::headless() provides a number of helper functions for managing this setup, and it includes optimizations to avoid redundant setup work.

Return values

CiviEnvBuilder

tearDown()

Post test cleanup.


    public
                    tearDown() : void

testBasicLinearPolling()

Setup a queue with a line of back-to-back tasks.


    public
                    testBasicLinearPolling() : void

The first task runs normally. The second task fails at first, but it is retried, and then succeeds.

testBasicParallelPolling()


    public
                    testBasicParallelPolling() : void

testBatchParallelPolling()

Create a parallel queue. Claim and execute tasks as batches.


    public
                    testBatchParallelPolling() : void

Batches are executed via hook_civicrm_queueRun_{runner}.

testBatchParallelPolling_WithBasicHandler()

Similar to testBatchParallelPolling(). But the hook-listener doesn't directly manipulate queue-items. Instead, it uses the BasicHandlerTrait.


    public
                    testBatchParallelPolling_WithBasicHandler() : void

testDelayedStart()


    public
                    testDelayedStart(array<string|int, mixed> $queueSpec) : mixed

Parameters

$queueSpec : array<string|int, mixed>

testEmptyPoll()


    public
                    testEmptyPoll() : void

testQueueItem()

Test that queue item permits updates to other fields, but not data.


    public
                    testQueueItem() : void

testReset()


    public
                    testReset() : mixed

testRetryWithDelinquencyAndSuccess()

Add a task. The task-running agent is a bit delinquent... so it forgets the first few tasks. But the third one works!


    public
                    testRetryWithDelinquencyAndSuccess() : void

testRetryWithEventualFailure()

Add a task which is never going to succeed. The task fails every time, and eventually we either delete it or abort the queue.


    public
                    testRetryWithEventualFailure(string $errorMode) : mixed

Parameters

$errorMode : string: Either 'delete' or 'abort'

testRetryWithPoliteExhaustion()

Add a task which is never going to succeed. Try it multiple times (until we run out of retries).


    public
                    testRetryWithPoliteExhaustion(string $errorMode) : mixed

Parameters

$errorMode : string: Either 'delete' or 'abort'

testRunLoop()


    public
                    testRunLoop() : mixed

testRunLoop_abort()


    public
                    testRunLoop_abort() : mixed

testSelect()


    public
                    testSelect() : void

testSelectRunAs()


    public
                    testSelectRunAs() : void

testServiceQueue_NeverComplete()

If a queue is created as a long-term service, then its work is never complete.


    public
                    testServiceQueue_NeverComplete() : void

testUserJobQueue_Completion()

If a queue is created as part of a user-job, then it has a fixed scope-of-work. The status should flip after completing its work.


    public
                    testUserJobQueue_Completion() : void

userLogout()


    public
                    userLogout() : mixed

assertCallback()


    protected
                    assertCallback(mixed $expectMethod, mixed $expectArgs, mixed $actualTask) : mixed

Parameters

$expectMethod : mixed
$expectArgs : mixed
$actualTask : mixed

assertLike()

Assert 2 sql strings are the same, ignoring double spaces.


    protected
                    assertLike(string $expectedSQL, string $actualSQL[, string $message = 'different sql' ]) : void

Parameters

$expectedSQL : string
$actualSQL : string
$message : string = 'different sql'

assertQueueStats()


    protected
                    assertQueueStats(int $total, int $ready, int $blocked, CRM_Queue_Queue $queue) : mixed

Parameters

$total : int
$ready : int
$blocked : int
$queue : CRM_Queue_Queue

conditionallyDeleteTestRecords()


    protected
                    conditionallyDeleteTestRecords() : void

deleteTestRecords()

Delete records previously created by the `saveTestRecords` function.


    protected
                    deleteTestRecords() : void

This should be called during the tearDown function if the test class does not use the transactional interface.

getRequiredValuesToCreate()

Get the required fields for the api entity + action.


    protected
                    getRequiredValuesToCreate(string $entity[, array<string|int, mixed> $values = [] ]) : array<string|int, mixed>

Parameters

$entity : string
$values : array<string|int, mixed> = []

Return values

array<string|int, mixed>

setUp()


    protected
                    setUp() : void

waitFor()

Repeatedly check $condition until it returns true (or until we exhaust timeout).


    protected
                    waitFor(float $interval, float $timeout, callable $condition) : int

Parameters

$interval : float: Seconds to wait between checks.
$timeout : float: Total maximum seconds to wait across all checks.
$condition : callable: The condition to check.

Return values

int —

Total number of intervals we had to wait/sleep.

waitForClaim()


    protected
                    waitForClaim(float $interval, float $timeout, string $queueName) : array<string|int, mixed>|null

Parameters

$interval : float
$timeout : float
$queueName : string

Return values

array<string|int, mixed>|null

createOptionValue()

Creates a dummy option value when one is required but the option list is empty


    private
                    createOptionValue(string $tableName, string $fieldName) : mixed|null

Parameters

$tableName : string
$fieldName : string

Return values

mixed|null

getFkID()

Get an ID for the appropriate entity.


    private
                    getFkID(string $fkEntity) : int

Parameters

$fkEntity : string

Return values

int

getRandomValue()


    private
                    getRandomValue(mixed $dataType) : int|null|string

Parameters

$dataType : mixed

Return values

int|null|string

getRequiredValue()

Attempt to get a value using field option, defaults, FKEntity, or a random value based on the data type.


    private
                    getRequiredValue(array<string|int, mixed> $field) : mixed

Parameters

$field : array<string|int, mixed>

isMissingValue()


    private
            static        isMissingValue(array<string|int, mixed> $values, string $fieldName) : bool

Parameters

$values : array<string|int, mixed>
$fieldName : string

Return values

bool

randomLetters()

Generate some random lowercase letters.


    private
                    randomLetters([int $len = 10 ]) : string

Parameters

$len : int = 10

Return values

string

QueueTest extends Api4TestBase in package CRM uses QueueTestTrait

Tags

Table of Contents

Properties

Methods

Properties

$testRecords

Methods

__construct()

Parameters

Tags

assertArrayKeyExists()

Parameters

assertArrayValuesEqual()

Parameters

assertAttributesEquals()

Parameters

Tags

assertTreeEquals()

Parameters

cleanup()

Parameters

createLoggedInUser()

Tags

Return values

createTestRecord()

Parameters

Tags

Return values

doSomething()

Parameters

dummyTask()

Parameters

Return values

getDelayableDrivers()

Return values

getErrorModes()

Return values

getTestRecord()

Parameters

Tags

Return values

onHookQueueRun()

Parameters

Tags

registerTestRecord()

Parameters

saveTestRecords()

Parameters

Tags

Return values

setUpHeadless()

Return values

tearDown()

Tags

testBasicLinearPolling()

Tags

testBasicParallelPolling()

testBatchParallelPolling()

Tags

testBatchParallelPolling_WithBasicHandler()

testDelayedStart()

Parameters

Tags

testEmptyPoll()

testQueueItem()

Tags

testReset()

testRetryWithDelinquencyAndSuccess()

testRetryWithEventualFailure()

Parameters

Tags

testRetryWithPoliteExhaustion()

Parameters

Tags

testRunLoop()

testRunLoop_abort()

testSelect()

testSelectRunAs()

testServiceQueue_NeverComplete()

QueueTest extends Api4TestBase
in package

CRM

uses QueueTestTrait