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 that "multiple bulk email recipients" setting is respected.
 132    */
 133   public function testMultipleBulkRecipients() {
 134     Civi::settings()->add([
 135       'civimail_multiple_bulk_emails' => 1,
 136     ]);
 137     $contactID = $this->individualCreate(['first_name' => 'test recipient']);
 138     $email1 = $this->callAPISuccess('email', 'create', [
 139       'contact_id' => $contactID,
 140       'email' => 'mail1@example.org',
 141       'is_bulkmail' => 1,
 142     ]);
 143     $email2 = $this->callAPISuccess('email', 'create', [
 144       'contact_id' => $contactID,
 145       'email' => 'mail2@example.org',
 146       'is_bulkmail' => 1,
 147     ]);
 148     $this->callAPISuccess('group_contact', 'create', [
 149       'contact_id' => $contactID,
 150       'group_id' => $this->_groupID,
 151       'status' => 'Added',
 152     ]);
 153     $mailing = $this->callAPISuccess('mailing', 'create', $this->_params);
 154     $this->assertEquals(2, $this->callAPISuccess('MailingRecipients', 'get', ['mailing_id' => $mailing['id']])['count']);
 155     $this->callAPISuccess('job', 'process_mailing', []);
 156     $this->_mut->assertRecipients([['mail1@example.org'], ['mail2@example.org']]);
 157     // Don't leave data lying around for other tests to screw up on.
 158     $this->callAPISuccess('Email', 'delete', ['id' => $email1['id']]);
 159     $this->callAPISuccess('Email', 'delete', ['id' => $email2['id']]);
 160   }
 161
 162   /**
 163    * Test pause and resume on Mailing.
 164    */
 165   public function testPauseAndResumeMailing() {
 166     $this->createContactsInGroup(10, $this->_groupID);
 167     Civi::settings()->add([
 168       'mailerBatchLimit' => 2,
 169     ]);
 170     $this->_mut->clearMessages();
 171     //Create a test mailing and check if the status is set to Scheduled.
 172     $result = $this->callAPISuccess('mailing', 'create', $this->_params);
 173     $jobs = $this->callAPISuccess('mailing_job', 'get', ['mailing_id' => $result['id']]);
 174     $this->assertEquals('Scheduled', $jobs['values'][$jobs['id']]['status']);
 175
 176     //Pause the mailing.
 177     CRM_Mailing_BAO_MailingJob::pause($result['id']);
 178     $jobs = $this->callAPISuccess('mailing_job', 'get', ['mailing_id' => $result['id']]);
 179     $this->assertEquals('Paused', $jobs['values'][$jobs['id']]['status']);
 180
 181     //Verify if Paused mailing isn't considered in process_mailing job.
 182     $this->callAPISuccess('job', 'process_mailing', []);
 183     //Check if mail log is empty.
 184     $this->_mut->assertMailLogEmpty();
 185     $jobs = $this->callAPISuccess('mailing_job', 'get', ['mailing_id' => $result['id']]);
 186     $this->assertEquals('Paused', $jobs['values'][$jobs['id']]['status']);
 187
 188     //Resume should set the status back to Scheduled.
 189     CRM_Mailing_BAO_MailingJob::resume($result['id']);
 190     $jobs = $this->callAPISuccess('mailing_job', 'get', ['mailing_id' => $result['id']]);
 191     $this->assertEquals('Scheduled', $jobs['values'][$jobs['id']]['status']);
 192
 193     //Execute the job and it should send the mailing to the recipients now.
 194     $this->callAPISuccess('job', 'process_mailing', []);
 195     $this->_mut->assertRecipients($this->getRecipients(1, 2));
 196     // Ensure that loading the report produces no errors.
 197     $report = CRM_Mailing_BAO_Mailing::report($result['id']);
 198     // dev/mailing#56 dev/mailing#57 Ensure that for completed mailings the jobs array is not empty.
 199     $this->assertTrue(!empty($report['jobs']));
 200     // Ensure that mailing name is correctly stored in the report.
 201     $this->assertEquals('mailing name', $report['mailing']['name']);
 202   }
 203
 204   /**
 205    * Test mail when in non-production environment.
 206    *
 207    */
 208   public function testMailNonProductionRun() {
 209     // Test in non-production mode.
 210     $params = [
 211       'environment' => 'Staging',
 212     ];
 213     $this->callAPISuccess('Setting', 'create', $params);
 214     //Assert if outbound mail is disabled.
 215     $mailingBackend = Civi::settings()->get('mailing_backend');
 216     $this->assertEquals($mailingBackend['outBound_option'], CRM_Mailing_Config::OUTBOUND_OPTION_DISABLED);
 217
 218     $this->createContactsInGroup(10, $this->_groupID);
 219     Civi::settings()->add([
 220       'mailerBatchLimit' => 2,
 221     ]);
 222     $this->callAPISuccess('mailing', 'create', $this->_params);
 223     $this->_mut->assertRecipients([]);
 224     $result = $this->callAPIFailure('job', 'process_mailing', []);
 225     $this->assertEquals($result['error_message'], "Job has not been executed as it is a Staging (non-production) environment.");
 226
 227     // Test with runInNonProductionEnvironment param.
 228     $this->callAPISuccess('job', 'process_mailing', ['runInNonProductionEnvironment' => TRUE]);
 229     $this->_mut->assertRecipients($this->getRecipients(1, 2));
 230
 231     $jobId = $this->callAPISuccessGetValue('Job', [
 232       'return' => "id",
 233       'api_action' => "group_rebuild",
 234     ]);
 235     $this->callAPISuccess('Job', 'create', [
 236       'id' => $jobId,
 237       'parameters' => "runInNonProductionEnvironment=TRUE",
 238     ]);
 239     $jobManager = new CRM_Core_JobManager();
 240     $jobManager->executeJobById($jobId);
 241
 242     //Assert if outbound mail is still disabled.
 243     $mailingBackend = Civi::settings()->get('mailing_backend');
 244     $this->assertEquals($mailingBackend['outBound_option'], CRM_Mailing_Config::OUTBOUND_OPTION_DISABLED);
 245
 246     // Test in production mode.
 247     $params = [
 248       'environment' => 'Production',
 249     ];
 250     $this->callAPISuccess('Setting', 'create', $params);
 251     $this->callAPISuccess('job', 'process_mailing', []);
 252     $this->_mut->assertRecipients($this->getRecipients(1, 2));
 253   }
 254
 255   public function concurrencyExamples() {
 256     $es = [];
 257
 258     // Launch 3 workers, but mailerJobsMax limits us to 1 worker.
 259     $es[0] = [
 260       [
 261         'recipients' => 20,
 262         'workers' => 3,
 263         // FIXME: lockHold is unrealistic/unrepresentative. In reality, this situation fails because
 264         // the data.* locks trample the worker.* locks. However, setting lockHold allows us to
 265         // approximate the behavior of what would happen *if* the lock-implementation didn't suffer
 266         // trampling effects.
 267         'lockHold' => 10,
 268         'mailerBatchLimit' => 4,
 269         'mailerJobsMax' => 1,
 270       ],
 271       [
 272         // 2 jobs which produce 0 messages
 273         0 => 2,
 274         // 1 job which produces 4 messages
 275         4 => 1,
 276       ],
 277       4,
 278     ];
 279
 280     // Launch 3 workers, but mailerJobsMax limits us to 2 workers.
 281     $es[1] = [
 282     // Settings.
 283       [
 284         'recipients' => 20,
 285         'workers' => 3,
 286         // FIXME: lockHold is unrealistic/unrepresentative. In reality, this situation fails because
 287         // the data.* locks trample the worker.* locks. However, setting lockHold allows us to
 288         // approximate the behavior of what would happen *if* the lock-implementation didn't suffer
 289         // trampling effects.
 290         'lockHold' => 10,
 291         'mailerBatchLimit' => 5,
 292         'mailerJobsMax' => 2,
 293       ],
 294       // Tallies.
 295       [
 296         // 1 job which produce 0 messages
 297         0 => 1,
 298         // 2 jobs which produce 5 messages
 299         5 => 2,
 300       ],
 301       // Total sent.
 302       10,
 303     ];
 304
 305     // Launch 3 workers and saturate them (mailerJobsMax=3)
 306     $es[2] = [
 307       // Settings.
 308       [
 309         'recipients' => 20,
 310         'workers' => 3,
 311         'mailerBatchLimit' => 6,
 312         'mailerJobsMax' => 3,
 313       ],
 314       // Tallies.
 315       [
 316         // 3 jobs which produce 6 messages
 317         6 => 3,
 318       ],
 319       // Total sent.
 320       18,
 321     ];
 322
 323     // Launch 4 workers and saturate them (mailerJobsMax=0)
 324     $es[3] = [
 325       // Settings.
 326       [
 327         'recipients' => 20,
 328         'workers' => 4,
 329         'mailerBatchLimit' => 6,
 330         'mailerJobsMax' => 0,
 331       ],
 332       // Tallies.
 333       [
 334         // 3 jobs which produce 6 messages
 335         6 => 3,
 336         // 1 job which produces 2 messages
 337         2 => 1,
 338       ],
 339       // Total sent.
 340       20,
 341     ];
 342
 343     // Launch 1 worker, 3 times in a row. Deliver everything.
 344     $es[4] = [
 345       // Settings.
 346       [
 347         'recipients' => 10,
 348         'workers' => 1,
 349         'iterations' => 3,
 350         'mailerBatchLimit' => 7,
 351       ],
 352       // Tallies.
 353       [
 354         // 1 job which produces 7 messages
 355         7 => 1,
 356         // 1 job which produces 3 messages
 357         3 => 1,
 358         // 1 job which produces 0 messages
 359         0 => 1,
 360       ],
 361       // Total sent.
 362       10,
 363     ];
 364
 365     // Launch 2 worker, 3 times in a row. Deliver everything.
 366     $es[5] = [
 367       // Settings.
 368       [
 369         'recipients' => 10,
 370         'workers' => 2,
 371         'iterations' => 3,
 372         'mailerBatchLimit' => 3,
 373       ],
 374       // Tallies.
 375       [
 376         // 3 jobs which produce 3 messages
 377         3 => 3,
 378         // 1 job which produces 1 messages
 379         1 => 1,
 380         // 2 jobs which produce 0 messages
 381         0 => 2,
 382       ],
 383       // Total sent.
 384       10,
 385     ];
 386
 387     // For two mailings, launch 1 worker, 5 times in a row. Deliver everything.
 388     $es[6] = [
 389       // Settings.
 390       [
 391         'mailings' => 2,
 392         'recipients' => 10,
 393         'workers' => 1,
 394         'iterations' => 5,
 395         'mailerBatchLimit' => 6,
 396       ],
 397       // Tallies.
 398       [
 399         // x6 => x4+x2 => x6 => x2 => x0
 400         // 3 jobs which produce 6 messages
 401         6 => 3,
 402         // 1 job which produces 2 messages
 403         2 => 1,
 404         // 1 job which produces 0 messages
 405         0 => 1,
 406       ],
 407       // Total sent.
 408       20,
 409     ];
 410
 411     return $es;
 412   }
 413
 414   /**
 415    * Setup various mail configuration options (eg $mailerBatchLimit,
 416    * $mailerJobMax) and spawn multiple worker threads ($workers).
 417    * Allow the threads to complete. (Optionally, repeat the above
 418    * process.) Finally, check to see if the right number of
 419    * jobs delivered the right number of messages.
 420    *
 421    * @param array $settings
 422    *   An array of settings (eg mailerBatchLimit, workers). See comments
 423    *   for $this->defaultSettings.
 424    * @param array $expectedTallies
 425    *    A listing of the number cron-runs keyed by their size.
 426    *    For example, array(10=>2) means that there 2 cron-runs
 427    *    which delivered 10 messages each.
 428    * @param int $expectedTotal
 429    *    The total number of contacts for whom messages should have
 430    *    been sent.
 431    * @dataProvider concurrencyExamples
 432    */
 433   public function testConcurrency($settings, $expectedTallies, $expectedTotal) {
 434     $settings = array_merge($this->defaultSettings, $settings);
 435
 436     $this->createContactsInGroup($settings['recipients'], $this->_groupID);
 437     Civi::settings()->add(CRM_Utils_Array::subset($settings, [
 438       'mailerBatchLimit',
 439       'mailerJobsMax',
 440       'mailThrottleTime',
 441     ]));
 442
 443     for ($i = 0; $i < $settings['mailings']; $i++) {
 444       $this->callAPISuccess('mailing', 'create', $this->_params);
 445     }
 446
 447     $this->_mut->assertRecipients([]);
 448
 449     $allApiResults = [];
 450     for ($iterationId = 0; $iterationId < $settings['iterations']; $iterationId++) {
 451       $apiCalls = $this->createExternalAPI();
 452       $apiCalls->addEnv(['CIVICRM_CRON_HOLD' => $settings['lockHold']]);
 453       for ($workerId = 0; $workerId < $settings['workers']; $workerId++) {
 454         $apiCalls->addCall('job', 'process_mailing', []);
 455       }
 456       $apiCalls->start();
 457       $this->assertEquals($settings['workers'], $apiCalls->getRunningCount());
 458
 459       $apiCalls->wait();
 460       $allApiResults = array_merge($allApiResults, $apiCalls->getResults());
 461     }
 462
 463     $actualTallies = $this->tallyApiResults($allApiResults);
 464     $this->assertEquals($expectedTallies, $actualTallies, 'API tallies should match.' . print_r([
 465       'expectedTallies' => $expectedTallies,
 466       'actualTallies' => $actualTallies,
 467       'apiResults' => $allApiResults,
 468     ], TRUE));
 469     $this->_mut->assertRecipients($this->getRecipients(1, $expectedTotal / $settings['mailings'], 'nul.example.com', $settings['mailings']));
 470     $this->assertEquals(0, $apiCalls->getRunningCount());
 471   }
 472
 473   /**
 474    * Create contacts in group.
 475    *
 476    * @param int $count
 477    * @param int $groupID
 478    * @param string $domain
 479    */
 480   public function createContactsInGroup($count, $groupID, $domain = 'nul.example.com') {
 481     for ($i = 1; $i <= $count; $i++) {
 482       $contactID = $this->individualCreate(['first_name' => $count, 'email' => 'mail' . $i . '@' . $domain]);
 483       $this->callAPISuccess('group_contact', 'create', [
 484         'contact_id' => $contactID,
 485         'group_id' => $groupID,
 486         'status' => 'Added',
 487       ]);
 488     }
 489   }
 490
 491   /**
 492    * Construct the list of email addresses for $count recipients.
 493    *
 494    * @param int $start
 495    * @param int $count
 496    * @param string $domain
 497    * @param int $mailings
 498    *
 499    * @return array
 500    */
 501   public function getRecipients($start, $count, $domain = 'nul.example.com', $mailings = 1) {
 502     $recipients = [];
 503     for ($m = 0; $m < $mailings; $m++) {
 504       for ($i = $start; $i < ($start + $count); $i++) {
 505         $recipients[][0] = 'mail' . $i . '@' . $domain;
 506       }
 507     }
 508     return $recipients;
 509   }
 510
 511   protected function cleanupMailingTest() {
 512     $this->quickCleanup([
 513       'civicrm_mailing',
 514       'civicrm_mailing_job',
 515       'civicrm_mailing_spool',
 516       'civicrm_mailing_group',
 517       'civicrm_mailing_recipients',
 518       'civicrm_mailing_event_queue',
 519       'civicrm_mailing_event_bounce',
 520       'civicrm_mailing_event_delivered',
 521       'civicrm_group',
 522       'civicrm_group_contact',
 523       'civicrm_contact',
 524     ]);
 525   }
 526
 527   /**
 528    * Categorize results based on (a) whether they succeeded
 529    * and (b) the number of messages sent.
 530    *
 531    * @param array $apiResults
 532    * @return array
 533    *   One key 'error' for all failures.
 534    *   A separate key for each distinct quantity.
 535    */
 536   protected function tallyApiResults($apiResults) {
 537     $ret = [];
 538     foreach ($apiResults as $apiResult) {
 539       $key = !empty($apiResult['is_error']) ? 'error' : $apiResult['values']['processed'];
 540       $ret[$key] = !empty($ret[$key]) ? 1 + $ret[$key] : 1;
 541     }
 542     return $ret;
 543   }
 544
 545 }