Merge branch 'master' of github.com:Codeception/codeception.github.com

DavertMik · DavertMik · commit 0cd688960c5d · 2017-06-03T23:49:31.000+03:00
diff --git a/docs/01-Introduction.md b/docs/01-Introduction.md
@@ -21,7 +21,21 @@ To test the behavior of your application as a whole, you should write functional
 Codeception supports all three testing types.
 Out of the box you have tools for writing unit, functional, and acceptance tests in a unified framework.
 
-Let's review the listed testing paradigms in reverse order.
+| | Codeception Unit Tests | Codeception Functional Tests | Codeception Acceptance Tests
+| --- | --- | --- | --- |
+| Scope of the test | Single PHP class | PHP Framework (Routing, Controllers, etc.) | Page in real browser |
+| Testing computer needs access to PHP files | Yes | Yes | No |
+| JavaScript  | No | No | Yes |
+| Webserver required | No | No | Yes |
+| Separate installations required | None | None | Selenium Server or PhantomJS |
+| Test execution speed | High | High | Low |
+| Configuration file | `unit.suite.yml` | `functional.suite.yml` | `acceptance.suite.yml` |
+
+One of the main advantages of Codeception is that you don't have to decide on just *one* type of testing. You can have all three!
+And chances are, that you will (sooner or later) need all three. That's why Codeception consists of three so-called "suites":
+A "unit suite" for all unit tests, a "functional suite" for all functional tests, and an "acceptance suite" for all acceptance tests.
+
+Let's review those three testing types in reverse order.
 
 ### Acceptance Tests
 
diff --git a/docs/03-AcceptanceTests.md b/docs/03-AcceptanceTests.md
@@ -32,6 +32,15 @@ $I->see('Welcome, Davert!');
 {% endhighlight %}
 
 **This scenario can be performed either by a simple PHP Browser or by a browser with Selenium WebDriver**.
+
+| | PhpBrowser | WebDriver |
+| --- | --- | --- |
+| Browser Engine | Guzzle + Symfony BrowserKit | Chrome or Firefox |
+| JavaScript | No | Yes |
+| `see`/`seeElement` checks if… | …text is present in source code | …text is actually visible to the user |
+| Read HTTP response headers | Yes | No |
+| Speed | Fast | Slow |
+
 We will start writing our first acceptance tests with a PhpBrowser.
 
 ## PHP Browser
@@ -357,13 +366,76 @@ $user_id = $I->grabFromCurrentUrl('~$/user/(\d+)/~');
 
 {% endhighlight %}
 
-## Selenium WebDriver
+## WebDriver: Selenium Server or PhantomJS
 
 A nice feature of Codeception is that most scenarios are similar, no matter of how they are executed.
 `PhpBrowser` was emulating browser requests but how to execute such test in a real browser like Chrome or Firefox? 
 Selenium WebDriver can drive them so in our acceptance tests we can automate scenarios we used to test manually.
 In such tests we should concentrate more on **testing the UI** than on testing functionality.
 
+"[Selenium WebDriver](http://www.seleniumhq.org/projects/webdriver/)" is the name of an API (specified by the Selenium project)
+to drive browsers automatically. Codeception supports two implementations of this API: Selenium Standalone Server and PhantomJS
+
+### Selenium Standalone Server
+
+Selenium Server is a piece of software that "drives" (i.e. runs) your local browser by sending commands (i.e. your test cases) to it.
+
+Overview of components:
+{% highlight yaml %}
+Codeception -> facebook/php-webdriver -> Selenium Server -> Gecko/Chrome Driver -> Browser (Chrome or Firefox)
+
+{% endhighlight %}
+
+Installation instructions:
+
+1. You need [Chrome](https://www.google.com/chrome/browser/desktop/) and/or [Firefox](http://www.mozilla.com/) :-)
+1. You need [Java](http://www.java.com/)
+1. Download [Selenium Standalone Server](http://www.seleniumhq.org/download/)
+1. Download [ChromeDriver](https://sites.google.com/a/chromium.org/chromedriver/)
+and/or [geckodriver](https://github.com/mozilla/geckodriver/releases) (for Firefox)
+and extract the executable to a folder where Selenium Server can find it
+(best guess: just drop it in the same folder where `selenium-server-standalone-xxx.jar` lives)
+1. Start Selenium Server with:
+    {% highlight bash %}
+
+    java -jar "/path/to/selenium-server-standalone-xxx.jar"
+    
+{% endhighlight %}
+
+[facebook/php-webdriver](https://github.com/facebook/php-webdriver) comes bundled with Codeception.
+
+### PhantomJS
+
+PhantomJS is a [headless browser](https://en.wikipedia.org/wiki/Headless_browser) based on the
+[WebKit](https://en.wikipedia.org/wiki/WebKit) rendering engine that renders your application like a real browser would.
+It just doesn't display the outcome to you.
+
+> Important notice: PhantomJS is not maintained anymore. Use it at your own risk.
+
+Overview of components:
+{% highlight yaml %}
+Codeception -> facebook/php-webdriver -> PhantomJS
+
+{% endhighlight %}
+
+Installation instructions:
+
+1. Download [PhantomJS](http://phantomjs.org/download.html) and extract it.
+1. Start the executable (located in the `bin` folder) with:
+    {% highlight bash %}
+
+    phantomjs --webdriver=4444
+    
+{% endhighlight %}
+
+Full list of available [command line arguments for PhantomJS](http://phantomjs.org/api/command-line.html)
+
+[facebook/php-webdriver](https://github.com/facebook/php-webdriver) comes bundled with Codeception.
+
+
+
+### Codeception Configuration
+
 To execute a test in a browser we need to change the suite configuration to use **WebDriver** instead of `PhpBrowser`.
 
 Modify your `acceptance.suite.yml` file:
@@ -380,7 +452,6 @@ modules:
 
 {% endhighlight %}
 
-In order to run browser tests you will need Selenium Server or PhantomJS.
 See [WebDriver Module](http://codeception.com/docs/modules/WebDriver) for details.
 
 Please note that actions executed in a browser will behave differently. For instance, `seeElement` won't just check that the element exists on a page,
diff --git a/docs/07-AdvancedUsage.md b/docs/07-AdvancedUsage.md
@@ -59,7 +59,7 @@ As you see, we are passing the Actor object into `tryToTest` method. This allows
 class BasicCest
 {
     // test
-    public function checkLogin(\AcceptanceTester $I)
+    public function tryToTest(\AcceptanceTester $I)
     {
         $I->wantTo('log in to site');
         $I->amOnPage('/');
diff --git a/docs/modules/AMQP.md b/docs/modules/AMQP.md
@@ -25,6 +25,7 @@ To use this module with Composer you need <em>"php-amqplib/php-amqplib": "~2.4"<
 * vhost: '/' - vhost to connect
 * cleanup: true - defined queues will be purged before running every test.
 * queues: [mail, twitter] - queues to cleanup
+* single_channel: false - create and use only one channel during test execution
 
 #### Example
 
@@ -37,6 +38,7 @@ To use this module with Composer you need <em>"php-amqplib/php-amqplib": "~2.4"<
                 password: 'guest'
                 vhost: '/'
                 queues: [queue1, queue2]
+                single_channel: false
 
 ### Public Properties
 
diff --git a/docs/modules/AngularJS.md b/docs/modules/AngularJS.md
@@ -891,8 +891,6 @@ Takes a screenshot of the current window and saves it to `tests/_output/debug`.
 $I->amOnPage('/user/edit');
 $I->makeScreenshot('edit_page');
 // saved to: tests/_output/debug/edit_page.png
-$I->makeScreenshot();
-// saved to: tests/_output/debug/2017-05-26_14-24-11_4b3403665fea6.png
 ?>
 
 {% endhighlight %}
diff --git a/docs/modules/Doctrine2.md b/docs/modules/Doctrine2.md
@@ -111,7 +111,7 @@ $user = $I->grabEntityFromRepository('User', array('id' => '1234'));
  * `Available since` 1.1
  * `param` $entity
  * `param array` $params
- * `return` object
+ * `return` array
 
 
 #### grabFromRepository
diff --git a/docs/modules/Laravel5.md b/docs/modules/Laravel5.md
@@ -1862,7 +1862,7 @@ $I->setCookie('PHPSESSID', 'el4ukv0kqbvoirg7nkp4dncpk3');
 
 #### submitForm
  
-Submits the given form on the page, with the given form
+Submits the given form on the page, optionally with the given form
 values.  Pass the form field's values as an array in the second
 parameter.
 
diff --git a/docs/modules/Lumen.md b/docs/modules/Lumen.md
@@ -1493,7 +1493,7 @@ $I->setCookie('PHPSESSID', 'el4ukv0kqbvoirg7nkp4dncpk3');
 
 #### submitForm
  
-Submits the given form on the page, with the given form
+Submits the given form on the page, optionally with the given form
 values.  Pass the form field's values as an array in the second
 parameter.
 
diff --git a/docs/modules/Phalcon.md b/docs/modules/Phalcon.md
@@ -1428,7 +1428,7 @@ $I->setCookie('PHPSESSID', 'el4ukv0kqbvoirg7nkp4dncpk3');
 
 #### submitForm
  
-Submits the given form on the page, with the given form
+Submits the given form on the page, optionally with the given form
 values.  Pass the form field's values as an array in the second
 parameter.
 
diff --git a/docs/modules/PhpBrowser.md b/docs/modules/PhpBrowser.md
@@ -1285,7 +1285,7 @@ Alias to `haveHttpHeader`
 
 #### submitForm
  
-Submits the given form on the page, with the given form
+Submits the given form on the page, optionally with the given form
 values.  Pass the form field's values as an array in the second
 parameter.
 
diff --git a/docs/modules/Silex.md b/docs/modules/Silex.md
@@ -1217,7 +1217,7 @@ $I->setCookie('PHPSESSID', 'el4ukv0kqbvoirg7nkp4dncpk3');
 
 #### submitForm
  
-Submits the given form on the page, with the given form
+Submits the given form on the page, optionally with the given form
 values.  Pass the form field's values as an array in the second
 parameter.
 
diff --git a/docs/modules/Symfony.md b/docs/modules/Symfony.md
@@ -1359,7 +1359,7 @@ $I->setCookie('PHPSESSID', 'el4ukv0kqbvoirg7nkp4dncpk3');
 
 #### submitForm
  
-Submits the given form on the page, with the given form
+Submits the given form on the page, optionally with the given form
 values.  Pass the form field's values as an array in the second
 parameter.
 
diff --git a/docs/modules/WebDriver.md b/docs/modules/WebDriver.md
@@ -953,7 +953,7 @@ If no parameters are provided, the full URI is returned.
 {% highlight php %}
 
 <?php
-$user_id = $I->grabFromCurrentUrl('~$/user/(\d+)/~');
+$user_id = $I->grabFromCurrentUrl('~^/user/(\d+)/~');
 $uri = $I->grabFromCurrentUrl();
 ?>
 
@@ -1058,8 +1058,6 @@ Takes a screenshot of the current window and saves it to `tests/_output/debug`.
 $I->amOnPage('/user/edit');
 $I->makeScreenshot('edit_page');
 // saved to: tests/_output/debug/edit_page.png
-$I->makeScreenshot();
-// saved to: tests/_output/debug/2017-05-26_14-24-11_4b3403665fea6.png
 ?>
 
 {% endhighlight %}
diff --git a/docs/modules/Yii1.md b/docs/modules/Yii1.md
@@ -1275,7 +1275,7 @@ $I->setCookie('PHPSESSID', 'el4ukv0kqbvoirg7nkp4dncpk3');
 
 #### submitForm
  
-Submits the given form on the page, with the given form
+Submits the given form on the page, optionally with the given form
 values.  Pass the form field's values as an array in the second
 parameter.
 
diff --git a/docs/modules/Yii2.md b/docs/modules/Yii2.md
@@ -1524,7 +1524,7 @@ $I->setCookie('PHPSESSID', 'el4ukv0kqbvoirg7nkp4dncpk3');
 
 #### submitForm
  
-Submits the given form on the page, with the given form
+Submits the given form on the page, optionally with the given form
 values.  Pass the form field's values as an array in the second
 parameter.
 
diff --git a/docs/modules/ZF1.md b/docs/modules/ZF1.md
@@ -1243,7 +1243,7 @@ $I->setCookie('PHPSESSID', 'el4ukv0kqbvoirg7nkp4dncpk3');
 
 #### submitForm
  
-Submits the given form on the page, with the given form
+Submits the given form on the page, optionally with the given form
 values.  Pass the form field's values as an array in the second
 parameter.
 
diff --git a/docs/modules/ZF2.md b/docs/modules/ZF2.md
@@ -1254,7 +1254,7 @@ $I->setCookie('PHPSESSID', 'el4ukv0kqbvoirg7nkp4dncpk3');
 
 #### submitForm
  
-Submits the given form on the page, with the given form
+Submits the given form on the page, optionally with the given form
 values.  Pass the form field's values as an array in the second
 parameter.
 
diff --git a/docs/modules/ZendExpressive.md b/docs/modules/ZendExpressive.md
@@ -1172,7 +1172,7 @@ $I->setCookie('PHPSESSID', 'el4ukv0kqbvoirg7nkp4dncpk3');
 
 #### submitForm
  
-Submits the given form on the page, with the given form
+Submits the given form on the page, optionally with the given form
 values.  Pass the form field's values as an array in the second
 parameter.
 

Original file line number	Diff line number	Diff line change
@@ -59,7 +59,7 @@ As you see, we are passing the Actor object into `tryToTest` method. This allows
`59`	`59`	`class BasicCest`
`60`	`60`	`{`
`61`	`61`	`// test`
`62`		`- public function checkLogin(\AcceptanceTester $I)`
	`62`	`+ public function tryToTest(\AcceptanceTester $I)`
`63`	`63`	`{`
`64`	`64`	`$I->wantTo('log in to site');`
`65`	`65`	`$I->amOnPage('/');`