Merge lp:~frankban/juju-quickstart/add-tox into lp:juju-quickstart

[Francesco Banconi]

Introduce tox for testing multiple sets of deps.

Quickstart must be run on several platforms/Ubuntu series,
each one with its own versions of the packages that
Quickstart depends on. The tox utility is used for both:
- handling those kind of separate scenarios;
- creating the development virtual environments.
The latter was previously done using virtualenv directly
in the Makefile. The new infrastructure should be
more flexible.

Update the relevant parts of the Makefile, also handling
the automatic installation of system dependencies.

Implement the ability to calculate the requirements
for the PyPI package automatically by parsing the
tox.ini file. I am not really sure about the method I
used (take a look at the setup.py file), but the
alternative is to manually update those and violate DRY.
I think we could give it a try and fall back to the
manual approach if required.

Also implement a correct behavior for
"python setup.py test", which now runs all the tests.

To test and QA this branch, run `make clean` and then
follow what described in the HACKING.rst file, in the
following paragraphs:
- Creating a development environment
- Testing and debugging the application
- Requirements
- Updating application and test dependencies

Thank you!

https://codereview.appspot.com/189580044/

[Francesco Banconi (frankban)]

Reviewers: mp+246761_code.launchpad.net,

Message:
Please take a look.

Description:
Introduce tox for testing multiple sets of deps.

Quickstart must be run on several platforms/Ubuntu series,
each one with its own versions of the packages that
Quickstart depends on. The tox utility is used for both:
- handling those kind of separate scenarios;
- creating the development virtual environments.
The latter was previously done using virtualenv directly
in the Makefile. The new infrastructure should be
more flexible.

Update the relevant parts of the Makefile, also handling
the automatic installation of system dependencies.

Implement the ability to calculate the requirements
for the PyPI package automatically by parsing the
tox.ini file. I am not really sure about the method I
used (take a look at the setup.py file), but the
alternative is to manually update those and violate DRY.
I think we could give it a try and fall back to the
manual approach if required.

Also implement a correct behavior for
"python setup.py test", which now runs all the tests.

To test and QA this branch, run `make clean` and then
follow what described in the HACKING.rst file, in the
following paragraphs:
- Creating a development environment
- Testing and debugging the application
- Requirements
- Updating application and test dependencies

Thank you!

https://code.launchpad.net/~frankban/juju-quickstart/add-tox/+merge/246761

(do not edit description out of merge proposal)

Please review this at https://codereview.appspot.com/189580044/

Affected files (+409, -171 lines):
   M .bzrignore
   M HACKING.rst
   M MANIFEST.in
   M Makefile
   A [revision details]
   D requirements.pip
   A setup.cfg
   M setup.py
   D test-requirements.pip
   A tox.ini

[Brad Crittenden (bac)]

LGTM. Did not try to QA yet. Tox may be very interesting for lots of our
projects.

https://codereview.appspot.com/189580044/diff/1/HACKING.rst
File HACKING.rst (right):

https://codereview.appspot.com/189580044/diff/1/HACKING.rst#newcode356
HACKING.rst:356: parsing ``tox.ini``, dependencies must be listed with
the following rules:
Could you try to re-word that sentence? I'm not sure what you're saying.

https://codereview.appspot.com/189580044/diff/1/HACKING.rst#newcode358
HACKING.rst:358: - each scenario must at least include a
"{[testenv]deps}" line in its deps:
Change the : to ; or ,

https://codereview.appspot.com/189580044/diff/1/MANIFEST.in
File MANIFEST.in (right):

https://codereview.appspot.com/189580044/diff/1/MANIFEST.in#newcode24
MANIFEST.in:24: # tox.ini file, removing it from this list will break
the source distribution
Again, this could be worded better.

https://codereview.appspot.com/189580044/diff/1/setup.py
File setup.py (right):

https://codereview.appspot.com/189580044/diff/1/setup.py#newcode43
setup.py:43: """Return Juju Quickstart package data by walking through
the project."""
A better explanation of what "package data" is would be nice.

https://codereview.appspot.com/189580044/diff/1/setup.py#newcode74
setup.py:74: for requirement in deps:
Maybe add

requirement = requirement.strip()

https://codereview.appspot.com/189580044/diff/1/tox.ini
File tox.ini (right):

https://codereview.appspot.com/189580044/diff/1/tox.ini#newcode42
tox.ini:42: basepython = python2.7
Is it required to repeat here?

https://codereview.appspot.com/189580044/

[lp:~frankban/juju-quickstart/add-tox]

130. By Francesco Banconi on 2015-01-30

Changes as per review.

[Francesco Banconi (frankban)]

Please take a look.

https://codereview.appspot.com/189580044/diff/1/HACKING.rst
File HACKING.rst (right):

https://codereview.appspot.com/189580044/diff/1/HACKING.rst#newcode356
HACKING.rst:356: parsing ``tox.ini``, dependencies must be listed with
the following rules:
On 2015/01/22 16:15:27, bac wrote:
> Could you try to re-word that sentence? I'm not sure what you're
saying.

Done.

https://codereview.appspot.com/189580044/diff/1/HACKING.rst#newcode358
HACKING.rst:358: - each scenario must at least include a
"{[testenv]deps}" line in its deps:
On 2015/01/22 16:15:27, bac wrote:
> Change the : to ; or ,

Done.

https://codereview.appspot.com/189580044/diff/1/MANIFEST.in
File MANIFEST.in (right):

https://codereview.appspot.com/189580044/diff/1/MANIFEST.in#newcode24
MANIFEST.in:24: # tox.ini file, removing it from this list will break
the source distribution
On 2015/01/22 16:15:27, bac wrote:
> Again, this could be worded better.

Done.

https://codereview.appspot.com/189580044/diff/1/setup.py
File setup.py (right):

https://codereview.appspot.com/189580044/diff/1/setup.py#newcode43
setup.py:43: """Return Juju Quickstart package data by walking through
the project."""
On 2015/01/22 16:15:27, bac wrote:
> A better explanation of what "package data" is would be nice.

Done.

https://codereview.appspot.com/189580044/diff/1/setup.py#newcode74
setup.py:74: for requirement in deps:
On 2015/01/22 16:15:27, bac wrote:
> Maybe add

> requirement = requirement.strip()

Done.

https://codereview.appspot.com/189580044/diff/1/tox.ini
File tox.ini (right):

https://codereview.appspot.com/189580044/diff/1/tox.ini#newcode42
tox.ini:42: basepython = python2.7
On 2015/01/22 16:15:27, bac wrote:
> Is it required to repeat here?

No it's not. Good catch!

https://codereview.appspot.com/189580044/

[Brad Crittenden (bac)]

Code is LGTM with the one suggestion for the Makefile.

QA OK on trusty

On OS X, the 'make sysdeps' suggests you use brew to install python-dev
python-setuptools and python-pip. Those package names are not the same
in brew and pip is installed via 'brew install python'. I'm not sure if
the equivalent of python-dev gets installed but 'make check' ran fine.

Perhaps you can adjust the message to be less misleading.

https://codereview.appspot.com/189580044/diff/20001/Makefile
File Makefile (right):

https://codereview.appspot.com/189580044/diff/20001/Makefile#newcode44
Makefile:44:
It is a bit odd to touch the canary on an non-Debian system when the
sysdeps were not installed.

https://codereview.appspot.com/189580044/

[Jeff Pihach (hatch)]

LGTM Thanks for all that this should help simplify testing quite a bit

https://codereview.appspot.com/189580044/

[Francesco Banconi (frankban)]

Thanks for the reviews!

https://codereview.appspot.com/189580044/diff/20001/Makefile
File Makefile (right):

https://codereview.appspot.com/189580044/diff/20001/Makefile#newcode44
Makefile:44:
On 2015/01/30 15:38:52, bac wrote:
> It is a bit odd to touch the canary on an non-Debian system when the
sysdeps
> were not installed.

I modified the message to be more clear. We need to touch the file so
that OSX users having all the required sysdeps installed can still
proceed without seeing the message each time.

https://codereview.appspot.com/189580044/

[lp:~frankban/juju-quickstart/add-tox]

131. By Francesco Banconi on 2015-01-30

Improve sysdeps message in Makefile.

[Francesco Banconi (frankban)]

*** Submitted:

Introduce tox for testing multiple sets of deps.

Quickstart must be run on several platforms/Ubuntu series,
each one with its own versions of the packages that
Quickstart depends on. The tox utility is used for both:
- handling those kind of separate scenarios;
- creating the development virtual environments.
The latter was previously done using virtualenv directly
in the Makefile. The new infrastructure should be
more flexible.

Update the relevant parts of the Makefile, also handling
the automatic installation of system dependencies.

Implement the ability to calculate the requirements
for the PyPI package automatically by parsing the
tox.ini file. I am not really sure about the method I
used (take a look at the setup.py file), but the
alternative is to manually update those and violate DRY.
I think we could give it a try and fall back to the
manual approach if required.

Also implement a correct behavior for
"python setup.py test", which now runs all the tests.

To test and QA this branch, run `make clean` and then
follow what described in the HACKING.rst file, in the
following paragraphs:
- Creating a development environment
- Testing and debugging the application
- Requirements
- Updating application and test dependencies

Thank you!

R=bac, benjamin.saller, jeff.pihach
CC=
https://codereview.appspot.com/189580044

https://codereview.appspot.com/189580044/

=== modified file '.bzrignore'
--- .bzrignore	2013-11-06 10:16:42 +0000
+++ .bzrignore	2015-01-30 16:35:06 +0000
@@ -1,8 +1,10 @@
 .coverage
 .DS_Store
 .emacs*
-.venv
+.sysdeps-installed
+.tox
 build
+devenv
 dist
 juju_quickstart.egg-info
 MANIFEST

=== modified file 'HACKING.rst'
--- HACKING.rst	2015-01-13 12:03:15 +0000
+++ HACKING.rst	2015-01-30 16:35:06 +0000
@@ -11,35 +11,68 @@
 Creating a development environment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The development environment is created in a virtualenv. The environment
-creation requires the *make*, *pip* and *virtualenv* programs to be installed.
-To do that, run the following::
-
-    $ make sysdeps
-
-At this point, from the root of this branch, run the command::
-
-    $ make
-
-This command will create a ``.venv`` directory in the branch root, ignored
-by DVCSes, containing the development virtual environment with all the
-dependencies.
+The development environment is created using the
+`tox <https://tox.readthedocs.org/en/latest/>`_ utility. To create the
+environment, just run ``make``. The first time it is run, ``make`` also
+installs the required system dependencies. For this reason sudo privileges can
+be asked in the process. When the command completes the development environment
+is ready and placed in the ``devenv`` directory inside the project's root.
+
+At this point it is possible to start contributing to the project. The steps
+for testing the application and running Juju Quickstart in development mode are
+described below. Thanks for contributing!
 
 Testing and debugging the application
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Run the tests::
+With the development environment correctly set up (after running ``make``), it
+is easy to run the tests with the following command::
 
     $ make test
 
-Run the tests and lint/pep8 checks::
+It is also possible to run a subset of the test suite by using nose directly,
+as it is already installed in the development environment, e.g.::
+
+    $ devenv/bin/nosetests quickstart/tests/test_app.py:TestWatch
+
+To run the development version of Juju Quickstart while making changes, or
+while reviewing a branch, use the following command::
+
+    $ devenv/bin/juju-quickstart
+
+The command above receives all usual Juju Quickstart arguments, so, for
+instance, to start the interactive session::
+
+    $ devenv/bin/juju-quickstart -i
+
+To run the Python linter and pep8 checks, use the following command::
+
+    $ make lint
+
+When a feature branch is ready, before proposing it, check that the code tests
+pass when Juju Quickstart is installed using the dependencies present in all
+supported platforms and Ubuntu series. To do that, run the following::
 
     $ make check
 
-Display help about all the available make targets, including instructions on
-setting up and running the application in the development environment::
-
-    $ make help
+The above leverages tox ability to create multiple virtual environments, each
+one with a specific set of requirements. The ``make check`` command is also
+run automatically when proposing a branch with ``lbox propose``.
+
+As a final note, having the development environment ready, it is also possible
+to use the ``tox`` command directly on the project. For instance, to run the
+tests only on the ``vivid`` scenario, use the following::
+
+    $ tox -e vivid
+
+Run ``make help`` for more information about all the available make targets.
+
+Requirements
+~~~~~~~~~~~~
+
+The Python requirements for Juju Quickstart are dynamically generated by
+parsing the ``tox.ini`` file. To check the requirements list, run
+``make requirements``.
 
 Installing the application
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -67,12 +100,6 @@
 
     $ juju quickstart -e local
 
-If you have not installed the application using ``sudo make install``, as
-described above, you can run it locally using the virtualenv's Python
-installation::
-
-    $ .venv/bin/python juju-quickstart --help
-
 Project structure
 ~~~~~~~~~~~~~~~~~
 
@@ -203,7 +230,8 @@
 packaging branch root. To print the version of the current Quickstart, from the
 juju-quickstart branch root, run the following::
 
-    $ .venv/bin/python juju-quickstart --version
+    $ make
+    $ devenv/bin/juju-quickstart --version
 
 If the ``debian/changelog`` file is outdated, install the ``devscripts``
 package and use ``dch`` to update the changelog, e.g.::
@@ -247,8 +275,8 @@
 Creating a Homebrew release
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The brew formula fetches its source from PyPI, so it must be done after the PyPI
-release.
+The brew formula fetches its source from PyPI, so it must be done after the
+PyPI release.
 
 1. Start with a fresh brew::
 
@@ -303,8 +331,8 @@
 #. Go to https://github.com/juju/homebrew to create a pull request.
 #. Copy the debian/changelog from the lp:juju-quickstart/packaging as the pull
    request comment.  Keep the name simple, e.g. 'juju-quickstart 1.4.0'.
-#. Watch the pull request and ensure it passes Jenkins.  If changes must be made,
-   rebase the branch and squash commits before pushing.
+#. Watch the pull request and ensure it passes Jenkins.  If changes must be
+   made, rebase the branch and squash commits before pushing.
 #. If the branch makes it through CI without errors it will be accepted and
    merged without human intervention. A recent branch took about two hours
    from the time the pull request was made.
@@ -323,17 +351,19 @@
 Updating application and test dependencies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Test dependencies are listed in the ``test-requirements.pip`` file in the
-branch root, application ones in the ``requirements.pip`` file. The former
-includes the latter, so any updates to the application requirements will also
-update the test dependencies and therefore the testing virtual environment.
-Note that, since the source requirements are dynamically generated parsing
-``requirements.pip``, that file must only include ``PACKAGE==VERSION`` formatted
-dependencies, and not other pip specific requirement specifications.
-
-Also ensure, before updating the application dependencies, that those packages
-are available in the main Ubuntu repositories for the series we support (from
-precise to vivid), or in the `Juju Quickstart Beta PPA
+Test and application dependencies are listed in the ``tox.ini`` file in the
+branch root. Note that, since the source requirements are dynamically generated
+parsing ``tox.ini``, when updating the list of dependencies in ``tox.ini``,
+these rules must be followed:
+
+- each scenario must at least include a "{[testenv]deps}" line in its deps,
+  this way tests can be run correctly inside the virtualenv;
+- keep each requirement in deps in its own line;
+- always use specific revisions for environments (i.e. always use "==").
+
+Also ensure, before updating the application dependencies, that the package
+versions reflect the ones available for each supported platform and in the
+`Juju Quickstart Beta PPA
 <https://launchpad.net/~juju-gui/+archive/quickstart-beta/+packages>`_.
 
 Please also keep up to date the possible values for the environments.yaml
@@ -341,6 +371,16 @@
 set of series supported by the Juju GUI charm
 (see ``quickstart.settings.JUJU_GUI_SUPPORTED_SERIES``).
 
+When introducing a new supported platform, do the following:
+
+- add a new section in the ``tox.ini`` file with a sensible name and list the
+  dependencies that we expect to be found on that platform/series;
+- add the platform name to the envlist option (in the tox section of the file);
+- if required, update ``quickstart.settings.JUJU_GUI_SUPPORTED_SERIES``;
+- run ``make requirements`` and ensure that the dynamically generated list of
+  requirements make sense;
+- run ``make check`` and ensure all the tests pass.
+
 Debugging bundle support
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -356,10 +396,10 @@
 information about what is going on. The GUI builtin server exposes some bundle
 information in two places:
 
-- ``https://<juju-gui-url>/gui-server-info`` displays in JSON format the current
-  status of all scheduled/started/completed bundle deployments;
-- ``/var/log/upstart/guiserver.log`` is the builtin server log file, which includes
-  logs output from the juju-deployer library.
+- ``https://<juju-gui-url>/gui-server-info`` displays in JSON format the
+  current status of all scheduled/started/completed bundle deployments;
+- ``/var/log/upstart/guiserver.log`` is the builtin server log file, which
+  includes logs output from the juju-deployer library.
 
 Moreover, setting ``builtin-server-logging=debug`` gives more debugging
 information, e.g. it prints to the log the contents of the WebSocket messages

=== modified file 'MANIFEST.in'
--- MANIFEST.in	2014-03-13 11:56:58 +0000
+++ MANIFEST.in	2015-01-30 16:35:06 +0000
@@ -19,8 +19,9 @@
 include MANIFEST.in
 include Makefile
 include README.rst
+include setup.cfg
 # Note: since the source requirements are dynamically generated parsing the
-# requirements.pip file, removing it from this list will break the source
-# distribution and therefore the Debian package builds. Do not do that.
-include requirements.pip
-include test-requirements.pip
+# tox.ini file, removing the "include tox.ini" entry below from this list would
+# break the source distribution and therefore the Debian package builds.
+# Do not do that.
+include tox.ini

=== modified file 'Makefile'
--- Makefile	2014-09-05 14:54:31 +0000
+++ Makefile	2015-01-30 16:35:06 +0000
@@ -15,75 +15,106 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 PYTHON = python
-SYSDEPS = build-essential python-dev python-pip python-virtualenv
-
-VENV = .venv
-VENV_ACTIVATE = $(VENV)/bin/activate
-
-
-$(VENV_ACTIVATE): test-requirements.pip requirements.pip
-	virtualenv --distribute -p $(PYTHON) $(VENV)
-	$(VENV)/bin/pip install -r test-requirements.pip || \
-		(touch test-requirements.pip; exit 1)
-	@touch $(VENV_ACTIVATE)
-
-all: setup
-
-check: test lint
-
+APT_SYSDEPS = python-dev python-pip python-setuptools
+# Since the python-tox package in Ubuntu uses Python 3, use pip to install tox
+# instead. This also works on OSX where tox is not present in Homebrew.
+PIP_SYSDEPS = tox
+
+SYSDEPS_INSTALLED = .sysdeps-installed
+DEVENV = devenv
+QUICKSTART = $(DEVENV)/bin/juju-quickstart
+
+.DEFAULT_GOAL := setup
+
+
+$(QUICKSTART): juju-quickstart setup.py tox.ini
+	@tox -e devenv
+
+$(SYSDEPS_INSTALLED): Makefile
+ifeq ($(shell command -v apt-get > /dev/null; echo $$?),0)
+	sudo apt-get install --yes $(APT_SYSDEPS)
+else
+	@echo 'System dependencies can only be installed automatically on'
+	@echo 'systems with "apt-get". On OSX you can manually use Homebrew'
+	@echo 'if there are missing dependencies corresponding to the following'
+	@echo 'Debian packages:'
+	@echo '$(APT_SYSDEPS).'
+endif
+	sudo pip2 install $(PIP_SYSDEPS)
+	touch $(SYSDEPS_INSTALLED)
+
+
+.PHONY: check
+check: setup
+	@tox -e lint
+	@tox
+
+.PHONY: clean
 clean:
 	$(PYTHON) setup.py clean
-	rm -rfv build/ dist/ juju_quickstart.egg-info MANIFEST
-	rm -rfv $(VENV)
+	# Remove the development environments.
+	rm -rfv $(DEVENV) .tox/
+	# Remove distribution artifacts.
+	rm -rfv *.egg build/ dist/ juju_quickstart.egg-info/ MANIFEST
+	# Remove tests artifacts.
+	rm -fv .coverage
+	# Remove the sysdeps canary file.
+	rm -fv $(SYSDEPS_INSTALLED)
+	# Remove Python compiled bytecode.
 	find . -name '*.pyc' -delete
 	find . -name '__pycache__' -type d -delete
-
-setup: $(VENV_ACTIVATE)
-
+	# Remove the virtualenv used in previous configurations.
+	rm -rfv .venv/
+
+.PHONY: help
 help:
 	@echo -e 'Juju Quickstart - list of make targets:\n'
-	@echo 'make sysdeps - Install the development environment system packages.'
 	@echo 'make - Set up the development and testing environment.'
 	@echo 'make test - Run tests.'
 	@echo 'make lint - Run linter and pep8.'
-	@echo 'make check - Run tests, linter and pep8.'
+	@echo 'make check - Run all the tests and lint in all supported scenarios.'
 	@echo 'make source - Create source package.'
 	@echo 'make install - Install on local system.'
-	@echo 'make run - Run the application in the development environment.\n'
-	@echo '  If "juju switch" has been used to set a default environment, that'
-	@echo '  environment will be used. It is possible to override the default'
-	@echo '  Juju environment by setting the JUJU_ENV environment variable,'
-	@echo '  e.g.: "make run JUJU_ENV=ec2".'
-	@echo 'make debug - Same as the "run" target but with the --debug flag.\n'
-	@echo 'make clean - Get rid of bytecode files, build and dist dirs, venv.'
+	@echo 'make clean - Get rid of bytecode files, build and dist dirs, venvs.'
 	@echo 'make release - Register and upload a release on PyPI.'
+	@echo 'make requirements - Print out the application requirements.'
+	@echo -e '\nAfter creating the development environment with "make", it is'
+	@echo 'also possible to do the following:'
+	@echo '- run the development version of Juju Quickstart by invoking'
+	@echo '  "$(QUICKSTART)";'
+	@echo '- run a specific subset of the test suite, e.g. with'
+	@echo '  "$(DEVENV)/bin/nosetests quickstart/tests/test_app.py:TestWatch";'
+	@echo '- use tox as usual on this project;'
+	@echo '  see https://tox.readthedocs.org/en/latest/'
 
+.PHONY: install
 install:
 	$(PYTHON) setup.py install
 	rm -rfv ./build ./dist ./juju_quickstart.egg-info
 
+.PHONY: lint
 lint: setup
-	@$(VENV)/bin/flake8 --show-source --exclude=$(VENV) ./quickstart
+	@$(DEVENV)/bin/flake8 --show-source quickstart
 
+.PHONY: release
 release: check
 	$(PYTHON) setup.py register sdist upload
 
-run: setup
-	$(VENV)/bin/python ./juju-quickstart
-
-debug: setup
-	$(VENV)/bin/python ./juju-quickstart --debug
-
+.PHONY: requirements
+requirements:
+	$(PYTHON) setup.py requirements
+
+.PHONY: setup
+setup: $(SYSDEPS_INSTALLED) $(QUICKSTART)
+
+.PHONY: source
 source:
 	$(PYTHON) setup.py sdist
 
-sysdeps:
-	sudo apt-get install --yes $(SYSDEPS)
+.PHONY: sysdeps
+sysdeps: $(SYSDEPS_INSTALLED)
 
+.PHONY: test
 test: setup
-	@$(VENV)/bin/nosetests -s --verbosity=2 \
-	    --with-coverage --cover-package=quickstart quickstart
-	@rm .coverage
-
-.PHONY: all clean check debug help install lint release run setup source \
-	sysdeps test
+	@$(DEVENV)/bin/nosetests \
+		--with-coverage --cover-erase --cover-package quickstart

=== removed file 'requirements.pip'
--- requirements.pip	2014-09-05 14:54:31 +0000
+++ requirements.pip	1970-01-01 00:00:00 +0000
@@ -1,31 +0,0 @@
-# Juju Quickstart application requirements.
-
-# This file is part of the Juju Quickstart Plugin, which lets users set up a
-# Juju environment in very few steps (https://launchpad.net/juju-quickstart).
-# Copyright (C) 2013 Canonical Ltd.
-#
-# This program is free software: you can redistribute it and/or modify it under
-# the terms of the GNU Affero General Public License version 3, as published by
-# the Free Software Foundation.
-#
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranties of MERCHANTABILITY,
-# SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Affero General Public License for more details.
-#
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-# Note: since the source requirements are dynamically generated parsing the
-# requirements.pip file, the list below must only include PACKAGE==VERSION
-# formatted dependencies. Do not include other pip specific requirement
-# specifications (e.g. -e ... or -r ...).
-
-# XXX: BradCrittenden 2014-05-23: jujuclient 0.17.5 does not specify the
-# version of websocket-client to use.  Remove websocket-client as a dependency
-# here when moving to a newer jujuclient that correctly specifies the
-# version.
-websocket-client==0.18.0
-jujuclient==0.18.4
-PyYAML==3.11
-urwid==1.2.1

=== added file 'setup.cfg'
--- setup.cfg	1970-01-01 00:00:00 +0000
+++ setup.cfg	2015-01-30 16:35:06 +0000
@@ -0,0 +1,20 @@
+# This file is part of the Juju Quickstart Plugin, which lets users set up a
+# Juju environment in very few steps (https://launchpad.net/juju-quickstart).
+# Copyright (C) 2015 Canonical Ltd.
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License version 3, as published by
+# the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranties of MERCHANTABILITY,
+# SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+[nosetests]
+detailed-errors=1
+nocapture=1
+verbosity=2

=== modified file 'setup.py'
--- setup.py	2014-01-29 15:25:06 +0000
+++ setup.py	2015-01-30 16:35:06 +0000
@@ -16,52 +16,140 @@
 
 """Juju Quickstart distribution file."""
 
+from __future__ import print_function
+
+import ConfigParser
+from distutils.core import Command
+from distutils.version import StrictVersion
 import os
+import shlex
+import sys
 
 from setuptools import (
     find_packages,
     setup,
 )
+from setuptools.command.test import test as TestCommand
 
 
 ROOT = os.path.abspath(os.path.dirname(__file__))
 PROJECT_NAME = 'quickstart'
 
+os.chdir(ROOT)
 project = __import__(PROJECT_NAME)
-description_path = os.path.join(ROOT, 'README.rst')
-
-requirements_path = os.path.join(ROOT, 'requirements.pip')
-requirements = [i.strip() for i in open(requirements_path).readlines()]
-install_requires = [i for i in requirements if i and not i.startswith('#')]
-
-os.chdir(ROOT)
-
-data_files = []
-for dirpath, dirnames, filenames in os.walk(PROJECT_NAME):
-    for i, dirname in enumerate(dirnames):
-        if dirname.startswith('.'):
-            del dirnames[i]
-    if '__init__.py' in filenames:
-        continue
-    elif filenames:
-        for f in filenames:
-            data_files.append(os.path.join(
-                dirpath[len(PROJECT_NAME) + 1:], f))
+
+
+def get_package_data():
+    """Return Juju Quickstart package data by walking through the project.
+
+    The package data includes all non-python files that must be included in
+    the source distribution.
+    """
+    data_files = []
+    for dirpath, dirnames, filenames in os.walk(PROJECT_NAME):
+        for i, dirname in enumerate(dirnames):
+            if dirname.startswith('.'):
+                del dirnames[i]
+        if '__init__.py' in filenames:
+            continue
+        elif filenames:
+            for f in filenames:
+                data_files.append(os.path.join(
+                    dirpath[len(PROJECT_NAME) + 1:], f))
+    return {PROJECT_NAME: data_files}
+
+
+def get_long_description():
+    """Retrieve the project long description from the README.rst file."""
+    with open(os.path.join(ROOT, 'README.rst')) as readme_file:
+        return readme_file.read()
+
+
+def get_install_requires():
+    """Dynamically generate the requirements list by parsing the tox file."""
+    config = ConfigParser.ConfigParser()
+    config.read(os.path.join(ROOT, 'tox.ini'))
+    all_versions = {}
+    test_requirements = '{[testenv]deps}'
+    platforms = config.get('tox', 'envlist').split(',')
+    for platform in platforms:
+        section = 'testenv:{}'.format(platform)
+        deps = filter(None, config.get(section, 'deps').splitlines())
+        for requirement in deps:
+            requirement = requirement.strip()
+            if requirement.startswith('#') or requirement == test_requirements:
+                continue
+            name, version = requirement.split('==')
+            versions = all_versions.setdefault(name, set())
+            versions.add(version)
+    requirements = []
+    for name, versions in all_versions.items():
+        if len(versions) == 1:
+            requirements.append('{}=={}'.format(name, versions.pop()))
+            continue
+        versions = list(sorted(versions, key=StrictVersion))
+        requirements.append(
+            '{}>={},<={}'.format(name, versions[0], versions[-1]))
+    return requirements
+
+
+class RequirementsCommand(Command):
+    """Set up the requirements command."""
+
+    description = 'output program requirements'
+    user_options = []
+
+    def initialize_options(self):
+        pass
+
+    def finalize_options(self):
+        pass
+
+    def run(self):
+        requirements = get_install_requires()
+        print('\n{}'.format('\n'.join(requirements)))
+
+
+class ToxCommand(TestCommand):
+    """Set up the tox testing command."""
+
+    user_options = [('tox-args=', 'a', 'Arguments to pass to tox')]
+
+    def initialize_options(self):
+        TestCommand.initialize_options(self)
+        self.tox_args = None
+
+    def finalize_options(self):
+        TestCommand.finalize_options(self)
+        self.test_args = []
+        self.test_suite = True
+
+    def run_tests(self):
+        # Import here, cause outside the eggs aren't loaded.
+        import tox
+        args = [] if self.tox_args is None else shlex.split(self.tox_args)
+        errno = tox.cmdline(args=args)
+        sys.exit(errno)
 
 
 setup(
     name='juju-quickstart',
     version=project.get_version(),
     description=project.__doc__,
-    long_description=open(description_path).read(),
+    long_description=get_long_description(),
     author='The Juju GUI team',
     author_email='[e-mail]',
     url='https://launchpad.net/juju-quickstart',
     keywords='juju quickstart plugin',
     packages=find_packages(),
-    package_data={PROJECT_NAME: data_files},
+    package_data=get_package_data(),
     scripts=['juju-quickstart'],
-    install_requires=install_requires,
+    install_requires=get_install_requires(),
+    tests_require=['tox'],
+    cmdclass = {
+        'requirements': RequirementsCommand,
+        'test': ToxCommand,
+    },
     zip_safe=False,
     classifiers=[
         'Development Status :: 5 - Production/Stable',

=== removed file 'test-requirements.pip'
--- test-requirements.pip	2014-09-05 14:54:31 +0000
+++ test-requirements.pip	1970-01-01 00:00:00 +0000
@@ -1,23 +0,0 @@
-# Juju Quickstart test requirements.
-
-# This file is part of the Juju Quickstart Plugin, which lets users set up a
-# Juju environment in very few steps (https://launchpad.net/juju-quickstart).
-# Copyright (C) 2013 Canonical Ltd.
-#
-# This program is free software: you can redistribute it and/or modify it under
-# the terms of the GNU Affero General Public License version 3, as published by
-# the Free Software Foundation.
-#
-# This program is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranties of MERCHANTABILITY,
-# SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-# Affero General Public License for more details.
-#
-# You should have received a copy of the GNU Affero General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-coverage==3.7.1
-flake8==2.2.3
-mock==1.0.1
-nose==1.3.4
--r requirements.pip

=== added file 'tox.ini'
--- tox.ini	1970-01-01 00:00:00 +0000
+++ tox.ini	2015-01-30 16:35:06 +0000
@@ -0,0 +1,115 @@
+# This file is part of the Juju Quickstart Plugin, which lets users set up a
+# Juju environment in very few steps (https://launchpad.net/juju-quickstart).
+# Copyright (C) 2015 Canonical Ltd.
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License version 3, as published by
+# the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranties of MERCHANTABILITY,
+# SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+[tox]
+# The envlist option must only include platform scenarios. In essence, those
+# are used to test Juju Quickstart with the specific dependencies present in
+# each supported OS platform.
+envlist = pypi,ppa,vivid
+# XXX frankban: currently tests do not pass on trusty and utopic scenarios.
+# Fix the tests, then remove the line above and uncomment the line below.
+# envlist = pypi,ppa,trusty,utopic,vivid
+
+
+# Define the base requirements and commands to use when testing the program.
+
+[testenv]
+basepython = python2.7
+deps =
+    mock==1.0.1
+    nose==1.3.4
+commands =
+    nosetests {posargs:--quiet}
+
+
+# Set up the development environment.
+
+[testenv:devenv]
+envdir = devenv
+usedevelop = True
+deps =
+    {[testenv]deps}
+    {[testenv:lint]deps}
+    coverage==3.7.1
+commands =
+
+
+# Set up different scenarios for each Juju Quickstart source repository.
+# Note that the setup.py distribution file calculates Juju Quickstart
+# requirements based on this file. For this reason, when updating dependencies,
+# respect the following rules:
+# - all scenarios must be listed in the envlist above (in the tox section);
+# - each scenario must at least include a "{[testenv]deps}" line in its deps;
+# - keep each requirement in deps in its own line;
+# - always use specific revisions for environments (i.e. use "==").
+# After updating this file, run "make requirements" and ensure the general
+# dependency rules in the output make sense.
+
+[testenv:pypi]
+# Always recreate the virtualenv here so that old installed dependencies are
+# not reused and a fresh pip install can be accurately simulated.
+recreate = True
+deps =
+    {[testenv]deps}
+    # All the dependencies are installed by Juju Quickstart itself, using
+    # the dynamically generated "install_requires" setup field.
+    # Note that, since Homebrew internally uses pip when installing Quickstart,
+    # this scenario also covers OSX installations.
+
+[testenv:ppa]
+deps =
+    {[testenv]deps}
+    # Dependencies present in ppa:juju/stable.
+    # See https://launchpad.net/~juju/+archive/ubuntu/stable.
+    websocket-client==0.18.0
+    jujuclient==0.18.4
+    urwid==1.2.1
+    # The distribution PyYAML requirement is used in this case.
+
+[testenv:trusty]
+deps =
+    {[testenv]deps}
+    # Ubuntu 14.04 (trusty) distro dependencies.
+    websocket-client==0.12.0
+    jujuclient==0.17.5
+    PyYAML==3.10
+    urwid==1.1.1
+
+[testenv:utopic]
+deps =
+    {[testenv]deps}
+    # Ubuntu 14.10 (utopic) distro dependencies.
+    websocket-client==0.12.0
+    jujuclient==0.17.5
+    PyYAML==3.11
+    urwid==1.2.1
+
+[testenv:vivid]
+deps =
+    {[testenv]deps}
+    # Ubuntu 15.04 (vivid) distro dependencies.
+    websocket-client==0.18.0
+    jujuclient==0.18.5
+    PyYAML==3.11
+    urwid==1.2.1
+
+
+# Define additional tox targets to be used to validate and lint the code.
+
+[testenv:lint]
+usedevelop = True
+deps = flake8==2.3.0
+commands = flake8 --show-source quickstart