Documents conan --test and should_test (conan-io#733)

Author: danimtb

changelog.rst

@@ -14,8 +14,8 @@ Check https://github.com/conan-io/conan for issues and more details about develo
 1.6.0 ()
 ----------------------
 
-- Feature: Added new ``self.run(..., run_environment=True)`` argument, that applies automatically ``PATH``, ``LD_LIBRARY_PATH`` and ``DYLD_LIBRARY_PATH``
-  environment variable, from the dependencies, to the execution of the current command.
+- Feature: Added new ``self.run(..., run_environment=True)`` argument, that applies automatically ``PATH``, ``LD_LIBRARY_PATH`` and
+  ``DYLD_LIBRARY_PATH`` environment variable, from the dependencies, to the execution of the current command.
 - Feature: Added new ``self.run(..., ignore_errors=True)`` argument, that inhibits launching an exception if the commands fails, user can
   capture the return code.
 - Feature: The ``json`` generator now outputs the settings and options
@@ -24,7 +24,10 @@ Check https://github.com/conan-io/conan for issues and more details about develo
 - Feature: Added ``filename`` parameter to ``tools.get()`` in case it cannot be deduced from URL.
 - Feature: Propagated ``keep_permissions`` and ``pattern`` parameters from ``tools.get()`` to ``tools.unzip()``.
 - Feature: Added XZ extensions to ``unzip()``. It will only work in Python 3 with lzma support enabled, producing an error otherwise.
-- Feature: Added `FRAMEWORK_SEARCH_PATHS` var to the xcode generator to support packaging Apple Frameworks. Read more :ref:`here<package_apple_framework>`.
+- Feature: Added `FRAMEWORK_SEARCH_PATHS` var to the xcode generator to support packaging Apple Frameworks. Read more
+  :ref:`here<package_apple_framework>`.
+- Feature: Added :command:`conan build --test` and ``should_configure`` attribute to control test stage. Read more
+  :ref:`here<attribute_build_stages>`.
 
 
 1.5.2 (5-July-2018)

reference/commands/development/build.rst

@@ -6,8 +6,9 @@ conan build
 
 .. code-block:: bash
 
-    $ conan build [-h] [-b] [-bf BUILD_FOLDER] [-c] [-i] [-if INSTALL_FOLDER]
-                  [-pf PACKAGE_FOLDER] [-sf SOURCE_FOLDER]
+    $ conan build [-h] [-b] [-bf BUILD_FOLDER] [-c] [-i] [-t]
+                  [-if INSTALL_FOLDER] [-pf PACKAGE_FOLDER]
+                  [-sf SOURCE_FOLDER]
                   path
 
 Calls your local conanfile.py 'build()' method. The recipe will be built in
@@ -24,18 +25,23 @@ folder will be configured as destination folder for the install step.
     optional arguments:
       -h, --help            show this help message and exit
       -b, --build           Execute the build step (variable should_build=True).
-                            When specified, configure/install won't run unless
-                            --configure/--install specified
+                            When specified, configure/install/test won't run
+                            unless --configure/--install/--test specified
       -bf BUILD_FOLDER, --build-folder BUILD_FOLDER
                             Directory for the build process. Defaulted to the
                             current directory. A relative path to current
                             directory can also be specified
       -c, --configure       Execute the configuration step (variable
-                            should_configure=True). When specified, build/install
-                            won't run unless --build/--install specified
+                            should_configure=True). When specified,
+                            build/install/test won't run unless
+                            --build/--install/--test specified
       -i, --install         Execute the install step (variable
-                            should_install=True). When specified, configure/build
-                            won't run unless --configure/--build specified
+                            should_install=True). When specified,
+                            configure/build/test won't run unless
+                            --configure/--build/--test specified
+      -t, --test            Execute the test step (variable should_test=True).
+                            When specified, configure/build/install won't run
+                            unless --configure/--build/--install specified
       -if INSTALL_FOLDER, --install-folder INSTALL_FOLDER
                             Directory containing the conaninfo.txt and
                             conanbuildinfo.txt files (from previous 'conan
@@ -109,41 +115,20 @@ the files generators file. e.j ``conanbuildinfo.cmake``
 
 **Example**: Control the build stages
 
-Given a conanfile with this ``build()`` method:
-
-.. code-block:: python
-
-    def build(self):
-        cmake = CMake(self)
-        cmake.configure()
-        cmake.build()
-        cmake.install()
-
-If nothing is specified, all three methods will be called. But using command line arguments, this can be changed:
-
+You can control the build stages using :command:`--configure`/:command:`--build`/:command:`--install`/:command:`--test` arguments. Here is
+an example using the CMake build helper:
 
 .. code-block:: bash
 
-    $ conan build . -c # only run cmake.configure(). Other methods will do nothing
-    $ conan build . -b # only run cmake.build(). Other methods will do nothing
-    $ conan build . -i # only run cmake.install(). Other methods will do nothing
+    $ conan build . --confiure # only run cmake.configure(). Other methods will do nothing
+    $ conan build . --build    # only run cmake.build(). Other methods will do nothing
+    $ conan build . --install  # only run cmake.install(). Other methods will do nothing
+    $ conan build . --test     # only run cmake.test(). Other methods will do nothing
     # They can be combined
-    $ conan build . -c -b # run cmake.configure() + cmake.build(), but not cmake.install()
-
-
-Autotools and Meson helpers already implement the same functionality. For other build systems, you can use
-the following variables in the ``build()`` method:
-
-.. code-block:: python
+    $ conan build . -c -b # run cmake.configure() + cmake.build(), but not cmake.install() nor cmake.test
 
-    def build(self):
-        if self.should_configure:
-            # Run my configure stage
-        if self.should_build:
-            # Run my build stage
-        if self.should_install: # If my build has install, otherwise use package()
-            # Run my install stage
+If nothing is specified, all the methods will be called.
 
+.. seealso::
 
-Note these ``should_configure, should_build, should_install`` variables will always be ``True`` while
-building in the local cache. They can only be modified for the local flow with :command:`conan build`.
+    Read more about :ref:`attribute_build_stages`.

reference/conanfile/attributes.rst

@@ -483,13 +483,61 @@ generated, but you can specify different generators and even use more than one.
 
 Check the full :ref:`generators list<generators>`.
 
+.. _attribute_build_stages:
+
+should_configure, should_build, should_install, should_test
+-----------------------------------------------------------
+
+Read only variables defaulted to ``True``.
+
+This variables allow you control the build stages of a recipe during a :command:`conan build` command with the optional arguments
+:command:`--configure`/:command:`--build`/:command:`--install`/:command:`--test`. For example, given this ``build()`` method:
+
+.. code-block:: python
+
+    def build(self):
+        cmake = CMake(self)
+        cmake.configure()
+        cmake.build()
+        cmake.install()
+        cmake.test()
+
+If nothing is specified, all four methods will be called. But using command line arguments, this can be changed:
+
+.. code-block:: bash
+
+    $ conan build . --configure  # only run cmake.configure(). Other methods will do nothing
+    $ conan build . --build      # only run cmake.build(). Other methods will do nothing
+    $ conan build . --install    # only run cmake.install(). Other methods will do nothing
+    $ conan build . --test       # only run cmake.test(). Other methods will do nothing
+    # They can be combined
+    $ conan build . -c -b # run cmake.configure() + cmake.build(), but not cmake.install() nor cmake.test()
+
+Autotools and Meson helpers already implement the same functionality. For other build systems, you can use the these variables in the
+``build()`` method:
+
+.. code-block:: python
+
+    def build(self):
+        if self.should_configure:
+            # Run my configure stage
+        if self.should_build:
+            # Run my build stage
+        if self.should_install: # If my build has install, otherwise use package()
+            # Run my install stage
+        if self.should_test:
+            # Run my test stage
+
+Note these ``should_configure``, ``should_build``, ``should_install``, ``should_test`` variables will always be ``True`` while building in
+the cache and can be only modified for the local flow with :command:`conan build`.
+
 build_policy
 ------------
 
 With the ``build_policy`` attribute the package creator can change the default conan's build behavior.
 The allowed ``build_policy`` values are:
 
-- ``missing``: If no binary package is found, conan will build it without the need of invoke conan install with **--build missing** option.
+- ``missing``: If no binary package is found, Conan will build it without the need of invoke :command:`conan install --build missing` option.
 - ``always``: The package will be built always, **retrieving each time the source code** executing the "source" method.
 
 .. code-block:: python