event = SilentEvent(self._single_threaded_method, **args)
event.start()
thread_list.append(event)
- thread_list = self._watch_thread_limit(thread_list)
\ No newline at end of file
+ thread_list = self._watch_thread_limit(thread_list)
+
+Going agile
+-----------
+
+The kamaki.clients package contains a set of fine-grained unit-tests for all its packages.
+
+.. note:: unit tests require the optional python-mock package, version 1.X or better
+
+Using the tests
+^^^^^^^^^^^^^^^
+
+To run the tests, the kamaki source code has to be downloaded.
+
+.. code-block:: console
+
+ $ git clone https://code.grnet.gr/git/kamaki
+ $ cd kamaki/kamaki/clients
+
+In each package under kamaki.clients, there is a test module (test.py) where the tests are implemented. To run all tests, run the test.py file from kamaki.clients
+
+.. code-block:: console
+
+ $ python test.py
+
+To test a specific class, add the class name as an argument. E.g. for the Client class:
+
+.. code-block:: console
+
+ $ python test.py Client
+
+To test a specific method in a class, apply an extra argument, e.g. for the request method in the Client class:
+
+.. code-block:: console
+
+ $ python test.py Client request
+
+Each package contains a test module (test.py) which is also runnable from the command line. E.g. the pithos package contains a Pithos test which contains, among others, the download sub-test:
+
+.. code-block:: console
+
+ $ cd pithos
+
+ # Run all kamaki.clients.pithos tests
+ $ python test.py
+
+ # Run all kamaki.clients.pithos.PithoClient tests
+ $ python test.py Pithos
+
+ # Test kamaki.clients.pithos.PithosClient.download
+ $ python test.py Pithos download
+
+Mechanism
+^^^^^^^^^
+
+Each folder / package contains a test.py file, that represents the test module of this package. All test modules contain a set of classes that extent the TestCase class. They also contain a main method to run the tests.
+
+All classes in the tested package are tested by similarly-named classes in the test module. Methods that do no belong to a class are tested by testing classes named after the module tested methods belong to.
+
+For example, the kamaki.clients.pithos.PithosClient class is tested by the kamaki.clients.pithos.test.Pithos class, which the method in the kamaki.clients.utils module are tested by the kamaki.clients.utils.test.Utils testing class.
+
+
+Adding unit tests
+^^^^^^^^^^^^^^^^^
+After modifying or extending kamaki.clients method, classes, modules or packages, it is a good practice to also modify or extend the corresponding unit tests. What's more, it is recommended to modify or implement the tests that test the new behavior, before implementing the behavior itself.
+
+Modifying an existing method
+""""""""""""""""""""""""""""
+
+In case of an existing method modification, the programmer has to modify the corresponding test as well. By convention, the test method is located in the test module under the same package, in a TestCase subclass that is named with a name similar to the package or class that contains the tested method.
+
+Example 1: to modify the kamaki.clients.utils.filter_in method, the programmer has to also adjust the kamaki.clients.utils.test.Utils.test_filter_in method.
+
+Example 2: to modify the kamaki.clients.pithos.PithosRestClient.object_get, the programmer has to also adjust the kamaki.clients.pithos.test.PithosRest.test_object_get method.
+
+Adding a new method
+"""""""""""""""""""
+
+Programmers who want to implement a new method in an existing class, are encouraged to implement the corresponding unit test first. In order to do that, they should first find the testing class that is mapped to the class they need to extend.
+
+Example 1: To add a **list_special** method to kamaki.clients.astakos.AstakosClient, extend the kamaki.clients.astakos.test.Astakos test class, as shown bellow:
+
+.. code-block:: python
+
+ class Astakos(TestCase):
+ ...
+ def test_list_special(self):
+ """Test the list_special method"""
+ ...
+
+Example 2: To add a **get_random_int** method in kamaki.clients.utils module, extend the kamaki.clients.utils.test.Utils test class, as shown bellow:
+
+.. code-block:: python
+
+ class Utils(TestCase):
+ ...
+ def test_get_random_int(self):
+ """Test the get_random_int method"""
+ ...
+
+Implementing a new class or module
+""""""""""""""""""""""""""""""""""
+
+Each class or module needs a seperate test sub-module. By convention, each class or module under the kamaki.clients should be located in a separate directory.
+
+Example 1: To add a NewService class, that extents the kamaki.clients.Client interface:
+
+* create a new_service package and implement the unit tests in the kamaki.clients.new_service.test module:
+
+.. code-block:: console
+
+ $ mkdir new_service && touch new_service/test.py
+
+* create the file that will hold the package code and implement the module there:
+
+.. code-block:: console
+
+ $ touch new_service/__init__.py
+
+* Create the test class and methods in kamaki.clients.new_service.test
+
+.. code-block:: python
+
+ from unittest import TestCase
+
+ class NewServiceTest(TestCase):
+
+ def test_method1(self):
+ ...
+
+* Create the NewService and its actual functionality in kamaki.clients.new_service
+
+.. code-block:: python
+
+ from kamaki.clients import Client
+
+ class NewService(Client):
+
+ def method1(self, ...):
+ ...
+
+* Expose the new tests to top test module, by importing the test class to kamaki.clients.test
+
+..code-block:: python
+
+ # kamaki.clients.test module
+ ...
+ from kamaki.clients.new_service.test import NewService
+
+.. note:: If the new class or module is part of an existing sub-package, it is best to append its testing class in the existing test.py file of the sub-package it belongs to. For example, the kamaki.clients.pithos.PithosClient and kamaki.clients.pithos.rest_api.PithosRestClient classes are tested by two different classes (Pithos and PithosRest) in the same module (kamaki.clients.pithos.test).
+
$ sudo apt-get install kamaki
-Install ansicolors and/or progress (Optional but recommended)
-"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+Install ansicolors (optional but recommended)
+"""""""""""""""""""""""""""""""""""""""""""""
.. code-block:: console
$ sudo apt-get install python-ansicolors
- $ sudo apt-get install python-progress
+
+Install mock (for developers only)
+""""""""""""""""""""""""""""""""""
+
+.. code-block:: console
+
+ $ sudo apt-get install python-mock
+
+.. warning:: kamaki.clients unit-tests need python-mock 1.X or better. e.g.::
+
+ $ sudo apt-get install python-mock=1.0.1
.. _installing-from-pypi-ref:
$ pip install kamaki
-Install ansicolors / progress
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Packages **ansicolors** and **progress** are not required for running kamaki, but
-they are recommended as a user experience improvement. In specific, ansicolors
-adds colors to kamaki responses and progress adds progressbars to the commands
-that can make use of it (*/store download*, */store upload*, */server wait* etc.)
-
-Debian and Ubuntu
-"""""""""""""""""
+Install ansicolors
+""""""""""""""""""
-Follow the `Debian <#debian>`_ or `Ubuntu <#ubuntu>`_ installation procedure described earlier
-and then type:
+The **ansicolors** package is not required for running kamaki, but it is
+recommended as a user experience improvement. In specific, ansicolors
+adds colors to kamaki responses.
.. code-block:: console
- #For ansicolors
- $ sudo apt-get install python-ansicolors
-
- # For progress
- $ sudo apt-get install python-progress
+ $ pip install ansicolors
-From source
-"""""""""""
+Install mock
+""""""""""""
-If setuptools is not installed, `install them <http://pypi.python.org/pypi/setuptools>`_ and then type:
+The **mock** package is needed for running the prepared unit-tests in the kamaki.clients
+package. This feature is useful when extendnig / debugging kamaki functionality and is
+aimed to kamaki developers and contributors. Therefore, users can enjoy the full kamaki
+user experience without installing mock.
.. code-block:: console
- #For ansicolors
- $ pip install ansicolors
+ $ pip install mock
- #For progress
- $ pip install progress
+.. warning:: mock version >= 1.X
Mac OS X
--------
.. code-block:: console
$ easy_setup kamaki
-
-Install progress (optional)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-progress: command-line progress bars (in some commands)
-
-.. code-block:: console
-
- $ easy_setup progress
-
Optional features
-----------------
-For installing any all of the following, consult the `kamaki installation guide <installation.html#install-progress-and-or-ansicolors-optional>`_
+For installing any or all of the following, consult the `kamaki installation guide <installation.html#install-ansicolors>`_
* ansicolors
* Make command line / console user interface responses prettier with text formating (colors, bold, etc.)
* Can be switched on/off in kamaki configuration file: colors=on/off
+ * Has not been tested on non unix / linux based platforms
-* progress
- * Attach progress bars to various kamaki commands (e.g. kamaki store upload)
- * If desired, progress version should be 1.0.2 or better
+* mock
+ * For kamaki contributors only
+ * Allow unittests to run on kamaki.clients package
+ * Needs mock version 1.X or better
Any of the above features can be installed at any time before or after kamaki installation.
url=<URL of quotaholder service>
Quotaholder is not tested in livetest
+
+The unit testing system
+"""""""""""""""""""""""
+
+Kamaki container a set of finegrained unit tests for the kamaki.clients package. This set is not used when kamaki is running. Instead, it is aimed to developers who debug or extent the kamaki clients library. For more information, check the `Going Agile <developers/extending-clients-api.html#going-agile>`_ entry at the `developers section <developers/extending-clients-api.html>`_.
projects / kamaki / commitdiff