1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
Using Tox with the Jenkins Integration Server
=================================================
Using Jenkins multi-configuration jobs
-------------------------------------------
The Jenkins_ continuous integration server allows to define "jobs" with
"build steps" which can be test invocations. If you :doc:`install <../install>` ``tox`` on your
default Python installation on each Jenkins slave, you can easily create
a Jenkins multi-configuration job that will drive your tox runs from the CI-server side,
using these steps:
* install the Python plugin for Jenkins under "manage jenkins"
* create a "multi-configuration" job, give it a name of your choice
* configure your repository so that Jenkins can pull it
* (optional) configure multiple nodes so that tox-runs are performed
on multiple hosts
* configure ``axes`` by using :ref:`TOXENV <TOXENV>` as an axis
name and as values provide space-separated test environment names
you want Jenkins/tox to execute.
* add a **Python-build step** with this content (see also next example)::
import tox
tox.cmdline() # environment is selected by ``TOXENV`` env variable
* check ``Publish JUnit test result report`` and enter
``**/junit-*.xml`` as the pattern so that Jenkins collects
test results in the JUnit XML format.
The last point requires that your test command creates JunitXML files,
for example with ``py.test`` it is done like this:
.. code-block:: ini
commands = py.test --junitxml=junit-{envname}.xml
**zero-installation** for slaves
-------------------------------------------------------------
.. note::
This feature is broken currently because "toxbootstrap.py"
has been removed. Please file an issue if you'd like to
see it back.
If you manage many Jenkins slaves and want to use the latest officially
released tox (or latest development version) and want to skip manually
installing ``tox`` then substitute the above **Python build step** code
with this::
import urllib, os
url = "https://bitbucket.org/hpk42/tox/raw/default/toxbootstrap.py"
#os.environ['USETOXDEV']="1" # use tox dev version
d = dict(__file__='toxbootstrap.py')
exec urllib.urlopen(url).read() in d
d['cmdline'](['--recreate'])
The downloaded `toxbootstrap.py` file downloads all neccessary files to
install ``tox`` in a virtual sub environment. Notes:
* uncomment the line containing ``USETOXDEV`` to use the latest
development-release version of tox instead of the
latest released version.
* adapt the options in the last line as needed (the example code
will cause tox to reinstall all virtual environments all the time
which is often what one wants in CI server contexts)
Integrating "sphinx" documentation checks in a Jenkins job
----------------------------------------------------------------
If you are using a multi-configuration Jenkins job which collects
JUnit Test results you will run into problems using the previous
method of running the sphinx-build command because it will not
generate JUnit results. To accomodate this issue one solution
is to have ``py.test`` wrap the sphinx-checks and create a
JUnit result file which wraps the result of calling sphinx-build.
Here is an example:
1. create a ``docs`` environment in your ``tox.ini`` file like this::
[testenv:docs]
basepython=python
changedir=doc # or whereever you keep your sphinx-docs
deps=sphinx
py
commands=
py.test --tb=line -v --junitxml=junit-{envname}.xml check_sphinx.py
2. create a ``doc/check_sphinx.py`` file like this::
import py
import subprocess
def test_linkcheck(tmpdir):
doctrees = tmpdir.join("doctrees")
htmldir = tmpdir.join("html")
subprocess.check_call(
["sphinx-build", "-W", "-blinkcheck",
"-d", str(doctrees), ".", str(htmldir)])
def test_build_docs(tmpdir):
doctrees = tmpdir.join("doctrees")
htmldir = tmpdir.join("html")
subprocess.check_call([
"sphinx-build", "-W", "-bhtml",
"-d", str(doctrees), ".", str(htmldir)])
3. run ``tox -e docs`` and then you may integrate this environment
along with your other environments into Jenkins.
Note that ``py.test`` is only installed into the docs environment
and does not need to be in use or installed with any other environment.
.. _`jenkins artifact example`:
Access package artifacts between Jenkins jobs
--------------------------------------------------------
.. _`Jenkins Copy Artifact plugin`: http://wiki.jenkins-ci.org/display/HUDSON/Copy+Artifact+Plugin
In an extension to :ref:`artifacts` you can also configure Jenkins jobs to
access each others artifacts. ``tox`` uses the ``distshare`` directory
to access artifacts and in a Jenkins context (detected via existence
of the environment variable ``HUDSON_URL``); it defaults to
to ``{toxworkdir}/distshare``.
This means that each workspace will have its own ``distshare``
directory and we need to configure Jenkins to perform artifact copying.
The recommend way to do this is to install the `Jenkins Copy Artifact plugin`_
and for each job which "receives" artifacts you add a **Copy artifacts from another project** build step using roughly this configuration::
Project-name: name of the other (tox-managed) job you want the artifact from
Artifacts to copy: .tox/dist/*.zip # where tox jobs create artifacts
Target directory: .tox/distshare # where we want it to appear for us
Flatten Directories: CHECK # create no subdir-structure
You also need to configure the "other" job to archive artifacts; This
is done by checking ``Archive the artifacts`` and entering::
Files to archive: .tox/dist/*.zip
So our "other" job will create an sdist-package artifact and
the "copy-artifacts" plugin will copy it to our ``distshare`` area.
Now everything proceeds as :ref:`artifacts` shows it.
So if you are using defaults you can re-use and debug exactly the
same ``tox.ini`` file and make use of automatic sharing of
your artifacts between runs or Jenkins jobs.
Avoiding the "path too long" error with long shebang lines
---------------------------------------------------------------
If you are using Jenkins builds you might run into the issue
that tox can not call ``pip`` because the so called "shebang"
line is too long. There is a limit of 127 chars on some systems.
Probably the best way to fix the problem is to use the
new ``--workdir`` option which tells tox to use a specific
directory for its virtualenvironments. Set it to some unique
enough short path. If somebody is interested to do a PR
you could add a new option to tox which uses a random
directory for storing its workdir results and removes
it after the tox run finishes. This could be used
from CI environments where you probably anyway want
to recreate everything on new runs.
.. include:: ../links.txt
|
