blob: de4c4b1254916dfd840cef1d0744128776215b53 (
plain)
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
|
[](https://badge.fury.io/py/tox)
[](https://pypi.org/project/tox/)
[](https://dev.azure.com/toxdev/tox/_build/latest?definitionId=9&branchName=master)
[](https://tox.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/psf/black)
<a href="https://tox.readthedocs.io">
<img src="https://raw.githubusercontent.com/tox-dev/tox/master/docs/_static/img/tox.png"
alt="tox logo"
height="150px"
align="right">
</a>
# tox automation project
**Command line driven CI frontend and development task automation tool**
At its core tox povides a convenient way to run arbitrary commands in
isolated environments to serve as a single entry point for build, test
and release activities.
tox is highly
[configurable](https://tox.readthedocs.io/en/latest/config.html) and
[pluggable](https://tox.readthedocs.io/en/latest/plugins.html).
## Example: run tests with Python 2.7 and Python 3.7
tox is mainly used as a command line tool and needs a `tox.ini` or a
`tool.tox` section in `pyproject.toml` containing the configuration.
To test a simple project that has some tests, here is an example with
a `tox.ini` in the root of the project:
``` {.sourceCode .ini}
[tox]
envlist = py27,py37
[testenv]
deps = pytest
commands = pytest
```
``` {.sourceCode .console}
$ tox
[lots of output from what tox does]
[lots of output from commands that were run]
__________________ summary _________________
py27: commands succeeded
py37: commands succeeded
congratulations :)
```
tox created two ``testenvs`` - one based on Python2.7 and one based on
Python3.7, it installed pytest in them and ran the tests. The report at
the end summarizes which ``testenvs`` have failed and which have
succeeded.
**Note:** To learn more about what you can do with tox, have a look at
[the collection of examples in the
documentation](https://tox.readthedocs.io/en/latest/examples.html)
or [existing projects using
tox](https://github.com/search?l=INI&q=tox.ini+in%3Apath&type=Code).
### How it works
tox creates virtual environments for all configured so called
``testenvs``, it then installs the project and other necessary
dependencies and runs the configured set of commands. See [system
overview](https://tox.readthedocs.io/en/latest/#system-overview) for
more details.
<a href="https://tox.readthedocs.io/en/latest/#system-overview">
<img src="https://raw.githubusercontent.com/tox-dev/tox/master/docs/img/tox_flow.png"
alt="tox flow"
width="800px"
align="center">
</a>
### tox can be used for ...
- creating development environments
- running static code analysis and test tools
- automating package builds
- running tests against the package build by tox
- checking that packages install correctly with different Python
versions/interpreters
- unifying Continuous Integration and command line based testing
- building and deploying project documentation
- releasing a package to PyPI or any other platform
- limit: your imagination
### Documentation
Documentation for tox can be found at [Read The Docs](https://tox.readthedocs.org).
### Communication and questions
If you have questions or suggestions you can first check if they have already
been answered or discussed on our [issue tracker](https://github.com/tox-dev/tox/issues?utf8=%E2%9C%93&q=is%3Aissue+sort%3Aupdated-desc+label%3A%22type%3Aquestion+%3Agrey_question%3A%22+)
on [Stack Overflow (tagged with `tox`)](https://stackoverflow.com/questions/tagged/tox).
If you want to discuss topics or propose changes that might not (yet)
fit into an issue, you can get in touch via mail through
<tox-dev@python.org>.
We also have a [Gitter community](https://gitter.im/tox-dev/).
### Contributing
Contributions are welcome. See
[contributing](https://github.com/tox-dev/tox/blob/master/CONTRIBUTING.rst)
and our [Contributor Covenant Code of
Conduct](https://github.com/tox-dev/tox/blob/master/CODE_OF_CONDUCT.md).
Currently the [code](https://github.com/tox-dev/tox) and the
[issues](https://github.com/tox-dev/tox/issues) are hosted on Github.
The project is licensed under
[MIT](https://github.com/tox-dev/tox/blob/master/LICENSE).
|
