From 7aea08e1b0829447e1c40b9390544ca76b7ec4e1 Mon Sep 17 00:00:00 2001 From: Sam Hemelryk Date: Thu, 22 Mar 2012 10:45:17 +1300 Subject: [PATCH] MDL-31857 phpunit: PHPDoc and typo fixes during integration --- admin/tool/phpunit/index.php | 1 + lib/phpunit/bootstrap.php | 10 +-- lib/phpunit/lib.php | 69 ++++++++------- lib/phpunit/readme.md | 6 +- lib/tests/htmlpurifier_test.php | 18 ++-- lib/tests/phpunit_test.php | 15 +++- lib/tests/textlib_test.php | 145 ++++++++++++++++++++++++++++++-- mod/url/tests/lib_test.php | 8 ++ phpunit.xml.dist | 6 +- 9 files changed, 217 insertions(+), 61 deletions(-) diff --git a/admin/tool/phpunit/index.php b/admin/tool/phpunit/index.php index 5c55e7091db..1dbaded3c6c 100644 --- a/admin/tool/phpunit/index.php +++ b/admin/tool/phpunit/index.php @@ -19,6 +19,7 @@ * * @package tool_phpunit * @copyright 2012 Petr Skoda {@link http://skodak.org} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ define('NO_OUTPUT_BUFFERING', true); diff --git a/lib/phpunit/bootstrap.php b/lib/phpunit/bootstrap.php index 0dd6106423d..1530c005e51 100644 --- a/lib/phpunit/bootstrap.php +++ b/lib/phpunit/bootstrap.php @@ -24,7 +24,7 @@ * 131 - configuration problem * 132 - drop data, then install new test database * - * @package core_core + * @package core * @category phpunit * @copyright 2012 Petr Skoda {@link http://skodak.org} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -183,9 +183,9 @@ phpunit_util::init_globals(); /** * Print error and stop execution - * @param $text - * @param int $errorcode - * @return void - stops code execution with error code + * @param string $text An error message to display + * @param int $errorcode The error code (see docblock for detailed list) + * @return void stops code execution with error code */ function phpunit_bootstrap_error($text, $errorcode = 1) { fwrite(STDERR, $text."\n"); @@ -194,7 +194,7 @@ function phpunit_bootstrap_error($text, $errorcode = 1) { /** * Mark empty dataroot to be used for testing. - * @param $dataroot + * @param string $dataroot The dataroot directory * @return void */ function phpunit_bootstrap_initdataroot($dataroot) { diff --git a/lib/phpunit/lib.php b/lib/phpunit/lib.php index 41f7974e94d..6c01f37484e 100644 --- a/lib/phpunit/lib.php +++ b/lib/phpunit/lib.php @@ -17,19 +17,23 @@ /** * Various PHPUnit classes and functions * - * @package core_core + * @package core * @category phpunit * @copyright 2012 Petr Skoda {@link http://skodak.org} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ -require_once 'PHPUnit/Autoload.php'; // necessary when loaded from cli/util.php script +// necessary when loaded from cli/util.php script +// If this is missing then PHPUnit is not in your PHP include path. This normally +// happens if installation didn't complete correctly. Check your environment. +require_once 'PHPUnit/Autoload.php'; /** * Collection of utility methods. * - * @package core_phpunit + * @package core + * @category phpunit * @copyright 2012 Petr Skoda {@link http://skodak.org} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -39,6 +43,9 @@ class phpunit_util { */ protected static $tabledata = null; + /** + * @var array An array of globals cloned from CFG + */ protected static $globals = array(); /** @@ -134,7 +141,6 @@ class phpunit_util { /** * Called during bootstrap only! * @static - * @return void */ public static function init_globals() { global $CFG; @@ -236,7 +242,7 @@ class phpunit_util { * Note: To be used from CLI scripts only. * * @static - * @return void, may terminate execution with exit code + * @return void may terminate execution with exit code */ public static function drop_site() { global $DB, $CFG; @@ -270,7 +276,7 @@ class phpunit_util { * Note: To be used from CLI scripts only. * * @static - * @return void, may terminate execution with exit code + * @return void may terminate execution with exit code */ public static function install_site() { global $DB, $CFG; @@ -395,7 +401,7 @@ class phpunit_util { } } - $data = preg_replace('|.*|s', $suites, $data, 1); + $data = preg_replace('|.*|s', $suites, $data, 1); @unlink("$CFG->dirroot/phpunit.xml"); file_put_contents("$CFG->dirroot/phpunit.xml", $data); @@ -408,8 +414,9 @@ class phpunit_util { * * Note: this is supposed to work for very simple tests only. * - * @deprecated - * @package core_phpunit + * @deprecated since 2.3 + * @package core + * @category phpunit * @author Petr Skoda * @copyright 2012 Petr Skoda {@link http://skodak.org} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -417,10 +424,9 @@ class phpunit_util { class UnitTestCase extends PHPUnit_Framework_TestCase { /** - * @deprecated + * @deprecated since 2.3 * @param bool $expected * @param string $message - * @return void */ public function expectException($expected, $message = '') { // use phpdocs: @expectedException ExceptionClassName @@ -431,10 +437,9 @@ class UnitTestCase extends PHPUnit_Framework_TestCase { } /** - * @deprecated + * @deprecated since 2.3 * @param bool $expected * @param string $message - * @return void */ public static function expectError($expected = false, $message = '') { // not available in PHPUnit @@ -445,82 +450,75 @@ class UnitTestCase extends PHPUnit_Framework_TestCase { } /** - * @deprecated + * @deprecated since 2.3 * @static * @param mixed $actual * @param string $messages - * @return void */ public static function assertTrue($actual, $messages = '') { parent::assertTrue((bool)$actual, $messages); } /** - * @deprecated + * @deprecated since 2.3 * @static * @param mixed $actual * @param string $messages - * @return void */ public static function assertFalse($actual, $messages = '') { parent::assertFalse((bool)$actual, $messages); } /** - * @deprecated + * @deprecated since 2.3 * @static * @param mixed $expected * @param mixed $actual * @param string $message - * @return void */ public static function assertEqual($expected, $actual, $message = '') { parent::assertEquals($expected, $actual, $message); } /** - * @deprecated + * @deprecated since 2.3 * @static * @param mixed $expected * @param mixed $actual * @param string $message - * @return void */ public static function assertNotEqual($expected, $actual, $message = '') { parent::assertNotEquals($expected, $actual, $message); } /** - * @deprecated + * @deprecated since 2.3 * @static * @param mixed $expected * @param mixed $actual * @param string $message - * @return void */ public static function assertIdentical($expected, $actual, $message = '') { parent::assertSame($expected, $actual, $message); } /** - * @deprecated + * @deprecated since 2.3 * @static * @param mixed $expected * @param mixed $actual * @param string $message - * @return void */ public static function assertNotIdentical($expected, $actual, $message = '') { parent::assertNotSame($expected, $actual, $message); } /** - * @deprecated + * @deprecated since 2.3 * @static * @param mixed $actual * @param mixed $expected * @param string $message - * @return void */ public static function assertIsA($actual, $expected, $message = '') { parent::assertInstanceOf($expected, $actual, $message); @@ -529,10 +527,12 @@ class UnitTestCase extends PHPUnit_Framework_TestCase { /** - * The simplest PHPUnit test case customised for Moodle, - * do not modify database or any globals. + * The simplest PHPUnit test case customised for Moodle + * + * This test case does not modify database or any globals. * - * @package core_phpunit + * @package core + * @category phpunit * @copyright 2012 Petr Skoda {@link http://skodak.org} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -541,9 +541,9 @@ class basic_testcase extends PHPUnit_Framework_TestCase { /** * Constructs a test case with the given name. * - * @param string $name - * @param array $data - * @param string $dataName + * @param string $name + * @param array $data + * @param string $dataName */ public function __construct($name = NULL, array $data = array(), $dataName = '') { parent::__construct($name, $data, $dataName); @@ -598,5 +598,4 @@ class basic_testcase extends PHPUnit_Framework_TestCase { //TODO: somehow find out if there are changes in dataroot } -} - +} \ No newline at end of file diff --git a/lib/phpunit/readme.md b/lib/phpunit/readme.md index 5a67f11f05a..b5fa015671f 100644 --- a/lib/phpunit/readme.md +++ b/lib/phpunit/readme.md @@ -37,13 +37,13 @@ How to convert existing tests FAQs ---- -* Why is it necessary to execute the tests from commandline? PHPUnit is designed to be executed from shell, existing Moodle globals and constants would interfere with it. -* Why `tests` subdirectory? It should not collide with any plugin name because plugin names use singular form. +* Why is it necessary to execute the tests from the command line? PHPUnit is designed to be executed from shell, existing Moodle globals and constants would interfere with it. +* Why `tests` subdirectory? It is very unlikely that it will collide with any plugin name because plugin names use singular form. * Why is it necessary to include core and plugin suites in configuration files? PHPUnit does not seem to allow dynamic loading of tests from our dir structure. TODO ---- -* stage 2 - implement advaced_testcase - support for database modifications, object generators, automatic rollback of db, blobals and dataroot +* stage 2 - implement advanced_testcase - support for database modifications, object generators, automatic rollback of db, globals and dataroot * stage 3 - mocking and other advanced features, add support for execution of functional DB tests for different engines together (new options in phpunit.xml) * other - support for execution of tests and cli/util.php from web UI (to be implemented via shell execution), shell script that prepares everything for the first execution diff --git a/lib/tests/htmlpurifier_test.php b/lib/tests/htmlpurifier_test.php index a43b7d05580..f9ff4816c3b 100644 --- a/lib/tests/htmlpurifier_test.php +++ b/lib/tests/htmlpurifier_test.php @@ -17,7 +17,7 @@ /** * Unit tests for the HTMLPurifier integration * - * @package core_core + * @package core * @category phpunit * @copyright 2012 Petr Skoda {@link http://skodak.org} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -26,6 +26,14 @@ defined('MOODLE_INTERNAL') || die(); +/** + * HTMLPurifier test case + * + * @package core + * @category phpunit + * @copyright 2012 Petr Skoda {@link http://skodak.org} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class core_htmlpurifier_testcase extends basic_testcase { /** @@ -126,7 +134,7 @@ class core_htmlpurifier_testcase extends basic_testcase { * Test if linebreaks kept unchanged. * @return void */ - function test_line_breaking() { + public function test_line_breaking() { $text = "\n\raa\rsss\nsss\r"; $this->assertSame($text, purify_html($text)); } @@ -135,7 +143,7 @@ class core_htmlpurifier_testcase extends basic_testcase { * Test fixing of strict problems. * @return void */ - function test_tidy() { + public function test_tidy() { $text = "

xx"; $this->assertSame('

xx

', purify_html($text)); @@ -150,7 +158,7 @@ class core_htmlpurifier_testcase extends basic_testcase { * Test nesting - this used to cause problems in earlier versions * @return void */ - function test_nested_lists() { + public function test_nested_lists() { $text = ""; $this->assertSame($text, purify_html($text)); } @@ -159,7 +167,7 @@ class core_htmlpurifier_testcase extends basic_testcase { * Test that XSS protection works, complete smoke tests are in htmlpurifier itself. * @return void */ - function test_cleaning_nastiness() { + public function test_cleaning_nastiness() { $text = "xx"; $this->assertSame('xx', purify_html($text)); diff --git a/lib/tests/phpunit_test.php b/lib/tests/phpunit_test.php index 90ec3daabe2..0c43a41d0f1 100644 --- a/lib/tests/phpunit_test.php +++ b/lib/tests/phpunit_test.php @@ -14,18 +14,31 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . +/** + * PHPunit implementation unit tests + * + * @package core + * @category phpunit + * @copyright 2012 Petr Skoda {@link http://skodak.org} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + defined('MOODLE_INTERNAL') || die(); /** * Test integration of PHPUnit and custom Moodle hacks. * - * @package core_core + * @package core * @category phpunit * @copyright 2012 Petr Skoda {@link http://skodak.org} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class core_phpunit_basic_testcase extends basic_testcase { + /** + * Tests that bootstraping has occurred correctly + * @return void + */ public function test_bootstrap() { global $CFG; $this->assertTrue(isset($CFG->httpswwwroot)); diff --git a/lib/tests/textlib_test.php b/lib/tests/textlib_test.php index 9a7369149a9..a85d9ff7801 100644 --- a/lib/tests/textlib_test.php +++ b/lib/tests/textlib_test.php @@ -15,9 +15,9 @@ // along with Moodle. If not, see . /** - * textlib unit teststest + * textlib unit tests * - * @package core_core + * @package core * @category phpunit * @copyright 2012 Petr Skoda {@link http://skodak.org} * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later @@ -30,18 +30,26 @@ defined('MOODLE_INTERNAL') || die(); * Unit tests for our utf-8 aware text processing * * @package core - * @subpackage lib + * @category phpunit * @copyright 2010 Petr Skoda (http://skodak.org) * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class core_textlib_testcase extends basic_testcase { + /** + * Tests the static parse charset method + * @return void + */ public function test_parse_charset() { $this->assertSame(textlib::parse_charset('Cp1250'), 'windows-1250'); // does typo3 work? some encoding moodle does not use $this->assertSame(textlib::parse_charset('ms-ansi'), 'windows-1252'); } + /** + * Tests the static convert method + * @return void + */ public function test_convert() { $utf8 = "ŽluÅ¥oučký koníček"; $iso2 = pack("H*", "ae6c75bb6f75e86bfd206b6f6eede8656b"); @@ -79,6 +87,10 @@ class core_textlib_testcase extends basic_testcase { $this->assertSame(textlib::convert($str, 'GB18030', 'utf-8'), $utf8); } + /** + * Tests the static sub string method + * @return void + */ public function test_substr() { $str = "ŽluÅ¥oučký koníček"; $this->assertSame(textlib::substr($str, 0), $str); @@ -119,6 +131,10 @@ class core_textlib_testcase extends basic_testcase { $this->assertSame(textlib::substr($str, 1, 1, 'GB18030'), $s); } + /** + * Tests the static string length method + * @return void + */ public function test_strlen() { $str = "ŽluÅ¥oučký koníček"; $this->assertSame(textlib::strlen($str), 17); @@ -156,6 +172,10 @@ class core_textlib_testcase extends basic_testcase { $this->assertSame(textlib::strlen($str, 'GB18030'), 4); } + /** + * Tests the static strtolower method + * @return void + */ public function test_strtolower() { $str = "ŽluÅ¥oučký koníček"; $low = 'žluÅ¥oučký koníček'; @@ -187,6 +207,10 @@ class core_textlib_testcase extends basic_testcase { $this->assertSame(textlib::strtolower($str, 'GB18030'), $str); } + /** + * Tests the static strtoupper + * @return void + */ public function test_strtoupper() { $str = "ŽluÅ¥oučký koníček"; $up = 'ŽLUŤOUČKÝ KONÍČEK'; @@ -218,31 +242,55 @@ class core_textlib_testcase extends basic_testcase { $this->assertSame(textlib::strtoupper($str, 'GB18030'), $str); } + /** + * Tests the static strpos method + * @return void + */ public function test_strpos() { $str = "ŽluÅ¥oučký koníček"; $this->assertSame(textlib::strpos($str, 'koníč'), 10); } + /** + * Tests the static strrpos + * @return void + */ public function test_strrpos() { $str = "ŽluÅ¥oučký koníček"; $this->assertSame(textlib::strrpos($str, 'o'), 11); } + /** + * Tests the static specialtoascii method + * @return void + */ public function test_specialtoascii() { $str = "ŽluÅ¥oučký koníček"; $this->assertSame(textlib::specialtoascii($str), 'Zlutoucky konicek'); } + /** + * Tests the static encode_mimeheader method + * @return void + */ public function test_encode_mimeheader() { $str = "ŽluÅ¥oučký koníček"; $this->assertSame(textlib::encode_mimeheader($str), '=?utf-8?B?xb1sdcWlb3XEjWvDvSBrb27DrcSNZWs=?='); } + /** + * Tests the static entities_to_utf8 method + * @return void + */ public function test_entities_to_utf8() { $str = "Žluťoučký koníček"; $this->assertSame(textlib::entities_to_utf8($str), "ŽluÅ¥oučký koníček"); } + /** + * Tests the static utf8_to_entities method + * @return void + */ public function test_utf8_to_entities() { $str = "ŽluÅ¥oučký koníček"; $this->assertSame(textlib::utf8_to_entities($str), "Žluťoučký koníček"); @@ -250,12 +298,20 @@ class core_textlib_testcase extends basic_testcase { } + /** + * Tests the static trim_utf8_bom method + * @return void + */ public function test_trim_utf8_bom() { $bom = "\xef\xbb\xbf"; $str = "ŽluÅ¥oučký koníček"; $this->assertSame(textlib::trim_utf8_bom($bom.$str.$bom), $str.$bom); } + /** + * Tests the static get_encodings method + * @return void + */ public function test_get_encodings() { $encodings = textlib::get_encodings(); $this->assertTrue(is_array($encodings)); @@ -263,15 +319,27 @@ class core_textlib_testcase extends basic_testcase { $this->assertTrue(isset($encodings['UTF-8'])); } + /** + * Tests the static code2utf8 method + * @return void + */ public function test_code2utf8() { $this->assertSame(textlib::code2utf8(381), 'Ž'); } + /** + * Tests the static strtotitle method + * @return void + */ public function test_strtotitle() { $str = "žluÅ¥oučký koníček"; $this->assertSame(textlib::strtotitle($str), "ŽluÅ¥oučký Koníček"); } + /** + * Tests the deprecated method of textlib that still require an instance. + * @return void + */ public function test_deprecated_textlib_get_instance() { ob_start(); $textlib = textlib_get_instance(); @@ -297,15 +365,26 @@ class core_textlib_testcase extends basic_testcase { * Used for sorting. * * @package core - * @subpackage lib + * @category phpunit * @copyright 2011 Sam Hemelryk * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class collatorlib_testcase extends basic_testcase { + /** + * @var string The initial lang, stored because we change it during testing + */ protected $initiallang = null; + + /** + * @var string The last error that has occured + */ protected $error = null; + /** + * Prepares things for this test case + * @return void + */ public function setUp() { global $SESSION; if (isset($SESSION->lang)) { @@ -319,6 +398,11 @@ class collatorlib_testcase extends basic_testcase { } parent::setUp(); } + + /** + * Cleans things up after this test case has run + * @return void + */ public function tearDown() { global $SESSION; parent::tearDown(); @@ -329,7 +413,12 @@ class collatorlib_testcase extends basic_testcase { unset($SESSION->lang); } } - function test_asort() { + + /** + * Tests the static asort method + * @return void + */ + public function test_asort() { $arr = array('b' => 'ab', 1 => 'aa', 0 => 'cc'); collatorlib::asort($arr); $this->assertSame(array_keys($arr), array(1, 'b', 0)); @@ -340,7 +429,12 @@ class collatorlib_testcase extends basic_testcase { $this->assertSame(array_keys($arr), array(1, 'b', 'a', 0), $this->error); $this->assertSame(array_values($arr), array('aa', 'ab', 'áb', 'cc'), $this->error); } - function test_asort_objects_by_method() { + + /** + * Tests the static asort_objects_by_method method + * @return void + */ + public function test_asort_objects_by_method() { $objects = array( 'b' => new string_test_class('ab'), 1 => new string_test_class('aa'), @@ -360,7 +454,12 @@ class collatorlib_testcase extends basic_testcase { $this->assertSame(array_keys($objects), array(1, 'b', 'a', 0), $this->error); $this->assertSame($this->get_ordered_names($objects, 'get_private_name'), array('aa', 'ab', 'áb', 'cc'), $this->error); } - function test_asort_objects_by_property() { + + /** + * Tests the static asort_objects_by_method method + * @return void + */ + public function asort_objects_by_property() { $objects = array( 'b' => new string_test_class('ab'), 1 => new string_test_class('aa'), @@ -380,6 +479,13 @@ class collatorlib_testcase extends basic_testcase { $this->assertSame(array_keys($objects), array(1, 'b', 'a', 0), $this->error); $this->assertSame($this->get_ordered_names($objects, 'publicname'), array('aa', 'ab', 'áb', 'cc'), $this->error); } + + /** + * Returns an array of sorted names + * @param array $objects + * @param string $methodproperty + * @return type + */ protected function get_ordered_names($objects, $methodproperty = 'get_protected_name') { $return = array(); foreach ($objects as $object) { @@ -398,23 +504,44 @@ class collatorlib_testcase extends basic_testcase { * Simple class used to work with the unit test. * * @package core - * @subpackage lib + * @category phpunit * @copyright 2011 Sam Hemelryk * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class string_test_class extends stdClass { + /** + * @var string A public property + */ public $publicname; + /** + * @var string A protected property + */ protected $protectedname; + /** + * @var string A private property + */ private $privatename; + /** + * Constructs the test instance + * @param string $name + */ public function __construct($name) { $this->publicname = $name; $this->protectedname = $name; $this->privatename = $name; } + /** + * Returns the protected property + * @return string + */ public function get_protected_name() { return $this->protectedname; } + /** + * Returns the protected property + * @return string + */ public function get_private_name() { return $this->publicname; } -} +} \ No newline at end of file diff --git a/mod/url/tests/lib_test.php b/mod/url/tests/lib_test.php index 752bc677ad8..406405a484b 100644 --- a/mod/url/tests/lib_test.php +++ b/mod/url/tests/lib_test.php @@ -36,11 +36,19 @@ defined('MOODLE_INTERNAL') || die(); */ class mod_url_lib_testcase extends basic_testcase { + /** + * Prepares things before this test case is initialised + * @return void + */ public static function setUpBeforeClass() { global $CFG; require_once($CFG->dirroot . '/mod/url/locallib.php'); } + /** + * Tests the url_appears_valid_url function + * @return void + */ public function test_url_appears_valid_url() { $this->assertTrue(url_appears_valid_url('http://example')); $this->assertTrue(url_appears_valid_url('http://www.example.com')); diff --git a/phpunit.xml.dist b/phpunit.xml.dist index 09456e10c22..7d7e212701f 100644 --- a/phpunit.xml.dist +++ b/phpunit.xml.dist @@ -15,7 +15,7 @@ verbose="false" > - + @@ -24,7 +24,7 @@ - - + + -- 2.17.1