ansible/docs/docsite/rst/dev_guide/testing_compile.rst

: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 <https://github.com/ansible/ansible/tree/devel/test/lib/ansible_test/_data/requirements>`_. Requirements files are named after their respective commands. See also the `constraints <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/requirements/constraints.txt>`_ 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 <https://github.com/ansible/community/blob/master/meetings/README.md>`_ so it can be discussed.
Remove more docs build errors (#45364) * orphans testing pages to avoid not-in-toctree errors * orphans various pages pending reorg * adds module_utils and special_vars to main TOC * uses a glob for scenario_guide TOC * normalize and Sentence-case headings on community pages, typos * re-orgs community TOC, adds all pages to toctree * removes scenario guides index page * adds style guide to community index * basic update to style guide * fix typo that created a new error * removes not-in-toctree from ignore errors list * leave removing files for future cleanup task 2018-09-11 18:51:47 +02:00			`:orphan:`

rewrite of the developer guide, part 1 (#45179) * rewrite of the developer guide, part 1 2018-09-07 15:57:36 +02:00			`.. _testing_compile:`

Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 2017-04-28 10:08:26 +02:00			`*************`
			`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`
Extend dev guide for collection testing and collection hacking (#68899) * Make clear which BOTMETA.yml is meant (some collections also have one), fix itemization, document /rebuild and /rebuild_failed, add section on how to test collections with ansible-test, update supported versions for compile tests, add a section on hacking collections, implement feedback. * Update docs/docsite/rst/dev_guide/developing_collections.rst Co-Authored-By: Felix Fontein <felix@fontein.de> Co-authored-by: Alicia Cozine <acozine@users.noreply.github.com> 2020-04-15 22:51:19 +02:00			`- 3.7`
			`- 3.8`
			`- 3.9`
Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 2017-04-28 10:08:26 +02:00
Convert ansible-test compile into a sanity test. 2018-01-24 20:07:24 +01:00			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``.

Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 2017-04-28 10:08:26 +02:00			`Running compile tests locally`
			`=============================`

Convert ansible-test compile into a sanity test. 2018-01-24 20:07:24 +01:00			`Compile tests can be run across the whole code base by doing:`
Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 2017-04-28 10:08:26 +02:00
			`.. code:: shell`

			`cd /path/to/ansible/source`
			`source hacking/env-setup`
Convert ansible-test compile into a sanity test. 2018-01-24 20:07:24 +01:00			`ansible-test sanity --test compile`
Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 2017-04-28 10:08:26 +02:00
			`Against a single file by doing:`

			`.. code:: shell`

Convert ansible-test compile into a sanity test. 2018-01-24 20:07:24 +01:00			`ansible-test sanity --test compile lineinfile`
Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 2017-04-28 10:08:26 +02:00
			`Or against a specific Python version by doing:`

			`.. code:: shell`

Convert ansible-test compile into a sanity test. 2018-01-24 20:07:24 +01:00			`ansible-test sanity --test compile --python 2.7 lineinfile`
Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 2017-04-28 10:08:26 +02:00
Minor testing docs improvements (#24103) Fix a few formatting issues spotted post review. Also reapply missing commit 2017-04-28 12:58:38 +02:00			`For advanced usage see the help:`
Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 2017-04-28 10:08:26 +02:00
			`.. code:: shell`

Convert ansible-test compile into a sanity test. 2018-01-24 20:07:24 +01:00			`ansible-test sanity --help`
Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 2017-04-28 10:08:26 +02:00

			`Installing dependencies`
			`=======================`

			``ansible-test`` has a number of dependencies , for ``compile`` tests we suggest running the tests with ``--local``, which is the default

Minor testing docs improvements (#24103) Fix a few formatting issues spotted post review. Also reapply missing commit 2017-04-28 12:58:38 +02:00			The dependencies can be installed using the ``--requirements`` argument. For example:
Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 2017-04-28 10:08:26 +02:00
			`.. code:: shell`

Convert ansible-test compile into a sanity test. 2018-01-24 20:07:24 +01:00			`ansible-test sanity --test compile --requirements lineinfile`
Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 2017-04-28 10:08:26 +02:00


dev_guide: Correct path to ansible-test requirements files (#66626) The requirements path was old due to file relocation in commit d651bda12390e46c85c4487859f030ed8851867a. 2020-01-21 16:16:48 +01:00			The full list of requirements can be found at `test/lib/ansible_test/_data/requirements <https://github.com/ansible/ansible/tree/devel/test/lib/ansible_test/_data/requirements>`_. Requirements files are named after their respective commands. See also the `constraints <https://github.com/ansible/ansible/blob/devel/test/lib/ansible_test/_data/requirements/constraints.txt>`_ applicable to all commands.
Docs how to test (2nd) (#24094) * Big testing doc refactor * Combine all the testing documentation in to one place to make it easier to find * Convert everything to RST * Create testing_network guide * Create testing landing page * For each section detail "how to run" and "how to extend testing" * More examples * Lots more detail 2017-04-28 10:08:26 +02:00

			`Extending compile tests`
			`=======================`

Convert ansible-test compile into a sanity test. 2018-01-24 20:07:24 +01:00			If you believe changes are needed to the compile tests please add a comment on the `Testing Working Group Agenda <https://github.com/ansible/community/blob/master/meetings/README.md>`_ so it can be discussed.