Merge lp:~frankban/juju-quickstart/quickstart-deploy into lp:juju-quickstart

[Francesco Banconi]

Deploy and expose the GUI.

Use a customized jujuclient.Environment
object in order to be able deploy to a
specific machine and to log traffic.

Tests: make check
QA: make run -> no errors and a resulting
juju environment with the GUI exposed
and deploying in the bootstrap node.

https://codereview.appspot.com/14764044/

[Francesco Banconi (frankban)]

Reviewers: mp+191679_code.launchpad.net,

Message:
Please take a look.

Description:
Deploy and expose the GUI.

Use a customized jujuclient.Environment
object in order to be able deploy to a
specific machine and to log traffic.

Tests: make check
QA: make run -> no errors and a resulting
juju environment with the GUI exposed
and deploying in the bootstrap node.

https://code.launchpad.net/~frankban/juju-quickstart/quickstart-deploy/+merge/191679

(do not edit description out of merge proposal)

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

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

[Gary Poster (gary)]

LGTM, with trivial. Thank you!

https://codereview.appspot.com/14764044/diff/1/quickstart/app.py
File quickstart/app.py (right):

https://codereview.appspot.com/14764044/diff/1/quickstart/app.py#newcode115
quickstart/app.py:115: # Retrieve the URL of the last charm revision
from
Nice way to be incremental.

https://codereview.appspot.com/14764044/diff/1/quickstart/juju.py
File quickstart/juju.py (right):

https://codereview.appspot.com/14764044/diff/1/quickstart/juju.py#newcode79
quickstart/juju.py:79: with jujuclient.Watcher(self.conn) as watcher:
I'm guessing the watcher stops itself and closes when the context
manager hook is called?

https://codereview.appspot.com/14764044/diff/1/quickstart/juju.py#newcode80
quickstart/juju.py:80: watcher.start()
If the previous comment is correct, it might be nice to add a comment to
that regard here. On first glance it seems odd that you have to call
start but you don't have to call stop.

https://codereview.appspot.com/14764044/

[Madison Scott-Clary (makyo)]

LGTM, thank you!

https://codereview.appspot.com/14764044/

[Francesco Banconi (frankban)]

*** Submitted:

Deploy and expose the GUI.

Use a customized jujuclient.Environment
object in order to be able deploy to a
specific machine and to log traffic.

Tests: make check
QA: make run -> no errors and a resulting
juju environment with the GUI exposed
and deploying in the bootstrap node.

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

https://codereview.appspot.com/14764044/diff/1/quickstart/juju.py
File quickstart/juju.py (right):

https://codereview.appspot.com/14764044/diff/1/quickstart/juju.py#newcode79
quickstart/juju.py:79: with jujuclient.Watcher(self.conn) as watcher:
On 2013/10/17 17:20:13, gary.poster wrote:
> I'm guessing the watcher stops itself and closes when the context
manager hook
> is called?

Yes indeed, added a comment.

https://codereview.appspot.com/14764044/diff/1/quickstart/juju.py#newcode80
quickstart/juju.py:80: watcher.start()
On 2013/10/17 17:20:13, gary.poster wrote:
> If the previous comment is correct, it might be nice to add a comment
to that
> regard here. On first glance it seems odd that you have to call start
but you
> don't have to call stop.

Well, removed the start call. The watcher is not started by the context
manager's __start__, but its "next" method does the following:
     if self.watcher_id is None:
         self.start()
So I hope removing the start() call makes the code less surprising.
Thanks for this suggestion.

https://codereview.appspot.com/14764044/

[Francesco Banconi (frankban)]

Thank you both for the reviews!

https://codereview.appspot.com/14764044/

=== modified file '.lbox'
--- .lbox	2013-10-14 11:43:06 +0000
+++ .lbox	2013-10-17 16:57:02 +0000
@@ -1,1 +1,1 @@
-propose -cr -for lp:juju-gui/juju-quickstart
+propose -cr -for lp:juju-quickstart

=== modified file 'Makefile'
--- Makefile	2013-10-15 18:25:57 +0000
+++ Makefile	2013-10-17 16:57:02 +0000
@@ -63,7 +63,7 @@
 	@$(VENV)/bin/flake8 --show-source --exclude=$(VENV) ./quickstart
 
 run: setup
-	$(VENV)/bin/python ./juju-quickstart
+	$(VENV)/bin/python ./juju-quickstart --debug
 
 source:
 	$(PYTHON) setup.py sdist

=== modified file 'quickstart/app.py'
--- quickstart/app.py	2013-10-16 15:59:23 +0000
+++ quickstart/app.py	2013-10-17 16:57:02 +0000
@@ -18,7 +18,12 @@
 
 import json
 
-from quickstart import utils
+import jujuclient
+
+from quickstart import (
+    juju,
+    utils,
+)
 
 
 class ProgramExit(Exception):
@@ -66,6 +71,7 @@
 
     Use the Juju CLI in a subprocess in order to retrieve the API addresses.
     Return the complete URL, e.g. "wss://api.example.com:17070".
+    Raise a ProgramExit if any error occurs.
     """
     retcode, output, error = utils.call(
         'juju', 'api-endpoints', '-e', env_name, '--format', 'json')
@@ -75,3 +81,42 @@
     # from the JSON output.
     api_address = json.loads(output)[0]
     return 'wss://{}'.format(api_address)
+
+
+def connect(api_url, admin_secret):
+    """Connect to the Juju API server and log in using the given credentials.
+
+    Return a connected and authenticated Juju Environment instance.
+    Raise a ProgramExit if any error occurs while establishing the WebSocket
+    connection or if the API returns an error response.
+    """
+    try:
+        env = juju.connect(api_url)
+    except Exception as err:
+        msg = 'unable to connect to the Juju API server on {}: {}'
+        raise ProgramExit(msg.format(api_url, err))
+    try:
+        env.login(admin_secret)
+    except jujuclient.EnvError as err:
+        msg = 'unable to log in to the Juju API server on {}: {}'
+        raise ProgramExit(msg.format(api_url, err.message))
+    return env
+
+
+def deploy_gui(env, service_name):
+    """Deploy and expose the given service, reusing the bootstrap node.
+
+    Receive an authenticated Juju Environment instance, the name of the service
+    and the corresponding charm URL.
+
+    Raise a ProgramExit if the API server returns an error response.
+    """
+    # XXX 2013-10-17 frankban:
+        # Retrieve the URL of the last charm revision from
+        # manage.jujucharms.com.
+    charm_url = 'cs:precise/juju-gui-77'
+    try:
+        env.deploy(service_name, charm_url, to=0)
+        env.expose(service_name)
+    except jujuclient.EnvError as err:
+        raise ProgramExit('bad API server response: {}'.format(err.message))

=== added file 'quickstart/juju.py'
--- quickstart/juju.py	1970-01-01 00:00:00 +0000
+++ quickstart/juju.py	2013-10-17 16:57:02 +0000
@@ -0,0 +1,108 @@
+# 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 API client."""
+
+import logging
+
+import jujuclient
+import websocket
+
+from quickstart import utils
+
+
+def connect(api_url):
+    """Return an Environment instance connected to the given API URL."""
+    connection = WebSocketConnection()
+    # See the websocket.create_connection function.
+    connection.settimeout(websocket.default_timeout)
+    connection.connect(api_url, origin=api_url)
+    return Environment(api_url, conn=connection)
+
+
+class Environment(jujuclient.Environment):
+    """A Juju bootstrapped environment.
+
+    Instances of this class can be used to run API operations on a Juju
+    environment. This is a subclass of the jujuclient.Environment object.
+    """
+
+    def deploy(
+            self, service_name, charm_url, num_units=1, config=None,
+            constraints=None, to=None):
+        """Deploy a charm. Local charms are not supported.
+
+        This method is overridden to add the ability to deploy to a specific
+        machine (i.e. support the ToMachineSpec API parameter).
+        """
+        service_config = {}
+        if config is not None:
+            service_config = self._prepare_strparams(config)
+        service_constraints = {}
+        if constraints is not None:
+            service_constraints = self._prepare_constraints(constraints)
+        params = {
+            'ServiceName': service_name,
+            'CharmURL': charm_url,
+            'NumUnits': num_units,
+            'Config': service_config,
+            'Constraints': service_constraints,
+        }
+        if to is not None:
+            params['ToMachineSpec'] = str(to)
+        request = {
+            'Type': 'Client',
+            'Request': 'ServiceDeploy',
+            'Params': params,
+        }
+        return self._rpc(request)
+
+    def watch_changes(self, processor):
+        """Start watching the changes occurring in the Juju environment.
+
+        For each changeset, call the given processor callable, and yield
+        the values returned by the processor.
+        """
+        with jujuclient.Watcher(self.conn) as watcher:
+            watcher.start()
+            for changeset in watcher:
+                changes = processor(changeset)
+                if changes:
+                    yield changes
+
+
+class WebSocketConnection(websocket.WebSocket):
+    """A WebSocket client connection.
+
+    This is a subclass of the websocket.WebSocket object.
+    """
+
+    def send(self, message):
+        """Send the given WebSocket message.
+
+        Overridden to add logging.
+        """
+        logging.debug('API message: --> {}'.format(utils.utf8(message)))
+        return super(WebSocketConnection, self).send(message)
+
+    def recv(self):
+        """Receive a message from the WebSocket server.
+
+        Overridden to add logging.
+        """
+        message = super(WebSocketConnection, self).recv()
+        logging.debug('API message: <-- {}'.format(utils.utf8(message)))
+        return message

=== modified file 'quickstart/manage.py'
--- quickstart/manage.py	2013-10-16 15:23:08 +0000
+++ quickstart/manage.py	2013-10-17 16:57:02 +0000
@@ -140,3 +140,6 @@
     print('retrieving the Juju API address')
     api_url = app.get_api_url(options.env_name)
     print('connecting to {}'.format(api_url))
+    env = app.connect(api_url, options.admin_secret)
+    print('deploying Juju GUI')
+    app.deploy_gui(env, 'juju-gui')

=== modified file 'quickstart/tests/helpers.py'
--- quickstart/tests/helpers.py	2013-10-16 12:12:31 +0000
+++ quickstart/tests/helpers.py	2013-10-17 16:57:02 +0000
@@ -24,20 +24,6 @@
 import yaml
 
 
-class CallTestsMixin(object):
-    """Easily use the quickstart.utils.call function."""
-
-    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 patch_multiple_calls(self, side_effect):
-        """Patch multiple subsequent quickstart.utils.call calls."""
-        mock_call = mock.Mock(side_effect=side_effect)
-        return mock.patch('quickstart.utils.call', mock_call)
-
-
 @contextmanager
 def assert_logs(messages, level='debug'):
     """Ensure the given messages are logged using the given log level.
@@ -51,6 +37,20 @@
     mock_log.assert_has_calls(expected_calls)
 
 
+class CallTestsMixin(object):
+    """Easily use the quickstart.utils.call function."""
+
+    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 patch_multiple_calls(self, side_effect):
+        """Patch multiple subsequent quickstart.utils.call calls."""
+        mock_call = mock.Mock(side_effect=side_effect)
+        return mock.patch('quickstart.utils.call', mock_call)
+
+
 class EnvFileTestsMixin(object):
     """Shared methods for testing a Juju environments file."""
 

=== modified file 'quickstart/tests/test_app.py'
--- quickstart/tests/test_app.py	2013-10-16 15:59:23 +0000
+++ quickstart/tests/test_app.py	2013-10-17 16:57:02 +0000
@@ -20,6 +20,7 @@
 import json
 import unittest
 
+import jujuclient
 import mock
 import yaml
 
@@ -49,6 +50,10 @@
         expected = 'juju-quickstart: error: {}'.format(error)
         self.assertEqual(expected, str(context_manager.exception))
 
+    def make_env_error(self, message):
+        """Create and return a jujuclient.EnvError with the given message."""
+        return jujuclient.EnvError({'Error': message})
+
 
 class TestBootstrap(
         helpers.CallTestsMixin, ProgramExitTestsMixin, unittest.TestCase):
@@ -181,3 +186,82 @@
                 app.get_api_url(self.env_name)
         mock_call.assert_called_once_with(
             'juju', 'api-endpoints', '-e', self.env_name, '--format', 'json')
+
+
+class TestConnect(ProgramExitTestsMixin, unittest.TestCase):
+
+    admin_secret = 'Secret!'
+    api_url = 'wss://api.example.com:17070'
+
+    def test_connection_established(self):
+        # The connection is done and the Environment instance is returned.
+        with mock.patch('quickstart.juju.connect') as mock_connect:
+            env = app.connect(self.api_url, self.admin_secret)
+        mock_connect.assert_called_once_with(self.api_url)
+        mock_env = mock_connect()
+        mock_env.login.assert_called_once_with(self.admin_secret)
+        self.assertEqual(mock_env, env)
+
+    def test_connection_error(self):
+        # A ProgramExit is raised if an error occurs in the connection.
+        mock_connect = mock.Mock(side_effect=ValueError('bad wolf'))
+        expected = 'unable to connect to the Juju API server on {}: bad wolf'
+        with mock.patch('quickstart.juju.connect', mock_connect):
+            with self.assert_program_exit(expected.format(self.api_url)):
+                app.connect(self.api_url, self.admin_secret)
+        mock_connect.assert_called_once_with(self.api_url)
+
+    def test_authentication_error(self):
+        # A ProgramExit is raised if an error occurs in the authentication.
+        expected = 'unable to log in to the Juju API server on {}: bad wolf'
+        with mock.patch('quickstart.juju.connect') as mock_connect:
+            mock_login = mock_connect().login
+            mock_login.side_effect = self.make_env_error('bad wolf')
+            with self.assert_program_exit(expected.format(self.api_url)):
+                app.connect(self.api_url, self.admin_secret)
+        mock_connect.assert_called_with(self.api_url)
+        mock_login.assert_called_once_with(self.admin_secret)
+
+    def test_other_errors(self):
+        # Any other errors occurred during the log in process are not trapped.
+        error = ValueError('explode!')
+        with mock.patch('quickstart.juju.connect') as mock_connect:
+            mock_login = mock_connect().login
+            mock_login.side_effect = error
+            with self.assertRaises(ValueError) as context_manager:
+                app.connect(self.api_url, self.admin_secret)
+        self.assertIs(error, context_manager.exception)
+
+
+class TestDeployGui(ProgramExitTestsMixin, unittest.TestCase):
+
+    def test_deployment(self):
+        # The function correctly deploys and exposes the service.
+        env = mock.Mock()
+        app.deploy_gui(env, 'my-gui')
+        env.assert_has_calls([
+            mock.call.deploy('my-gui', 'cs:precise/juju-gui-77', to=0),
+            mock.call.expose('my-gui')
+        ])
+
+    def test_api_error(self):
+        # A ProgramExit is raised if an error occurs in one of the API calls.
+        env = mock.Mock()
+        env.deploy.side_effect = self.make_env_error('service already exists')
+        expected = 'bad API server response: service already exists'
+        with self.assert_program_exit(expected):
+            app.deploy_gui(env, 'another-gui')
+        env.deploy.assert_called_once_with(
+            'another-gui', 'cs:precise/juju-gui-77', to=0)
+
+    def test_other_errors(self):
+        # Any other errors occurred during the process are not trapped.
+        error = ValueError('explode!')
+        env = mock.Mock()
+        env.expose.side_effect = error
+        with self.assertRaises(ValueError) as context_manager:
+            app.deploy_gui(env, 'juju-gui')
+        env.deploy.assert_called_once_with(
+            'juju-gui', 'cs:precise/juju-gui-77', to=0)
+        env.expose.assert_called_once_with('juju-gui')
+        self.assertIs(error, context_manager.exception)

=== added file 'quickstart/tests/test_juju.py'
--- quickstart/tests/test_juju.py	1970-01-01 00:00:00 +0000
+++ quickstart/tests/test_juju.py	2013-10-17 16:57:02 +0000
@@ -0,0 +1,210 @@
+# 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 API client."""
+
+import unittest
+
+import mock
+import websocket
+
+from quickstart import juju
+from quickstart.tests import helpers
+
+
+class TestConnect(unittest.TestCase):
+
+    api_url = 'wss://api.example.com:17070'
+
+    @mock.patch('quickstart.juju.WebSocketConnection')
+    def test_environment_connection(self, mock_conn):
+        # A connected Environment instance is correctly returned.
+        env = juju.connect(self.api_url)
+        mock_conn.assert_called_once_with()
+        conn = mock_conn()
+        conn.assert_has_calls([
+            mock.call.settimeout(websocket.default_timeout),
+            mock.call.connect(self.api_url, origin=self.api_url)
+        ])
+        self.assertIsInstance(env, juju.Environment)
+        self.assertEqual(self.api_url, env.endpoint)
+        self.assertEqual(conn, env.conn)
+
+
+class TestEnvironment(unittest.TestCase):
+
+    api_url = 'wss://api.example.com:17070'
+    charm_url = 'cs:precise/juju-gui-77'
+    service_name = 'juju-gui'
+
+    def setUp(self):
+        # Set up an Environment instance.
+        api_url = self.api_url
+        with mock.patch('websocket.create_connection') as mock_connect:
+            self.env = juju.Environment(api_url)
+        mock_connect.assert_called_once_with(api_url, origin=api_url)
+        # Keep track of watcher changes in the changesets list.
+        self.changesets = []
+
+    def make_deploy_request(self, **kwargs):
+        """Create and return a deploy request.
+
+        Use kwargs to add or override request parameters.
+        """
+        params = {
+            'ServiceName': self.service_name,
+            'CharmURL': self.charm_url,
+            'NumUnits': 1,
+            'Config': {},
+            'Constraints': {},
+        }
+        params.update(kwargs)
+        return {
+            'Type': 'Client',
+            'Request': 'ServiceDeploy',
+            'Params': params,
+        }
+
+    def processor(self, changeset):
+        self.changesets.append(changeset)
+        return changeset
+
+    @mock.patch('quickstart.juju.Environment._rpc')
+    def test_deploy(self, mock_rpc):
+        # The deploy API call is properly generated.
+        self.env.deploy(self.service_name, self.charm_url)
+        mock_rpc.assert_called_once_with(self.make_deploy_request())
+
+    @mock.patch('quickstart.juju.Environment._rpc')
+    def test_deploy_config(self, mock_rpc):
+        # The deploy API call is properly generated when passing settings.
+        self.env.deploy(
+            self.service_name, self.charm_url,
+            config={'key1': 'value1', 'key2': 42})
+        expected = self.make_deploy_request(
+            Config={'key1': 'value1', 'key2': '42'})
+        mock_rpc.assert_called_once_with(expected)
+
+    @mock.patch('quickstart.juju.Environment._rpc')
+    def test_deploy_constraints(self, mock_rpc):
+        # The deploy API call is properly generated when passing constraints.
+        constraints = {'cpu-cores': 8, 'mem': 16}
+        self.env.deploy(
+            self.service_name, self.charm_url, constraints=constraints)
+        expected = self.make_deploy_request(Constraints=constraints)
+        mock_rpc.assert_called_once_with(expected)
+
+    @mock.patch('quickstart.juju.Environment._rpc')
+    def test_deploy_to(self, mock_rpc):
+        # The deploy API call is properly generated when passing a machine
+        # specification.
+        self.env.deploy(self.service_name, self.charm_url, to=0)
+        expected = self.make_deploy_request(ToMachineSpec='0')
+        mock_rpc.assert_called_once_with(expected)
+
+    @mock.patch('quickstart.juju.jujuclient.Watcher._rpc')
+    def test_watch_changes(self, mock_rpc):
+        # It is possible to watch for changes using a processor callable.
+        changeset1 = ['change1', 'change2']
+        changeset2 = ['change3']
+        mock_rpc.side_effect = [
+            # Define the response to the watcher's start call.
+            {'Response': {}, 'AllWatcherId': 42},
+            # Define two responses to the two subsequent next calls.
+            {'Response': {}, 'Deltas': changeset1},
+            {'Response': {}, 'Deltas': changeset2},
+            # Define the response to the watcher's stop call.
+            {'Response': {}},
+        ]
+        watcher = self.env.watch_changes(self.processor)
+        # The first set of changes is correctly returned.
+        changeset = watcher.next()
+        self.assertEqual(changeset1, changeset)
+        # The second set of changes is correctly returned.
+        changeset = watcher.next()
+        self.assertEqual(changeset2, changeset)
+        # All the changes have been processed.
+        self.assertEqual([changeset1, changeset2], self.changesets)
+        # Ensure the API has been used properly.
+        mock_rpc.assert_has_calls([
+            mock.call({'Type': 'Client', 'Request': 'WatchAll', 'Params': {}}),
+            mock.call({'Type': 'AllWatcher', 'Request': 'Next', 'Id': 42}),
+            mock.call({'Type': 'AllWatcher', 'Request': 'Next', 'Id': 42}),
+        ])
+
+    @mock.patch('quickstart.juju.jujuclient.Watcher._rpc')
+    def test_watch_closed(self, mock_rpc):
+        # A stop API call on the AllWatcher is performed when the watcher is
+        # garbage collected.
+        mock_rpc.side_effect = [
+            # Define the response to the watcher's start call.
+            {'Response': {}, 'AllWatcherId': 42},
+            # Define a response to a next call.
+            {'Response': {}, 'Deltas': ['change1', 'change2']},
+            # Define the response to the watcher's stop call.
+            {'Response': {}},
+        ]
+        watcher = self.env.watch_changes(self.processor)
+        # The first set of changes is correctly returned.
+        watcher.next()
+        del watcher
+        # Ensure the API has been used properly.
+        mock_rpc.assert_has_calls([
+            mock.call({'Type': 'Client', 'Request': 'WatchAll', 'Params': {}}),
+            mock.call({'Type': 'AllWatcher', 'Request': 'Next', 'Id': 42}),
+            mock.call({'Type': 'AllWatcher', 'Request': 'Stop', 'Id': 42}),
+        ])
+
+
+class TestWebSocketConnection(unittest.TestCase):
+
+    snowman = u'Here is a snowman\u00a1: \u2603'
+
+    def setUp(self):
+        with mock.patch('socket.socket') as mock_socket:
+            self.conn = juju.WebSocketConnection()
+        # Patch the socket.send() function used by the send method.
+        self.mock_send = mock_socket().send
+        # The recv method calls the recv_data one.
+        self.conn.recv_data = self.mock_recv = mock.Mock()
+
+    def test_send(self):
+        # Outgoing messages are properly logged.
+        with helpers.assert_logs(['API message: --> my message'], 'debug'):
+            self.conn.send('my message')
+        self.assertTrue(self.mock_send.called)
+
+    def test_send_unicode(self):
+        # Outgoing unicode messages are properly logged.
+        expected = 'API message: --> {}'.format(self.snowman.encode('utf-8'))
+        with helpers.assert_logs([expected], 'debug'):
+            self.conn.send(self.snowman)
+        self.assertTrue(self.mock_send.called)
+
+    def test_recv(self):
+        # Incoming messages are properly logged.
+        self.mock_recv.return_value = (42, 'my message')
+        with helpers.assert_logs(['API message: <-- my message'], 'debug'):
+            self.conn.recv()
+        self.mock_recv.assert_called_once_with()
+
+    def test_recv_unicode(self):
+        # Incoming unicode messages are properly logged.
+        self.mock_recv.return_value = (42, self.snowman)
+        expected = 'API message: <-- {}'.format(self.snowman.encode('utf-8'))
+        with helpers.assert_logs([expected], 'debug'):
+            self.conn.recv()
+        self.mock_recv.assert_called_once_with()

=== modified file 'quickstart/tests/test_utils.py'
--- quickstart/tests/test_utils.py	2013-10-16 12:12:31 +0000
+++ quickstart/tests/test_utils.py	2013-10-17 16:57:02 +0000
@@ -216,3 +216,23 @@
         })
         agent_state = utils.parse_status_output(output)
         self.assertEqual('started', agent_state)
+
+
+class TestUtf8(unittest.TestCase):
+
+    def test_unicode(self):
+        # A unicode value is correctly converted.
+        value = utils.utf8(u'foo')
+        self.assertIsInstance(value, str)
+        self.assertEqual('foo', value)
+
+    def test_bytes(self):
+        # A bytes value is left untouched.
+        original = 'foo'
+        value = utils.utf8(original)
+        self.assertIsInstance(value, str)
+        self.assertIs(original, value)
+
+    def test_none(self):
+        # The None value is returned as is.
+        self.assertIsNone(utils.utf8(None))

=== modified file 'quickstart/utils.py'
--- quickstart/utils.py	2013-10-16 12:12:31 +0000
+++ quickstart/utils.py	2013-10-17 16:57:02 +0000
@@ -143,3 +143,13 @@
     if state is None:
         raise ValueError('agent state not found in {}'.format(status))
     return state
+
+
+def utf8(value):
+    """Return the utf8 encoded version of the given value.
+
+    The given value is returned as is if already encoded or not a string.
+    """
+    if isinstance(value, unicode):
+        return value.encode('utf-8')
+    return value