simpletest.module 21.4 KB
Newer Older
1 2 3 4 5 6 7 8 9
<?php
// $Id$

/**
 * Implementation of hook_help().
 */
function simpletest_help($path, $arg) {
  switch ($path) {
    case 'admin/help#simpletest':
10 11 12 13 14
      $output  = '<p>' . t('The SimpleTest module is a framework for running automated unit tests in Drupal. It can be used to verify a working state of Drupal before and after any code changes, or as a means for developers to write and execute tests for their modules.') .'</p>';
      $output .= '<p>' . t('Visit <a href="@admin-simpletest">Administer >> Site building >> SimpleTest</a> to display a list of available tests. For comprehensive testing, select <em>all</em> tests, or individually select tests for more targeted testing. Note that it might take several minutes for all tests to complete.)', array('@admin-simpletest' => url('admin/build/testing'))) .'</p>';
      $output .= '<p>' . t('After the tests have run, a message will be displayed next to each test group indicating whether tests within it passed, failed, or had exceptions. A pass means that a test returned the expected results, while fail means that it did not. An exception normally indicates an error outside of the test, such as a PHP warning or notice. If there were fails or exceptions, the results are expanded, and the tests that had issues will be indicated in red or pink rows. Use these results to refine your code and tests until all tests return a pass.') .'</p>';
      $output .= '<p>' . t('For more information on creating and modifying your own tests, see the <a href="@simpletest-api">SimpleTest API Documentation</a> in the Drupal handbook.', array('@simpletest-api' => 'http://drupal.org/simpletest')) .'</p>';
      $output .= '<p>' . t('For more information, see the online handbook entry for <a href="@simpletest">SimpleTest module</a>.', array('@simpletest' => 'http://drupal.org/handbook/modules/simpletest')) .'</p>';
15 16 17 18 19 20 21 22 23 24
      return $output;
  }
}

/**
 * Implementation of hook_menu().
 */
function simpletest_menu() {
  $items['admin/build/testing'] = array(
    'title' => 'Testing',
25 26
    'page callback' => 'drupal_get_form',
    'page arguments' => array('simpletest_test_form'),
27 28 29 30 31 32 33 34 35 36 37
    'description' => 'Run tests against Drupal core and your active modules. These tests help assure that your site code is working as designed.',
    'access arguments' => array('administer unit tests'),
  );
  return $items;
}

/**
 * Implementation of hook_perm().
 */
function simpletest_perm() {
  return array(
38 39 40 41
    'administer unit tests' => array(
      'title' => t('Administer unit tests'),
      'description' => t('Manage and run automated testing. %warning', array('%warning' => t('Warning: Give to trusted roles only; this permission has security implications.'))),
    ),
42 43 44 45
  );
}

/**
46
 * Implementation of hook_theme().
47 48 49
 */
function simpletest_theme() {
  return array(
50 51
    'simpletest_test_table' => array(
      'arguments' => array('table' => NULL)
52 53
    ),
    'simpletest_result_summary' => array(
54 55 56 57 58 59
      'arguments' => array('form' => NULL)
    ),
  );
}

/**
60
 * Menu callback for both running tests and listing possible tests
61
 */
62 63
function simpletest_test_form() {
  $form = array();
64 65

  // List out all tests in groups for selection.
66 67
  $uncategorized_tests = simpletest_get_all_tests();
  $tests = simpletest_categorize_tests($uncategorized_tests);
68 69
  $selected_tests = array();

70
  if (isset($_SESSION['test_id'])) {
71
    // Select all results using the active test ID used to group them.
72
    $results = db_query("SELECT * FROM {simpletest} WHERE test_id = %d ORDER BY test_class, message_id", $_SESSION['test_id']);
73

74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93
    $summary = array(
      '#theme' => 'simpletest_result_summary',
      '#pass' => 0,
      '#fail' => 0,
      '#exception' => 0,
      '#weight' => -10,
    );
    $form['summary'] = $summary;
    $form['results'] = array();
    $group_summary = array();
    $map = array(
      'pass' => theme('image', 'misc/watchdog-ok.png'),
      'fail' => theme('image', 'misc/watchdog-error.png'),
      'exception' => theme('image', 'misc/watchdog-warning.png'),
    );
    $header = array(t('Message'), t('Group'), t('Filename'), t('Line'), t('Function'), array('colspan' => 2, 'data' => t('Status')));
    while ($result = db_fetch_object($results)) {
      $class = $result->test_class;
      $info = $uncategorized_tests[$class]->getInfo();
      $group = $info['group'];
94
      $selected_tests[$group][$class] = TRUE;
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115
      if (!isset($group_summary[$group])) {
        $group_summary[$group] = $summary;
      }
      $element = &$form['results'][$group][$class];
      if (!isset($element)) {
        $element['summary'] = $summary;
      }
      $status = $result->status;
      // This reporter can only handle pass, fail and exception.
      if (isset($map[$status])) {
        $element['#title'] = $info['name'];
        $status_index = '#'. $status;
        $form['summary'][$status_index]++;
        $group_summary[$group][$status_index]++;
        $element['summary'][$status_index]++;
        $element['result_table']['#rows'][] = array(
          'data' => array(
            $result->message,
            $result->message_group,
            basename($result->file),
            $result->line,
116
            $result->function,
117 118 119 120 121 122
            $map[$status],
          ),
          'class' => "simpletest-$status",
        );
      }
      unset($element);
123
    }
124 125

    // Clear test results.
126
    simpletest_clean_results_table($_SESSION['test_id']);
127 128
    unset($_SESSION['test_id']);

129 130 131 132 133 134 135 136 137 138 139 140
    $all_ok = TRUE;
    foreach ($form['results'] as $group => &$elements) {
      $group_ok = TRUE;
      foreach ($elements as $class => &$element) {
        $info = $uncategorized_tests[$class]->getInfo();
        $ok = $element['summary']['#fail'] + $element['summary']['#exception'] == 0;
        $element += array(
          '#type' => 'fieldset',
          '#collapsible' => TRUE,
          '#collapsed' => $ok,
          '#description' => $info['description'],
        );
141
        $element['result_table']['#markup'] = theme('table', $header, $element['result_table']['#rows']);
142 143 144 145 146 147 148 149 150 151 152 153
        $element['summary']['#ok'] = $ok;
        $group_ok = $group_ok && $ok;
      }
      $elements += array(
        '#type' => 'fieldset',
        '#title' => $group,
        '#collapsible' => TRUE,
        '#collapsed' => $group_ok,
        'summary' => $group_summary[$group],
      );
      $elements['summary']['#ok'] = $group_ok;
      $all_ok = $group_ok && $all_ok;
154
    }
155
    $form['summary']['#ok'] = $all_ok;
156
  }
157 158 159 160 161 162 163 164
  $form['tests'] = array(
    '#type' => 'fieldset',
    '#title' => t('Tests'),
    '#description' => t('Select the tests you would like to run, and click Run tests.'),
  );
  $form['tests']['table'] = array(
    '#theme' => 'simpletest_test_table'
    );
165
  foreach ($tests as $group_name => $test_group) {
166 167 168
    $form['tests']['table'][$group_name] = array(
      '#collapsed' => TRUE,
    );
169
    foreach ($test_group as $test) {
170
      $test_info = $test->getInfo();
171
      $test_class = get_class($test);
172
      $is_selected = isset($selected_tests[$group_name][$test_class]);
173
      $form['tests']['table'][$group_name][$test_class] = array(
174 175
        '#type' => 'checkbox',
        '#title' => $test_info['name'],
176
        '#default_value' => $is_selected,
177 178
        '#description' => $test_info['description'],
      );
179 180 181
      if ($is_selected) {
        $form['tests']['table'][$group_name]['#collapsed'] = FALSE;
      }
182 183 184
    }
  }

185 186
  // Action buttons.
  $form['tests']['op'] = array(
187 188 189
    '#type' => 'submit',
    '#value' => t('Run tests'),
  );
190
  $form['reset'] = array(
191 192 193 194
    '#type' => 'fieldset',
    '#collapsible' => FALSE,
    '#collapsed' => FALSE,
    '#title' => t('Clean test environment'),
195
    '#description' => t('Remove tables with the prefix "simpletest" and temporary directories that are left over from tests that crashed. This is intended for developers when creating tests.'),
196
  );
197
  $form['reset']['op'] = array(
198 199
    '#type' => 'submit',
    '#value' => t('Clean environment'),
200
    '#submit' => array('simpletest_clean_environment'),
201
  );
202

203
  return $form;
204 205
}

206
function theme_simpletest_test_table($table) {
207
  drupal_add_css(drupal_get_path('module', 'simpletest') . '/simpletest.css');
208
  drupal_add_js(drupal_get_path('module', 'simpletest') . '/simpletest.js');
209 210

  // Create header for test selection table.
211
  $header = array(
212 213 214
    theme('table_select_header_cell'),
    array('data' => t('Test'), 'class' => 'simpletest_test'),
    array('data' => t('Description'), 'class' => 'simpletest_description'),
215
  );
216 217

  // Define the images used to expand/collapse the test groups.
218 219
  $js = array(
    'images' => array(
220 221
      theme('image', 'misc/menu-collapsed.png', 'Expand', 'Expand'),
      theme('image', 'misc/menu-expanded.png', 'Collapsed', 'Collapsed'),
222
    ),
223 224
  );

225
  // Go through each test group and create a row.
226
  $rows = array();
227 228
  foreach (element_children($table) as $key) {
    $element = &$table[$key];
229
    $row = array();
230

231
    // Make the class name safe for output on the page by replacing all
232 233 234
    // non-word/decimal characters with a dash (-).
    $test_class = strtolower(trim(preg_replace("/[^\w\d]/", "-", $key)));

235 236 237 238 239
    // Select the right "expand"/"collapse" image, depending on whether the
    // category is expanded (at least one test selected) or not.
    $collapsed = !empty($element['#collapsed']);
    $image_index = $collapsed ? 0 : 1;

240
    // Place-holder for checkboxes to select group of tests.
241
    $row[] = array('id' => $test_class, 'class' => 'simpletest-select-all');
242 243

    // Expand/collapse image and group title.
244
    $row[] = array(
245
      'data' =>  '<div class="simpletest-image" id="simpletest-test-group-' . $test_class . '"></div>&nbsp;' .
246
                 '<label for="' . $test_class . '-select-all" class="simpletest-group-label">' . $key . '</label>',
247
      'style' => 'font-weight: bold;'
248 249 250 251 252 253
      );

      $row[] = isset($element['#description']) ? $element['#description'] : '&nbsp;';
      $rows[] = array('data' => $row, 'class' => 'simpletest-group');

      // Add individual tests to group.
254 255 256 257 258 259
      $current_js = array(
        'testClass' => $test_class . '-test',
        'testNames' => array(),
        'imageDirection' => $image_index,
        'clickActive' => FALSE,
      );
260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278
      foreach (element_children($element) as $test_name) {
        $test = $element[$test_name];
        $row = array();

        $current_js['testNames'][] = 'edit-' . $test_name;

        // Store test title and description so that checkbox won't render them.
        $title = $test['#title'];
        $description = $test['#description'];

        unset($test['#title']);
        unset($test['#description']);

        // Test name is used to determine what tests to run.
        $test['#name'] = $test_name;

        $row[] = drupal_render($test);
        $row[] = theme('indentation', 1) . '<label for="edit-' . $test_name . '">' . $title . '</label>';
        $row[] = '<div class="description">' . $description . '</div>';
279
        $rows[] = array('data' => $row, 'class' => $test_class . '-test' . ($collapsed ? ' js-hide' : ''));
280
      }
281 282
      $js['simpletest-test-group-'. $test_class] = $current_js;
      unset($table[$key]);
283
  }
284 285

  // Add js array of settings.
286
  drupal_add_js(array('simpleTest' => $js), 'setting');
287 288 289

  if (empty($rows)) {
    return '<strong>' . t('No tests to display.') . '</strong>';
290
  }
291
  else {
292
    return theme('table', $header, $rows, array('id' => 'simpletest-form-table'));
293 294 295
  }
}

296 297 298 299 300 301 302 303 304 305 306 307
/**
 * Implementation of hook_js_alter().
 */
function simpletest_js_alter(&$javascript) {
  // Since SimpleTest is a special use case for the table select, stick the
  // SimpleTest JavaScript above the table select.
  $simpletest = drupal_get_path('module', 'simpletest') . '/simpletest.js';
  if (array_key_exists($simpletest, $javascript) && array_key_exists('misc/tableselect.js', $javascript)) {
    $javascript[$simpletest]['weight'] = $javascript['misc/tableselect.js']['weight'] - 1;
  }
}

308 309 310 311 312
function theme_simpletest_result_summary($form, $text = NULL) {
  return '<div class="simpletest-'. ($form['#ok'] ? 'pass' : 'fail') .'">' . _simpletest_format_summary_line($form) . '</div>';
}

function _simpletest_format_summary_line($summary) {
313
  return t('@pass, @fail, and @exception', array(
314 315 316 317 318 319
    '@pass' => format_plural(isset($summary['#pass']) ? $summary['#pass'] : 0, '1 pass', '@count passes'),
    '@fail' => format_plural(isset($summary['#fail']) ? $summary['#fail'] : 0, '1 fail', '@count fails'),
    '@exception' => format_plural(isset($summary['#exception']) ? $summary['#exception'] : 0, '1 exception', '@count exceptions'),
  ));
}

320
/**
321
 * Run selected tests.
322
 */
323
function simpletest_test_form_submit($form, &$form_state) {
324
  // Ensure that all classes are loaded before we create instances to get test information and run.
325
  simpletest_get_all_tests();
326 327 328

  // Get list of tests.
  $tests_list = array();
329
  foreach ($form_state['values'] as $class_name => $value) {
330
    if (class_exists($class_name) && $value === 1) {
331 332 333 334
      $tests_list[] = $class_name;
    }
  }
  if (count($tests_list) > 0 ) {
335
    simpletest_run_tests($tests_list, 'drupal');
336 337
  }
  else {
338
    drupal_set_message(t('No test(s) selected.'), 'error');
339 340 341 342
  }
}

/**
343 344
 * Actually runs tests.
 *
345 346 347 348 349
 * @param $test_list
 *   List of tests to run.
 * @param $reporter
 *   Which reporter to use. Allowed values are: text, xml, html and drupal,
 *   drupal being the default.
350
 */
351
function simpletest_run_tests($test_list, $reporter = 'drupal') {
352
  cache_clear_all();
353
  $test_id = db_insert('simpletest_test_id')->useDefaults(array('test_id'))->execute();
354

355 356 357 358 359 360
  // Get the info for the first test being run.
  $first_test = array_shift($test_list);
  $first_instance = new $first_test();
  array_unshift($test_list, $first_test);
  $info = $first_instance->getInfo();

361 362 363 364
  $batch = array(
    'title' => t('Running SimpleTests'),
    'operations' => array(
      array('_simpletest_batch_operation', array($test_list, $test_id)),
365
    ),
366 367
    'finished' => '_simpletest_batch_finished',
    'redirect' => 'admin/build/testing',
368
    'progress_message' => '',
369
    'css' => array(drupal_get_path('module', 'simpletest') . '/simpletest.css'),
370
    'init_message' => t('Processing test @num of @max - %test.', array('%test' => $info['name'], '@num' => '1', '@max' => count($test_list))),
371 372
  );
  batch_set($batch);
373 374 375 376 377 378 379
  // Normally, the forms portion of the batch API takes care of calling
  // batch_process(), but in the process it saves the whole $form into the
  // database (which is huge for the test selection form).
  // By calling batch_process() directly, we skip that behavior and ensure
  // that we don't exceed the size of data that can be sent to the database
  // (max_allowed_packet on MySQL).
  batch_process();
380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410
}

/**
 * Batch operation callback.
 */
function _simpletest_batch_operation($test_list_init, $test_id, &$context) {
  // Ensure that all classes are loaded before we unserialize some instances.
  simpletest_get_all_tests();

  // Get working values.
  if (!isset($context['sandbox']['max'])) {
    // First iteration: initialize working values.
    $test_list = $test_list_init;
    $context['sandbox']['max'] = count($test_list);
    $test_results = array('#pass' => 0, '#fail' => 0, '#exception' => 0);
  }
  else {
    // Nth iteration: get the current values where we last stored them.
    $test_list = $context['sandbox']['tests'];
    $test_results = $context['sandbox']['test_results'];
  }
  $max = $context['sandbox']['max'];

  // Perform the next test.
  $test_class = array_shift($test_list);
  $test = new $test_class($test_id);
  $test->run();
  $size = count($test_list);
  $info = $test->getInfo();

  // Gather results and compose the report.
411
  $test_results[$test_class] = $test->results;
412 413 414 415 416 417
  foreach ($test_results[$test_class] as $key => $value) {
    $test_results[$key] += $value;
  }
  $test_results[$test_class]['#name'] = $info['name'];
  $items = array();
  foreach (element_children($test_results) as $class) {
418
    array_unshift($items, '<div class="simpletest-' . ($test_results[$class]['#fail'] + $test_results[$class]['#exception'] ? 'fail' : 'pass') . '">' . t('@name: @summary', array('@name' => $test_results[$class]['#name'], '@summary' => _simpletest_format_summary_line($test_results[$class]))) . '</div>');
419
  }
420 421 422
  $context['message'] = t('Processed test @num of @max - %test.', array('%test' => $info['name'], '@num' => $max - $size, '@max' => $max));
  $context['message'] .= '<div class="simpletest-' . ($test_results['#fail'] + $test_results['#exception'] ? 'fail' : 'pass') . '">Overall results: ' . _simpletest_format_summary_line($test_results) . '</div>';
  $context['message'] .= theme('item_list', $items);
423 424 425 426 427 428 429 430 431 432 433

  // Save working values for the next iteration.
  $context['sandbox']['tests'] = $test_list;
  $context['sandbox']['test_results'] = $test_results;
  // The test_id is the only thing we need to save for the report page.
  $context['results']['test_id'] = $test_id;

  // Multistep processing: report progress.
  $context['finished'] = 1 - $size / $max;
}

434
function _simpletest_batch_finished($success, $results, $operations, $elapsed) {
435
  if (isset($results['test_id'])) {
436
    drupal_set_session('test_id', $results['test_id']);
437
  }
438
  if ($success) {
439
    drupal_set_message(t('The tests finished in @elapsed.', array('@elapsed' => $elapsed)));
440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455
  }
  else {
    drupal_set_message(t('The tests did not successfully finish.'), 'error');
  }
}

/**
 * Get a list of all of the tests.
 *
 * @return
 *   An array of tests, with the class name as the keys and the instantiated
 *   versions of the classes as the values.
 */
function simpletest_get_all_tests() {
  static $formatted_classes;
  if (!isset($formatted_classes)) {
456
    require_once DRUPAL_ROOT . '/' . drupal_get_path('module', 'simpletest') . '/drupal_web_test_case.php';
457 458 459 460 461 462 463 464 465 466
    $files = array();
    foreach (array_keys(module_rebuild_cache()) as $module) {
      $module_path = drupal_get_path('module', $module);
      $test = $module_path . "/$module.test";
      if (file_exists($test)) {
        $files[] = $test;
      }

      $tests_directory = $module_path . '/tests';
      if (is_dir($tests_directory)) {
467
        foreach (file_scan_directory($tests_directory, '/\.test$/') as $file) {
468
          $files[] = $file->filename;
469 470
        }
      }
471 472 473 474
    }

    $existing_classes = get_declared_classes();
    foreach ($files as $file) {
475
      include_once DRUPAL_ROOT . '/' . $file;
476 477 478 479 480 481
    }
    $classes = array_values(array_diff(get_declared_classes(), $existing_classes));
    $formatted_classes = array();
    foreach ($classes as $key => $class) {
      if (method_exists($class, 'getInfo')) {
        $formatted_classes[$class] = new $class;
482
      }
483
    }
484
  }
485 486 487 488 489 490
  if (count($formatted_classes) == 0) {
    drupal_set_message('No test cases found.', 'error');
    return FALSE;
  }
  return $formatted_classes;
}
491

492 493 494 495 496 497 498 499 500 501 502 503 504
/**
 * Categorize the tests into groups.
 *
 * @param $tests
 *   A list of tests from simpletest_get_all_tests.
 * @see simpletest_get_all_tests.
 */
function simpletest_categorize_tests($tests) {
  $groups = array();
  foreach ($tests as $test => $instance) {
    $info = $instance->getInfo();
    $groups[$info['group']][$test] = $instance;
  }
505
  uksort($groups, 'strnatcasecmp');
506
  return $groups;
507 508 509 510 511 512 513 514
}

/**
 * Remove all temporary database tables and directories.
 */
function simpletest_clean_environment() {
  simpletest_clean_database();
  simpletest_clean_temporary_directories();
515 516
  $count = simpletest_clean_results_table();
  drupal_set_message(t('Removed @count test results.', array('@count' => $count)));
517 518 519
}

/**
520
 * Removed prefixed tables from the database that are left over from crashed tests.
521 522
 */
function simpletest_clean_database() {
523
  $tables = db_find_tables(Database::getConnection()->prefixTables('{simpletest}') . '%');
524
  $schema = drupal_get_schema_unprocessed('simpletest');
525
  $ret = array();
526
  foreach (array_diff_key($tables, $schema) as $table) {
527 528
    // Strip the prefix and skip tables without digits following "simpletest",
    // e.g. {simpletest_test_id}.
529 530 531
    if (preg_match('/simpletest\d+.*/', $table, $matches)) {
      db_drop_table($ret, $matches[0]);
    }
532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548
  }

  if (count($ret) > 0) {
    drupal_set_message(t('Removed @count left over tables.', array('@count' => count($ret))));
  }
  else {
    drupal_set_message(t('No left over tables to remove.'));
  }
}

/**
 * Find all left over temporary directories and remove them.
 */
function simpletest_clean_temporary_directories() {
  $files = scandir(file_directory_path());
  $count = 0;
  foreach ($files as $file) {
549
    $path = file_directory_path() . '/' . $file;
550
    if (is_dir($path) && preg_match('/^simpletest\d+/', $file)) {
551
      file_unmanaged_delete_recursive($path);
552 553 554 555 556 557 558 559 560 561 562 563
      $count++;
    }
  }

  if ($count > 0) {
    drupal_set_message(t('Removed @count temporary directories.', array('@count' => $count)));
  }
  else {
    drupal_set_message(t('No temporary directories to remove.'));
  }
}

564
/**
565 566 567 568 569 570
 * Clear the test result tables.
 *
 * @param $test_id
 *   Test ID to remove results for, or NULL to remove all results.
 * @return
 *   The number of results removed or FALSE.
571
 */
572
function simpletest_clean_results_table($test_id = NULL) {
573
  if (variable_get('simpletest_clear_results', TRUE)) {
574 575 576 577 578 579 580 581 582 583 584 585
    if ($test_id) {
      $count = db_result(db_query('SELECT COUNT(test_id) FROM {simpletest_test_id} WHERE test_id = :test_id', array(':test_id' => $test_id)));

      db_delete("simpletest")
        ->condition('test_id', $test_id)
        ->execute();
      db_delete("simpletest_test_id")
        ->condition('test_id', $test_id)
        ->execute();
    }
    else {
      $count = db_result(db_query('SELECT COUNT(test_id) FROM {simpletest_test_id}'));
586

587 588 589 590
      // Clear test results.
      db_delete("simpletest")->execute();
      db_delete("simpletest_test_id")->execute();
    }
591

592
    return $count;
593
  }
594
  return FALSE;
595
}