From 807d923de0ad7db5e88ff28a58ca4663d12c3312 Mon Sep 17 00:00:00 2001
From: Carlos Granados <barel.barelon@gmail.com>
Date: Sat, 17 May 2025 09:10:05 +0200
Subject: [PATCH] docs: document path options

---
 user_guide/command_line_tool.rst            |  4 ++
 user_guide/configuration.rst                |  1 +
 user_guide/configuration/printing_paths.rst | 50 +++++++++++++++++++++
 3 files changed, 55 insertions(+)
 create mode 100644 user_guide/configuration/printing_paths.rst

diff --git a/user_guide/command_line_tool.rst b/user_guide/command_line_tool.rst
index 7364baa..cf30a62 100644
--- a/user_guide/command_line_tool.rst
+++ b/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
diff --git a/user_guide/configuration.rst b/user_guide/configuration.rst
index 991df34..b5db886 100644
--- a/user_guide/configuration.rst
+++ b/user_guide/configuration.rst
@@ -8,6 +8,7 @@ profiles.
    :maxdepth: 2
 
    configuration/suites.rst
+   configuration/printing_paths.rst
    configuration/yaml_configuration.rst
 
 ``behat.php``
diff --git a/user_guide/configuration/printing_paths.rst b/user_guide/configuration/printing_paths.rst
new file mode 100644
index 0000000..b4ad74a
--- /dev/null
+++ b/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. By default
+the path will be relative to the current directory. This behaviour can be modified through
+configuration or on the command line:
+
+``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 include placeholders that Behat will replace
+at run time. 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}"