Explicit test package (#2341)

* Explicit test require

* Update devtools/build_requires.rst

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>

* Update reference/commands/creator/create.rst

Co-authored-by: Carlos Zoido <mrgalleta@gmail.com>

Co-authored-by: Francisco Ramírez <franchuti688@gmail.com>
Co-authored-by: Carlos Zoido <mrgalleta@gmail.com>

devtools/build_requires.rst

@@ -273,30 +273,45 @@ be used to compute the ``package_id`` following the ``default_python_requires_id
 ``self.info.python_requires.xxxx_mode()`` in recipes.
 
 
+.. _testing_build_requires:
+
+
 Testing build_requires
 ----------------------
 
 .. warning::
 
     This is an **experimental** feature, subject to future breaking changes
 
-Available since: `1.36.0 <https://github.com/conan-io/conan/releases>`_
+Available since: `1.44.0 <https://github.com/conan-io/conan/releases>`_
 
-From Conan 1.36, it is possible to test ``build_requires`` with the ``test_package`` functionality.
-What is necessary is to specify in the ``test_package/conanfile.py``, that the tested package
-is a build tool, which can be done with:
+From Conan 1.44, it is possible to test ``build_requires`` with the ``test_package`` functionality.
+In the ``test_package/conanfile.py``, specify the ``test_type = "explicit"`` and use the variable
+``self.tested_reference_str`` to explicitly require the reference as a ``test_require``:
 
 .. code-block:: python
 
     from conans import ConanFile
 
     class Pkg(ConanFile):
-        test_type = "build_requires"
+        test_type = "explicit"
 
-        ...
+        def build_requirements(self):
+            self.test_requires(self.tested_reference_str)
 
-The rest of the test *conanfile.py* should take into account that the reference automatically injected
-will be a ``build_require``.
 
 If for some reason, it is necessary to test the same package both as a regular require and a build_require,
-then it is possible to specify: ``test_type = "build_requires", "requires"``.
+then it is possible to specify:
+
+.. code-block:: python
+
+    from conans import ConanFile
+
+    class Pkg(ConanFile):
+        test_type = "explicit"
+
+        def requirements(self):
+            self.requires(self.tested_reference_str)
+
+        def build_requirements(self):
+            self.test_requires(self.tested_reference_str)

reference/commands/creator/create.rst

@@ -208,8 +208,8 @@ In case of installing a pre-built binary, steps from 5 to 11 will be skipped. No
 The ``--build-require``, new in Conan 1.37, is experimental. It allows to create the package using the
 configuration and settings of the "build" context, as it was a ``build_require``. This feature allows
 to create packages in a way that is consistent to the way they will be used later. When there is a
-``test_package``, then it is possible to specify there the ``test_type`` directly, no need to provide it
-in the command line.
+``test_package``, it is possible to use there the ``test_type="explicit"`` and ``self.test_requires(self.tested_reference_str)``.
+There is no need to provide it in the command line, :ref:`check "testing build requires" <testing_build_requires>` to know more.
 
 
 --require-override