mirror of
https://github.com/fedora-python/tox-current-env.git
synced 2024-12-24 09:06:15 +01:00
187 lines
7.3 KiB
ReStructuredText
187 lines
7.3 KiB
ReStructuredText
===============
|
|
tox-current-env
|
|
===============
|
|
---------------------------------------------------------------------------------------
|
|
`tox <https://tox.readthedocs.io/>`_ plugin to run tests in current Python environment
|
|
---------------------------------------------------------------------------------------
|
|
|
|
The ``tox-current-env`` plugin adds two options:
|
|
|
|
``tox --current-env``
|
|
Runs the tox testenv's ``commands`` in the current Python environment
|
|
(that is, the environment where ``tox`` is invoked from and installed in).
|
|
Unlike regular ``tox`` invocation, this installs no dependendencies declared in ``deps``.
|
|
An attempt to run this with a Python version that doesn't match will fail
|
|
(if ``tox`` is invoked from an Python 3.7 environment, any non 3.7 testenv will fail).
|
|
|
|
``tox --print-deps-only``
|
|
Instead of running any ``commands``,
|
|
simply prints the declared dependencies in ``deps`` to the standard output.
|
|
This is useful for preparing the current environment for the above.
|
|
|
|
Invoking ``tox`` without any of the above options should behave as regular ``tox`` invocation without this plugin.
|
|
Any deviation from this behavior is considered a bug.
|
|
|
|
|
|
Motivation
|
|
----------
|
|
|
|
Obviously, ``tox`` was created to run tests in isolated Python virtual environments.
|
|
The ``--current-env`` flag totally defeats the purpose of ``tox``.
|
|
Why would anybody do that, you might ask.
|
|
|
|
This plugin was created for `Fedora <https://fedoralovespython.org/>`_'s needs.
|
|
When we package Python software as RPM packages, we try to run the upstream test suite during package build.
|
|
However there is no standardization of declaring Python test dependencies or invoking tests.
|
|
The de-facto standard is ``tox``.
|
|
However we need to test if the software works integrated into Fedora,
|
|
not if it works with ``pip``-installed packages in an isolated environment.
|
|
By running the tests in *current environment*, we can achieve that.
|
|
|
|
If you are interested in the RPM packaging part of this,
|
|
see Fedora's `%pyproject RPM macros <https://src.fedoraproject.org/rpms/pyproject-rpm-macros>`_.
|
|
|
|
|
|
Installation
|
|
------------
|
|
|
|
Install this via ``pip``:
|
|
|
|
.. code-block:: console
|
|
|
|
$ python -m pip install tox-current-env
|
|
|
|
Or install the development version by cloning `the git repository <https://github.com/fedora-python/tox-current-env>`_
|
|
and ``pip``-installing locally:
|
|
|
|
.. code-block:: console
|
|
|
|
$ git clone https://github.com/fedora-python/tox-current-env
|
|
$ cd tox-current-env
|
|
$ python -m pip install -e .
|
|
|
|
|
|
Usage
|
|
-----
|
|
|
|
When the plugin is installed, use ``tox`` with the ``--current-env`` or `` --print-deps-only`` and all the other options as usual. Assuming your ``tox`` is installed on Python 3.7:
|
|
|
|
.. code-block:: console
|
|
|
|
$ tox -e py37 --current-env
|
|
py37 create: /home/pythonista/projects/holy-grail/tests/.tox/py37
|
|
py37 installed: ...list of packages from the current environment...
|
|
py37 run-test-pre: PYTHONHASHSEED='3333333333'
|
|
py37 run-test: commands...
|
|
...runs tests in current environment's Python...
|
|
___________________________________ summary ____________________________________
|
|
py37: commands succeeded
|
|
congratulations :)
|
|
|
|
Attempting to run the ``py36`` environment's test will fail:
|
|
|
|
.. code-block:: console
|
|
|
|
$ tox -e py37 --current-env
|
|
py36 create: /home/pythonista/projects/holy-grail/tests/.tox/py36
|
|
ERROR: InterpreterMismatch: tox_current_env: interpreter versions do not match:
|
|
in current env: (3, 7, 4, 'final', 0)
|
|
requested: (3, 6, 9, 'final', 0)
|
|
___________________________________ summary ____________________________________
|
|
ERROR: py36: InterpreterMismatch: tox_current_env: interpreter versions do not match:
|
|
in current env: (3, 7, 4, 'final', 0)
|
|
requested: (3, 6, 9, 'final', 0)
|
|
|
|
To get list of test dependencies, run:
|
|
|
|
.. code-block:: console
|
|
|
|
$ tox -e py37 --print-deps-only
|
|
py37 create: /home/pythonista/projects/holy-grail/tests/.tox/py37
|
|
py37 installed: ...you can see almost anything here...
|
|
py37 run-test-pre: PYTHONHASHSEED='3333333333'
|
|
dep1
|
|
dep2
|
|
...
|
|
___________________________________ summary ____________________________________
|
|
py37: commands succeeded
|
|
congratulations :)
|
|
|
|
|
|
Caveats, warnings and limitations
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Running (especially third party software's) tests in your system installed Python environment is dangerous.
|
|
Always install ``tox`` and this plugin to some isolated environment,
|
|
such as Python virtualenv, Linux container or chroot.
|
|
You have been warned.
|
|
|
|
In order to support the ``python`` command in the ``commands`` section,
|
|
the current environment invocation of ``tox`` creates a fake virtual environment
|
|
that just have a symbolic link to the Python executable.
|
|
This can lead to slightly different results of tests than invoking them directly,
|
|
especially if you have assumptions about ``sys.executable`` in your tests.
|
|
Any other commands (such as ``pytest``) are not linked anywhere
|
|
and it is the users' responsibility to make sure such commands are in ``$PATH`` and use the correct Python.
|
|
|
|
Regardless of any `Python flags <https://docs.python.org/3/using/cmdline.html>`_ used in the shebang of ``tox``,
|
|
the tests are invoked with ``sys.executable`` without any added flags
|
|
(unless explicitly invoked with them in the ``commands`` section).
|
|
|
|
The ``installed:`` line in the output of ``tox --print-deps-only`` shows irrelevant output
|
|
(based on the content of the real or faked virtual environment).
|
|
|
|
Running ``tox --current-env`` after regular ``tox``
|
|
(that is without the ``--current-env`` switch)
|
|
or vice versa is not supported without the ``--recreate/-r`` flag
|
|
(``tox`` will emergency abort in that situation).
|
|
Additionally, running ``tox --current-env``,
|
|
uninstalling the ``tox-current-env``
|
|
and running ``tox`` without the ``--recreate/-r`` flag
|
|
will most likely attempt to install packages into your current environment
|
|
and will provide further undefined results.
|
|
Being uninstalled, ``tox-current-env`` cannot longer prevent this.
|
|
|
|
The current environment's Python is tested for the major and minor version only.
|
|
Possibly multiple different 3.X versions (such as CPython and PyPy) are treated as equal.
|
|
|
|
Only Linux is supported, with special emphasis on Fedora.
|
|
This plugin might work on other Unix-like systems,
|
|
but does not work on Microsoft Windows.
|
|
|
|
This is an alpha quality software.
|
|
Use it at your on your own risk.
|
|
|
|
|
|
Development, issues, support
|
|
----------------------------
|
|
|
|
The development happens on GitHub,
|
|
at the `fedora-python/tox-current-env <https://github.com/fedora-python/tox-current-env>`_ repository.
|
|
You can use the `issue tracker <https://github.com/fedora-python/tox-current-env/issues>`_ there for any discussion
|
|
or send Pull Requests.
|
|
|
|
|
|
Tests
|
|
~~~~~
|
|
|
|
In order to run the tests, you'll need ``tox`` and Python 3.6, 3.7 and 3.8 installed.
|
|
The integration tests assume all three are available.
|
|
On Fedora, you just need to ``dnf install tox``.
|
|
|
|
Run ``tox`` to invoke the tests.
|
|
|
|
Running tests of this plugin with this plugin installed and ``--current-env`` flag will most likely blow up.
|
|
|
|
|
|
License
|
|
-------
|
|
|
|
The ``tox-current-env`` project is licensed under so-called MIT license, full text available in the `LICENSE <https://github.com/fedora-python/tox-current-env/blob/master/LICENSE>`_ file.
|
|
|
|
|
|
Code of Conduct
|
|
---------------
|
|
|
|
The ``tox-current-env`` project follows the `Fedora's Code of Conduct <https://docs.fedoraproject.org/en-US/project/code-of-conduct/>`_.
|