From 08ec8a3ea0bb30b554711ed4847fc7253e0293c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Fr=C3=A9mont?= Date: Tue, 11 Mar 2025 09:07:10 +0100 Subject: [PATCH] [PHP-Config] Update main configuration --- user_guide/configuration.rst | 381 ++++++++++++++++++++++++----------- 1 file changed, 268 insertions(+), 113 deletions(-) diff --git a/user_guide/configuration.rst b/user_guide/configuration.rst index a050d71..9c66f03 100644 --- a/user_guide/configuration.rst +++ b/user_guide/configuration.rst @@ -1,7 +1,7 @@ Configuration ============= -Behat has a very powerful configuration system based on ``YAML`` configuration files and +Behat has a very powerful configuration system based on ``PHP`` configuration files and profiles. .. toctree:: @@ -9,24 +9,28 @@ profiles. configuration/suites.rst -``behat.yml`` +``behat.php`` ------------- -All configuration happens inside a single configuration file in the ``YAML`` +All configuration happens inside a single configuration file in the ``PHP`` or the ``YAML`` format. By default, Behat loads the configuration from the first file matching: #. ``behat.yaml`` or ``behat.yml`` #. ``behat.yaml.dist`` or ``behat.yml.dist`` #. ``behat.dist.yaml`` or ``behat.dist.yml`` +#. ``behat.php`` +#. ``behat.dist.php`` #. ``config/behat.yaml`` or ``config/behat.yml`` #. ``config/behat.yaml.dist`` or ``config/behat.yml.dist`` #. ``config/behat.dist.yaml`` or ``config/behat.dist.yml`` +#. ``config/behat.php`` +#. ``config/behat.dist.php`` You can also tell Behat where your config file is with the ``--config`` option: .. code-block:: bash - $ behat --config custom-config.yml + $ behat --config custom-config.php All configuration parameters in that file are defined under a profile name root (``default:`` for example). A profile is just a custom name you can use to @@ -35,13 +39,21 @@ executing your feature suite. The default profile is always ``default``. All other profiles inherit parameters from the ``default`` profile. If you only need one profile, define -all of your parameters under the ``default:`` root: +all of your parameters under the ``default`` profile: -.. code-block:: yaml +.. code-block:: php - # behat.yml - default: - #... + withProfile( + new Profile('default') + //... + ) + ; Overriding ``default`` params ----------------------------- @@ -52,68 +64,110 @@ define a new profile that overrides configuration parameters defined in the Let's assume we have a ``default`` profile as such: -.. code-block:: yaml +.. code-block:: php + + withFilter(new TagFilter('@runthisonlyondefault')) + ; - # behat.yml - default: - suites: - default: - filters: - tags: "@runthisonlyondefault" + return new Config() + ->withProfile( + new Profile('default') + ->withSuite($defaultSuite) + ) + ; Now we want a profile that changes the tag which is to be run in the default suite. We can add the profile and just override: -.. code-block:: yaml +.. code-block:: php + + withFilter(new TagFilter('@runthisonlyondefault')) + ; + + $profile1DefaultSuite = new Suite('default') + ->withFilter(new TagFilter('@runthisonlyonprofile1')) + ; + + return new Config() + ->withProfile( + new Profile('default') + ->withSuite($defaultSuite) + ) + ->withProfile( + new Profile('profile1') + ->withSuite($profile1DefaultSuite) + ) + ; - # behat.yml - default: - suites: - default: - filters: - tags: "@runthisonlyondefault" +Or maybe we want to unset the tag filter for a profile: - profile1: - suites: - default: - filters: - tags: "@runthisonlyonprofile1" +.. code-block:: php -Or maybe we want to unset the tag filter for a profile: + withFilter(new TagFilter('@runthisonlyondefault')) + ; - # behat.yml - default: - suites: - default: - filters: - tags: "@runthisonlyondefault" + $profile1DefaultSuite = new Suite('default', ['filters' => null]); - profile1: - suites: - default: - filters: ~ + return new Config() + ->withProfile( + new Profile('default') + ->withSuite($defaultSuite) + ) + ->withProfile( + new Profile('profile1') + ->withSuite($profile1DefaultSuite) + ) + ; Importing Config ---------------- -The ``imports`` block can be used to merge multiple configuration files in to +The ``import`` methods can be used to merge multiple configuration files in to one loaded config in Behat, using the following syntax: -.. code-block:: yaml +.. code-block:: php + + import([ + 'config/base.behat.php', + 'config/ci.behat.php', + ]) + ; -All files from the ``imports`` block will be loaded by Behat and merged, in -the listed order, into your ``behat.yml`` config. This is especially useful +All files from the ``import`` method will be loaded by Behat and merged, in +the listed order, into your ``behat.php`` config. This is especially useful when you want to tweak configuration slightly between local development and on Continuous Integration environments by using partial configuration files. -This allows configuration files listed in the ``imports`` key to override +This allows configuration files listed in the ``import`` method to override configuration values for previously listed files. Global profile configuration @@ -121,28 +175,50 @@ Global profile configuration You can set some global configuration in your profile configuration: -.. code-block:: yaml +.. code-block:: php - # behat.yml - default: - testers: # these are the default values - stop_on_failure: false - strict: false + withProfile( + new Profile('default', [ + 'testers' => [ + // these are the default values + 'stop_on_failure' => false, + 'strict' => false, + ], + ]) + ) + ; - # behat.yml - default: - testers: - stop_on_failure: true - strict: false +Combining the fact that you can override the default profile, you can change the configuration per profile: - ci: - testers: - stop_on_failure: false - strict: true +.. code-block:: php + + withProfile( + new Profile('default', [ + 'testers' => [ + 'stop_on_failure' => true, + 'strict' => false, + ], + ]) + ) + ->withProfile( + new Profile('ci', [ + 'testers' => [ + 'stop_on_failure' => false, + 'strict' => true, + ], + ]) + ) + ; This way, with the default profile behat will stop on failure and won't be strict, but will not stop and will be strict if the CI profile is selected. @@ -160,15 +236,40 @@ environment variable: export BEHAT_PARAMS='{"extensions" : {"Behat\\MinkExtension" : {"base_url" : "https://www.example.com/"}}}' -You can set any value for any option that is available in a ``behat.yml`` file. -Just provide options in *JSON* format. Behat will use those options as defaults. -You can always override them with the settings in the project ``behat.yml`` +You can set any value for any option that is available in a ``behat.php`` file. +Just provide options in *JSON* format. Behat will use those options as defaults. +You can always override them with the settings in the project ``behat.php`` file (it has higher priority). +.. tip:: + + You can convert the PHP configuration to JSON using the ``toArray`` method. + + .. code-block:: php + + withProfile( + new Profile('default') + ->withFilter(new TagFilter('~@wip')) + ) + ; + + var_dump(json_encode($config->toArray())); + + .. code-block:: json + + {"default":{"gherkin":{"filters":{"tags":"~@wip"}}}} + .. tip:: In order to specify a parameter in an environment variable, the value - *must not* exist in your ``behat.yml`` + *must not* exist in your ``behat.php`` .. tip:: @@ -184,14 +285,20 @@ with the option to override the filters at the command line. This is achieved by specifying the filter in the ``gherkin`` configuration: -.. code-block:: yaml +.. code-block:: php - # behat.yml + withProfile( + new Profile('default') + ->withFilter(new TagFilter('~@wip')) + ) + ; In this instance, scenarios tagged as ``@wip`` will be ignored unless the CLI command is run with a custom filter, e.g.: @@ -204,34 +311,53 @@ Custom Autoloading Sometimes you will need to place your ``features`` folder somewhere other than the default location (e.g. ``app/features``). All you need to do is specify the path -you want to autoload via ``behat.yml``: +you want to autoload via ``behat.php``: -.. code-block:: yaml +.. code-block:: php - # behat.yml + withProfile( + new Profile('default', [ + 'autoload' => [ + '' => '%paths.base%/app/features/bootstrap', + ], + ]) + ) + ; If you wish to namespace your features (for example: to be PSR-1 compliant) you will need to add the namespace to the classes and also tell behat where to load them. Here ``contexts`` is an array of classes: -.. code-block:: yaml +.. code-block:: php + [ + '' => '%paths.base%/app/features/bootstrap', + ], + ]); - default: - autoload: - '': '%paths.base%/app/features/bootstrap' - suites: - default: - contexts: [My\Application\Namespace\Bootstrap\FeatureContext] + $defaultProfile->withSuite( + new Suite('default') + ->withContexts('My\Application\Namespace\Bootstrap\FeatureContext') + ); + return new Config() + ->withProfile($defaultProfile) + ; -Using ``behat.yml`` to autoload will only allow for ``PSR-0``. +Using ``behat.php`` to autoload will only allow for ``PSR-0``. You can also use ``composer.json`` to autoload, which will also allow for ``PSR-4``: .. code-block:: json @@ -245,41 +371,70 @@ You can also use ``composer.json`` to autoload, which will also allow for ``PSR- } If you add this to your ``composer.json`` file, then you won't need to specify autoloading in -your ``behat.yml`` file: +your ``behat.php`` file: + +.. code-block:: php -.. code-block:: yaml + withSuite( + new Suite('default') + ->withContexts('My\Application\Namespace\Bootstrap\FeatureContext') + ) + ; - default: - suites: - default: - contexts: [My\Application\Namespace\Bootstrap\FeatureContext] + return new Config() + ->withProfile($defaultProfile) + ; Formatters ---------- Default formatters can be enabled by specifying them in the profile. -.. code-block:: yaml +.. code-block:: php - # behat.yml + withProfile( + new Profile('default') + ->withFormatter( + new PrettyFormatter() + ) + ) + ; Extensions ---------- Extensions can be configured like this: -.. code-block:: yaml - - # behat.yml - - default: - extensions: - Behat\MinkExtension: - base_url: http://www.example.com - selenium2: ~ +.. code-block:: php + + withProfile( + new Profile('default') + >withExtension( + new Extension('Behat\MinkExtension', [ + 'base_url' => 'http://www.example.com', + 'selenium2' => null, + ]) + ) + ) + ;