From 11c2f79e8f554ebb906a5113274a1e22b0b0412a Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Tue, 25 Mar 2025 16:08:44 +0100 Subject: [PATCH 1/2] Add info about Yaml configuration and the config converter --- ...ting_a_context_configuration_extension.rst | 36 ++++++---- cookbooks/custom_formatter.rst | 71 +++++++++++-------- user_guide/command_line_tool.rst | 2 + .../command_line_tool/informative_output.rst | 8 --- user_guide/configuration.rst | 1 + .../configuration/yaml_configuration.rst | 63 ++++++++++++++++ 6 files changed, 130 insertions(+), 51 deletions(-) create mode 100644 user_guide/configuration/yaml_configuration.rst diff --git a/cookbooks/creating_a_context_configuration_extension.rst b/cookbooks/creating_a_context_configuration_extension.rst index d8423d0..983664c 100644 --- a/cookbooks/creating_a_context_configuration_extension.rst +++ b/cookbooks/creating_a_context_configuration_extension.rst @@ -223,20 +223,28 @@ 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('HelloWorld\ServiceContainer\HelloWorldExtension', [ + 'text' => 'Hi there!', + 'enable' => true, + ])) + ->withSuite(new Suite('default') + ->withContexts( + 'FeatureContext', + 'HelloWorld\Context\HelloWorldContext' + ))); And now a scenario like this one: diff --git a/cookbooks/custom_formatter.rst b/cookbooks/custom_formatter.rst index 1d0c321..aa44cc7 100644 --- a/cookbooks/custom_formatter.rst +++ b/cookbooks/custom_formatter.rst @@ -415,22 +415,30 @@ 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('HelloWorld\BehatReviewdogFormatter\ReviewdogFormatterExtension'))); + ->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 +453,28 @@ 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('HelloWorld\BehatReviewdogFormatter\ReviewdogFormatterExtension'))) + ->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..b74dfdf --- /dev/null +++ b/user_guide/configuration/yaml_configuration.rst @@ -0,0 +1,63 @@ +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. + +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. From 4c102f37bbd233135ddcf4b6695fe4b42aa2921f Mon Sep 17 00:00:00 2001 From: Carlos Granados Date: Wed, 2 Apr 2025 16:28:57 +0200 Subject: [PATCH 2/2] Updates after PR review --- cookbooks/creating_a_context_configuration_extension.rst | 9 ++++++--- cookbooks/custom_formatter.rst | 6 ++++-- user_guide/configuration/yaml_configuration.rst | 3 +++ 3 files changed, 13 insertions(+), 5 deletions(-) diff --git a/cookbooks/creating_a_context_configuration_extension.rst b/cookbooks/creating_a_context_configuration_extension.rst index 983664c..ab7c64e 100644 --- a/cookbooks/creating_a_context_configuration_extension.rst +++ b/cookbooks/creating_a_context_configuration_extension.rst @@ -233,17 +233,20 @@ Here's the ``behat.php``: use Behat\Config\Extension; use Behat\Config\Profile; use Behat\Config\Suite; + use FeatureContext; + use HelloWorld\Context\HelloWorldContext; + use HelloWorld\ServiceContainer\HelloWorldExtension; return new Config() ->withProfile(new Profile('default') - ->withExtension(new Extension('HelloWorld\ServiceContainer\HelloWorldExtension', [ + ->withExtension(new Extension(HelloWorldExtension::class, [ 'text' => 'Hi there!', 'enable' => true, ])) ->withSuite(new Suite('default') ->withContexts( - 'FeatureContext', - 'HelloWorld\Context\HelloWorldContext' + FeatureContext::class, + HelloWorldContext::class ))); And now a scenario like this one: diff --git a/cookbooks/custom_formatter.rst b/cookbooks/custom_formatter.rst index aa44cc7..578f598 100644 --- a/cookbooks/custom_formatter.rst +++ b/cookbooks/custom_formatter.rst @@ -427,10 +427,11 @@ and configure it to use the formatter: use Behat\Config\Formatter\Formatter; use Behat\Config\Formatter\PrettyFormatter; use Behat\Config\Profile; + use HelloWorld\BehatReviewdogFormatter\ReviewdogFormatterExtension; return new Config() ->withProfile(new Profile('default') - ->withExtension(new Extension('HelloWorld\BehatReviewdogFormatter\ReviewdogFormatterExtension'))); + ->withExtension(new Extension(ReviewdogFormatterExtension::class))); ->withFormatter(new PrettyFormatter()) // "reviewdog" here is the "name" given in our formatter ->withFormatter(new Formatter('reviewdog', [ @@ -463,10 +464,11 @@ you can configure it like this: use Behat\Config\Formatter\PrettyFormatter; use Behat\Config\Formatter\ProgressFormatter; use Behat\Config\Profile; + use HelloWorld\BehatReviewdogFormatter\ReviewdogFormatterExtension; return new Config() ->withProfile(new Profile('default') - ->withExtension(new Extension('HelloWorld\BehatReviewdogFormatter\ReviewdogFormatterExtension'))) + ->withExtension(new Extension(ReviewdogFormatterExtension::class))) ->withFormatter(new PrettyFormatter()) ->withProfile(new Profile('ci') ->disableFormatter('pretty') diff --git a/user_guide/configuration/yaml_configuration.rst b/user_guide/configuration/yaml_configuration.rst index b74dfdf..6cb6e9e 100644 --- a/user_guide/configuration/yaml_configuration.rst +++ b/user_guide/configuration/yaml_configuration.rst @@ -47,6 +47,9 @@ This will load the default config file loaded by your project and convert it fro 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: