Merge pull request #186 from carlos-granados/formatter-options

docs: add documentation for formatter options

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);
+
+
+
+
+
+
+