From df4059e7f6db1662566bd23308634936896e8bb8 Mon Sep 17 00:00:00 2001
From: Pascal CESCON - Amoifr <pascal.cescon@gmail.com>
Date: Thu, 3 Sep 2026 15:43:13 +0200
Subject: [PATCH] docs: Document the DataTable and DocString step argument
 types

---
 user_guide/writing_scenarios.rst | 41 ++++++++++++++++++++++----------
 1 file changed, 29 insertions(+), 12 deletions(-)

diff --git a/user_guide/writing_scenarios.rst b/user_guide/writing_scenarios.rst
index 1db7175..9337513 100644
--- a/user_guide/writing_scenarios.rst
+++ b/user_guide/writing_scenarios.rst
@@ -321,22 +321,35 @@ usually as input to a ``Given`` or as expected output from a ``Then``:
 
     .. code-block:: php
 
-        use Behat\Gherkin\Node\TableNode;
+        use Behat\Step\DataTable;
         use Behat\Step\Given;
 
         // ...
 
         #[Given('the following people exist:')]
-        public function thePeopleExist(TableNode $table)
+        public function thePeopleExist(DataTable $table)
         {
-            foreach ($table as $row) {
+            foreach ($table->asMaps() as $row) {
                 // $row['name'], $row['email'], $row['phone']
             }
         }
 
-    A table is injected into a definition as a ``TableNode`` object, from
-    which you can get hash by columns (``TableNode::getHash()`` method) or by
-    rows (``TableNode::getRowsHash()``).
+    Type the parameter as ``DataTable`` and Behat passes the table as such.
+    It reads the table in whichever shape the step needs:
+
+    * ``asMaps()`` uses the first row as keys, giving one associative array
+      per following row, which is what the example above iterates over;
+    * ``asLists()`` returns every row as a plain list of cells, header row
+      included, for a table with no header;
+    * ``asMap()`` turns a two-column table into a single associative array,
+      which suits a table of settings or of expected values;
+    * ``cell()``, ``row()``, ``column()``, ``height()``, ``width()``,
+      ``isEmpty()`` and ``transpose()`` cover the rest.
+
+    ``DataTable`` was added in Behat 3.33. Typing the parameter as
+    ``Behat\Gherkin\Node\TableNode`` still works and is not deprecated, but
+    ``DataTable`` keeps your definitions decoupled from the Gherkin syntax
+    tree.
 
 Pystrings
 ^^^^^^^^^
@@ -371,20 +384,24 @@ three double-quote marks (``"""``), placed on their own line:
 
     .. code-block:: php
 
-        use Behat\Gherkin\Node\PyStringNode;
+        use Behat\Step\DocString;
         use Behat\Step\Given;
 
         // ...
 
         #[Given('a blog post named :title with:')]
-        public function blogPost($title, PyStringNode $markdown)
+        public function blogPost($title, DocString $markdown)
         {
-            $this->createPost($title, $markdown->getRaw());
+            $this->createPost($title, $markdown->getContent());
         }
 
-    PyStrings are stored in a ``PyStringNode`` instance, which you can simply
-    convert to a string with ``(string) $pystring`` or ``$pystring->getRaw()``
-    as in the example above.
+    Type the parameter as ``DocString`` to receive the text. Read it with
+    ``getContent()``, or cast it with ``(string) $markdown``.
+
+    ``DocString`` was added in Behat 3.33. Typing the parameter as
+    ``Behat\Gherkin\Node\PyStringNode`` still works and is not deprecated,
+    but ``DocString`` keeps your definitions decoupled from the Gherkin syntax
+    tree.
 
 .. note::