docs: add changelog, upgrade guide, and missing explanation for $params

user_guide_src/source/changelogs/v4.3.7.rst

@@ -12,6 +12,10 @@ Release Date: Unreleased
 BREAKING
 ********
 
+- **FeatureTestTrait:** When using :ref:`withBodyFormat() <feature-formatting-the-request>`,
+  the priority of the request body has been changed.
+  See :ref:`Upgrading Guide <upgrade-437-feature-testing>` for details.
+
 Message Changes
 ***************
 

user_guide_src/source/installation/upgrade_437.rst

@@ -18,6 +18,27 @@ Mandatory File Changes
 Breaking Changes
 ****************
 
+.. _upgrade-437-feature-testing:
+
+Feature Testing Request Body
+============================
+
+If you call:
+
+1. :ref:`withBody() <feature-setting-the-body>`
+2. and :ref:`withBodyFormat() <feature-formatting-the-request>`
+3. and pass the ``$params`` to :ref:`call() <feature-requesting-a-page>` (or shorthand methods)
+
+the priority for a Request body has been changed. In the unlikely event that you
+have test code affected by this change, modify it.
+
+For example, now the ``$params`` is used to build the request body, and the ``$body``
+is not used::
+
+    $this->withBody($body)->withBodyFormat('json')->call('post', $params)
+
+Previously, the ``$body`` was used for the request body.
+
 Breaking Enhancements
 *********************
 

user_guide_src/source/testing/feature.rst

@@ -21,6 +21,8 @@ are called if you implement your own methods.
 
 .. literalinclude:: feature/001.php
 
+.. _feature-requesting-a-page:
+
 Requesting a Page
 =================
 
@@ -32,7 +34,8 @@ To do this, you use the ``call()`` method.
 3. The third parameter ``$params`` accepts an array that is used to populate the
    superglobal variables for the HTTP verb you are using. So, a method of **GET**
    would have the **$_GET** variable populated, while a **POST** request would
-   have the **$_POST** array populated.
+   have the **$_POST** array populated. The ``$params`` is also used in
+   :ref:`feature-formatting-the-request`.
 
    .. note:: The ``$params`` array does not make sense for every HTTP verb, but is
       included for consistency.
@@ -82,6 +85,8 @@ to send out emails. You can tell the system to skip any event handling with the
 
 .. literalinclude:: feature/007.php
 
+.. _feature-formatting-the-request:
+
 Formatting the Request
 -----------------------
 
@@ -96,6 +101,8 @@ This will also set the `Content-Type` header for your request accordingly.
 
 .. literalinclude:: feature/008.php
 
+.. _feature-setting-the-body:
+
 Setting the Body
 ----------------