tests/phpunit/api/v3/JobProcessMailingTest.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  * File for the CiviCRM APIv3 job functions
  14  *
  15  * @package CiviCRM_APIv3
  16  * @subpackage API_Job
  17  *
  18  * @copyright CiviCRM LLC https://civicrm.org/licensing
  19  * @version $Id: Job.php 30879 2010-11-22 15:45:55Z shot $
  20  *
  21  */
  22
  23 /**
  24  * Class api_v3_JobTest
  25  * @group headless
  26  * @group civimail
  27  */
  28 class api_v3_JobProcessMailingTest extends CiviUnitTestCase {
  29   protected $_apiversion = 3;
  30
  31   public $DBResetRequired = FALSE;
  32   public $_entity = 'Job';
  33   public $_params = [];
  34   private $_groupID;
  35   private $_email;
  36
  37   protected $defaultSettings;
  38
  39   /**
  40    * @var CiviMailUtils
  41    */
  42   private $_mut;
  43
  44   public function setUp() {
  45     $this->cleanupMailingTest();
  46     parent::setUp();
  47     // DGW
  48     CRM_Mailing_BAO_MailingJob::$mailsProcessed = 0;
  49     $this->_groupID = $this->groupCreate();
  50     $this->_email = 'test@test.test';
  51     $this->_params = [
  52       'subject' => 'Accidents in cars cause children',
  53       'body_text' => 'BEWARE children need regular infusions of toys. Santa knows your {domain.address}. There is no {action.optOutUrl}.',
  54       'name' => 'mailing name',
  55       'created_id' => 1,
  56       'groups' => ['include' => [$this->_groupID]],
  57       'scheduled_date' => 'now',
  58     ];
  59     $this->defaultSettings = [
  60       // int, #mailings to send
  61       'mailings' => 1,
  62       // int, #contacts to receive mailing
  63       'recipients' => 20,
  64       // int, #concurrent cron jobs
  65       'workers' => 1,
  66       // int, #times to spawn all the workers
  67       'iterations' => 1,
  68       // int, #extra seconds each cron job should hold lock
  69       'lockHold' => 0,
  70       // int, max# recipients to send in a given cron run
  71       'mailerBatchLimit' => 0,
  72       // int, max# concurrent jobs
  73       'mailerJobsMax' => 0,
  74       // int, max# recipients in each job
  75       'mailerJobSize' => 0,
  76       // int, microseconds separating messages
  77       'mailThrottleTime' => 0,
  78     ];
  79     $this->_mut = new CiviMailUtils($this, TRUE);
  80     $this->callAPISuccess('mail_settings', 'get', ['api.mail_settings.create' => ['domain' => 'chaos.org']]);
  81   }
  82
  83   /**
  84    */
  85   public function tearDown() {
  86     //$this->_mut->clearMessages();
  87     $this->_mut->stop();
  88     CRM_Utils_Hook::singleton()->reset();
  89     // DGW
  90     CRM_Mailing_BAO_MailingJob::$mailsProcessed = 0;
  91     //$this->cleanupMailingTest();
  92     parent::tearDown();
  93   }
  94
  95   public function testBasic() {
  96     $this->createContactsInGroup(10, $this->_groupID);
  97     Civi::settings()->add([
  98       'mailerBatchLimit' => 2,
  99     ]);
 100     $this->callAPISuccess('mailing', 'create', $this->_params);
 101     $this->_mut->assertRecipients([]);
 102     $this->callAPISuccess('job', 'process_mailing', []);
 103     $this->_mut->assertRecipients($this->getRecipients(1, 2));
 104   }
 105
 106   /**
 107    * Test what happens when a contact is set to decesaed
 108    */
 109   public function testDecesasedRecepient() {
 110     $contactID = $this->individualCreate(['first_name' => 'test dead recipeint', 'email' => 'mailtestdead@civicrm.org']);
 111     $this->callAPISuccess('group_contact', 'create', [
 112       'contact_id' => $contactID,
 113       'group_id' => $this->_groupID,
 114       'status' => 'Added',
 115     ]);
 116     $this->createContactsInGroup(2, $this->_groupID);
 117     Civi::settings()->add([
 118       'mailerBatchLimit' => 2,
 119     ]);
 120     $mailing = $this->callAPISuccess('mailing', 'create', $this->_params);
 121     $this->assertEquals(3, $this->callAPISuccess('MailingRecipients', 'get', ['mailing_id' => $mailing['id']])['count']);
 122     $this->_mut->assertRecipients([]);
 123     $this->callAPISuccess('Contact', 'create', ['id' => $contactID, 'is_deceased' => 1, 'contact_type' => 'Individual']);
 124     $this->callAPISuccess('job', 'process_mailing', []);
 125     // Check that the deceased contact is not found in the mailing.
 126     $this->_mut->assertRecipients($this->getRecipients(1, 2));
 127
 128   }
 129
 130   /**
 131    * Test pause and resume on Mailing.
 132    */
 133   public function testPauseAndResumeMailing() {
 134     $this->createContactsInGroup(10, $this->_groupID);
 135     Civi::settings()->add([
 136       'mailerBatchLimit' => 2,
 137     ]);
 138     $this->_mut->clearMessages();
 139     //Create a test mailing and check if the status is set to Scheduled.
 140     $result = $this->callAPISuccess('mailing', 'create', $this->_params);
 141     $jobs = $this->callAPISuccess('mailing_job', 'get', ['mailing_id' => $result['id']]);
 142     $this->assertEquals('Scheduled', $jobs['values'][$jobs['id']]['status']);
 143
 144     //Pause the mailing.
 145     CRM_Mailing_BAO_MailingJob::pause($result['id']);
 146     $jobs = $this->callAPISuccess('mailing_job', 'get', ['mailing_id' => $result['id']]);
 147     $this->assertEquals('Paused', $jobs['values'][$jobs['id']]['status']);
 148
 149     //Verify if Paused mailing isn't considered in process_mailing job.
 150     $this->callAPISuccess('job', 'process_mailing', []);
 151     //Check if mail log is empty.
 152     $this->_mut->assertMailLogEmpty();
 153     $jobs = $this->callAPISuccess('mailing_job', 'get', ['mailing_id' => $result['id']]);
 154     $this->assertEquals('Paused', $jobs['values'][$jobs['id']]['status']);
 155
 156     //Resume should set the status back to Scheduled.
 157     CRM_Mailing_BAO_MailingJob::resume($result['id']);
 158     $jobs = $this->callAPISuccess('mailing_job', 'get', ['mailing_id' => $result['id']]);
 159     $this->assertEquals('Scheduled', $jobs['values'][$jobs['id']]['status']);
 160
 161     //Execute the job and it should send the mailing to the recipients now.
 162     $this->callAPISuccess('job', 'process_mailing', []);
 163     $this->_mut->assertRecipients($this->getRecipients(1, 2));
 164     // Ensure that loading the report produces no errors.
 165     $report = CRM_Mailing_BAO_Mailing::report($result['id']);
 166     // dev/mailing#56 dev/mailing#57 Ensure that for completed mailings the jobs array is not empty.
 167     $this->assertTrue(!empty($report['jobs']));
 168     // Ensure that mailing name is correctly stored in the report.
 169     $this->assertEquals('mailing name', $report['mailing']['name']);
 170   }
 171
 172   /**
 173    * Test mail when in non-production environment.
 174    *
 175    */
 176   public function testMailNonProductionRun() {
 177     // Test in non-production mode.
 178     $params = [
 179       'environment' => 'Staging',
 180     ];
 181     $this->callAPISuccess('Setting', 'create', $params);
 182     //Assert if outbound mail is disabled.
 183     $mailingBackend = Civi::settings()->get('mailing_backend');
 184     $this->assertEquals($mailingBackend['outBound_option'], CRM_Mailing_Config::OUTBOUND_OPTION_DISABLED);
 185
 186     $this->createContactsInGroup(10, $this->_groupID);
 187     Civi::settings()->add([
 188       'mailerBatchLimit' => 2,
 189     ]);
 190     $this->callAPISuccess('mailing', 'create', $this->_params);
 191     $this->_mut->assertRecipients([]);
 192     $result = $this->callAPIFailure('job', 'process_mailing', []);
 193     $this->assertEquals($result['error_message'], "Job has not been executed as it is a Staging (non-production) environment.");
 194
 195     // Test with runInNonProductionEnvironment param.
 196     $this->callAPISuccess('job', 'process_mailing', ['runInNonProductionEnvironment' => TRUE]);
 197     $this->_mut->assertRecipients($this->getRecipients(1, 2));
 198
 199     $jobId = $this->callAPISuccessGetValue('Job', [
 200       'return' => "id",
 201       'api_action' => "group_rebuild",
 202     ]);
 203     $this->callAPISuccess('Job', 'create', [
 204       'id' => $jobId,
 205       'parameters' => "runInNonProductionEnvironment=TRUE",
 206     ]);
 207     $jobManager = new CRM_Core_JobManager();
 208     $jobManager->executeJobById($jobId);
 209
 210     //Assert if outbound mail is still disabled.
 211     $mailingBackend = Civi::settings()->get('mailing_backend');
 212     $this->assertEquals($mailingBackend['outBound_option'], CRM_Mailing_Config::OUTBOUND_OPTION_DISABLED);
 213
 214     // Test in production mode.
 215     $params = [
 216       'environment' => 'Production',
 217     ];
 218     $this->callAPISuccess('Setting', 'create', $params);
 219     $this->callAPISuccess('job', 'process_mailing', []);
 220     $this->_mut->assertRecipients($this->getRecipients(1, 2));
 221   }
 222
 223   public function concurrencyExamples() {
 224     $es = [];
 225
 226     // Launch 3 workers, but mailerJobsMax limits us to 1 worker.
 227     $es[0] = [
 228       [
 229         'recipients' => 20,
 230         'workers' => 3,
 231         // FIXME: lockHold is unrealistic/unrepresentative. In reality, this situation fails because
 232         // the data.* locks trample the worker.* locks. However, setting lockHold allows us to
 233         // approximate the behavior of what would happen *if* the lock-implementation didn't suffer
 234         // trampling effects.
 235         'lockHold' => 10,
 236         'mailerBatchLimit' => 4,
 237         'mailerJobsMax' => 1,
 238       ],
 239       [
 240         // 2 jobs which produce 0 messages
 241         0 => 2,
 242         // 1 job which produces 4 messages
 243         4 => 1,
 244       ],
 245       4,
 246     ];
 247
 248     // Launch 3 workers, but mailerJobsMax limits us to 2 workers.
 249     $es[1] = [
 250     // Settings.
 251       [
 252         'recipients' => 20,
 253         'workers' => 3,
 254         // FIXME: lockHold is unrealistic/unrepresentative. In reality, this situation fails because
 255         // the data.* locks trample the worker.* locks. However, setting lockHold allows us to
 256         // approximate the behavior of what would happen *if* the lock-implementation didn't suffer
 257         // trampling effects.
 258         'lockHold' => 10,
 259         'mailerBatchLimit' => 5,
 260         'mailerJobsMax' => 2,
 261       ],
 262       // Tallies.
 263       [
 264         // 1 job which produce 0 messages
 265         0 => 1,
 266         // 2 jobs which produce 5 messages
 267         5 => 2,
 268       ],
 269       // Total sent.
 270       10,
 271     ];
 272
 273     // Launch 3 workers and saturate them (mailerJobsMax=3)
 274     $es[2] = [
 275       // Settings.
 276       [
 277         'recipients' => 20,
 278         'workers' => 3,
 279         'mailerBatchLimit' => 6,
 280         'mailerJobsMax' => 3,
 281       ],
 282       // Tallies.
 283       [
 284         // 3 jobs which produce 6 messages
 285         6 => 3,
 286       ],
 287       // Total sent.
 288       18,
 289     ];
 290
 291     // Launch 4 workers and saturate them (mailerJobsMax=0)
 292     $es[3] = [
 293       // Settings.
 294       [
 295         'recipients' => 20,
 296         'workers' => 4,
 297         'mailerBatchLimit' => 6,
 298         'mailerJobsMax' => 0,
 299       ],
 300       // Tallies.
 301       [
 302         // 3 jobs which produce 6 messages
 303         6 => 3,
 304         // 1 job which produces 2 messages
 305         2 => 1,
 306       ],
 307       // Total sent.
 308       20,
 309     ];
 310
 311     // Launch 1 worker, 3 times in a row. Deliver everything.
 312     $es[4] = [
 313       // Settings.
 314       [
 315         'recipients' => 10,
 316         'workers' => 1,
 317         'iterations' => 3,
 318         'mailerBatchLimit' => 7,
 319       ],
 320       // Tallies.
 321       [
 322         // 1 job which produces 7 messages
 323         7 => 1,
 324         // 1 job which produces 3 messages
 325         3 => 1,
 326         // 1 job which produces 0 messages
 327         0 => 1,
 328       ],
 329       // Total sent.
 330       10,
 331     ];
 332
 333     // Launch 2 worker, 3 times in a row. Deliver everything.
 334     $es[5] = [
 335       // Settings.
 336       [
 337         'recipients' => 10,
 338         'workers' => 2,
 339         'iterations' => 3,
 340         'mailerBatchLimit' => 3,
 341       ],
 342       // Tallies.
 343       [
 344         // 3 jobs which produce 3 messages
 345         3 => 3,
 346         // 1 job which produces 1 messages
 347         1 => 1,
 348         // 2 jobs which produce 0 messages
 349         0 => 2,
 350       ],
 351       // Total sent.
 352       10,
 353     ];
 354
 355     // For two mailings, launch 1 worker, 5 times in a row. Deliver everything.
 356     $es[6] = [
 357       // Settings.
 358       [
 359         'mailings' => 2,
 360         'recipients' => 10,
 361         'workers' => 1,
 362         'iterations' => 5,
 363         'mailerBatchLimit' => 6,
 364       ],
 365       // Tallies.
 366       [
 367         // x6 => x4+x2 => x6 => x2 => x0
 368         // 3 jobs which produce 6 messages
 369         6 => 3,
 370         // 1 job which produces 2 messages
 371         2 => 1,
 372         // 1 job which produces 0 messages
 373         0 => 1,
 374       ],
 375       // Total sent.
 376       20,
 377     ];
 378
 379     return $es;
 380   }
 381
 382   /**
 383    * Setup various mail configuration options (eg $mailerBatchLimit,
 384    * $mailerJobMax) and spawn multiple worker threads ($workers).
 385    * Allow the threads to complete. (Optionally, repeat the above
 386    * process.) Finally, check to see if the right number of
 387    * jobs delivered the right number of messages.
 388    *
 389    * @param array $settings
 390    *   An array of settings (eg mailerBatchLimit, workers). See comments
 391    *   for $this->defaultSettings.
 392    * @param array $expectedTallies
 393    *    A listing of the number cron-runs keyed by their size.
 394    *    For example, array(10=>2) means that there 2 cron-runs
 395    *    which delivered 10 messages each.
 396    * @param int $expectedTotal
 397    *    The total number of contacts for whom messages should have
 398    *    been sent.
 399    * @dataProvider concurrencyExamples
 400    */
 401   public function testConcurrency($settings, $expectedTallies, $expectedTotal) {
 402     $settings = array_merge($this->defaultSettings, $settings);
 403
 404     $this->createContactsInGroup($settings['recipients'], $this->_groupID);
 405     Civi::settings()->add(CRM_Utils_Array::subset($settings, [
 406       'mailerBatchLimit',
 407       'mailerJobsMax',
 408       'mailThrottleTime',
 409     ]));
 410
 411     for ($i = 0; $i < $settings['mailings']; $i++) {
 412       $this->callAPISuccess('mailing', 'create', $this->_params);
 413     }
 414
 415     $this->_mut->assertRecipients([]);
 416
 417     $allApiResults = [];
 418     for ($iterationId = 0; $iterationId < $settings['iterations']; $iterationId++) {
 419       $apiCalls = $this->createExternalAPI();
 420       $apiCalls->addEnv(['CIVICRM_CRON_HOLD' => $settings['lockHold']]);
 421       for ($workerId = 0; $workerId < $settings['workers']; $workerId++) {
 422         $apiCalls->addCall('job', 'process_mailing', []);
 423       }
 424       $apiCalls->start();
 425       $this->assertEquals($settings['workers'], $apiCalls->getRunningCount());
 426
 427       $apiCalls->wait();
 428       $allApiResults = array_merge($allApiResults, $apiCalls->getResults());
 429     }
 430
 431     $actualTallies = $this->tallyApiResults($allApiResults);
 432     $this->assertEquals($expectedTallies, $actualTallies, 'API tallies should match.' . print_r([
 433       'expectedTallies' => $expectedTallies,
 434       'actualTallies' => $actualTallies,
 435       'apiResults' => $allApiResults,
 436     ], TRUE));
 437     $this->_mut->assertRecipients($this->getRecipients(1, $expectedTotal / $settings['mailings'], 'nul.example.com', $settings['mailings']));
 438     $this->assertEquals(0, $apiCalls->getRunningCount());
 439   }
 440
 441   /**
 442    * Create contacts in group.
 443    *
 444    * @param int $count
 445    * @param int $groupID
 446    * @param string $domain
 447    */
 448   public function createContactsInGroup($count, $groupID, $domain = 'nul.example.com') {
 449     for ($i = 1; $i <= $count; $i++) {
 450       $contactID = $this->individualCreate(['first_name' => $count, 'email' => 'mail' . $i . '@' . $domain]);
 451       $this->callAPISuccess('group_contact', 'create', [
 452         'contact_id' => $contactID,
 453         'group_id' => $groupID,
 454         'status' => 'Added',
 455       ]);
 456     }
 457   }
 458
 459   /**
 460    * Construct the list of email addresses for $count recipients.
 461    *
 462    * @param int $start
 463    * @param int $count
 464    * @param string $domain
 465    * @param int $mailings
 466    *
 467    * @return array
 468    */
 469   public function getRecipients($start, $count, $domain = 'nul.example.com', $mailings = 1) {
 470     $recipients = [];
 471     for ($m = 0; $m < $mailings; $m++) {
 472       for ($i = $start; $i < ($start + $count); $i++) {
 473         $recipients[][0] = 'mail' . $i . '@' . $domain;
 474       }
 475     }
 476     return $recipients;
 477   }
 478
 479   protected function cleanupMailingTest() {
 480     $this->quickCleanup([
 481       'civicrm_mailing',
 482       'civicrm_mailing_job',
 483       'civicrm_mailing_spool',
 484       'civicrm_mailing_group',
 485       'civicrm_mailing_recipients',
 486       'civicrm_mailing_event_queue',
 487       'civicrm_mailing_event_bounce',
 488       'civicrm_mailing_event_delivered',
 489       'civicrm_group',
 490       'civicrm_group_contact',
 491       'civicrm_contact',
 492     ]);
 493   }
 494
 495   /**
 496    * Categorize results based on (a) whether they succeeded
 497    * and (b) the number of messages sent.
 498    *
 499    * @param array $apiResults
 500    * @return array
 501    *   One key 'error' for all failures.
 502    *   A separate key for each distinct quantity.
 503    */
 504   protected function tallyApiResults($apiResults) {
 505     $ret = [];
 506     foreach ($apiResults as $apiResult) {
 507       $key = !empty($apiResult['is_error']) ? 'error' : $apiResult['values']['processed'];
 508       $ret[$key] = !empty($ret[$key]) ? 1 + $ret[$key] : 1;
 509     }
 510     return $ret;
 511   }
 512
 513 }