diff --git a/user_guide/command_line_tool/formatting.rst b/user_guide/command_line_tool/formatting.rst index 51a4385..44b14ab 100644 --- a/user_guide/command_line_tool/formatting.rst +++ b/user_guide/command_line_tool/formatting.rst @@ -1,8 +1,8 @@ -Format Options -============== +Output Formatters +================= Behat supports different ways of printing output information. Output printers -in ``behat`` are called *formats* or *formatters*. You can tell ``behat`` to +in Behat are called *formats* or *formatters*. You can tell Behat to run with a specific formatter by providing the ``--format`` option: .. code-block:: bash @@ -13,9 +13,9 @@ run with a specific formatter by providing the ``--format`` option: The default formatter is ``pretty``. -``behat`` supports 2 formatters out of the box: +Behat supports 3 formatters out of the box: -* ``pretty`` - prints the feature as is: +* ``pretty`` - prints the feature as is, with the full text of each step. .. image:: /images/formatter-pretty.png :align: center @@ -25,8 +25,9 @@ run with a specific formatter by providing the ``--format`` option: .. image:: /images/formatter-progress.png :align: center +* ``junit`` - prints the output to xml files in the standard junit.xml format -If you don't want to print output to the console, you can tell ``behat`` +If you don't want to print output to the console, you can tell Behat to print output to a file instead of ``STDOUT`` with the ``--out`` option: .. code-block:: bash @@ -50,16 +51,133 @@ them to use different ones - specify them with ``--out``: .. code-block:: bash - $ behat -f pretty -o ~/pretty.out -f progress -o std -f junit -o xml + $ behat -f pretty -o ~/pretty.out -f progress -o std + -f junit -o xml In this case, output of pretty formatter will be written to ``~/pretty.out`` file, output of junit formatter will be written to ``xml`` folder and progress formatter will just print to console. Behat tries hard to identify if your terminal supports colors or not, but -sometimes it still fails. In such cases, you can force ``behat`` to +sometimes it still fails. In such cases, you can force Behat to use colors (or not) with the options ``--colors`` or ``--no-colors``, respectively: .. code-block:: bash $ behat --no-colors + +Format Options +-------------- + +The formatters can be configured with some options. The following options are available for +all formatters: + +* ``output_verbosity`` indicates the level of detail of the output. Use one of the ``OutputFactory::*`` constants +* ``output_path`` indicates the path where the output should be saved. Equivalent to the ``--out`` command + line option. Should be a file or folder, depending on the formatter. +* ``output_decorate`` determines whether the output generated by Behat is "decorated" with formatting, + such as colors, bold text, or other visual enhancements. Should be a boolean, defaults to true. +* ``output_styles`` can be used to override the default styles used by Behat to display the different output + elements. It should be an array where the key is the style that needs to be overridden and which points to an array of + three values. The first one is the foreground color, the second one the background color and the third one an array of + optional styles. + +The styles available for redefinition are: + +* ``keyword`` style of Gherkin keywords +* ``stdout`` style of stdout output +* ``exception`` style of exceptions +* ``undefined`` style of undefined steps +* ``pending`` style of pending steps +* ``pending_param`` style of pending step params +* ``failed`` style of failed steps +* ``failed_param`` style of failed step params +* ``passed`` style of passed steps +* ``passed_param`` style of passed steo params +* ``skipped`` style of skipped steps +* ``skipped_param`` style of skipped step params +* ``comment`` style of comments +* ``tag`` style of scenario/feature tags + +Available colors for first two arguments (``fg`` and ``bg``) are: ``black``, ``red``, ``green``, ``yellow``, +``blue``, ``magenta``, ``cyan`` and ``white``. + +Available optional styles are: ``bold``, ``underscore``, ``blink``, ``reverse`` and ``conceal`` + +Pretty formatter +^^^^^^^^^^^^^^^^ + +The following options are specific to the Pretty formatter: + +* ``timer`` show time and memory usage at the end of the test run. Boolean, defaults to true. +* ``expand`` print each example of a scenario outline separately. Boolean, defaults to false. +* ``paths`` display the file path and line number for each scenario and the context file and method for each step. + Boolean, defaults to true. +* ``multiline`` print out PyStrings and TableNodes in full. Boolean, defaults to true. +* ``showOutput`` show the test stdout output as part of the formatter output. Should be one of the + ``ShowOutputOption`` enum values, defaults to ``ShowOutputOption::Yes``. + +Progress formatter +^^^^^^^^^^^^^^^^^^ + +The following options are specific to the Progress formatter: + +* ``timer`` show time and memory usage at the end of the test run. Boolean, defaults to true. +* ``showOutput`` show the test stdout output as part of the formatter output. Should be one of the + ``ShowOutputOption`` enum values, defaults to ``ShowOutputOption::InSummary``. + +Setting format options +^^^^^^^^^^^^^^^^^^^^^^ + +Format options can be set using the ``withFormatter()`` function of the ``Profile`` PHP config class. For example: + +.. code-block:: php + + use Behat\Config\Config; + use Behat\Config\Profile; + use Behat\Config\Formatter\PrettyFormatter; + + $profile = (new Profile('default')) + ->withFormatter((new PrettyFormatter(paths: false)) + ->withOutputStyles([ + 'comment' => [ + 'black', 'white', + ['underscore', 'bold'] + ] + ]) + ) + ; + + return (new Config())->withProfile($profile); + +These options can also be set on the command line by using the + ``--format-setting`` option which accepts a json object with this configuration. For example: + +.. code-block:: bash + + $ behat --format-settings='{\"paths\": false}' + +Disabling a formatter +^^^^^^^^^^^^^^^^^^^^^ + +You can disable a formatter so that it won't be available by using the ``disableFormatter()`` function of the +``Profile`` PHP config class. For example: + +.. code-block:: php + + use Behat\Config\Config; + use Behat\Config\Profile; + use Behat\Config\Formatter\PrettyFormatter; + + $profile = (new Profile('default')) + ->disableFormatter(PrettyFormatter::NAME) + ; + + return (new Config())->withProfile($profile); + + + + + + +