Konstantine Rybnikov avatar Konstantine Rybnikov committed 7a73f3b Draft

put some love into doc update

Comments (0)

Files changed (5)

docs/code/minimal_example.py

+import unittest
+from mockstar import prefixed_p
+from sample_app.blog import forms
+
+ppatch = prefixed_p("sample_app.blog.forms")  # module under test
+
+
+class TestPostForm(unittest.TestCase):
+    @ppatch('is_post_exist')     # list / describe side-effects
+    def side_effects(self, se):
+        se.is_post_exist.return_value = False  # default side-effects behavior
+        return self.invoke(se)
+
+    def test_should_be_valid_for_simple_data(self, se):
+        form = forms.PostForm({'title': 'foo', 'content': 'bar'})
+
+        self.assertTrue(form.is_valid())
+
+    def test_should_get_error_on_existing_post_title(self, se):
+        se.is_post_exist.return_value = True
+        form = forms.PostForm({'title': 'foo', 'content': 'bar'})
+
+        self.assertFalse(form.is_valid())
+        self.assertEquals(dict(form.errors),
+                          ["Post with this title already exists"])

docs/code/philosophy.py

+# file sample_app/blog/forms.py
+
+class PostForm(forms.Form):
+    title = forms.CharField()
+    content = forms.TextField()
+
+    def clean(self):
+        if is_post_exist(self.cleaned_data['title']):
+            raise ValidationError(_(u"Post with this title already exists"))
+        return self.cleaned_data
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-======================================
- Mockstar -- Mocking Like a Rockstar!
-======================================
+Mockstar -- Declarative Mocking Like a Rockstar!
+================================================
 
-Mockstar is a bunch of small enhances on top of `Mock
-<http://www.voidspace.org.uk/python/mock/mock.html>`_ library that can
-give you a lot of mocking and unit-testing goods.
-
-.. note::
-
-   Mockstar is still in development, but my team already uses it in
-   our project heavily, so it should get stable API soon.
+Mockstar is a small enhance on top of `Mock
+<http://www.voidspace.org.uk/python/mock/mock.html>`_ library that
+gives you declarative way to write your unit-tests.
 
 Author: `Konstantine Rybnikov <http://redhotchilipython.com/>`_. Main
 repository on bitbucket: `https://bitbucket.org/k_bx/mockstar
 <https://bitbucket.org/k_bx/mockstar>`_.
 
-Unit-testing with MockStar
-==========================
+Philosophy
+----------
+
+Usually, **unit under test** is something simple, like function or
+method. It's result is dependent on it's arguments and calls to some
+external dependencies (side-effects). For example, here:
+
+.. literalinclude:: code/philosophy.py
+
+Unit under test is ``PostForm`` class (more precicely, it's ``clean``
+method here), it has one side-effect, which is ``is_post_exist``
+function.
+
+Usually, you create a single test module for single code module (well,
+I do). So in this example **module under test** would be
+``myapp.blog.forms``.
+
+Minimal test-case example
+-------------------------
+
+Your minimal test case would look something like this:
+
+.. literalinclude:: code/minimal_example.py
+
+More detailed introduction
+--------------------------
 
 So, you want to implement and test your unit. Let's say it's a
 function :func:`create_user` that will look like this when it is done:
 
 .. literalinclude:: code/unit_test_mockstar.py
 
-I hope you like mockstar's aspiration to fight copy-paste and useless
-typing.
+I hope you like mockstar's aspiration to get declarative way of
+writing unit-tests and reduce of copypasta.
 
 Installation
-============
+------------
 
 To install mockstar, just type::
 
       :maxdepth: 2
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
 
 def p(*args, **kw):
     """
-    Acts like :func:``mock.patch``, but passes side-effects (patched mocks)
-    into special dict-like ``se`` parameter.
+    Acts like :func:``mock.patch``, but passes side-effects (patched
+    mocks) into special dict-like ``se`` parameter.
     """
     def rv_decorator(fn):
         new_patchers = []
     LONG_DESCRIPTION = f.read()
 
 setup(name='mockstar',
-      version='0.1.10',
+      version='0.1.11',
       description=DESCRIPTION,
       long_description=LONG_DESCRIPTION,
       author='Konstantine Rybnikov',
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.