Merge branch 'feature/refactor-tests' into develop

Author: weynhamz

PHPCtags.class.php

@@ -7,12 +7,8 @@ class PHPCtags
 
     private $mParser;
 
-    private $mOptions;
-
-    public function __construct($file, $options=array())
+    public function __construct()
     {
-        //@todo Check for existence
-        $this->mFile = $file;
         $this->mKinds= array(
             'c' => 'class',
             'm' => 'method',
@@ -23,7 +19,6 @@ public function __construct($file, $options=array())
             'i' => 'interface',
         );
         $this->mParser = new PHPParser_Parser(new PHPParser_Lexer);
-        $this->mOptions = $options;
     }
 
     private function getNodeAccess($node)
@@ -143,7 +138,7 @@ private function struct($node, $parent=array())
         return $structs;
     }
 
-    private function render($structs)
+    private function render($structs, $options)
     {
         $str = '';
         $lines = file($this->mFile);
@@ -159,37 +154,37 @@ private function render($structs)
 
             $str .= "\t" . $this->mFile;
 
-            if ($this->mOptions['excmd'] == 'number') {
+            if ($options['excmd'] == 'number') {
                 $str .= "\t" . $struct['line'];
             } else { //excmd == 'mixed' or 'pattern', default behavior
                 $str .= "\t" . "/^" . rtrim($lines[$struct['line'] - 1], "\n") . "$/";
             }
 
-            if ($this->mOptions['format'] == 1) {
+            if ($options['format'] == 1) {
                 $str .= "\n";
                 continue;
             }
 
             $str .= ";\"";
 
             #field=k, kind of tag as single letter
-            if (in_array('k', $this->mOptions['fields'])) {
-                in_array('z', $this->mOptions['fields']) && $str .= "kind:";
+            if (in_array('k', $options['fields'])) {
+                in_array('z', $options['fields']) && $str .= "kind:";
                 $str .= "\t" . $struct['kind'];
             } else
             #field=K, kind of tag as fullname
-            if (in_array('K', $this->mOptions['fields'])) {
-                in_array('z', $this->mOptions['fields']) && $str .= "kind:";
+            if (in_array('K', $options['fields'])) {
+                in_array('z', $options['fields']) && $str .= "kind:";
                 $str .= "\t" . $this->mKinds[$struct['kind']];
             }
 
             #field=n
-            if (in_array('n', $this->mOptions['fields'])) {
+            if (in_array('n', $options['fields'])) {
                 $str .= "\t" . "line:" . $struct['line'];
             }
 
             #field=s
-            if (in_array('s', $this->mOptions['fields']) && !empty($struct['scope'])) {
+            if (in_array('s', $options['fields']) && !empty($struct['scope'])) {
                 $scope = array_pop($struct['scope']);
                 list($type,$name) = each($scope);
                 switch ($type) {
@@ -206,7 +201,7 @@ private function render($structs)
             }
 
             #field=a
-            if (in_array('a', $this->mOptions['fields']) && !empty($struct['access'])) {
+            if (in_array('a', $options['fields']) && !empty($struct['access'])) {
                 $str .= "\t" . "access:" . $struct['access'];
             }
 
@@ -215,9 +210,11 @@ private function render($structs)
         return $str;
     }
 
-    public function export()
+    public function export($file, $options)
     {
+        //@todo Check for existence
+        $this->mFile = $file;
         $structs = $this->struct($this->mParser->parse(file_get_contents($this->mFile)));
-        echo $this->render($structs);
+        echo $this->render($structs,$options);
     }
 }

phpctags

@@ -44,5 +44,5 @@ if(!isset($options['fields'])) {
     $options['fields'] = str_split($options['fields']);
 }
 
-$ctags = new PHPCtags($file, $options);
-$ctags->export();
+$ctags = new PHPCtags();
+$ctags->export($file, $options);

tests/PHPCtagsTest.php

@@ -1,4 +1,6 @@
 <?php
+require_once __DIR__ . '/PHPCtagsTestCase.php';
+
 /**
  * Generated by PHPUnit_SkeletonGenerator on 2012-07-10 at 02:00:19.
  */
@@ -15,13 +17,7 @@ class PHPCtagsTest extends PHPUnit_Framework_TestCase
      */
     protected function setUp()
     {
-        $options = array(
-            'excmd' => 'pattern',
-            'fields' => array('n','k','s','S','a'),
-            'format' => 2,
-        );
-
-        $this->object = new PHPCtags(__DIR__ . '/PHPCtagsTest.example.php', $options);
+        $this->object = new PHPCtags();
     }
 
     /**
@@ -32,12 +28,59 @@ protected function tearDown()
     {
     }
 
+    /**
+     * Data provider
+     **/
+    public function provider()
+    {
+        $testcases_files = array();
+        $testcases = scandir(__DIR__ . '/testcases');
+        foreach($testcases as $testcase)
+        {
+            if($testcase === '.' || $testcase === '..') {
+                continue;
+            }
+            $testcases_files[] = array($testcase);
+        }
+        return $testcases_files;
+    }
+
     /**
      * @covers PHPCtags::export
+     * @dataProvider provider
      */
-    public function testExport()
+    public function testExport($testcase)
     {
-        $this->object->export();
+        require_once __DIR__ . '/testcases/' . $testcase;
+        $testcase_id = strstr($testcase, '.', true);
+        $testcase_class = 't_' . $testcase_id;
+        $testcase_object = new $testcase_class;
+
+        $testcase_expect = $testcase_object->getExpectResult();
+
+        ob_start();
+        $testcase_example = $testcase_object->getExample();
+        $testcase_options = $testcase_object->getOptions();
+        $this->object->export($testcase_example, $testcase_options);
+        $testcase_result = ob_get_contents();
+        ob_end_clean();
+
+        $expected_result = __DIR__ . '/' . $testcase_id . '.testcase.expect';
+        $acctural_result = __DIR__ . '/' . $testcase_id . '.testcase.result';
+
+        $msg = <<<EOF
+Test case '$testcase' has failed.
+Expected result has been dumped to '$expected_result'
+Acctural result has been dumped to '$acctural_result'
+EOF;
+
+        try {
+            $this->assertEquals(md5($testcase_expect), md5($testcase_result), $msg);
+        } catch (PHPUnit_Framework_ExpectationFailedException $e) {
+            file_put_contents($expected_result, $testcase_expect);
+            file_put_contents($acctural_result, $testcase_result);
+            throw $e;
+        }
     }
 
 }

tests/PHPCtagsTestCase.php

@@ -0,0 +1,79 @@
+<?php
+
+abstract class PHPCtagsTestCase {
+
+    protected $mFormat;
+
+    protected $mOptions;
+
+    protected $mExample;
+
+    public function __construct()
+    {
+        $this->mFormat = "<name>\t<file>\t/^<line content>$/;\"\t<kind>\tline:<line number>\t<scope>\t<access>";
+        $this->mOptions = array(
+            'excmd' => 'pattern',
+            'fields' => array('n','k','s','a'),
+            'format' => 2,
+        );
+    }
+
+    public function getOptions()
+    {
+        return $this->mOptions;
+    }
+
+    public function getExample()
+    {
+        return realpath(__DIR__ . '/examples/' . $this->mExample . '.example.php');
+    }
+
+    public function getExampleDefine()
+    {
+        require_once __DIR__ . '/examples/' . $this->mExample . '.example.define.php';
+        if (function_exists('e_' . $this->mExample . '_define')) {
+            $define = call_user_func('e_' . $this->mExample . '_define');
+        } else {
+            die('example definition not exist');
+        }
+        return $define;
+    }
+
+    public function getExampleContent()
+    {
+        return file($this->getExample());
+    }
+
+    public function getExpectResult()
+    {
+        $testcase_expect = '';
+        $testcase_example_define = $this->getExampleDefine();
+        $testcase_example_content = $this->getExampleContent();
+        foreach ($testcase_example_define as $define) {
+            $line = $this->mFormat;
+
+            $line = preg_replace('/<name>/', $define['name'], $line);
+            $line = preg_replace('/<file>/', $this->getExample(), $line);
+            $line = preg_replace('/<line content>/', rtrim($testcase_example_content[$define['line'] - 1], "\n"), $line);
+            $line = preg_replace('/<kind>/', $define['kind'], $line);
+            $line = preg_replace('/<line number>/', $define['line'], $line);
+            if(!empty($define['scope'])) {
+                $line = preg_replace('/<scope>/', $define['scope'], $line);
+            } else {
+                $line = preg_replace('/<scope>/', '', $line);
+            }
+            if(!empty($define['access'])) {
+                $line = preg_replace('/<access>/', 'access:' . $define['access'], $line);
+            } else {
+                $line = preg_replace('/<access>/', '', $line);
+            }
+            $line = rtrim($line, "\t");
+            $line .= "\n";
+
+            $testcase_expect .= $line;
+        }
+
+        return $testcase_expect;
+
+    }
+}

tests/README.md

@@ -0,0 +1,127 @@
+How to write a test case
+========================
+
+We are using [PHPUnit][] for testing.
+
+[PHPUnit]:https://github.com/sebastianbergmann/phpunit/
+
+This directory contains test cases for phpctags. The structure is shown as
+below.
+
+```
+tests/
+    |--examples/
+    |   |-- <example_identifier>.example.php
+    |   |-- <example_identifier>.example.define.php
+    |   |-- ...
+    |--testcases/
+    |   |-- <testcase_identifier>.testcase.php
+    |   |-- ...
+    |--bootstrap.php
+    |--PHPCtagsTest.php
+    |--PHPCtagsTestCase.php
+````
+
+`examples/` directory holds the example file for testing named as
+`<example_identifier>.example.php` and its token definition file named
+as `<example_identifier>.example.define.php`. The `<example_identifier>`
+should be unique and only contians characters in the range of `[0-9a-zA-Z_]`,
+especially should not contain a dot.
+
+File `<example_identifiler>.example.define.php` contains only one function
+named as `e_<example_identifier>_define` which returns an array contains
+information about tokens in the corresponding example file. This array consists
+of a set of arrays ordered by the occurrence order of the tokens in the example
+file. Each of these arrays consits of the following keys.
+
+* `name`
+
+    Required, name of the token
+
+* `line`
+
+    Required, line number of the token
+
+* `kind`
+
+    Required, kind descriptor of the token in one character.
+    For a full definition kind descriptor, please see `PHPCtags::$mKinds`.
+
+* `scope`
+
+    Optional, scope definition of the token
+
+* `access`
+
+    Optional, access restriction for the token
+
+For example, assuming we have the following code in an example file named as
+`foo.example.php`.
+
+```
+<?php
+class Foo {
+    public function bar() {
+    }
+}
+```
+
+Then, our `foo.example.define.php` should contain the following code which
+reflect the token information about the example code above and will be used
+to generate the expected result.
+
+```
+<?php
+function e_foo_define()
+{
+    return array(
+        array(
+            'name'=>'Foo',
+            'line'=>'2',
+            'kind'=>'c',
+        ),
+        array(
+            'name'=>'bar',
+            'line'=>'3',
+            'kind'=>'m',
+            'scope'=>'class:Foo',
+            'access'=>'public',
+        ),
+    );
+}
+```
+
+After finishing adding the example files, it is the time to add a test case for
+this example. All test cases are located at `testcases/` directory and named
+as `<testcase_identifier>.<testcase_description>.testcase.php`. All test case
+classes should extend from the basic abstract class `PHPCtagsTestCase` and be
+named as `t_<testcase_identifier>`. Only `$mExample` property must be assigned
+in the `__construt` function of the test case class. The other two properties
+`$mFormat` and `$mOptions` have default value predifined in the `__construct`
+function of the base `PHPCtagsTestCase` class which could be easily overwrited.
+
+Here is the test case class for the previous example and should be stored in
+file `test_foo.testcase.php`.
+
+```
+<?php
+class t_test_foo extends PHPCtagsTestCase {
+
+    public function __construct()
+    {
+        parent::__construct();
+        $this->mExample = 'foo';
+    }
+
+}
+```
+
+There is no naming restriction for `<example_identifier>` and
+`<testcase_identifier>`. Generally, the identifier for a bug fix reported in
+the issue list should be named as `bugfix_<issue number>`.
+
+We are done now. Now the `PHPCtagsTest` class will automatically find these
+test cases and use them to feed the `testExport()` method by a means called
+__[Parameterized Test][]__.
+
+[Parameterized Test]:http://xunitpatterns.com/Parameterized%20Test.html