Classes Reference (Codeception#3707)

* * added Codeption\Module reference
* added generators to Robofile to build docs for public API classes
* regenerated all classes references

* added APC module

RoboFile.php

@@ -357,27 +357,18 @@ public function buildDocsUtils()
             $className = '\Codeception\Util\\' . $utilName;
             $source = self::REPO_BLOB_URL."/".self::STABLE_BRANCH."/src/Codeception/Util/$utilName.php";
 
-            $this->taskGenDoc('docs/reference/' . $utilName . '.md')
-                ->docClass($className)
-                ->append(
-                    '<p>&nbsp;</p><div class="alert alert-warning">Reference is taken from the source code. '
-                    .'<a href="'.$source.'">Help us to improve documentation. Edit module reference</a></div>'
-                )
-                ->processClassDocBlock(function (ReflectionClass $r, $text) {
-                    return $text . "\n";
-                })->processMethodSignature(function (ReflectionMethod $r, $text) {
-                    return '### ' . $r->getName();
-                })->processMethodDocBlock(function (ReflectionMethod $r, $text) use ($utilName, $source) {
-                    $line = $r->getStartLine();
-                    if ($r->isStatic()) {
-                        $text = "\n*static*\n$text";
-                    }
-                    $text = preg_replace("~@(.*?)([$\s])~", ' * `$1` $2', $text);
-                    $text .= "\n[See source]($source#L$line)";
-                    return "\n" . $text."\n";
-                })
-                ->reorderMethods('ksort')
-                ->run();
+            $this->documentApiClass('docs/reference/' . $utilName . '.md', $className, $source);
+        }
+    }
+
+    public function buildDocsApi()
+    {
+        $this->say("API Classes");
+        $apiClasses = ['Codeception\Module'];
+
+        foreach ($apiClasses as $apiClass) {
+            $name = (new ReflectionClass($apiClass))->getShortName();
+            $this->documentApiClass('docs/reference/' . $name . '.md', $apiClass, true);
         }
     }
 
@@ -864,4 +855,55 @@ public function codestyleFix()
             ->arg('--ignore=tests,vendor,package,docs')
             ->run();
     }
+
+    /**
+     * @param $file
+     * @param $className
+     * @param $source
+     */
+    protected function documentApiClass($file, $className, $all = false)
+    {
+        $uri = str_replace('\\', '/', $className);
+        $source = self::REPO_BLOB_URL."/".self::STABLE_BRANCH."/src/$uri.php";
+
+        $this->taskGenDoc($file)
+            ->docClass($className)
+            ->filterMethods(function(ReflectionMethod $r) use ($all, $className) {
+                return $all || $r->isPublic();
+            })
+            ->append(
+                '<p>&nbsp;</p><div class="alert alert-warning">Reference is taken from the source code. '
+                . '<a href="' . $source . '">Help us to improve documentation. Edit module reference</a></div>'
+            )
+            ->processPropertySignature(function($r) {
+                return "\n#### $" . $r->name. "\n\n";
+            })
+            ->processPropertyDocBlock(function($r, $text) {
+                $modifiers = implode(' ', \Reflection::getModifierNames($r->getModifiers()));
+                $text = ' *' . $modifiers . '* **$' . $r->name . "**\n" . $text;
+                $text = preg_replace("~@(.*?)\s(.*)~", 'type `$2`', $text);
+                return $text;
+            })
+            ->processClassDocBlock(
+                function (ReflectionClass $r, $text) {
+                    return $text . "\n";
+                }
+            )
+            ->processMethodSignature(function($r, $text) {
+                return "#### {$r->name}()\n\n" . ltrim($text, '#');
+            })
+            ->processMethodDocBlock(
+                function (ReflectionMethod $r, $text) use ($file) {
+                    $file = str_replace(__DIR__, '', $r->getFileName());
+                    $source = self::REPO_BLOB_URL."/".self::STABLE_BRANCH. $file;
+
+                    $line = $r->getStartLine();
+                    $text = preg_replace("~^\s?@(.*?)\s~m", ' * `$1` $2', $text);
+                    $text .= "\n[See source]($source#L$line)";
+                    return "\n" . $text . "\n";
+                }
+            )
+            ->reorderMethods('ksort')
+            ->run();
+    }
 }

docs/modules/AngularJS.md

@@ -775,7 +775,7 @@ $I->pressKey('#name', array('ctrl', 'a'), \Facebook\WebDriver\WebDriverKeys::DEL
 ```
 
  * `param` $element
- * `param` $char Can be char or array with modifier. You can provide several chars.
+ * `param` $char string|array Can be char or array with modifier. You can provide several chars.
  * `throws`  \Codeception\Exception\ElementNotFound
 
 
@@ -1341,6 +1341,24 @@ $I->submitForm('#my-form', [
     ]
 ]);
 ```
+
+The `$button` parameter can be either a string, an array or an instance
+of Facebook\WebDriver\WebDriverBy. When it is a string, the
+button will be found by its "name" attribute. If $button is an
+array then it will be treated as a strict selector and a WebDriverBy
+will be used verbatim.
+
+For example, given the following HTML:
+
+``` html
+<input type="submit" name="submitButton" value="Submit" />
+```
+
+`$button` could be any one of the following:
+  - 'submitButton'
+  - ['name' => 'submitButton']
+  - WebDriverBy::name('submitButton')
+
  * `param` $selector
  * `param` $params
  * `param` $button

docs/modules/Apc.md

@@ -0,0 +1,116 @@
+# Apc
+
+
+This module interacts with the [Alternative PHP Cache (APC)](http://php.net/manual/en/intro.apcu.php)
+using either _APCu_ or _APC_ extension.
+
+Performs a cleanup by flushing all values after each test run.
+
+## Status
+
+* Maintainer: **Serghei Iakovlev**
+* Stability: **stable**
+* Contact: [email protected]
+
+### Example (`unit.suite.yml`)
+
+```yaml
+   modules:
+       - Apc
+```
+
+Be sure you don't use the production server to connect.
+
+
+
+## Actions
+
+### dontSeeInApc
+ 
+Checks item in APC(u) doesn't exist or is the same as expected.
+
+Examples:
+
+``` php
+<?php
+// With only one argument, only checks the key does not exist
+$I->dontSeeInApc('users_count');
+
+// Checks a 'users_count' exists does not exist or its value is not the one provided
+$I->dontSeeInApc('users_count', 200);
+?>
+```
+
+ * `param string|string[]` $key
+ * `param mixed` $value
+
+
+### flushApc
+
+Clears the APC(u) cache
+
+
+### grabValueFromApc
+
+Grabs value from APC(u) by key.
+
+Example:
+
+``` php
+<?php
+$users_count = $I->grabValueFromApc('users_count');
+?>
+```
+
+ * `param string|string[]` $key
+
+
+### haveInApc
+
+Stores an item `$value` with `$key` on the APC(u).
+
+Examples:
+
+```php
+<?php
+// Array
+$I->haveInApc('users', ['name' => 'miles', 'email' => 'miles * `davis.com']);` 
+
+// Object
+$I->haveInApc('user', UserRepository::findFirst());
+
+// Key as array of 'key => value'
+$entries = [];
+$entries['key1'] = 'value1';
+$entries['key2'] = 'value2';
+$entries['key3'] = ['value3a','value3b'];
+$entries['key4'] = 4;
+$I->haveInApc($entries, null);
+?>
+```
+
+ * `param string|array` $key
+ * `param mixed` $value
+ * `param int` $expiration
+
+
+### seeInApc
+
+Checks item in APC(u) exists and the same as expected.
+
+Examples:
+
+``` php
+<?php
+// With only one argument, only checks the key exists
+$I->seeInApc('users_count');
+
+// Checks a 'users_count' exists and has the value 200
+$I->seeInApc('users_count', 200);
+?>
+```
+
+ * `param string|string[]` $key
+ * `param mixed` $value
+
+<p>&nbsp;</p><div class="alert alert-warning">Module reference is taken from the source code. <a href="https://github.com/Codeception/Codeception/tree/2.2/src/Codeception/Module/Apc.php">Help us to improve documentation. Edit module reference</a></div>

docs/modules/Db.md

@@ -47,7 +47,7 @@ if you run into problems loading dumps and cleaning databases.
 * password *required* - password
 * dump - path to database dump
 * populate: true - whether the the dump should be loaded before the test suite is started
-* cleanup: true - whether the dump should be reloaded after each test
+* cleanup: true - whether the dump should be reloaded before each test
 * reconnect: false - whether the module should reconnect to the database before each test
 
 ## Example

docs/modules/Laravel5.md

@@ -8,7 +8,8 @@ See the Acceptance tests section below for more details.
 
 As of Codeception 2.2 this module only works for Laravel 5.1 and later releases.
 If you want to test a Laravel 5.0 application you have to use Codeception 2.1.
-You can also upgrade your Laravel application to 5.1, for more details check the Laravel Upgrade Guide at <https://laravel.com/docs/master/upgrade>.
+You can also upgrade your Laravel application to 5.1, for more details check the Laravel Upgrade Guide
+at <https://laravel.com/docs/master/upgrade>.
 
 ## Demo project
 <https://github.com/janhenkgerritsen/codeception-laravel5-sample>
@@ -27,33 +28,43 @@ You can also upgrade your Laravel application to 5.1, for more details check the
 
 ## Config
 
-* cleanup: `boolean`, default `true` - all db queries will be run in transaction, which will be rolled back at the end of test.
-* run_database_migrations: `boolean`, default `false` - enable to run database migrations before each test.
-* environment_file: `string`, default `.env` - The .env file to load for the tests.
-* bootstrap: `string`, default `bootstrap/app.php` - Relative path to app.php config file.
-* root: `string`, default `` - Root path of our application.
-* packages: `string`, default `workbench` - Root path of application packages (if any).
-* disable_exception_handling: `boolean`, default `true` - disable Laravel exception handling
+* cleanup: `boolean`, default `true` - all database queries will be run in a transaction,
+  which will be rolled back at the end of each test.
+* run_database_migrations: `boolean`, default `false` - run database migrations before each test.
+* database_migrations_path: `string`, default `` - path to the database migrations, relative to the root of the application.
+* run_database_seeder: `boolean`, default `false` - run database seeder before each test.
+* database_seeder_class: `string`, default `` - database seeder class name.
+* environment_file: `string`, default `.env` - the environment file to load for the tests.
+* bootstrap: `string`, default `bootstrap/app.php` - relative path to app.php config file.
+* root: `string`, default `` - root path of the application.
+* packages: `string`, default `workbench` - root path of application packages (if any).
+* disable_exception_handling: `boolean`, default `true` - disable Laravel exception handling.
 * disable_middleware: `boolean`, default `false` - disable all middleware.
 * disable_events: `boolean`, default `false` - disable events (does not disable model events).
 * disable_model_events: `boolean`, default `false` - disable model events.
-* url: `string`, default `` - The application URL.
+* url: `string`, default `` - the application URL.
 
 ## API
 
-* app - `Illuminate\Foundation\Application` instance
-* client - `\Symfony\Component\BrowserKit\Client` instance
+* app - `Illuminate\Foundation\Application`
+* config - `array`
 
 ## Parts
 
-* ORM - include only haveRecord/grabRecord/seeRecord/dontSeeRecord actions
+* ORM - only include the database methods of this module:
+    * have
+    * haveMultiple
+    * haveRecord
+    * grabRecord
+    * seeRecord
+    * dontSeeRecord
 
 ## Acceptance tests
 
 You should not use this module for acceptance tests.
 If you want to use Laravel functionality with your acceptance tests,
 for example to do test setup, you can initialize the Laravel functionality
-by adding the following lines of code to your suite `_bootstrap.php` file:
+by adding the following lines of code to the `_bootstrap.php` file of your test suite:
 
     require 'bootstrap/autoload.php';
     $app = require 'bootstrap/app.php';
@@ -862,7 +873,23 @@ $value = $I->grabTextFrom('~<input value=(.*?)]~sgi'); // match with a regex
 
 
 ### have
-__not documented__
+ 
+Use Laravel's model factory to create a model.
+Can only be used with Laravel 5.1 and later.
+
+``` php
+<?php
+$I->have('App\User');
+$I->have('App\User', ['name' => 'John Doe']);
+$I->have('App\User', [], 'admin');
+?>
+```
+
+ * `see`  http://laravel.com/docs/5.1/testing#model-factories
+ * `param string` $model
+ * `param array` $attributes
+ * `param string` $name
+ * `[Part]` orm
 
 
 ### haveBinding
@@ -935,7 +962,24 @@ $I->haveInstance('My\Class', new My\Class());
 
 
 ### haveMultiple
-__not documented__
+
+Use Laravel's model factory to create multiple models.
+Can only be used with Laravel 5.1 and later.
+
+``` php
+<?php
+$I->haveMultiple('App\User', 10);
+$I->haveMultiple('App\User', 10, ['name' => 'John Doe']);
+$I->haveMultiple('App\User', 10, [], 'admin');
+?>
+```
+
+ * `see`  http://laravel.com/docs/5.1/testing#model-factories
+ * `param string` $model
+ * `param int` $times
+ * `param array` $attributes
+ * `param string` $name
+ * `[Part]` orm
 
 
 ### haveRecord