Freeze docs: PyInstaller hook and wording

As discussed during the review, suggest in general
to use PyInstaller and just mention pytest.freeze_includes()
in less detail on how to actually use it, because it varies
from tool to tool.
This commit is contained in:
Bruno Oliveira 2016-07-27 08:49:00 -03:00
parent ed36d627e4
commit ae9d3bf886
1 changed files with 15 additions and 23 deletions

View File

@ -699,8 +699,8 @@ and run it::
You'll see that the fixture finalizers could use the precise reporting
information.
Integrating pytest runner and PyInstaller
-----------------------------------------
Freezing pytest
---------------
If you freeze your application using a tool like
`PyInstaller <https://pyinstaller.readthedocs.io>`_
@ -708,29 +708,21 @@ in order to distribute it to your end-users, it is a good idea to also package
your test runner and run your tests using the frozen application. This way packaging
errors such as dependencies not being included into the executable can be detected early
while also allowing you to send test files to users so they can run them in their
machines, which can be invaluable to obtain more information about a hard to reproduce bug.
machines, which can be useful to obtain more information about a hard to reproduce bug.
Unfortunately ``PyInstaller`` can't discover them
automatically because of ``pytest``'s use of dynamic module loading, so you
must declare them explicitly by using ``pytest.freeze_includes()`` and an
auxiliary script:
Fortunately recent ``PyInstaller`` releases already have a custom hook
for pytest, but if you are using another tool to freeze executables
such as ``cx_freeze`` or ``py2exe``, you can use ``pytest.freeze_includes()``
to obtain the full list of internal pytest modules. How to configure the tools
to find the internal modules varies from tool to tool, however.
Instead of freezing the pytest runner as a separate executable, you can make
your frozen program work as the pytest runner by some clever
argument handling during program startup. This allows you to
have a single executable, which is usually more convenient.
.. code-block:: python
# contents of create_executable.py
import pytest
import subprocess
hidden = []
for x in pytest.freeze_includes():
hidden.extend(['--hidden-import', x])
args = ['pyinstaller'] + hidden + ['runtests_script.py']
subprocess.check_call(' '.join(args), shell=True)
If you don't want to ship a different executable just in order to run your tests,
you can make your program check for a certain flag and pass control
over to ``pytest`` instead. For example::
# contents of app_main.py
import sys
@ -742,7 +734,7 @@ over to ``pytest`` instead. For example::
# by your argument-parsing library of choice as usual
...
This makes it convenient to execute your tests from within your frozen
application, using standard ``py.test`` command-line options::
This allows you to execute tests using the frozen
application with standard ``py.test`` command-line options::
./app_main --pytest --verbose --tb=long --junitxml=results.xml test-suite/