diff --git a/doc/en/example/simple.rst b/doc/en/example/simple.rst index 76ee97ab3..5275c52c8 100644 --- a/doc/en/example/simple.rst +++ b/doc/en/example/simple.rst @@ -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 `_ @@ -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/