Merge lp:~frankban/juju-gui/quickstart-bootstrap into lp:juju-gui/juju-quickstart

[Francesco Banconi]

Parse and validate the environment file/options.

Check if the given environment name exists,
ensure it does not use the local provider,
ensure it includes an admin-secret,
retrieve the admin-secret.

Tests: make check

https://codereview.appspot.com/14669047/

[Francesco Banconi (frankban)]

Reviewers: mp+191234_code.launchpad.net,

Message:
Please take a look.

Description:
Parse and validate the environment file/options.

Check if the given environment name exists,
ensure it does not use the local provider,
ensure it includes an admin-secret,
retrieve the admin-secret.

Tests: make check

https://code.launchpad.net/~frankban/juju-gui/quickstart-bootstrap/+merge/191234

(do not edit description out of merge proposal)

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

Affected files (+633, -17 lines):
   M Makefile
   A [revision details]
   M juju-quickstart
   A quickstart/app.py
   M quickstart/manage.py
   A quickstart/tests/helpers.py
   A quickstart/tests/test_app.py
   M quickstart/tests/test_manage.py
   A quickstart/tests/test_utils.py
   A quickstart/utils.py

[Gary Poster (gary)]

LGTM with a few trivials. Thank you.

https://codereview.appspot.com/14669047/diff/1/Makefile
File Makefile (right):

https://codereview.appspot.com/14669047/diff/1/Makefile#newcode20
Makefile:20: JUJU_ENV ?= quickstart
So...this is used by make run to override the normal Python logic of the
command. I'm not quite sure of the value, but I'm fine with it.

https://codereview.appspot.com/14669047/diff/1/quickstart/tests/helpers.py
File quickstart/tests/helpers.py (right):

https://codereview.appspot.com/14669047/diff/1/quickstart/tests/helpers.py#newcode17
quickstart/tests/helpers.py:17: """Tests helpers for the Juju Quickstart
plugin."""
Trivial: Test helpers

https://codereview.appspot.com/14669047/diff/1/quickstart/tests/test_manage.py
File quickstart/tests/test_manage.py (right):

https://codereview.appspot.com/14669047/diff/1/quickstart/tests/test_manage.py#newcode119
quickstart/tests/test_manage.py:119: and a it is also possible to
simulate an arbitrary environment name.
trivial: and it is

https://codereview.appspot.com/14669047/diff/1/quickstart/tests/test_utils.py
File quickstart/tests/test_utils.py (right):

https://codereview.appspot.com/14669047/diff/1/quickstart/tests/test_utils.py#newcode48
quickstart/tests/test_utils.py:48: self.assertEqual(2, retcode)
checking precise non-zero retcode seems a bit risky, even though it
probably is practically fine for something as ancient as ls.

https://codereview.appspot.com/14669047/diff/1/quickstart/tests/test_utils.py#newcode58
quickstart/tests/test_utils.py:58: self.assertEqual(127, retcode)
likewise

https://codereview.appspot.com/14669047/diff/1/quickstart/tests/test_utils.py#newcode112
quickstart/tests/test_utils.py:112: with self.patch_call(0,
output='Exterminate!') as mock_call:
lol

https://codereview.appspot.com/14669047/diff/1/quickstart/utils.py
File quickstart/utils.py (right):

https://codereview.appspot.com/14669047/diff/1/quickstart/utils.py#newcode58
quickstart/utils.py:58: retcode, output, _ = call('juju', 'switch')
I wonder which is more fragile: relying on a regex of a stdout reply, or
looking at ~/.juju/current-environment and
~/.juju/environments.yaml[default]? This is certainly easier, so I
suppose that's a compelling argument, given that the answer to my
question is not obvious to me.

https://codereview.appspot.com/14669047/

[Madison Scott-Clary (makyo)]

LGTM, thank you!

https://codereview.appspot.com/14669047/

[lp:~frankban/juju-gui/quickstart-bootstrap]

9. By Francesco Banconi on 2013-10-15

Changes as per review.

[Francesco Banconi (frankban)]

*** Submitted:

Parse and validate the environment file/options.

Check if the given environment name exists,
ensure it does not use the local provider,
ensure it includes an admin-secret,
retrieve the admin-secret.

Tests: make check

R=gary.poster, matthew.scott
CC=
https://codereview.appspot.com/14669047

https://codereview.appspot.com/14669047/diff/1/Makefile
File Makefile (right):

https://codereview.appspot.com/14669047/diff/1/Makefile#newcode20
Makefile:20: JUJU_ENV ?= quickstart
On 2013/10/15 17:02:11, gary.poster wrote:
> So...this is used by make run to override the normal Python logic of
the
> command. I'm not quite sure of the value, but I'm fine with it.

You are right, since JUJU_ENV and the default env are already handled by
the application, this no longer makes sense. Fixed.

https://codereview.appspot.com/14669047/diff/1/quickstart/tests/helpers.py
File quickstart/tests/helpers.py (right):

https://codereview.appspot.com/14669047/diff/1/quickstart/tests/helpers.py#newcode17
quickstart/tests/helpers.py:17: """Tests helpers for the Juju Quickstart
plugin."""
On 2013/10/15 17:02:11, gary.poster wrote:
> Trivial: Test helpers

Done.

https://codereview.appspot.com/14669047/diff/1/quickstart/tests/test_manage.py
File quickstart/tests/test_manage.py (right):

https://codereview.appspot.com/14669047/diff/1/quickstart/tests/test_manage.py#newcode119
quickstart/tests/test_manage.py:119: and a it is also possible to
simulate an arbitrary environment name.
On 2013/10/15 17:02:11, gary.poster wrote:
> trivial: and it is

Done.

https://codereview.appspot.com/14669047/diff/1/quickstart/tests/test_utils.py
File quickstart/tests/test_utils.py (right):

https://codereview.appspot.com/14669047/diff/1/quickstart/tests/test_utils.py#newcode48
quickstart/tests/test_utils.py:48: self.assertEqual(2, retcode)
On 2013/10/15 17:02:11, gary.poster wrote:
> checking precise non-zero retcode seems a bit risky, even though it
probably is
> practically fine for something as ancient as ls.

Good suggestion, fixed.

https://codereview.appspot.com/14669047/diff/1/quickstart/tests/test_utils.py#newcode58
quickstart/tests/test_utils.py:58: self.assertEqual(127, retcode)
On 2013/10/15 17:02:11, gary.poster wrote:
> likewise

In this case this is safe because we return 127 ourselves.

https://codereview.appspot.com/14669047/diff/1/quickstart/utils.py
File quickstart/utils.py (right):

https://codereview.appspot.com/14669047/diff/1/quickstart/utils.py#newcode58
quickstart/utils.py:58: retcode, output, _ = call('juju', 'switch')
On 2013/10/15 17:02:11, gary.poster wrote:
> I wonder which is more fragile: relying on a regex of a stdout reply,
or looking
> at ~/.juju/current-environment and ~/.juju/environments.yaml[default]?
  This is
> certainly easier, so I suppose that's a compelling argument, given
that the
> answer to my question is not obvious to me.

As discussed, I will ask juju-core devs about
~/.juju/current-environment (is it reliable?, if not, is "juju switch
--format json" a good idea?).

https://codereview.appspot.com/14669047/

[Francesco Banconi (frankban)]

Thank you Gary and Matthew!

https://codereview.appspot.com/14669047/

=== modified file 'Makefile'
--- Makefile	2013-10-14 15:54:00 +0000
+++ Makefile	2013-10-16 07:23:37 +0000
@@ -15,10 +15,6 @@
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 PYTHON = python
-
-# Define the default Juju environment used by "make run".
-JUJU_ENV ?= local
-
 SYSDEPS = build-essential python-pip python-virtualenv
 
 VENV = .venv
@@ -36,7 +32,7 @@
 
 clean:
 	$(PYTHON) setup.py clean
-	rm -rfv build/ dist/ ./juju_quickstart.egg-info MANIFEST
+	rm -rfv build/ dist/ juju_quickstart.egg-info MANIFEST
 	rm -rfv $(VENV)
 	find . -name '*.pyc' -delete
 	find . -name '__pycache__' -type d -delete
@@ -53,9 +49,10 @@
 	@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 '  An environment named "local" is used by default.'
-	@echo '  Define the JUJU_ENV environment variable to select another'
-	@echo '  environment, e.g.: "make run JUJU_ENV=ec2".'
+	@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 clean - Get rid of bytecode files, build and dist dirs, venv.'
 
 install:
@@ -66,7 +63,7 @@
 	@$(VENV)/bin/flake8 --show-source --exclude=$(VENV) ./quickstart
 
 run: setup
-	$(VENV)/bin/python ./juju-quickstart --environment $(JUJU_ENV)
+	$(VENV)/bin/python ./juju-quickstart
 
 source:
 	$(PYTHON) setup.py sdist
@@ -77,5 +74,6 @@
 test: setup
 	@$(VENV)/bin/nosetests -s --verbosity=2 \
 	    --with-coverage --cover-package=quickstart quickstart
+	@rm .coverage
 
 .PHONY: all clean check help install lint run setup source sysdeps test

=== modified file 'juju-quickstart'
--- juju-quickstart	2013-10-14 15:24:29 +0000
+++ juju-quickstart	2013-10-16 07:23:37 +0000
@@ -18,9 +18,17 @@
 
 """Juju Quickstart plugin entry point."""
 
-from quickstart import manage
+import sys
+
+from quickstart import (
+    app,
+    manage,
+)
 
 
 if __name__ == '__main__':
     options = manage.setup()
-    manage.run(options)
+    try:
+        manage.run(options)
+    except app.ProgramExit as err:
+        sys.exit(str(err))

=== added file 'quickstart/app.py'
--- quickstart/app.py	1970-01-01 00:00:00 +0000
+++ quickstart/app.py	2013-10-16 07:23:37 +0000
@@ -0,0 +1,42 @@
+# This file is part of the Juju GUI, which lets users view and manage Juju
+# environments within a graphical interface (https://launchpad.net/juju-gui).
+# 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/>.
+
+"""Juju Quickstart base application functions."""
+
+
+class ProgramExit(Exception):
+    """An error occurred while setting up the Juju environment.
+
+    Raise this exception if you want the program to exit gracefully printing
+    the error message to stderr.
+    """
+
+    def __init__(self, message):
+        self.message = message
+
+    def __str__(self):
+        return 'juju-quickstart: error: {}'.format(self.message)
+
+
+def bootstrap(env_name):
+    """Bootstrap the Juju environment with the given name.
+
+    Return the environment API address (e.g. "api.example.com:17070").
+    Raise a ProgramExit if any error occurs in the bootstrap process.
+    Otherwise return when the environment is bootstrapped and the API server
+    is ready to accept connections.
+    """
+    # TODO: everything!

=== modified file 'quickstart/manage.py'
--- quickstart/manage.py	2013-10-14 15:24:29 +0000
+++ quickstart/manage.py	2013-10-16 07:23:37 +0000
@@ -21,9 +21,13 @@
 import os
 
 import quickstart
-
-
-default_envfile = os.path.expanduser('~/.juju/environments.yaml')
+from quickstart import (
+    app,
+    utils,
+)
+
+
+juju_home = os.getenv('JUJU_HOME', '~/.juju')
 description = 'set up a Juju environment (including the GUI) in very few steps'
 version = quickstart.get_version()
 
@@ -36,26 +40,77 @@
         parser.exit()
 
 
+def _validate_env(options, parser):
+    """Validate and process the provided environment related options.
+
+    Exit with an error if options are not valid.
+    """
+    env_file = os.path.abspath(os.path.expanduser(options.env_file))
+    # Validate the environment name.
+    env_name = options.env_name
+    if env_name is None:
+        return parser.error(
+            'unable to find an environment name to use\n'
+            'It is possible to specify the environment name by either:\n'
+            '  - passing the -e or --environment argument;\n'
+            '  - setting the JUJU_ENV environment variable;\n'
+            '  - using "juju switch" to select the default environment to use.'
+        )
+    # Validate the environment file.
+    try:
+        env_type, admin_secret = utils.parse_env_file(env_file, env_name)
+    except ValueError as err:
+        return parser.error(str(err))
+    # XXX 2013-10-15 frankban: add support for local providers.
+    if env_type == 'local':
+        return parser.error('the local provider is not currently supported')
+    # Update the options namespace with the new values.
+    options.admin_secret = admin_secret
+    options.env_file = env_file
+    options.env_type = env_type
+
+
 def setup():
-    """Set up the application options."""
+    """Set up the application options.
+
+    Return the options as a namespace containing the followin attributes:
+        - admin_secret: the password to use to access the Juju API;
+        - env_file: the absolute path of the Juju environments.yaml file;
+        - env_name: the name of the Juju environment to use;
+        - env_type: the provider type of the selected Juju environment.
+
+    Exit with an error if the provided arguments are not valid.
+    """
+    default_env_name = utils.get_default_env_name()
+    # Define the help message for the --environment option.
+    env_help = 'the name of the Juju environment to use'
+    if default_env_name is not None:
+        env_help = '{} (%(default)s)'.format(env_help)
+    # Create and set up the arguments parser.
     parser = argparse.ArgumentParser(description=quickstart.__doc__)
     parser.add_argument(
-        '-e', '--environment', required=True, dest='env_name',
-        help='the name of the Juju environment to use')
+        '-e', '--environment', default=default_env_name, dest='env_name',
+        help=env_help)
     parser.add_argument(
-        '--environments-file', dest='env_file', type=file,
-        default=default_envfile,
-        help='the path to the Juju environments YAML file')
+        '--environments-file',
+        default=os.path.join(juju_home, 'environments.yaml'), dest='env_file',
+        help='the path to the Juju environments YAML file (%(default)s)')
     parser.add_argument(
         '--version', action='version', version='%(prog)s {}'.format(version))
     # This is required by juju-core: see "juju help plugins".
     parser.add_argument(
         '--description', action=_DescriptionAction, default=argparse.SUPPRESS,
         nargs=0, help="show program's description and exit")
-    return parser.parse_args()
+    # Parse the provided arguments.
+    options = parser.parse_args()
+    # Validate and process the provided arguments.
+    _validate_env(options, parser)
+    return options
 
 
 def run(options):
-    """Run the application"""
+    """Run the application."""
     print('juju quickstart v{}'.format(version))
-    # TODO: everything!
+    print('bootstrapping the {} environment (type: {})'.format(
+        options.env_name, options.env_type))
+    app.bootstrap(options.env_name)

=== added file 'quickstart/tests/helpers.py'
--- quickstart/tests/helpers.py	1970-01-01 00:00:00 +0000
+++ quickstart/tests/helpers.py	2013-10-16 07:23:37 +0000
@@ -0,0 +1,60 @@
+# This file is part of the Juju GUI, which lets users view and manage Juju
+# environments within a graphical interface (https://launchpad.net/juju-gui).
+# 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/>.
+
+"""Test helpers for the Juju Quickstart plugin."""
+
+from contextlib import contextmanager
+import os
+import tempfile
+
+import yaml
+
+
+class ValueErrorTestsMixin(object):
+    """Set up some base methods for testing functions raising ValueErrors."""
+
+    @contextmanager
+    def assert_value_error(self, error):
+        """Ensure a ValueError is raised in the context block.
+
+        Also check that the exception includes the expected error message.
+        """
+        with self.assertRaises(ValueError) as context_manager:
+            yield
+        self.assertEqual(error, str(context_manager.exception))
+
+
+class EnvFileTestsMixin(object):
+    """Shared methods for testing a Juju environments file."""
+
+    valid_contents = yaml.safe_dump({
+        'environments': {'aws': {'admin-secret': 'Secret!', 'type': 'ec2'}},
+    })
+
+    def make_env_file(self, contents=None):
+        """Create a Juju environments file containing the given contents.
+
+        If contents is None, use the valid environment contents defined in
+        self.valid_contents.
+        Return the environments file path.
+        """
+        if contents is None:
+            contents = self.valid_contents
+        env_file = tempfile.NamedTemporaryFile(delete=False)
+        self.addCleanup(os.remove, env_file.name)
+        env_file.write(contents)
+        env_file.close()
+        return env_file.name

=== added file 'quickstart/tests/test_app.py'
--- quickstart/tests/test_app.py	1970-01-01 00:00:00 +0000
+++ quickstart/tests/test_app.py	2013-10-16 07:23:37 +0000
@@ -0,0 +1,29 @@
+# This file is part of the Juju GUI, which lets users view and manage Juju
+# environments within a graphical interface (https://launchpad.net/juju-gui).
+# 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/>.
+
+"""Tests for the Juju Quickstart base application functions."""
+
+import unittest
+
+from quickstart import app
+
+
+class TestProgramExit(unittest.TestCase):
+
+    def test_string_representation(self):
+        # The error is properly represented as a string.
+        exception = app.ProgramExit('bad wolf')
+        self.assertEqual('juju-quickstart: error: bad wolf', str(exception))

=== modified file 'quickstart/tests/test_manage.py'
--- quickstart/tests/test_manage.py	2013-10-14 15:24:29 +0000
+++ quickstart/tests/test_manage.py	2013-10-16 07:23:37 +0000
@@ -17,11 +17,15 @@
 """Tests for the Juju Quickstart management infrastructure."""
 
 import argparse
+import os
 import unittest
 
 import mock
+import yaml
 
+import quickstart
 from quickstart import manage
+from quickstart.tests import helpers
 
 
 class TestDescriptionAction(unittest.TestCase):
@@ -39,3 +43,130 @@
         self.assertIsNone(args.test)
         mock_print.assert_called_once_with(manage.description)
         mock_exit.assert_called_once_with(0)
+
+
+class TestValidateEnv(helpers.EnvFileTestsMixin, unittest.TestCase):
+
+    def setUp(self):
+        self.parser = mock.Mock()
+
+    def make_options(self, env_file, env_name=None):
+        """Return a mock options object which includes the passed arguments."""
+        return mock.Mock(env_file=env_file, env_name=env_name)
+
+    def test_resulting_options(self):
+        # The options object is correctly set up.
+        env_file = self.make_env_file()
+        options = self.make_options(env_file, env_name='aws')
+        manage._validate_env(options, self.parser)
+        self.assertEqual('Secret!', options.admin_secret)
+        self.assertEqual(env_file, options.env_file)
+        self.assertEqual('aws', options.env_name)
+        self.assertEqual('ec2', options.env_type)
+
+    def test_expand_user(self):
+        # The ~ construct is correctly expanded in the validation process.
+        env_file = self.make_env_file()
+        # Split the full path of the env file, e.g. from a full "/tmp/env.file"
+        # path retrieve the base path "/tmp" and the file name "env.file".
+        # By doing that we can simulate that the user's home is "/tmp" and that
+        # the env file is "~/env.file".
+        base_path, filename = os.path.split(env_file)
+        path = '~/{}'.format(filename)
+        options = self.make_options(env_file=path, env_name='aws')
+        with mock.patch('os.environ', {'HOME': base_path}):
+            manage._validate_env(options, self.parser)
+        self.assertEqual(env_file, options.env_file)
+
+    def test_no_env_name(self):
+        # A parser error is invoked if the environment name is missing.
+        options = self.make_options(self.make_env_file())
+        manage._validate_env(options, self.parser)
+        self.assertTrue(self.parser.error.called)
+        message = self.parser.error.call_args[0][0]
+        self.assertIn('unable to find an environment name to use', message)
+
+    def test_error_parsing_env_file(self):
+        # A parser error is invoked if an error occurs parsing the env file.
+        env_file = self.make_env_file()
+        options = self.make_options(env_file, env_name='no-such')
+        manage._validate_env(options, self.parser)
+        expected = 'environment no-such not found in {}'.format(env_file)
+        self.parser.error.assert_called_once_with(expected)
+
+    def test_local_provider(self):
+        # The parser exits with an error if the provided environment name
+        # refers to a local provider type.
+        contents = yaml.safe_dump({
+            'environments': {
+                'lxc': {'admin-secret': 'Secret!', 'type': 'local'},
+            },
+        })
+        env_file = self.make_env_file(contents)
+        options = self.make_options(env_file, env_name='lxc')
+        manage._validate_env(options, self.parser)
+        expected = 'the local provider is not currently supported'
+        self.parser.error.assert_called_once_with(expected)
+
+
[e-mail]('quickstart.manage._validate_env', mock.Mock())
+class TestSetup(unittest.TestCase):
+
+    def patch_get_default_env_name(self, env_name=None):
+        """Patch the function used by setup() to retrieve the default env name.
+
+        This way the test does not rely on the user's Juju environment set up,
+        and it is also possible to simulate an arbitrary environment name.
+        """
+        mock_get_default_env_name = mock.Mock(return_value=env_name)
+        path = 'quickstart.manage.utils.get_default_env_name'
+        return mock.patch(path, mock_get_default_env_name)
+
+    def call_setup(self, args, env_name=None):
+        """Call the setup function simulating the given args and env name.
+
+        Also ensure the program exits without errors.
+        """
+        with mock.patch('sys.argv', ['juju-quickstart'] + args):
+            with mock.patch('sys.exit') as mock_exit:
+                with self.patch_get_default_env_name(env_name):
+                    manage.setup()
+        mock_exit.assert_called_once_with(0)
+
+    def test_help(self):
+        # The program help message is properly formatted.
+        with mock.patch('sys.stdout') as mock_stdout:
+            self.call_setup(['--help'])
+        stdout_write = mock_stdout.write
+        self.assertTrue(stdout_write.called)
+        # Retrieve the output from the mock call.
+        output = stdout_write.call_args[0][0]
+        self.assertIn('usage: juju-quickstart', output)
+        self.assertIn(quickstart.__doc__, output)
+        self.assertIn('--environment', output)
+        # Without a default environment, the -e option has no default.
+        self.assertIn('the name of the Juju environment to use\n', output)
+
+    def test_help_with_default_environment(self):
+        # The program help message is properly formatted when a default Juju
+        # environment is found.
+        with mock.patch('sys.stdout') as mock_stdout:
+            self.call_setup(['--help'], env_name='hp')
+        stdout_write = mock_stdout.write
+        self.assertTrue(stdout_write.called)
+        # Retrieve the output from the mock call.
+        output = stdout_write.call_args[0][0]
+        self.assertIn('the name of the Juju environment to use (hp)\n', output)
+
+    def test_description(self):
+        # The program description is properly printed out as required by juju.
+        with mock.patch('__builtin__.print') as mock_print:
+            self.call_setup(['--description'])
+        mock_print.assert_called_once_with(manage.description)
+
+    def test_version(self):
+        # The program version is properly printed to stderr.
+        with mock.patch('sys.stderr') as mock_stderr:
+            self.call_setup(['--version'])
+        expected = 'juju-quickstart {}\n'.format(quickstart.get_version())
+        mock_stderr.write.assert_called_once_with(expected)

=== added file 'quickstart/tests/test_utils.py'
--- quickstart/tests/test_utils.py	1970-01-01 00:00:00 +0000
+++ quickstart/tests/test_utils.py	2013-10-16 07:23:37 +0000
@@ -0,0 +1,178 @@
+# This file is part of the Juju GUI, which lets users view and manage Juju
+# environments within a graphical interface (https://launchpad.net/juju-gui).
+# 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/>.
+
+"""Tests for the Juju Quickstart utility functions and classes."""
+
+import unittest
+
+import mock
+import yaml
+
+from quickstart import utils
+from quickstart.tests import helpers
+
+
+class TestCall(unittest.TestCase):
+
+    def test_success(self):
+        # A zero exit code and the subprocess output are correctly returned.
+        retcode, output, error = utils.call('echo')
+        self.assertEqual(0, retcode)
+        self.assertEqual('\n', output)
+        self.assertEqual('', error)
+
+    def test_multiple_arguments(self):
+        # A zero exit code and the subprocess output are correctly returned
+        # when executing a command passing multiple arguments.
+        retcode, output, error = utils.call('echo', 'we are the borg!')
+        self.assertEqual(0, retcode)
+        self.assertEqual('we are the borg!\n', output)
+        self.assertEqual('', error)
+
+    def test_failure(self):
+        # An error code and the error are returned if the subprocess fails.
+        retcode, output, error = utils.call('ls', 'no-such-file')
+        self.assertNotEqual(0, retcode)
+        self.assertEqual('', output)
+        self.assertEqual(
+            'ls: cannot access no-such-file: No such file or directory\n',
+            error)
+
+    def test_invalid_command(self):
+        # An error code and the error are returned if the subprocess fails to
+        # find the provided command in the PATH.
+        retcode, output, error = utils.call('no-such-command')
+        self.assertEqual(127, retcode)
+        self.assertEqual('', output)
+        self.assertEqual(
+            'no-such-command: [Errno 2] No such file or directory',
+            error)
+
+
+class TestGetDefaultEnvName(unittest.TestCase):
+
+    def patch_call(self, retcode, output='', error=''):
+        """Patch the quickstart.utils.call function."""
+        mock_call = mock.Mock(return_value=(retcode, output, error))
+        return mock.patch('quickstart.utils.call', mock_call)
+
+    def test_environment_variable(self):
+        # The environment name is successfully returned if JUJU_ENV is set.
+        with mock.patch('os.environ', {'JUJU_ENV': 'ec2'}):
+            env_name = utils.get_default_env_name()
+        self.assertEqual('ec2', env_name)
+
+    def test_empty_environment_variable(self):
+        # The environment name is not found if JUJU_ENV is empty.
+        with self.patch_call(1):
+            with mock.patch('os.environ', {'JUJU_ENV': ' '}):
+                env_name = utils.get_default_env_name()
+        self.assertIsNone(env_name)
+
+    def test_no_environment_variable(self):
+        # The environment name is not found if JUJU_ENV is not defined.
+        with self.patch_call(1):
+            with mock.patch('os.environ', {}):
+                env_name = utils.get_default_env_name()
+        self.assertIsNone(env_name)
+
+    def test_juju_switch(self):
+        # The environment name is successfully returned if previously set using
+        # the "juju switch" command.
+        output = 'Current environment: "hp"\n'
+        with self.patch_call(0, output=output) as mock_call:
+            with mock.patch('os.environ', {}):
+                env_name = utils.get_default_env_name()
+        self.assertEqual('hp', env_name)
+        mock_call.assert_called_once_with('juju', 'switch')
+
+    def test_juju_switch_failure(self):
+        # The environment name is not found if "juju switch" returns an error.
+        with self.patch_call(1) as mock_call:
+            with mock.patch('os.environ', {}):
+                env_name = utils.get_default_env_name()
+        self.assertIsNone(env_name)
+        mock_call.assert_called_once_with('juju', 'switch')
+
+    def test_juju_switch_nonsense(self):
+        # The environment name is not found if "juju switch" goes crazy.
+        with self.patch_call(0, output='Exterminate!') as mock_call:
+            with mock.patch('os.environ', {}):
+                env_name = utils.get_default_env_name()
+        self.assertIsNone(env_name)
+        mock_call.assert_called_once_with('juju', 'switch')
+
+
+class TestParseEnvFile(
+        helpers.EnvFileTestsMixin, helpers.ValueErrorTestsMixin,
+        unittest.TestCase):
+
+    def test_no_file(self):
+        # A ValueError is raised if the environments file is not found.
+        expected = (
+            'unable to open environments file: '
+            "[Errno 2] No such file or directory: '/no/such/file.yaml'"
+        )
+        with self.assert_value_error(expected):
+            utils.parse_env_file('/no/such/file.yaml', 'ec2')
+
+    def test_invalid_yaml(self):
+        # A ValueError is raised if the environments file is not a valid YAML.
+        env_file = self.make_env_file(':')
+        with self.assertRaises(ValueError) as context_manager:
+            utils.parse_env_file(env_file, 'ec2')
+        expected = 'unable to parse environments file {}'.format(env_file)
+        self.assertIn(expected, str(context_manager.exception))
+
+    def test_invalid_yaml_contents(self):
+        # A ValueError is raised if the environments file is not well formed.
+        env_file = self.make_env_file('a-string')
+        expected = 'invalid YAML contents in {}: a-string'.format(env_file)
+        with self.assert_value_error(expected):
+            utils.parse_env_file(env_file, 'ec2')
+
+    def test_no_env(self):
+        # A ValueError is raised if the environment is not found in the YAML.
+        contents = yaml.safe_dump({'environments': {'local': {}}})
+        env_file = self.make_env_file(contents)
+        expected = 'environment ec2 not found in {}'.format(env_file)
+        with self.assert_value_error(expected):
+            utils.parse_env_file(env_file, 'ec2')
+
+    def test_no_provider_type(self):
+        # A ValueError is raised if the provider type is not included in the
+        # environment info.
+        contents = yaml.safe_dump({'environments': {'aws': {}}})
+        env_file = self.make_env_file(contents)
+        expected = 'aws provider type not found in {}'.format(env_file)
+        with self.assert_value_error(expected):
+            utils.parse_env_file(env_file, 'aws')
+
+    def test_no_admin_secret(self):
+        # A ValueError is raised if the admin secret is not included in the
+        # environment info.
+        contents = yaml.safe_dump({'environments': {'aws': {'type': 'ec2'}}})
+        env_file = self.make_env_file(contents)
+        expected = 'aws admin secret not found in {}'.format(env_file)
+        with self.assert_value_error(expected):
+            utils.parse_env_file(env_file, 'aws')
+
+    def test_success(self):
+        # The environment provider type and admin secret are returned.
+        env_file = self.make_env_file()
+        env_type, admin_secret = utils.parse_env_file(env_file, 'aws')
+        self.assertEqual('ec2', env_type)
+        self.assertEqual('Secret!', admin_secret)

=== added file 'quickstart/utils.py'
--- quickstart/utils.py	1970-01-01 00:00:00 +0000
+++ quickstart/utils.py	2013-10-16 07:23:37 +0000
@@ -0,0 +1,110 @@
+# This file is part of the Juju GUI, which lets users view and manage Juju
+# environments within a graphical interface (https://launchpad.net/juju-gui).
+# 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/>.
+
+"""Juju Quickstart utility functions and classes."""
+
+import re
+import os
+import subprocess
+
+import yaml
+
+# Compile the regular expression used to parse the "juju switch" output.
+_juju_switch_expression = re.compile(r'Current environment: "([\w-]+)"\n')
+
+
+def call(*args):
+    """Call a subprocess passing the given arguments.
+
+    Take the subcommand and its parameters as args.
+
+    Return a tuple containing the subprocess return code, output and error.
+    """
+    pipe = subprocess.PIPE
+    try:
+        process = subprocess.Popen(args, stdout=pipe, stderr=pipe)
+    except OSError as err:
+        # A return code 127 is returned by the shell when the command is not
+        # found in the PATH.
+        return 127, '', '{}: {}'.format(args[0], err)
+    output, error = process.communicate()
+    return process.poll(), output, error
+
+
+def get_default_env_name():
+    """Return the current Juju environment name.
+
+    The environment name can be set either by setting the JUJU_ENV environment
+    variable or by using "juju switch". The former overrides the latter.
+
+    Return None if a default environment is not found.
+    """
+    env_name = os.getenv('JUJU_ENV', '').strip()
+    if env_name:
+        return env_name
+    retcode, output, _ = call('juju', 'switch')
+    if retcode:
+        return None
+    match = _juju_switch_expression.match(output)
+    if match is not None:
+        return match.groups()[0]
+
+
+def parse_env_file(env_file, env_name):
+    """Parse the provided Juju environment.yaml file.
+
+    Return a tuple containing the provider type and the admin secret associated
+    with the given environment name.
+
+    Raise a ValueError if:
+      - the environment file is not found;
+      - the environment file contents are not parsable by YAML;
+      - the YAML contents are not properly structured;
+      - the environment named envname is not found;
+      - the environment does not include the "type" field;
+      - the environment does not include the "admin_secret" field.
+    """
+    # Load the Juju environments file.
+    try:
+        environments_file = open(env_file)
+    except IOError as err:
+        msg = 'unable to open environments file: {}'.format(err)
+        raise ValueError(msg)
+    # Parse the Juju environments file.
+    try:
+        environments = yaml.safe_load(environments_file)
+    except Exception as err:
+        msg = 'unable to parse environments file {}: {}'.format(env_file, err)
+        raise ValueError(msg)
+    # Retrieve the information about the current environment.
+    try:
+        environment = environments.get('environments', {}).get(env_name)
+    except AttributeError as err:
+        msg = 'invalid YAML contents in {}: {}'.format(env_file, environments)
+        raise ValueError(msg)
+    if environment is None:
+        msg = 'environment {} not found in {}'.format(env_name, env_file)
+        raise ValueError(msg)
+    # Retrieve the provider type and the admin secret.
+    env_type = environment.get('type')
+    if env_type is None:
+        msg = '{} provider type not found in {}'.format(env_name, env_file)
+        raise ValueError(msg)
+    admin_secret = environment.get('admin-secret')
+    if admin_secret is None:
+        msg = '{} admin secret not found in {}'.format(env_name, env_file)
+        raise ValueError(msg)
+    return env_type, admin_secret