Provide documentation for SymfonyExtension v2

docs/_config.yml

@@ -1 +0,0 @@
-theme: jekyll-theme-minimal

docs/bs2e_differences.md

@@ -0,0 +1,13 @@
+## Differences from Behat/Symfony2Extension
+
+### Contexts as services
+
+In *Behat/Symfony2Extension* the dependencies of a context are defined in the Behat configuration file. In this extension,
+contexts are defined as services - this makes reusing suites effortless, also allowing to support autowiring and autoconfiguration.
+
+### Isolated driver
+
+The Mink driver provided with this extension differs from the one provided with *Behat/Symfony2Extension*,
+as it uses an isolated application kernel instance, so that services state changes within your contexts does not affect 
+the driver results. With that limitation, changing the driver to a different one is seamless. For more information, look
+at [this issue](https://github.com/Behat/Symfony2Extension/issues/112).

docs/configuration_reference.md

@@ -0,0 +1,47 @@
+## Configuration reference
+
+By default, if no confguration is passed, *SymfonyExtension* will try its best to guess it.
+The full configuration tree looks like that:
+
+```yaml
+# behat.yml.dist / behat.yml
+
+default:
+    extensions:
+        FriendsOfBehat\SymfonyExtension:
+            bootstrap: ~
+            kernel:
+                class: ~
+                file: ~
+                environment: ~
+                debug: ~
+```
+
+ * **`bootstrap`**: 
+ 
+    It is a path to the file requried once while the extension is loaded. You can use this file to set up your testing 
+    environment - set some enviornment variables or preload an external file.
+    If you do not pass any, it would look for either `config/bootstrap.php` (Symfony 4) or `app/autoload.php` (Symfony 3). 
+    If none are found, no file would be loaded.
+    
+ * **`kernel.class`**:
+ 
+    It is a fully qualified class name of the application kernel class.
+    If you do not pass any, it would look for either `App\Kernel` (Symfony 4) or `AppKernel` (Symfony 3).
+    If none are found, an exception would be thrown and you would be required to specify it explicitly.
+    
+ * **`kernel.file`**:
+ 
+    It is a path to the file containing the application kernel class. You might want to set it if your kernel is not
+    autoloaded by Composer's autoloaded.
+    If `kernel.class` is not defined, it would automatically use `app/AppKernel.php` if `AppKernel` class was autoconfigured.
+    
+ * **`kernel.environment`**:
+ 
+    It allows you to force using a given environment. If it is not set, it uses `APP_ENV` environment variable if defined
+    or falls back to `test`.
+    
+ * **`kernel.debug`**:
+ 
+    It allows you to force enabling or disabling debug mode. If it is not set, it uses `APP_DEBUG` environment variable 
+    if defined or falls back to `true`.

docs/installation.md

@@ -0,0 +1,115 @@
+## Installation
+
+### Symfony 4 (with Flex)
+
+1. Require this extension using *Composer* and allow for using contrib recipes:
+
+```bash
+composer require --dev friends-of-behat/symfony-extension:^2.0
+```
+
+### Symfony 4 (without Flex)
+
+1. Require this extension using *Composer*:
+
+```bash
+composer require --dev friends-of-behat/symfony-extension:^2.0
+```
+
+2. Enable it within your Behat configuration:
+
+```yaml
+# behat.yml.dist / behat.yml
+
+default:
+    extensions:
+        FriendsOfBehat\SymfonyExtension: ~
+```
+
+3. Register a helper bundle in your kernel:
+
+```php
+# config/bundles.php
+
+return [
+    // ...
+    FriendsOfBehat\SymfonyExtension\Bundle\FriendsOfBehatSymfonyExtensionBundle::class => ['test' => true],
+];
+```
+
+4. Create `tests/Behat` directory for Behat-related classes:
+
+```bash
+mkdir -p tests/Behat
+```
+
+5. Set up autowiring and autoconfiguration for Behat-related services you'll create later:
+
+```yaml
+# config/services_test.yaml
+
+services:
+    _defaults:
+        autowire: true
+        autoconfigure: true
+
+    App\Tests\Behat\:
+        resource: '../tests/Behat/*'
+```
+
+### Symfony 3 (old directory structure)
+
+1. Require this extension using *Composer*:
+
+```bash
+composer require --dev friends-of-behat/symfony-extension:^2.0
+```
+
+2. Enable it within your Behat configuration:
+
+```yaml
+# behat.yml.dist / behat.yml
+
+default:
+    extensions:
+        FriendsOfBehat\SymfonyExtension: ~
+```
+
+3. Register a helper bundle in your kernel:
+
+```php
+# app/AppKernel.php
+
+public function registerBundles()
+{
+    $bundles = array(
+        // ...
+    );
+    
+    if ('test' === $this->getEnvironment()) {
+        $bundles[] = new \FriendsOfBehat\SymfonyExtension\Bundle\FriendsOfBehatSymfonyExtensionBundle();
+    }
+}
+```
+
+4. Create `tests/Behat` directory for Behat-related classes:
+
+```bash
+mkdir -p tests/Behat
+```
+
+5. Set up autowiring and autoconfiguration for Behat-related services you'll create later:
+
+```yaml
+# app/config/config_test.yml
+
+# ...
+
+services:
+    _defaults:
+        autowire: true
+        autoconfigure: true
+
+    Tests\Behat\:
+        resource: '../../tests/Behat/*'
+```

docs/mink_integration.md

@@ -0,0 +1,42 @@
+## Mink integration
+
+*SymfonyExtension* provides an integration with [Mink](https://github.com/minkphp/Mink) and defines a dedicated,
+isolated driver to use for Symfony application testing.
+
+### Installation
+
+1. Require the packages needed for the driver using *Composer*:
+
+```bash
+composer require --dev behat/mink-extension behat/mink-browserkit-driver
+```
+
+2. Enable the bundled driver:
+
+```yaml
+# behat.yml.dist / behat.yml
+
+default:
+    extensions:
+        # ...
+        Behat\MinkExtension:
+            sessions:
+                symfony:
+                    symfony: ~
+```
+
+### Usage
+
+This integration provides two services to use inside Symfony container:
+
+ * **`behat.mink.default_session`** (autowired by `\Behat\Mink\Session`) - the default Mink session for the current scenario
+ 
+ * **`behat.mink.parameters`** (autoconfigured by `$minkParameters`) - an array (`\ArrayAccess` object) containing the 
+ configuration parameters of `MinkExtension`
+
+### Caveats
+
+This driver behaviour differs from the one provided with [`Behat/Symfony2Extension`](https://github.com/Behat/Symfony2Extension),
+as it uses an isolated application kernel instance, so that services state changes within your contexts does not affect 
+the driver results. With that limitation, changing the driver to a different one is seamless. For more information, look
+at [this issue](https://github.com/Behat/Symfony2Extension/issues/112). 

docs/usage.md

@@ -0,0 +1,146 @@
+## Usage
+
+This tutorial assumes you're using the new directory structure with autowiring and autoconfiguration enabled.
+Let's first create a sample feature file (which is quite useless for demo purposes):
+
+```gherkin
+Feature: Using SymfonyExtension
+
+    Scenario: Checking the application's kernel environment
+        Then the application's kernel should use "test" environment
+``` 
+
+There are two methods to check the kernel's environment - either by calling `getEnviornment()` method on the kernel itself 
+or by injecting `%kernel.environment%` parameter.
+
+We'll need also a dummy context implementation:
+
+```php
+<?php
+
+# tests/Behat/DemoContext.php
+
+namespace App\Tests\Behat;
+// If using Symfony 3, use namespace "Tests\Behat" instead
+
+use Behat\Behat\Context\Context;
+
+final class DemoContext implements Context
+{
+    /**
+     * @Then the application's kernel should use :expected environment 
+     */
+    public function kernelEnvironmentShouldBe(string $expected): void
+    {
+    }
+}
+```
+
+And also a suite defined in Behat configuration:
+
+```yaml
+# behat.yml.dist / behat.yml
+
+default:
+    suites:
+        default:
+            contexts:
+                - App\Tests\Behat\DemoContext
+
+```
+
+After running Behat, the scenario should be passing.
+
+### Services injection
+
+Modify the existing `DemoContext` to be able to inject a kernel instance:
+
+```php
+<?php
+
+// ...
+
+use Symfony\Component\HttpKernel\KernelInterface;
+
+final class DemoContext implements Context
+{
+    /** @var KernelInterface */
+    private $kernel;
+    
+    public function __construct(KernelInterface $kernel) 
+    {
+        $this->kernel = $kernel;
+    }
+
+    /**
+     * @Then the application's kernel should use :expected environment 
+     */
+    public function kernelEnvironmentShouldBe(string $expected): void
+    {
+        if ($this->kernel->getEnvironment() !== $expected) {
+            throw new \RuntimeException();
+        }
+    }
+}
+```
+
+If you're using autowiring and autoconfiguration, that's all you need! After running Behat, you should see a passing scenario.
+
+If you're not, you need to register your context as a public service and define its dependencies:
+
+```yaml
+# config/services_test.yaml (Symfony 4)
+# app/config/config_test.yml (Symfony 3)
+
+services:
+    App\Tests\DemoContext:
+        public: true
+        arguments:
+            - "@kernel"
+```
+
+### Parameters injection
+
+Modify the existing `DemoContext` to be able to inject a kernel environment as a parameter:
+
+```php
+<?php
+
+// ...
+
+final class DemoContext implements Context
+{
+    /** @var string */
+    private $environment;
+    
+    public function __construct(string $environment) 
+    {
+        $this->environment = $environment;
+    }
+
+    /**
+     * @Then the application's kernel should use :expected environment 
+     */
+    public function kernelEnvironmentShouldBe(string $expected): void
+    {
+        if ($this->environment !== $expected) {
+            throw new \RuntimeException();
+        }
+    }
+}
+```
+
+If you're using autowiring and autoconfiguration, that's all you need! After running Behat, you should see a passing scenario.
+
+If you're not, you need to register your context as a public service and define its dependencies:
+
+```yaml
+# config/services_test.yaml (Symfony 4)
+# app/config/config_test.yml (Symfony 3)
+
+services:
+    App\Tests\DemoContext:
+        public: true
+        arguments:
+            - "%kernel.environment%"
+```