diff --git a/docs/docsite/rst/dev_guide/developing_collections_testing.rst b/docs/docsite/rst/dev_guide/developing_collections_testing.rst index 7f36dcdfa6d..50d55ca5b58 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_testing.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_testing.rst @@ -4,7 +4,7 @@ Testing collections ******************* -Testing your collection ensures that your code works well and integrates well with the rest of the Ansible ecosystem. Your collection should pass the general compile and sanity tests for Ansible code. You should also add unit tests to cover the code in your collection and integration tests to cover the interactions between your collection and ansible-core. +Testing your collection ensures that your code works well and integrates well with the rest of the Ansible ecosystem. Your collection should pass the sanity tests for Ansible code. You should also add unit tests to cover the code in your collection and integration tests to cover the interactions between your collection and ansible-core. .. contents:: :local: @@ -15,20 +15,20 @@ Testing tools The main tool for testing collections is ``ansible-test``, Ansible's testing tool described in :ref:`developing_testing` and provided by both the ``ansible`` and ``ansible-core`` packages. -You can run several compile and sanity checks, as well as run unit and integration tests for plugins using ``ansible-test``. When you test collections, test against the ansible-core version(s) you are targeting. +You can run several sanity tests, as well as run unit and integration tests for plugins using ``ansible-test``. When you test collections, test against the ansible-core version(s) you are targeting. You must always execute ``ansible-test`` from the root directory of a collection. You can run ``ansible-test`` in Docker containers without installing any special requirements. The Ansible team uses this approach in Azure Pipelines both in the ansible/ansible GitHub repository and in the large community collections such as `community.general `_ and `community.network `_. The examples below demonstrate running tests in Docker containers. -Compile and sanity tests ------------------------- +Sanity tests +------------ -To run all compile and sanity tests: +To run all sanity tests: .. code-block:: shell-session ansible-test sanity --docker default -v -See :ref:`testing_compile` and :ref:`testing_sanity` for more information. See the :ref:`full list of sanity tests ` for details on the sanity tests and how to fix identified issues. +See :ref:`testing_sanity` for more information. See the :ref:`full list of sanity tests ` for details on the sanity tests and how to fix identified issues. Adding unit tests ----------------- diff --git a/docs/docsite/rst/dev_guide/testing.rst b/docs/docsite/rst/dev_guide/testing.rst index a587a746088..6b4716ddfec 100644 --- a/docs/docsite/rst/dev_guide/testing.rst +++ b/docs/docsite/rst/dev_guide/testing.rst @@ -26,9 +26,6 @@ Types of tests At a high level we have the following classifications of tests: -:compile: - * :ref:`testing_compile` - * Test python code against a variety of Python versions. :sanity: * :ref:`testing_sanity` * Sanity tests are made up of scripts and tools used to perform static code analysis. diff --git a/docs/docsite/rst/dev_guide/testing/sanity/compile.rst b/docs/docsite/rst/dev_guide/testing/sanity/compile.rst index 222f94e4855..507e30981a8 100644 --- a/docs/docsite/rst/dev_guide/testing/sanity/compile.rst +++ b/docs/docsite/rst/dev_guide/testing/sanity/compile.rst @@ -1,4 +1,32 @@ +.. _testing_compile: + compile ======= -See :ref:`testing_compile` for more information. +All Python source files must successfully compile using all supported Python versions. + +.. note:: + + The list of supported Python versions is dependent on the version of ``ansible-core`` that you are using. + Make sure you consult the version of the documentation which matches your ``ansible-core`` version. + +Controller code, including plugins in Ansible Collections, must support the following Python versions: + +- 3.11 +- 3.10 +- 3.9 + +Code which runs on targets (``modules`` and ``module_utils``) must support all controller supported Python versions, +as well as the additional Python versions supported only on targets: + +- 3.8 +- 3.7 +- 3.6 +- 3.5 +- 2.7 + +.. note:: + + Ansible Collections can be + `configured _` + to support a subset of the target-only Python versions. diff --git a/docs/docsite/rst/dev_guide/testing_compile.rst b/docs/docsite/rst/dev_guide/testing_compile.rst index a4119f55d7e..2f258c8b076 100644 --- a/docs/docsite/rst/dev_guide/testing_compile.rst +++ b/docs/docsite/rst/dev_guide/testing_compile.rst @@ -1,76 +1,8 @@ :orphan: -.. _testing_compile: ************* Compile Tests ************* -.. contents:: Topics - -Overview -======== - -Compile tests check source files for valid syntax on all supported python versions: - -- 2.4 (Ansible 2.3 only) -- 2.6 -- 2.7 -- 3.5 -- 3.6 -- 3.7 -- 3.8 -- 3.9 - -NOTE: In Ansible 2.4 and earlier the compile test was provided by a dedicated sub-command ``ansible-test compile`` instead of a sanity test using ``ansible-test sanity --test compile``. - -Running compile tests locally -============================= - -Compile tests can be run across the whole code base by doing: - -.. code:: shell - - cd /path/to/ansible/source - source hacking/env-setup - ansible-test sanity --test compile - -Against a single file by doing: - -.. code:: shell - - ansible-test sanity --test compile lineinfile - -Or against a specific Python version by doing: - -.. code:: shell - - ansible-test sanity --test compile --python 2.7 lineinfile - -For advanced usage see the help: - -.. code:: shell - - ansible-test sanity --help - - -Installing dependencies -======================= - -``ansible-test`` has a number of dependencies , for ``compile`` tests we suggest running the tests with ``--local``, which is the default - -The dependencies can be installed using the ``--requirements`` argument. For example: - -.. code:: shell - - ansible-test sanity --test compile --requirements lineinfile - - - -The full list of requirements can be found at `test/lib/ansible_test/_data/requirements `_. Requirements files are named after their respective commands. See also the `constraints `_ applicable to all commands. - - -Extending compile tests -======================= - -If you believe changes are needed to the compile tests please add a comment on the `Testing Working Group Agenda `_ so it can be discussed. +This page has moved to :ref:`testing_compile`.