Merge pull request #450 from magnetik/doc

[2.0] Split and move doc to own folder
liip · Oct 2, 2018 · 6886642 · 6886642
2 parents f3b4642 + 8e72e38
commit 6886642
Show file tree

Hide file tree

Showing 9 changed files with 754 additions and 780 deletions.
diff --git a/README.md b/README.md
diff --git a/doc/basic.md b/doc/basic.md
@@ -0,0 +1,131 @@
+Basic usage
+===========
+
+Use `$this->makeClient` to create a Client object. Client is a Symfony class
+that can simulate HTTP requests to your controllers and then inspect the
+results. It is covered by the [functional tests](http://symfony.com/doc/current/book/testing.html#functional-tests)
+section of the Symfony documentation.
+
+After making a request, use `assertStatusCode` to verify the HTTP status code.
+If it fails it will display the last exception message or validation errors
+encountered by the Client object.
+
+If you are expecting validation errors, test them with `assertValidationErrors`.
+
+```php
+use Liip\FunctionalTestBundle\Test\WebTestCase;
+
+class MyControllerTest extends WebTestCase
+{
+    public function testContact()
+    {
+        $client = $this->makeClient();
+        $crawler = $client->request('GET', '/contact');
+        $this->assertStatusCode(200, $client);
+
+        $form = $crawler->selectButton('Submit')->form();
+        $crawler = $client->submit($form);
+
+        // We should get a validation error for the empty fields.
+        $this->assertStatusCode(200, $client);
+        $this->assertValidationErrors(['data.email', 'data.message'], $client->getContainer());
+
+        // Try again with with the fields filled out.
+        $form = $crawler->selectButton('Submit')->form();
+        $form->setValues(['contact[email]' => 'nobody@example.com', 'contact[message]' => 'Hello']);
+        $client->submit($form);
+        $this->assertStatusCode(302, $client);
+    }
+}
+```
+
+### Methods
+
+#### Check HTTP status codes
+
+##### isSuccessful()
+
+Check that the request succedded:
+
+```php
+$client = $this->makeClient();
+$client->request('GET', '/contact');
+
+// Successful HTTP request
+$this->isSuccessful($client->getResponse());
+```
+
+Add `false` as the second argument in order to check that the request failed:
+
+```php
+$client = $this->makeClient();
+$client->request('GET', '/error');
+
+// Request returned an error
+$this->isSuccessful($client->getResponse(), false);
+```
+
+In order to test more specific status codes, use `assertStatusCode()`:
+
+##### assertStatusCode()
+
+Check the HTTP status code from the request:
+
+```php
+$client = $this->makeClient();
+$client->request('GET', '/contact');
+
+// Standard response for successful HTTP request
+$this->assertStatusCode(302, $client);
+```
+
+#### Get Crawler or content
+
+##### fetchCrawler()
+
+Get a [Crawler](http://api.symfony.com/master/Symfony/Component/DomCrawler/Crawler.html) instance from an URL:
+
+```php
+$crawler = $this->fetchCrawler('/contact');
+
+// There is one <body> tag
+$this->assertSame(
+    1,
+    $crawler->filter('html > body')->count()
+);
+```
+
+##### fetchContent()
+
+Get the content of an URL:
+
+```php
+$content = $this->fetchContent('/contact');
+
+// `filter()` can't be used since the output is HTML code, check the content directly
+$this->assertContains(
+    '<h1>LiipFunctionalTestBundle</h1>',
+    $content
+);
+```
+
+#### Routing
+
+##### getURL()
+
+Generate an URL from a route:
+
+```php
+$path = $this->getUrl(
+    'route_name',
+    array(
+        'argument_1' => 'liip',
+        'argument_2' => 'test',
+    )
+);
+
+$client = $this->makeClient();
+$client->request('GET', $path);
+
+$this->isSuccessful($client->getResponse());
+```
diff --git a/doc/command.md b/doc/command.md
@@ -0,0 +1,47 @@
+Command Tests
+=============
+
+If you need to test commands, you might need to tweak the output to your needs.
+You can adjust the command verbosity:
+```yaml
+# app/config/config_test.yml
+liip_functional_test:
+    command_verbosity: debug
+```
+Supported values are ```quiet```, ```normal```, ```verbose```, ```very_verbose```
+and ```debug```. The default value is ```normal```.
+
+You can also configure this on a per-test basis:
+```php
+use Liip\FunctionalTestBundle\Test\WebTestCase;
+
+class MyTestCase extends WebTestCase {
+
+    public function myTest() {
+        $this->verbosityLevel = 'debug';
+        $this->runCommand('myCommand');
+    }
+}
+```
+
+Depending where your tests are running, you might want to disable the output
+decorator:
+```yaml
+# app/config/config_test.yml
+liip_functional_test:
+    command_decoration: false
+```
+The default value is true.
+
+You can also configure this on a per-test basis:
+```php
+use Liip\FunctionalTestBundle\Test\WebTestCase;
+
+class MyTestCase extends WebTestCase {
+
+    public function myTest() {
+        $this->decorated = false;
+        $this->runCommand('myCommand');
+    }
+}
+```