<commit_before>**************
Stack-In-A-Box
**************

Testing framework for RESTful APIs such as the OpenStack/Rackspace APIs

.. image:: https://travis-ci.org/BenjamenMeyer/stackInABox.svg?branch=master
   :target: https://travis-ci.org/BenjamenMeyer/stackInABox
   :alt: Travis-CI Status

========
Overview
========

Stack-In-A-Box is a RESTful API Testing Framework for unit testing applications against the other services with support for OpenStack/Rackspace APIs.

==========
Installing
==========

Installation is simple:


.. code-block:: bash 

   pip install stackinabox

=====
Goals
=====

- Enable Python modules to be unit tested against externals services and the OpenStack/Rackspace services (f.e Keystone) in particular in an environment entirely controlled by the unittest.
- The service should be started/stopped and configured from the setup/teardown methods of the unittest
- Support both Postive and Negative testing
- Testing should be easy to do:
  - you shouldn't need to know the ins and outs of each service
  - you should be able to register what you need (f.e keystone, swift) and have it just work
- should be useable on systems like Travis (https://travis-ci.org/)
- should be light on requirements
  - we don't want to bloat your testing to fit our needs
  - if we have many requirements they could interfere with your requirements:w
- The code being unit-tested should not be able to tell the difference of whether it is working with Stack-In-A-Box or the real thing
  - the should be nothing special about setting up the test
  - if you don't turn on Stack-In-A-Box then the code should be able to call the real thing

========================
Why not use framework X?
========================

I considered a couple frameworks and tools, but they didn't quite meet the goal.

For instance, mimic (https://github.com/rackerlabs/mimic) is a great tool for testing multiple things. However, you have to start/stop it separately from your tests.
On the other hand, pretenders (https://github.com/pretenders) has a nice framework too, but it doesn't actually use sockets.

================
What's Provided?
================

It's a work in progress. Here's the list of current targets in-order:

- Keystone v2
- Keystone v3
- Swift

Thus far Keystone v2 provides end-points for:

- Listing tenants
- Listing users

It also has support in the backend for:

- tenant (add/remove/enable/disable)
- users (add/remove/enable/disable, apikey, password)
- tokens (add/remove, revoke, validate, admin tokens)
- roles (add, assign)

=======================
Working with Frameworks
=======================

Stack-In-A-Box does not itself provide a socket interception framework.
Out-of-the-box it supports two frameworks:

- HTTPretty (https://github.com/gabrielfalcao/HTTPretty)
- Responses (https://github.com/dropbox/responses)

You can use either one, and you must pull them in via your own test requirements.

Both of these are extremely easy to use as shown in the following examples:

---------
HTTPretty
---------

.. code-block:: python

    import unittest

    import httpretty
    import requests

    import stackinabox.util_httpretty
    from stackinabox.stack import StackInABox
    from stackinabox.services.hello import HelloService<commit_msg>Update README.rst<commit_after>**************
Stack-In-A-Box
**************

Testing framework for RESTful APIs such as the OpenStack/Rackspace APIs

.. image:: https://travis-ci.org/BenjamenMeyer/stackInABox.svg?branch=master
   :target: https://travis-ci.org/BenjamenMeyer/stackInABox
   :alt: Travis-CI Status

========
Overview
========

Stack-In-A-Box is a RESTful API Testing Framework for unit testing applications against the other services with support for OpenStack/Rackspace APIs.

==========
Installing
==========

Installation is simple:


.. code-block:: bash 

   pip install stackinabox

=====
Goals
=====

- Enable Python modules to be unit tested against externals services and the OpenStack/Rackspace services (f.e Keystone) in particular in an environment entirely controlled by the unittest.
- The service should be started/stopped and configured from the setup/teardown methods of the unittest
- Support both Postive and Negative testing
- Testing should be easy to do:
  - you shouldn't need to know the ins and outs of each service
  - you should be able to register what you need (f.e keystone, swift) and have it just work
- should be useable on systems like Travis (https://travis-ci.org/)
- should be light on requirements
  - we don't want to bloat your testing to fit our needs
  - if we have many requirements they could interfere with your requirements:w
- The code being unit-tested should not be able to tell the difference of whether it is working with Stack-In-A-Box or the real thing
  - the should be nothing special about setting up the test
  - if you don't turn on Stack-In-A-Box then the code should be able to call the real thing

========================
Why not use framework X?
========================

I considered a couple frameworks and tools, but they didn't quite meet the goal.

For instance, mimic (https://github.com/rackerlabs/mimic) is a great tool for testing multiple things. However, you have to start/stop it separately from your tests.
On the other hand, pretenders (https://github.com/pretenders) has a nice framework too, but it doesn't actually use sockets.

================
What's Provided?
================

It's a work in progress. Here's the list of current targets in-order:

- Keystone v2
- Keystone v3
- Swift

Thus far Keystone v2 provides end-points for:

- Listing tenants
- Listing users

It also has support in the backend for:

- tenant (add/remove/enable/disable)
- users (add/remove/enable/disable, apikey, password)
- tokens (add/remove, revoke, validate, admin tokens)
- roles (add, assign)

=======================
Working with Frameworks
=======================

Stack-In-A-Box does not itself provide a socket interception framework.
Out-of-the-box it supports two frameworks:

- HTTPretty (https://github.com/gabrielfalcao/HTTPretty)
- Responses (https://github.com/dropbox/responses)
- Requests-Mock(https://git.openstack.org/cgit/stackforge/requests-mock)

You can use either one, and you must pull them in via your own test requirements.

Both of these are extremely easy to use as shown in the following examples:

---------
HTTPretty
---------

.. code-block:: python

    import unittest

    import httpretty
    import requests

    import stackinabox.util_httpretty
    from stackinabox.stack import StackInABox
    from stackinabox.services.hello import HelloService
{'fraction_non_alphanumeric': 0.12603399007369528, 'fraction_numerical': 0.0009023913370431644, 'mean_word_length': 4.0416982562547386, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 15, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1237889', 'n_tokens_mistral': 1909, 'n_tokens_neox': 1796, 'n_words': 795}