TestBase.php 55.3 KB
Newer Older
1
2
3
4
<?php

/**
 * @file
5
 * Contains \Drupal\simpletest\TestBase.
6
7
8
9
 */

namespace Drupal\simpletest;

10
use Drupal\Component\Render\MarkupInterface;
11
use Drupal\Component\Utility\Crypt;
12
use Drupal\Component\Utility\SafeMarkup;
13
use Drupal\Core\Database\Database;
14
use Drupal\Core\Config\ConfigImporter;
15
use Drupal\Core\Config\StorageComparer;
16
use Drupal\Core\Database\ConnectionNotDefinedException;
17
use Drupal\Core\Config\StorageInterface;
18
use Drupal\Core\Site\Settings;
19
use Drupal\Core\StreamWrapper\PublicStream;
20
use Drupal\Core\Utility\Error;
21
22
23
24

/**
 * Base class for Drupal tests.
 *
25
 * Do not extend this class directly; use either
26
 * \Drupal\simpletest\WebTestBase or \Drupal\simpletest\KernelTestBase.
27
28
 */
abstract class TestBase {
29
30

  use SessionTestTrait;
31
  use RandomGeneratorTrait;
32
  use AssertHelperTrait;
33

34
35
36
37
38
39
40
  /**
   * The test run ID.
   *
   * @var string
   */
  protected $testId;

41
42
43
44
45
46
47
  /**
   * The site directory of this test run.
   *
   * @var string
   */
  protected $siteDirectory = NULL;

48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
  /**
   * The database prefix of this test run.
   *
   * @var string
   */
  protected $databasePrefix = NULL;

  /**
   * Time limit for the test.
   */
  protected $timeLimit = 500;

  /**
   * Current results of this test case.
   *
   * @var Array
   */
  public $results = array(
    '#pass' => 0,
    '#fail' => 0,
    '#exception' => 0,
    '#debug' => 0,
  );

  /**
   * Assertions thrown in that test case.
   *
   * @var Array
   */
  protected $assertions = array();

  /**
   * This class is skipped when looking for the source of an assertion.
   *
   * When displaying which function an assert comes from, it's not too useful
   * to see "WebTestBase->drupalLogin()', we would like to see the test
   * that called it. So we need to skip the classes defining these helper
   * methods.
   */
  protected $skipClasses = array(__CLASS__ => TRUE);

89
90
91
  /**
   * TRUE if verbose debugging is enabled.
   *
92
   * @var bool
93
   */
94
  public $verbose;
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

  /**
   * Incrementing identifier for verbose output filenames.
   *
   * @var integer
   */
  protected $verboseId = 0;

  /**
   * Safe class name for use in verbose output filenames.
   *
   * Namespaces separator (\) replaced with _.
   *
   * @var string
   */
  protected $verboseClassName;

  /**
   * Directory where verbose output files are put.
   *
   * @var string
   */
  protected $verboseDirectory;

119
120
121
122
123
124
125
126
127
128
129
130
  /**
   * URL to the verbose output file directory.
   *
   * @var string
   */
  protected $verboseDirectoryUrl;

  /**
   * The original configuration (variables), if available.
   *
   * @var string
   * @todo Remove all remnants of $GLOBALS['conf'].
131
   * @see https://www.drupal.org/node/2183323
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
   */
  protected $originalConf;

  /**
   * The original configuration (variables).
   *
   * @var string
   */
  protected $originalConfig;

  /**
   * The original configuration directories.
   *
   * An array of paths keyed by the CONFIG_*_DIRECTORY constants defined by
   * core/includes/bootstrap.inc.
   *
   * @var array
   */
  protected $originalConfigDirectories;

  /**
   * The original container.
   *
   * @var \Symfony\Component\DependencyInjection\ContainerInterface
   */
  protected $originalContainer;

  /**
   * The original file directory, before it was changed for testing purposes.
   *
   * @var string
   */
  protected $originalFileDirectory = NULL;

  /**
   * The original language.
   *
   * @var \Drupal\Core\Language\LanguageInterface
   */
  protected $originalLanguage;

173
174
175
176
177
178
179
  /**
   * The original database prefix when running inside Simpletest.
   *
   * @var string
   */
  protected $originalPrefix;

180
  /**
181
   * The original installation profile.
182
183
184
   *
   * @var string
   */
185
186
187
  protected $originalProfile;

  /**
188
   * The name of the session cookie of the test-runner.
189
190
191
192
   *
   * @var string
   */
  protected $originalSessionName;
193

194
195
  /**
   * The settings array.
196
197
   *
   * @var array
198
199
200
   */
  protected $originalSettings;

201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
  /**
   * The original array of shutdown function callbacks.
   *
   * @var array
   */
  protected $originalShutdownCallbacks;

  /**
   * The site directory of the original parent site.
   *
   * @var string
   */
  protected $originalSite;

  /**
   * The original user, before testing began.
   *
   * @var \Drupal\Core\Session\AccountProxyInterface
   */
  protected $originalUser;

222
223
224
225
226
227
228
  /**
   * The public file directory for the test environment.
   *
   * This is set in TestBase::prepareEnvironment().
   *
   * @var string
   */
229
  protected $publicFilesDirectory;
230

231
232
233
234
235
236
237
  /**
   * The private file directory for the test environment.
   *
   * This is set in TestBase::prepareEnvironment().
   *
   * @var string
   */
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
  protected $privateFilesDirectory;

  /**
   * The temporary file directory for the test environment.
   *
   * This is set in TestBase::prepareEnvironment().
   *
   * @var string
   */
  protected $tempFilesDirectory;

  /**
   * The translation file directory for the test environment.
   *
   * This is set in TestBase::prepareEnvironment().
   *
   * @var string
   */
  protected $translationFilesDirectory;
257

258
  /**
259
260
   * Whether to die in case any test assertion fails.
   *
261
   * @var bool
262
263
   *
   * @see run-tests.sh
264
   */
265
  public $dieOnFail = FALSE;
266

267
268
269
270
271
272
273
  /**
   * The DrupalKernel instance used in the test.
   *
   * @var \Drupal\Core\DrupalKernel
   */
  protected $kernel;

274
275
276
277
278
279
280
  /**
   * The dependency injection container used in the test.
   *
   * @var \Symfony\Component\DependencyInjection\ContainerInterface
   */
  protected $container;

281
282
283
284
285
286
287
  /**
   * The config importer that can used in a test.
   *
   * @var \Drupal\Core\Config\ConfigImporter
   */
  protected $configImporter;

288
289
290
291
292
293
294
  /**
   * Set to TRUE to strict check all configuration saved.
   *
   * @see \Drupal\Core\Config\Testing\ConfigSchemaChecker
   *
   * @var bool
   */
295
  protected $strictConfigSchema = TRUE;
296

297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
  /**
   * An array of config object names that are excluded from schema checking.
   *
   * @var string[]
   */
  protected static $configSchemaCheckerExclusions = array(
    // Following are used to test lack of or partial schema. Where partial
    // schema is provided, that is explicitly tested in specific tests.
    'config_schema_test.noschema',
    'config_schema_test.someschema',
    'config_schema_test.schema_data_types',
    'config_schema_test.no_schema_data_types',
    // Used to test application of schema to filtering of configuration.
    'config_test.dynamic.system',
  );

313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
  /**
   * HTTP authentication method (specified as a CURLAUTH_* constant).
   *
   * @var int
   * @see http://php.net/manual/en/function.curl-setopt.php
   */
  protected $httpAuthMethod = CURLAUTH_BASIC;

  /**
   * HTTP authentication credentials (<username>:<password>).
   *
   * @var string
   */
  protected $httpAuthCredentials = NULL;

328
329
330
331
332
333
334
335
336
337
  /**
   * Constructor for Test.
   *
   * @param $test_id
   *   Tests with the same id are reported together.
   */
  public function __construct($test_id = NULL) {
    $this->testId = $test_id;
  }

338
339
340
341
342
  /**
   * Performs setup tasks before each individual test method is run.
   */
  abstract protected function setUp();

343
344
345
346
347
348
349
350
351
352
  /**
   * Checks the matching requirements for Test.
   *
   * @return
   *   Array of errors containing a list of unmet requirements.
   */
  protected function checkRequirements() {
    return array();
  }

353
354
355
356
357
358
359
360
361
  /**
   * Helper method to store an assertion record in the configured database.
   *
   * This method decouples database access from assertion logic.
   *
   * @param array $assertion
   *   Keyed array representing an assertion, as generated by assert().
   *
   * @see self::assert()
362
363
364
   *
   * @return \Drupal\Core\Database\StatementInterface|int|null
   *   The message ID.
365
366
367
   */
  protected function storeAssertion(array $assertion) {
    return self::getDatabaseConnection()
368
      ->insert('simpletest', ['return' => Database::RETURN_INSERT_ID])
369
370
371
372
      ->fields($assertion)
      ->execute();
  }

373
374
375
376
  /**
   * Internal helper: stores the assert.
   *
   * @param $status
377
   *   Can be 'pass', 'fail', 'exception', 'debug'.
378
   *   TRUE is a synonym for 'pass', FALSE for 'fail'.
379
   * @param string|\Drupal\Component\Render\MarkupInterface $message
380
   *   (optional) A message to display with the assertion. Do not translate
381
   *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
382
383
   *   variables in the message text, not t(). If left blank, a default message
   *   will be displayed.
384
   * @param $group
385
386
387
388
   *   (optional) The group this message is in, which is displayed in a column
   *   in test output. Use 'Debug' to indicate this is debugging output. Do not
   *   translate this string. Defaults to 'Other'; most tests do not override
   *   this default.
389
390
391
392
393
394
395
396
   * @param $caller
   *   By default, the assert comes from a function whose name starts with
   *   'test'. Instead, you can specify where this assert originates from
   *   by passing in an associative array as $caller. Key 'file' is
   *   the name of the source file, 'line' is the line number and 'function'
   *   is the caller function itself.
   */
  protected function assert($status, $message = '', $group = 'Other', array $caller = NULL) {
397
    if ($message instanceof MarkupInterface) {
398
399
      $message = (string) $message;
    }
400
401
402
403
404
405
406
407
408
409
410
411
412
413
    // Convert boolean status to string status.
    if (is_bool($status)) {
      $status = $status ? 'pass' : 'fail';
    }

    // Increment summary result counter.
    $this->results['#' . $status]++;

    // Get the function information about the call to the assertion method.
    if (!$caller) {
      $caller = $this->getAssertionCall();
    }

    // Creation assertion array that can be displayed while tests are running.
414
    $assertion = array(
415
416
417
418
419
420
421
422
423
424
425
      'test_id' => $this->testId,
      'test_class' => get_class($this),
      'status' => $status,
      'message' => $message,
      'message_group' => $group,
      'function' => $caller['function'],
      'line' => $caller['line'],
      'file' => $caller['file'],
    );

    // Store assertion for display after the test has completed.
426
427
428
    $message_id = $this->storeAssertion($assertion);
    $assertion['message_id'] = $message_id;
    $this->assertions[] = $assertion;
429
430
431
432
433
434
435

    // We do not use a ternary operator here to allow a breakpoint on
    // test failure.
    if ($status == 'pass') {
      return TRUE;
    }
    else {
436
      if ($this->dieOnFail && ($status == 'fail' || $status == 'exception')) {
437
438
        exit(1);
      }
439
440
441
442
443
444
445
446
447
448
449
      return FALSE;
    }
  }

  /**
   * Store an assertion from outside the testing context.
   *
   * This is useful for inserting assertions that can only be recorded after
   * the test case has been destroyed, such as PHP fatal errors. The caller
   * information is not automatically gathered since the caller is most likely
   * inserting the assertion on behalf of other code. In all other respects
450
   * the method behaves just like \Drupal\simpletest\TestBase::assert() in terms
451
452
453
454
455
   * of storing the assertion.
   *
   * @return
   *   Message ID of the stored assertion.
   *
456
457
   * @see \Drupal\simpletest\TestBase::assert()
   * @see \Drupal\simpletest\TestBase::deleteAssert()
458
459
460
461
462
463
464
465
   */
  public static function insertAssert($test_id, $test_class, $status, $message = '', $group = 'Other', array $caller = array()) {
    // Convert boolean status to string status.
    if (is_bool($status)) {
      $status = $status ? 'pass' : 'fail';
    }

    $caller += array(
466
      'function' => 'Unknown',
467
      'line' => 0,
468
      'file' => 'Unknown',
469
470
471
472
473
474
475
476
477
478
479
480
481
    );

    $assertion = array(
      'test_id' => $test_id,
      'test_class' => $test_class,
      'status' => $status,
      'message' => $message,
      'message_group' => $group,
      'function' => $caller['function'],
      'line' => $caller['line'],
      'file' => $caller['file'],
    );

482
    // We can't use storeAssertion() because this method is static.
483
484
    return self::getDatabaseConnection()
      ->insert('simpletest')
485
486
487
488
489
490
491
492
493
      ->fields($assertion)
      ->execute();
  }

  /**
   * Delete an assertion record by message ID.
   *
   * @param $message_id
   *   Message ID of the assertion to delete.
494
   *
495
496
497
   * @return
   *   TRUE if the assertion was deleted, FALSE otherwise.
   *
498
   * @see \Drupal\simpletest\TestBase::insertAssert()
499
500
   */
  public static function deleteAssert($message_id) {
501
    // We can't use storeAssertion() because this method is static.
502
503
    return (bool) self::getDatabaseConnection()
      ->delete('simpletest')
504
505
506
507
      ->condition('message_id', $message_id)
      ->execute();
  }

508
509
510
  /**
   * Returns the database connection to the site running Simpletest.
   *
511
   * @return \Drupal\Core\Database\Connection
512
513
514
   *   The database connection to use for inserting assertions.
   */
  public static function getDatabaseConnection() {
515
516
517
    // Check whether there is a test runner connection.
    // @see run-tests.sh
    // @todo Convert Simpletest UI runner to create + use this connection, too.
518
    try {
519
      $connection = Database::getConnection('default', 'test-runner');
520
521
    }
    catch (ConnectionNotDefinedException $e) {
522
523
524
525
526
527
528
529
530
531
532
      // Check whether there is a backup of the original default connection.
      // @see TestBase::prepareEnvironment()
      try {
        $connection = Database::getConnection('default', 'simpletest_original_default');
      }
      catch (ConnectionNotDefinedException $e) {
        // If TestBase::prepareEnvironment() or TestBase::restoreEnvironment()
        // failed, the test-specific database connection does not exist
        // yet/anymore, so fall back to the default of the (UI) test runner.
        $connection = Database::getConnection('default', 'default');
      }
533
534
535
536
    }
    return $connection;
  }

537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
  /**
   * Cycles through backtrace until the first non-assertion method is found.
   *
   * @return
   *   Array representing the true caller.
   */
  protected function getAssertionCall() {
    $backtrace = debug_backtrace();

    // The first element is the call. The second element is the caller.
    // We skip calls that occurred in one of the methods of our base classes
    // or in an assertion function.
   while (($caller = $backtrace[1]) &&
         ((isset($caller['class']) && isset($this->skipClasses[$caller['class']])) ||
           substr($caller['function'], 0, 6) == 'assert')) {
      // We remove that call.
      array_shift($backtrace);
    }

556
    return Error::getLastCaller($backtrace);
557
558
559
  }

  /**
560
561
562
   * Check to see if a value is not false.
   *
   * False values are: empty string, 0, NULL, and FALSE.
563
564
565
566
   *
   * @param $value
   *   The value on which the assertion is to be done.
   * @param $message
567
   *   (optional) A message to display with the assertion. Do not translate
568
   *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
569
570
   *   variables in the message text, not t(). If left blank, a default message
   *   will be displayed.
571
   * @param $group
572
573
574
575
   *   (optional) The group this message is in, which is displayed in a column
   *   in test output. Use 'Debug' to indicate this is debugging output. Do not
   *   translate this string. Defaults to 'Other'; most tests do not override
   *   this default.
576
   *
577
578
579
580
   * @return
   *   TRUE if the assertion succeeded, FALSE otherwise.
   */
  protected function assertTrue($value, $message = '', $group = 'Other') {
581
    return $this->assert((bool) $value, $message ? $message : SafeMarkup::format('Value @value is TRUE.', array('@value' => var_export($value, TRUE))), $group);
582
583
584
  }

  /**
585
586
587
   * Check to see if a value is false.
   *
   * False values are: empty string, 0, NULL, and FALSE.
588
589
590
591
   *
   * @param $value
   *   The value on which the assertion is to be done.
   * @param $message
592
   *   (optional) A message to display with the assertion. Do not translate
593
   *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
594
595
   *   variables in the message text, not t(). If left blank, a default message
   *   will be displayed.
596
   * @param $group
597
598
599
600
   *   (optional) The group this message is in, which is displayed in a column
   *   in test output. Use 'Debug' to indicate this is debugging output. Do not
   *   translate this string. Defaults to 'Other'; most tests do not override
   *   this default.
601
   *
602
603
604
605
   * @return
   *   TRUE if the assertion succeeded, FALSE otherwise.
   */
  protected function assertFalse($value, $message = '', $group = 'Other') {
606
    return $this->assert(!$value, $message ? $message : SafeMarkup::format('Value @value is FALSE.', array('@value' => var_export($value, TRUE))), $group);
607
608
609
610
611
612
613
614
  }

  /**
   * Check to see if a value is NULL.
   *
   * @param $value
   *   The value on which the assertion is to be done.
   * @param $message
615
   *   (optional) A message to display with the assertion. Do not translate
616
   *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
617
618
   *   variables in the message text, not t(). If left blank, a default message
   *   will be displayed.
619
   * @param $group
620
621
622
623
   *   (optional) The group this message is in, which is displayed in a column
   *   in test output. Use 'Debug' to indicate this is debugging output. Do not
   *   translate this string. Defaults to 'Other'; most tests do not override
   *   this default.
624
   *
625
626
627
628
   * @return
   *   TRUE if the assertion succeeded, FALSE otherwise.
   */
  protected function assertNull($value, $message = '', $group = 'Other') {
629
    return $this->assert(!isset($value), $message ? $message : SafeMarkup::format('Value @value is NULL.', array('@value' => var_export($value, TRUE))), $group);
630
631
632
633
634
635
636
637
  }

  /**
   * Check to see if a value is not NULL.
   *
   * @param $value
   *   The value on which the assertion is to be done.
   * @param $message
638
   *   (optional) A message to display with the assertion. Do not translate
639
   *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
640
641
   *   variables in the message text, not t(). If left blank, a default message
   *   will be displayed.
642
   * @param $group
643
644
645
646
   *   (optional) The group this message is in, which is displayed in a column
   *   in test output. Use 'Debug' to indicate this is debugging output. Do not
   *   translate this string. Defaults to 'Other'; most tests do not override
   *   this default.
647
   *
648
649
650
651
   * @return
   *   TRUE if the assertion succeeded, FALSE otherwise.
   */
  protected function assertNotNull($value, $message = '', $group = 'Other') {
652
    return $this->assert(isset($value), $message ? $message : SafeMarkup::format('Value @value is not NULL.', array('@value' => var_export($value, TRUE))), $group);
653
654
655
656
657
658
659
660
661
662
  }

  /**
   * Check to see if two values are equal.
   *
   * @param $first
   *   The first value to check.
   * @param $second
   *   The second value to check.
   * @param $message
663
   *   (optional) A message to display with the assertion. Do not translate
664
   *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
665
666
   *   variables in the message text, not t(). If left blank, a default message
   *   will be displayed.
667
   * @param $group
668
669
670
671
   *   (optional) The group this message is in, which is displayed in a column
   *   in test output. Use 'Debug' to indicate this is debugging output. Do not
   *   translate this string. Defaults to 'Other'; most tests do not override
   *   this default.
672
   *
673
674
675
676
   * @return
   *   TRUE if the assertion succeeded, FALSE otherwise.
   */
  protected function assertEqual($first, $second, $message = '', $group = 'Other') {
677
    // Cast objects implementing MarkupInterface to string instead of
678
    // relying on PHP casting them to string depending on what they are being
679
    // comparing with.
680
681
    $first = $this->castSafeStrings($first);
    $second = $this->castSafeStrings($second);
682
683
684
685
686
687
    $is_equal = $first == $second;
    if (!$is_equal || !$message) {
      $default_message = SafeMarkup::format('Value @first is equal to value @second.', array('@first' => var_export($first, TRUE), '@second' => var_export($second, TRUE)));
      $message = $message ? $message . PHP_EOL . $default_message : $default_message;
    }
    return $this->assert($is_equal, $message, $group);
688
689
690
691
692
693
694
695
696
697
  }

  /**
   * Check to see if two values are not equal.
   *
   * @param $first
   *   The first value to check.
   * @param $second
   *   The second value to check.
   * @param $message
698
   *   (optional) A message to display with the assertion. Do not translate
699
   *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
700
701
   *   variables in the message text, not t(). If left blank, a default message
   *   will be displayed.
702
   * @param $group
703
704
705
706
   *   (optional) The group this message is in, which is displayed in a column
   *   in test output. Use 'Debug' to indicate this is debugging output. Do not
   *   translate this string. Defaults to 'Other'; most tests do not override
   *   this default.
707
   *
708
709
710
711
   * @return
   *   TRUE if the assertion succeeded, FALSE otherwise.
   */
  protected function assertNotEqual($first, $second, $message = '', $group = 'Other') {
712
    // Cast objects implementing MarkupInterface to string instead of
713
714
715
716
717
718
719
720
721
722
    // relying on PHP casting them to string depending on what they are being
    // comparing with.
    $first = $this->castSafeStrings($first);
    $second = $this->castSafeStrings($second);
    $not_equal = $first != $second;
    if (!$not_equal || !$message) {
      $default_message = SafeMarkup::format('Value @first is not equal to value @second.', array('@first' => var_export($first, TRUE), '@second' => var_export($second, TRUE)));
      $message = $message ? $message . PHP_EOL . $default_message : $default_message;
    }
    return $this->assert($not_equal, $message, $group);
723
724
725
726
727
728
729
730
731
732
  }

  /**
   * Check to see if two values are identical.
   *
   * @param $first
   *   The first value to check.
   * @param $second
   *   The second value to check.
   * @param $message
733
   *   (optional) A message to display with the assertion. Do not translate
734
   *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
735
736
   *   variables in the message text, not t(). If left blank, a default message
   *   will be displayed.
737
   * @param $group
738
739
740
741
   *   (optional) The group this message is in, which is displayed in a column
   *   in test output. Use 'Debug' to indicate this is debugging output. Do not
   *   translate this string. Defaults to 'Other'; most tests do not override
   *   this default.
742
   *
743
744
745
746
   * @return
   *   TRUE if the assertion succeeded, FALSE otherwise.
   */
  protected function assertIdentical($first, $second, $message = '', $group = 'Other') {
747
748
749
750
751
752
    $is_identical = $first === $second;
    if (!$is_identical || !$message) {
      $default_message = SafeMarkup::format('Value @first is identical to value @second.', array('@first' => var_export($first, TRUE), '@second' => var_export($second, TRUE)));
      $message = $message ? $message . PHP_EOL . $default_message : $default_message;
    }
    return $this->assert($is_identical, $message, $group);
753
754
755
756
757
758
759
760
761
762
  }

  /**
   * Check to see if two values are not identical.
   *
   * @param $first
   *   The first value to check.
   * @param $second
   *   The second value to check.
   * @param $message
763
   *   (optional) A message to display with the assertion. Do not translate
764
   *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
765
766
   *   variables in the message text, not t(). If left blank, a default message
   *   will be displayed.
767
   * @param $group
768
769
770
771
   *   (optional) The group this message is in, which is displayed in a column
   *   in test output. Use 'Debug' to indicate this is debugging output. Do not
   *   translate this string. Defaults to 'Other'; most tests do not override
   *   this default.
772
   *
773
774
775
776
   * @return
   *   TRUE if the assertion succeeded, FALSE otherwise.
   */
  protected function assertNotIdentical($first, $second, $message = '', $group = 'Other') {
777
778
779
780
781
782
    $not_identical = $first !== $second;
    if (!$not_identical || !$message) {
      $default_message = SafeMarkup::format('Value @first is not identical to value @second.', array('@first' => var_export($first, TRUE), '@second' => var_export($second, TRUE)));
      $message = $message ? $message . PHP_EOL . $default_message : $default_message;
    }
    return $this->assert($not_identical, $message, $group);
783
784
  }

785
786
787
788
789
790
791
792
  /**
   * Checks to see if two objects are identical.
   *
   * @param object $object1
   *   The first object to check.
   * @param object $object2
   *   The second object to check.
   * @param $message
793
   *   (optional) A message to display with the assertion. Do not translate
794
   *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
795
796
   *   variables in the message text, not t(). If left blank, a default message
   *   will be displayed.
797
   * @param $group
798
799
800
801
   *   (optional) The group this message is in, which is displayed in a column
   *   in test output. Use 'Debug' to indicate this is debugging output. Do not
   *   translate this string. Defaults to 'Other'; most tests do not override
   *   this default.
802
803
804
805
   *
   * @return
   *   TRUE if the assertion succeeded, FALSE otherwise.
   */
806
  protected function assertIdenticalObject($object1, $object2, $message = '', $group = 'Other') {
807
808
809
    $message = $message ?: SafeMarkup::format('@object1 is identical to @object2', array(
      '@object1' => var_export($object1, TRUE),
      '@object2' => var_export($object2, TRUE),
810
811
812
813
814
    ));
    $identical = TRUE;
    foreach ($object1 as $key => $value) {
      $identical = $identical && isset($object2->$key) && $object2->$key === $value;
    }
815
    return $this->assertTrue($identical, $message, $group);
816
817
  }

818
819
820
821
822
823
824
  /**
   * Asserts that no errors have been logged to the PHP error.log thus far.
   *
   * @return bool
   *   TRUE if the assertion succeeded, FALSE otherwise.
   *
   * @see TestBase::prepareEnvironment()
825
   * @see \Drupal\Core\DrupalKernel::bootConfiguration()
826
827
828
829
830
831
   */
  protected function assertNoErrorsLogged() {
    // Since PHP only creates the error.log file when an actual error is
    // triggered, it is sufficient to check whether the file exists.
    return $this->assertFalse(file_exists(DRUPAL_ROOT . '/' . $this->siteDirectory . '/error.log'), 'PHP error.log is empty.');
  }
832

833
834
835
836
  /**
   * Fire an assertion that is always positive.
   *
   * @param $message
837
   *   (optional) A message to display with the assertion. Do not translate
838
   *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
839
840
   *   variables in the message text, not t(). If left blank, a default message
   *   will be displayed.
841
   * @param $group
842
843
844
845
   *   (optional) The group this message is in, which is displayed in a column
   *   in test output. Use 'Debug' to indicate this is debugging output. Do not
   *   translate this string. Defaults to 'Other'; most tests do not override
   *   this default.
846
   *
847
848
849
850
851
852
853
854
855
856
857
   * @return
   *   TRUE.
   */
  protected function pass($message = NULL, $group = 'Other') {
    return $this->assert(TRUE, $message, $group);
  }

  /**
   * Fire an assertion that is always negative.
   *
   * @param $message
858
   *   (optional) A message to display with the assertion. Do not translate
859
   *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
860
861
   *   variables in the message text, not t(). If left blank, a default message
   *   will be displayed.
862
   * @param $group
863
864
865
866
   *   (optional) The group this message is in, which is displayed in a column
   *   in test output. Use 'Debug' to indicate this is debugging output. Do not
   *   translate this string. Defaults to 'Other'; most tests do not override
   *   this default.
867
   *
868
869
870
871
872
873
874
875
876
877
878
   * @return
   *   FALSE.
   */
  protected function fail($message = NULL, $group = 'Other') {
    return $this->assert(FALSE, $message, $group);
  }

  /**
   * Fire an error assertion.
   *
   * @param $message
879
   *   (optional) A message to display with the assertion. Do not translate
880
   *   messages: use \Drupal\Component\Utility\SafeMarkup::format() to embed
881
882
   *   variables in the message text, not t(). If left blank, a default message
   *   will be displayed.
883
   * @param $group
884
885
886
887
   *   (optional) The group this message is in, which is displayed in a column
   *   in test output. Use 'Debug' to indicate this is debugging output. Do not
   *   translate this string. Defaults to 'Other'; most tests do not override
   *   this default.
888
889
   * @param $caller
   *   The caller of the error.
890
   *
891
892
893
894
895
896
897
898
899
900
901
902
903
904
   * @return
   *   FALSE.
   */
  protected function error($message = '', $group = 'Other', array $caller = NULL) {
    if ($group == 'User notice') {
      // Since 'User notice' is set by trigger_error() which is used for debug
      // set the message to a status of 'debug'.
      return $this->assert('debug', $message, 'Debug', $caller);
    }

    return $this->assert('exception', $message, $group, $caller);
  }

  /**
905
   * Logs a verbose message in a text file.
906
   *
907
908
   * The link to the verbose message will be placed in the test results as a
   * passing assertion with the text '[verbose message]'.
909
910
911
912
913
914
915
   *
   * @param $message
   *   The verbose message to be stored.
   *
   * @see simpletest_verbose()
   */
  protected function verbose($message) {
916
917
918
919
920
    // Do nothing if verbose debugging is disabled.
    if (!$this->verbose) {
      return;
    }

921
922
923
924
    $message = '<hr />ID #' . $this->verboseId . ' (<a href="' . $this->verboseClassName . '-' . ($this->verboseId - 1) . '-' . $this->testId . '.html">Previous</a> | <a href="' . $this->verboseClassName . '-' . ($this->verboseId + 1) . '-' . $this->testId . '.html">Next</a>)<hr />' . $message;
    $verbose_filename =  $this->verboseClassName . '-' . $this->verboseId . '-' . $this->testId . '.html';
    if (file_put_contents($this->verboseDirectory . '/' . $verbose_filename, $message)) {
      $url = $this->verboseDirectoryUrl . '/' . $verbose_filename;
925
926
      // Not using \Drupal\Core\Utility\LinkGeneratorInterface::generate()
      // to avoid invoking the theme system, so that unit tests
927
      // can use verbose() as well.
928
      $url = '<a href="' . $url . '" target="_blank">Verbose message</a>';
929
      $this->error($url, 'User notice');
930
    }
931
    $this->verboseId++;
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
  }

  /**
   * Run all tests in this class.
   *
   * Regardless of whether $methods are passed or not, only method names
   * starting with "test" are executed.
   *
   * @param $methods
   *   (optional) A list of method names in the test case class to run; e.g.,
   *   array('testFoo', 'testBar'). By default, all methods of the class are
   *   taken into account, but it can be useful to only run a few selected test
   *   methods during debugging.
   */
  public function run(array $methods = array()) {
947
948
949
950
951
952
953
954
955
956
957
958
959
    $class = get_class($this);

    if ($missing_requirements = $this->checkRequirements()) {
      $object_info = new \ReflectionObject($this);
      $caller = array(
        'file' => $object_info->getFileName(),
      );
      foreach ($missing_requirements as $missing_requirement) {
        TestBase::insertAssert($this->testId, $class, FALSE, $missing_requirement, 'Requirements check', $caller);
      }
      return;
    }

960
    TestServiceProvider::$currentTest = $this;
961
    $simpletest_config = $this->config('simpletest.settings');
962

963
964
965
966
    // Unless preset from run-tests.sh, retrieve the current verbose setting.
    if (!isset($this->verbose)) {
      $this->verbose = $simpletest_config->get('verbose');
    }
967

968
    if ($this->verbose) {
969
970
      // Initialize verbose debugging.
      $this->verbose = TRUE;
971
      $this->verboseDirectory = PublicStream::basePath() . '/simpletest/verbose';
972
      $this->verboseDirectoryUrl = file_create_url($this->verboseDirectory);
973
974
975
976
977
      if (file_prepare_directory($this->verboseDirectory, FILE_CREATE_DIRECTORY) && !file_exists($this->verboseDirectory . '/.htaccess')) {
        file_put_contents($this->verboseDirectory . '/.htaccess', "<IfModule mod_expires.c>\nExpiresActive Off\n</IfModule>\n");
      }
      $this->verboseClassName = str_replace("\\", "_", $class);
    }
978
979
    // HTTP auth settings (<username>:<password>) for the simpletest browser
    // when sending requests to the test site.
980
    $this->httpAuthMethod = (int) $simpletest_config->get('httpauth.method');
981
982
983
    $username = $simpletest_config->get('httpauth.username');
    $password = $simpletest_config->get('httpauth.password');
    if (!empty($username) && !empty($password)) {
984
      $this->httpAuthCredentials = $username . ':' . $password;
985
986
    }

987
988
989
990
    // Force assertion failures to be thrown as AssertionError for PHP 5 & 7
    // compatibility.
    \Drupal\Component\Assertion\Handle::register();

991
992
993
    set_error_handler(array($this, 'errorHandler'));
    // Iterate through all the methods in this class, unless a specific list of
    // methods to run was passed.
994
995
996
    $test_methods = array_filter(get_class_methods($class), function ($method) {
      return strpos($method, 'test') === 0;
    });
997
998
999
1000
1001
    if (empty($test_methods)) {
      // Call $this->assert() here because we need to pass along custom caller
      // information, lest the wrong originating code file/line be identified.
      $this->assert(FALSE, 'No test methods found.', 'Requirements', array('function' => __METHOD__ . '()', 'file' => __FILE__, 'line' => __LINE__));
    }
1002
    if ($methods) {
1003
1004
1005
1006
1007
1008
      $test_methods = array_intersect($test_methods, $methods);
    }
    foreach ($test_methods as $method) {
      // Insert a fail record. This will be deleted on completion to ensure
      // that testing completed.
      $method_info = new \ReflectionMethod($class, $method);
1009
      $caller = array(
1010
1011
1012
        'file' => $method_info->getFileName(),
        'line' => $method_info->getStartLine(),
        'function' => $class . '->' . $method . '()',
1013
      );
1014
1015
1016
1017
      $test_completion_check_id = TestBase::insertAssert($this->testId, $class, FALSE, 'The test did not complete due to a fatal error.', 'Completion check', $caller);

      try {
        $this->prepareEnvironment();
1018
      }
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
      catch (\Exception $e) {
        $this->exceptionHandler($e);
        // The prepareEnvironment() method isolates the test from the parent
        // Drupal site by creating a random database prefix and test site
        // directory. If this fails, a test would possibly operate in the
        // parent site. Therefore, the entire test run for this test class
        // has to be aborted.
        // restoreEnvironment() cannot be called, because we do not know
        // where exactly the environment setup failed.
        break;
      }

      try {
        $this->setUp();
      }
      catch (\Exception $e) {
        $this->exceptionHandler($e);
        // Abort if setUp() fails, since all test methods will fail.
        // But ensure to clean up and restore the environment, since
        // prepareEnvironment() succeeded.
        $this->restoreEnvironment();
        break;
1041
      }
1042
1043
      try {
        $this->$method();
1044
      }
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
      catch (\Exception $e) {
        $this->exceptionHandler($e);
      }
      try {
        $this->tearDown();
      }
      catch (\Exception $e) {
        $this->exceptionHandler($e);
        // If a test fails to tear down, abort the entire test class, since
        // it is likely that all tests will fail in the same way and a
        // failure here only results in additional test artifacts that have
        // to be manually deleted.
        $this->restoreEnvironment();
        break;
      }

      $this->restoreEnvironment();
      // Remove the test method completion check record.
      TestBase::deleteAssert($test_completion_check_id);
1064
    }
1065

1066
    TestServiceProvider::$currentTest = NULL;
1067
1068
1069
1070
1071
    // Clear out the error messages and restore error handler.
    drupal_get_messages();
    restore_error_handler();
  }

1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
  /**
   * Generates a database prefix for running tests.
   *
   * The database prefix is used by prepareEnvironment() to setup a public files
   * directory for the test to be run, which also contains the PHP error log,
   * which is written to in case of a fatal error. Since that directory is based
   * on the database prefix, all tests (even unit tests) need to have one, in
   * order to access and read the error log.
   *
   * @see TestBase::prepareEnvironment()
   *
   * The generated database table prefix is used for the Drupal installation
   * being performed for the test. It is also used as user agent HTTP header
1085
1086
1087
1088
   * value by the cURL-based browser of WebTestBase, which is sent to the Drupal
   * installation of the test. During early Drupal bootstrap, the user agent
   * HTTP header is parsed, and if it matches, all database queries use the
   * database table prefix that has been generated here.
1089
1090
1091
1092
   *
   * @see WebTestBase::curlInitialize()
   * @see drupal_valid_test_ua()
   */
1093
  private function prepareDatabasePrefix() {
1094
1095
1096
1097
1098
1099
1100
1101
    // Ensure that the generated test site directory does not exist already,
    // which may happen with a large amount of concurrent threads and
    // long-running tests.
    do {
      $suffix = mt_rand(100000, 999999);
      $this->siteDirectory = 'sites/simpletest/' . $suffix;
      $this->databasePrefix = 'simpletest' . $suffix;
    } while (is_dir(DRUPAL_ROOT . '/' . $this->siteDirectory));
1102
1103
1104
1105

    // As soon as the database prefix is set, the test might start to execute.
    // All assertions as well as the SimpleTest batch operations are associated
    // with the testId, so the database prefix has to be associated with it.
1106
    $affected_rows = self::getDatabaseConnection()->update('simpletest_test_id')
1107
1108
1109
      ->fields(array('last_prefix' => $this->databasePrefix))
      ->condition('test_id', $this->testId)
      ->execute();
1110
1111
1112
    if (!$affected_rows) {
      throw new \RuntimeException('Failed to set up database prefix.');
    }
1113
1114
1115
1116
1117
  }

  /**
   * Changes the database connection to the prefixed one.
   *
1118
   * @see TestBase::prepareEnvironment()
1119
   */
1120
  private function changeDatabasePrefix() {
1121
1122
1123
    if (empty($this->databasePrefix)) {
      $this->prepareDatabasePrefix();
    }
1124
1125
1126
1127
1128
1129
1130
    // If the backup already exists, something went terribly wrong.
    // This case is possible, because database connection info is a static
    // global state construct on the Database class, which at least persists
    // for all test methods executed in one PHP process.
    if (Database::getConnectionInfo('simpletest_original_default')) {
      throw new \RuntimeException("Bad Database connection state: 'simpletest_original_default' connection key already exists. Broken test?");
    }
1131
1132
1133
1134
1135

    // Clone the current connection and replace the current prefix.
    $connection_info = Database::getConnectionInfo('default');
    Database::renameConnection('default', 'simpletest_original_default');
    foreach ($connection_info as $target => $value) {
1136
1137
1138
1139
1140
      // Replace the full table prefix definition to ensure that no table
      // prefixes of the test runner leak into the test.
      $connection_info[$target]['prefix'] = array(
        'default' => $value['prefix']['default'] . $this->databasePrefix,
      );
1141
1142
    }
    Database::addConnectionInfo('default', 'default', $connection_info['default']);
1143
  }
1144

1145
1146
1147
  /**
   * Act on global state information before the environment is altered for a test.
   *
1148
   * Allows e.g. KernelTestBase to prime system/extension info from the
1149
1150
1151
1152
   * parent site (and inject it into the test environment so as to improve
   * performance).
   */
  protected function beforePrepareEnvironment() {
1153
1154
1155
1156
1157
1158
1159
  }

  /**
   * Prepares the current environment for running the test.
   *
   * Backups various current environment variables and resets them, so they do
   * not interfere with the Drupal site installation in which tests are executed
1160
   * and can be restored in TestBase::restoreEnvironment().
1161
1162
1163
1164
   *
   * Also sets up new resources for the testing environment, such as the public
   * filesystem and configuration directories.
   *
1165
1166
1167
1168
1169
   * This method is private as it must only be called once by TestBase::run()
   * (multiple invocations for the same test would have unpredictable
   * consequences) and it must not be callable or overridable by test classes.
   *
   * @see TestBase::beforePrepareEnvironment()
1170
   */
1171
  private function prepareEnvironment() {
1172
    $user = \Drupal::currentUser();
1173
1174
1175
1176
1177
1178
    // Allow (base) test classes to backup global state information.
    $this->beforePrepareEnvironment();

    // Create the database prefix for this test.
    $this->prepareDatabasePrefix();

1179
    $language_interface = \Drupal::languageManager()->getCurrentLanguage();
1180

1181
    // When running the test runner within a test, back up the original database
1182
1183
    // prefix.
    if (DRUPAL_TEST_IN_CHILD_SITE) {
1184
1185
1186
      $this->originalPrefix = drupal_valid_test_ua();
    }

1187
    // Backup current in-memory configuration.
1188
1189
    $site_path = \Drupal::service('site.path');
    $this->originalSite = $site_path;
1190
    $this->originalSettings = Settings::getAll();
1191
    $this->originalConfig = $GLOBALS['config'];
1192
    // @todo Remove all remnants of $GLOBALS['conf'].
1193
    // @see https://www.drupal.org/node/2183323
1194
    $this->originalConf = isset($GLOBALS['conf']) ? $GLOBALS['conf'] : NULL;
1195
1196

    // Backup statics and globals.
1197
    $this->originalContainer = clone \Drupal::getContainer();
1198
    $this->originalLanguage = $language_interface;
1199
    $this->originalConfigDirectories = $GLOBALS['config_directories'];
1200
1201

    // Save further contextual information.
1202
1203
    // Use the original files directory to avoid nesting it within an existing
    // simpletest directory if a test is executed within a test.
1204
    $this->originalFileDirectory = Settings::get('file_public_path', $site_path . '/files');
1205
    $this->originalProfile = drupal_get_profile();
1206
    $this->originalUser = isset($user) ? clone $user : NULL;
1207

1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
    // Prevent that session data is leaked into the UI test runner by closing
    // the session and then setting the session-name (i.e. the name of the
    // session cookie) to a random value. If a test starts a new session, then
    // it will be associated with a different session-name. After the test-run
    // it can be safely destroyed.
    // @see TestBase::restoreEnvironment()
    if (PHP_SAPI !== 'cli' && session_status() === PHP_SESSION_ACTIVE) {
      session_write_close();
    }
    $this->originalSessionName = session_name();
    session_name('SIMPLETEST' . Crypt::randomBytesBase64());
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229

    // Save and clean the shutdown callbacks array because it is static cached
    // and will be changed by the test run. Otherwise it will contain callbacks
    // from both environments and the testing environment will try to call the
    // handlers defined by the original one.
    $callbacks = &drupal_register_shutdown_function();
    $this->originalShutdownCallbacks = $callbacks;
    $callbacks = array();

    // Create test directory ahead of installation so fatal errors and debug
    // information can be logged during installation process.
1230
1231
1232
    file_prepare_directory($this->siteDirectory, FILE_CREATE_DIRECTORY | FILE_MODIFY_PERMISSIONS);

    // Prepare filesystem directory paths.
1233
1234
1235
1236
    $this->publicFilesDirectory = $this->siteDirectory . '/files';
    $this->privateFilesDirectory = $this->siteDirectory . '/private';
    $this->tempFilesDirectory = $this->siteDirectory . '/temp';
    $this->translationFilesDirectory = $this->siteDirectory . '/translations';
1237

1238
    $this->generatedTestFiles = FALSE;
1239

1240
1241
1242
    // Ensure the configImporter is refreshed for each test.
    $this->configImporter = NULL;

1243
1244
    // Unregister all custom stream wrappers of the parent site.
    // Availability of Drupal stream wrappers varies by test base class:
1245
    // - KernelTestBase supports and maintains stream wrappers in a custom
1246
1247
1248
    //   way.
    // - WebTestBase re-initializes Drupal stream wrappers after installation.
    // The original stream wrappers are restored after the test run.
1249
    // @see TestBase::restoreEnvironment()
1250
    $this->originalContainer->get('stream_wrapper_manager')->unregister();
1251

1252
    // Reset statics.
1253
1254
    drupal_static_reset();

1255
1256
    // Ensure there is no service container.
    $this->container = NULL;
1257
    \Drupal::unsetContainer();
1258

1259
    // Unset globals.
1260
    unset($GLOBALS['config_directories']);
1261
1262
    unset($GLOBALS['config']);
    unset($GLOBALS['conf']);
1263

1264
1265
    // Log fatal errors.
    ini_set('log_errors', 1);
1266
    ini_set('error_log', DRUPAL_ROOT . '/' . $this->siteDirectory . '/error.log');
1267

1268
1269
1270
    // Change the database prefix.
    $this->changeDatabasePrefix();

1271
1272
1273
    // After preparing the environment and changing the database prefix, we are
    // in a valid test environment.
    drupal_valid_test_ua($this->databasePrefix);
1274

1275
1276
1277
1278
    // Reset settings.
    new Settings(array(
      // For performance, simply use the database prefix as hash salt.
      'hash_salt' => $this->databasePrefix,
1279
      'container_yamls' => [],
1280
1281
    ));

1282
    drupal_set_time_limit($this->timeLimit);
1283
1284
  }

1285
  /**
1286
   * Performs cleanup tasks after each individual test method has been run.
1287
1288
1289
1290
1291
1292
   */
  protected function tearDown() {
  }

  /**
   * Cleans up the test environment and restores the original environment.
1293
   *
1294
   * Deletes created files, database tables, and reverts environment changes.
1295
1296
1297
1298
1299
1300
1301
   *
   * This method needs to be invoked for both unit and integration tests.
   *
   * @see TestBase::prepareDatabasePrefix()
   * @see TestBase::changeDatabasePrefix()
   * @see TestBase::prepareEnvironment()
   */
1302
  private function restoreEnvironment() {
1303
1304
1305
1306
1307
1308
1309
1310
1311
    // Destroy the session if one was started during the test-run.
    $_SESSION = array();
    if (PHP_SAPI !== 'cli' && session_status() === PHP_SESSION_ACTIVE) {
      session_destroy();
      $params = session_get_cookie_params();
      setcookie(session_name(), '', REQUEST_TIME - 3600, $params['path'], $params['domain'], $params['secure'], $params['httponly']);
    }
    session_name($this->originalSessionName);

1312
1313
1314
1315
1316
1317
1318
    // Reset all static variables.
    // Unsetting static variables will potentially invoke destruct methods,
    // which might call into functi