docs: document path options

Author: carlos-granados

user_guide/command_line_tool.rst

@@ -41,6 +41,10 @@ This is a summary of the usage of Behat in the command line:
           Set formatters parameters using json object.
           Keys are parameter names, values are values. (multiple
           values allowed)
+      --print-absolute-paths
+          Print absolute paths in output
+      --editor-url=EDITOR-URL
+          URL template for opening files in an editor
       --init
           Initialize all registered test suites.
       --lang=LANG

user_guide/configuration.rst

@@ -8,6 +8,7 @@ profiles.
    :maxdepth: 2
 
    configuration/suites.rst
+   configuration/printing_paths.rst
    configuration/yaml_configuration.rst
 
 ``behat.php``

user_guide/configuration/printing_paths.rst

@@ -0,0 +1,50 @@
+Printing paths
+==============
+
+When showing test results or failures Behat will print the path to the related files. Usually it will
+simply print a path which is relative to the current directory but there are some configuration options
+that will let you modify this:
+
+``Print Absolute Paths``: if this is set to true, Behat will print the full absolute path instead.
+
+``Editor URL``: if this is set, Behat will surround each path with a link that, when clicked, will open
+the file in your IDE. This parameter is a template which can use some placeholders which will be
+replaced at run time by Behat. The available placeholders are
+
+- ``{relPath}``: Relative path to the file
+- ``{absPath}``: Absolute path to the file
+- ``{line}}``: Line number (note that this is optional and may not be available in some cases)
+
+The specific value that you need to use will depend on your IDE and other factors (for example, it may
+need to be different if you are running your code within a Docker container). Some examples could be:
+
+- For PhpStorm: ``phpstorm://open?file={relPath}&line={line}``
+- For VS Code: ``vscode://file/{absPath}:{line}``
+
+.. note::
+
+    The path style can be different for the visible path and the one used in the editor URL. For example you
+    might have a visible relative path and use an absolute path in the URL.
+
+These options can be set using the ``withPathOptions()`` function of the ``Profile`` config object, for example:
+
+.. code-block:: php
+
+    <?php
+    // behat.php
+
+    use Behat\Config\Config;
+    use Behat\Config\Profile;
+
+    return (new Config())
+        ->withProfile((new Profile('default'))
+            ->withPathOptions(
+                printAbsolutePaths: true,
+                editorUrl: 'phpstorm://open?file={relPath}&line={line}'
+            ));
+
+They can also be set as command line options (notice that the editor URL will usually need to be quoted):
+
+.. code-block:: bash
+
+    behat --print-absolute-paths --editor-url="phpstorm://open?file={relPath}&line={line}"