diff --git a/cookbooks/creating_a_context_configuration_extension.rst b/cookbooks/creating_a_context_configuration_extension.rst index d8423d0..ab7c64e 100644 --- a/cookbooks/creating_a_context_configuration_extension.rst +++ b/cookbooks/creating_a_context_configuration_extension.rst @@ -223,20 +223,31 @@ the ``HelloWorldExtension`` key and configure our ``text`` and ``enable`` value. Finally, we need to load the ``HelloWorld\Context\HelloWorldContext`` into our suite. -Here's the ``behat.yaml``: - -.. code-block:: yaml - - default: - suites: - default: - contexts: - - FeatureContext - - HelloWorld\Context\HelloWorldContext - extensions: - HelloWorld\ServiceContainer\HelloWorldExtension: - text: 'Hi there!' - enable: true +Here's the ``behat.php``: + +.. code-block:: php + + withProfile(new Profile('default') + ->withExtension(new Extension(HelloWorldExtension::class, [ + 'text' => 'Hi there!', + 'enable' => true, + ])) + ->withSuite(new Suite('default') + ->withContexts( + FeatureContext::class, + HelloWorldContext::class + ))); And now a scenario like this one: diff --git a/cookbooks/custom_formatter.rst b/cookbooks/custom_formatter.rst index 1d0c321..578f598 100644 --- a/cookbooks/custom_formatter.rst +++ b/cookbooks/custom_formatter.rst @@ -415,22 +415,31 @@ file. Integration in your project ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You need to add the extension in your Behat configuration file (default is ``behat.yml``) +You need to add the extension in your Behat configuration file (default is ``behat.php``) and configure it to use the formatter: -.. code:: yaml - - default: - extensions: - HelloWorld\BehatReviewdogFormatter\ReviewdogFormatterExtension: ~ +.. code:: php - formatters: - pretty: true - reviewdog: # "reviewdog" here is the "name" given in our formatter - # output_path is optional and handled directly by Behat - output_path: 'build/logs/behat' - # file_name is optional and a custom parameter that we inject into the printer - file_name: 'reviewdog-behat.json' + withProfile(new Profile('default') + ->withExtension(new Extension(ReviewdogFormatterExtension::class))); + ->withFormatter(new PrettyFormatter()) + // "reviewdog" here is the "name" given in our formatter + ->withFormatter(new Formatter('reviewdog', [ + // 'file_name' is optional and a custom parameter that we inject into the printer + 'file_name' => 'reviewdog-behat.json', + ]) + // outputPath is optional and handled directly by Behat + ->withOutputPath('build/logs/behat')) .. note:: @@ -445,23 +454,29 @@ You can activate the extension only when you specify a profile in your command ( For example if you want the pretty formatter by default, but both progress and reviewdog on your CI, you can configure it like this: -.. code:: yaml - - default: - extensions: - HelloWorld\BehatReviewdogFormatter\ReviewdogFormatterExtension: ~ - - formatters: - pretty: true - - ci: - formatters: - pretty: false - progress: true - reviewdog: - output_path: 'build/logs/behat' - file_name: 'reviewdog-behat.json' +.. code:: php + withProfile(new Profile('default') + ->withExtension(new Extension(ReviewdogFormatterExtension::class))) + ->withFormatter(new PrettyFormatter()) + ->withProfile(new Profile('ci') + ->disableFormatter('pretty') + ->withFormatter(new ProgressFormatter()) + ->withFormatter(new Formatter('reviewdog', [ + 'file_name' => 'reviewdog-behat.json', + ]) + ->withOutputPath('build/logs/behat'))); Enjoy! ------- diff --git a/user_guide/command_line_tool.rst b/user_guide/command_line_tool.rst index ba0e7e7..7634478 100644 --- a/user_guide/command_line_tool.rst +++ b/user_guide/command_line_tool.rst @@ -107,6 +107,8 @@ This is a summary of the usage of Behat in the command line: addition to exceptions. -h, --help Display this help message. + --convert-config + Convert the configuration to the PHP format. --config-reference Display the configuration reference. --debug diff --git a/user_guide/command_line_tool/informative_output.rst b/user_guide/command_line_tool/informative_output.rst index 4703932..88416b9 100644 --- a/user_guide/command_line_tool/informative_output.rst +++ b/user_guide/command_line_tool/informative_output.rst @@ -93,12 +93,4 @@ This can also be set for each profile using the PHP configuration: ) ; -Or the yaml configuration: - -.. code-block:: yaml - - default: - definitions: - print_unused_definitions: true - diff --git a/user_guide/configuration.rst b/user_guide/configuration.rst index 9c66f03..991df34 100644 --- a/user_guide/configuration.rst +++ b/user_guide/configuration.rst @@ -8,6 +8,7 @@ profiles. :maxdepth: 2 configuration/suites.rst + configuration/yaml_configuration.rst ``behat.php`` ------------- diff --git a/user_guide/configuration/yaml_configuration.rst b/user_guide/configuration/yaml_configuration.rst new file mode 100644 index 0000000..6cb6e9e --- /dev/null +++ b/user_guide/configuration/yaml_configuration.rst @@ -0,0 +1,66 @@ +Yaml configuration +================== + +Currently the preferred way to define the configuration for your Behat project +is by using one or more files with PHP configuration. + +But historically this configuration could also be expressed in files in the Yaml +format. This possibility is still available for now, and you can use it instead +of PHP configuration in your projects - however it will likely be deprecated and +removed in the future. + +Here is an example of how some configuration could look using a Yaml file: + +.. code-block:: yaml + + imports: + - imported.yaml + + default: + formatters: + progress: ~ + junit: false + suites: + my_suite: + contexts: + - MyContext + paths: + - "one.feature" + filters: + tags: "@run" + extensions: + MyCustomExtension: ~ + +Converting your configuration +----------------------------- + +If your project uses the legacy Yaml format for your configuration, you can easily +convert them to the PHP format by using the built in config converter. + +To use it, just run: + +.. code-block:: bash + + vendor/bin/behat --convert-config + +This will load the default config file loaded by your project and convert it from the +Yaml format to the PHP format. It will also convert any config files that are imported +by this main file. It will then remove the old Yaml files. + +We recommend carefully reviewing the generated config, particularly if you are using extensions, +custom formatters, or have complex configuration files. + +If you want to convert any other config file which is not your default config file (for +example a config file used in the CI environment), just load it with the ``-c`` +(or ``--config``) option like this: + +.. code-block:: bash + + vendor/bin/behat --convert-config -c ci-behat.yml + +This will load the ``ci-behat.yml`` config file and convert it to the PHP format. + +.. note:: + + Behat needs to be able to load this config file before converting it, so it must be + a valid Behat config file.