veyra/friends-of-behat-symfony-extension
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feature #51 Provide documentation for SymfonyExtension v2 (pamil)

Browse Source 
This PR was merged into the 2.0-dev branch.

Discussion
----------



Commits
-------

b5e6348a3a Provide documentation for SymfonyExtension v2
This commit is contained in:
Kamil Kokot
2019-01-21 12:57:04 +01:00
committed by GitHub
parent 237cbac77e b5e6348a3a
commit 578427d0a6
7 changed files with 388 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
README.md
View File

@@ -4,6 +4,29 @@
<h1 align="center">SymfonyExtension</h1> <h1 align="center">SymfonyExtension</h1>
<p align="center">Integrates Behat with Symfony (<code>^3.4</code> and <code>^4.1</code>).</p> This Behat extension provides an integration with Symfony (both `^3.4` and `^4.1`) and Mink driver for Symfony application.
It allows for:
* defining your contexts as regular Symfony services
Inspired by [Behat/Symfony2Extension](https://github.com/Behat/Symfony2Extension). * autowiring and autoconfiguring your contexts
* testing your Symfony application without having to set up a server
## Documentation
* [Installation](docs/installation.md)
* [Usage](docs/usage.md)
* [Mink integration](docs/mink_integration.md)
* [Behat/Symfony2Extension differences](docs/bs2e_differences.md)
* [Configuration reference](docs/configuration_reference.md)
## License
This extension is completely free and released under permissive [MIT license](LICENSE).
## Authors
It is originally created by [Kamil Kokot](https://github.com/pamil).
See the list of [all contributors](https://github.com/FriendsOfBehat/SymfonyExtension/graphs/contributors).

1
docs/_config.yml
View File

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

13
docs/bs2e_differences.md Normal file
View File

@@ -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).

47
docs/configuration_reference.md Normal file
View File

@@ -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`.

115
docs/installation.md Normal file
View File

@@ -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/*'
```

42
docs/mink_integration.md Normal file
View File

@@ -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).

146
docs/usage.md Normal file
View File

@@ -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%"
```