Redesign the poc

Author: jpic

README.rst

@@ -12,81 +12,83 @@ I'm pretty lazy when it comes to writing tests for existing code, however, I'm
 even lazier when it comes to repetitive manual testing action.
 
 This package aims at de-duplicating the data import tests from
-django-representatives and django-representatives-votes which is to be re-used
-in django-cities-light.
+django-representatives and django-representatives-votes which is re-used in
+django-cities-light.
 
 Database state assertion
 ========================
 
 A nice way to test a data import script is to create a source data fixture with
 a subset of data, ie. with only 10 cities instead of 28K or only 3 european
 parliament representatives instead of 3600, feed the import function with that
-and then compare the database state with a django fixture. For example:
+and then compare the database state with a django fixture. This looks like what
+I was used to do:
 
 - use such a command to create a small data extract
   `shuf -n3 cities15000.txt > cities_light/tests/cities_test_fixture.txt`,
 - use it against the import script on a clean database,
 - verify the database manually, and run
   `django-admin dumpdata --indent=4 cities_light > cities_light/tests/cities_test_expected.txt`
-- then, make a test case that calls the import script against the fixture and
-  call test_light's function to assert that the database contains only the
-  expected data.
+- then, make a test case that calls the import script against the fixture,
+- write and maintain some funny (fuzzy ?) repetitive test code to ensure that
+  the database is in the expected state.
 
 When a bug is fixed, just add the case to the fixture and repeat the process to
 create new expected data dumps, use coverage to ensure no case is missed.
 
-Predictible serialization
-=========================
+With django-dbdiff, I just need to maintain to initial data extract, and test
+it with ``Fixture.assertNoDiff('appname/path/to/fixture',
+models=[YourModelToTest])`` in a ``django.test.TransactionTestCase`` which has
+``reset_sequences=True``:
 
-It is important to use serializers which dump data in a predictible way because
-this app relies on diff between an expected - user-generated and versioned -
-fixture and dumped database data.
-
-Django's default model-to-dict logic - implemented in
-django.core.serializers.python.Serializer.get_dump_object() - returns a dict,
-this app registers a slightly modified version of the default json serializer
-which returns OrderedDicts instead.
-
-In addition, dbdiff serialization forces Decimal normalization, because
-trailing zeros could happen in inconsistent ways.
-
-Cross-database fixture compatibility
-====================================
-
-MySQL doesn't have microseconds in datetimes, so dbdiff's serializer removes
-microseconds from datetimes so that fixtures are cross-database compatible
-which make them usable for cross-database testing.
+- if the fixture in question doesn't exist, it'll be automatically created on
+  with dumpdata for the concerned models on the first run, raising
+  "FixtureCreated" exception to fail the test and inform of the path of the
+  created fixture, so that it doesn't mislead the user in thinking the test
+  passed with an existing fixture,
+- if the fixture exists, it'll run dumpdata on the models concerned and GNU
+  diff it against the fixture, if there's any output it'll be raised in the
+  "DiffFound" exception, failing the test and printing the diff.
 
 Usage
 =====
 
-MySQL, SQLite and PostgreSQL, Python 2.7 and 3.4 are supported along with
-Django 1.7 to 1.10 - it's always better to support django's master so that we
-can upgrade easily when it is released.
+Example::
 
-Install ``django-dbdiff`` with pip and add ``dbdiff`` to ``INSTALLED_APPS``.
+    from django import TransactionTestCase
+    from dbdiff.fixture import Fixture
 
-When ``dbdiff`` is installed, ``dumpdata`` will use its serializers which have
-predictible output and cross-database support, so fixtures dumped without
-``dbdiff`` installed will have to be regenerated after ``dbdiff`` is installed.
 
-Example::
+    class YourImportTest(test.TransactionTestCase):
+        reset_sequences = True
+
+        def test_your_import(self):
+            your_import()
 
-    from dbdiff import dbdiff
+            Fixture('yourapp/tests/yourtest.json',
+                    models=[YourModel]).assertNoDiff()
 
-    your_import_function()
-    assert not dbdiff.diff('your_app/tests/some_fixture.json')
+The first time, it will raise a ``FixtureCreated`` exception, and the test will
+fail. This is to inform the user that the test didn't really run. On the next
+run though, it will pass.
 
 If any difference is found between the database and the test fixture, then
 ``diff()`` will return the diff as outputed by GNU diff.
 
-A context manager that will raise an exception if a diff is found is also
-provided, it's able to delete models and reset the PK sequences for them::
+See tests and docstrings for crunchy details.
 
-    with dbdiff.exact('your_app/fixture.json'):
-        # do stuff
+Requirements
+============
 
-More public API tests can be found in dbidff/tests/test_dbdiff.py.
+MySQL, SQLite and PostgreSQL, Python 2.7 and 3.4 are supported along with
+Django 1.7 to 1.10 - it's always better to support django's master so that we
+can **upgrade easily when it is released**, which is one of the selling points
+for having 100% coverage.
+
+Install
+=======
+
+Install ``django-dbdiff`` with pip and add ``dbdiff`` to ``INSTALLED_APPS``.
 
 Django model observer
 =====================

dbdiff/apps.py

@@ -5,10 +5,12 @@
 from django.apps import AppConfig
 from django.core.serializers import register_serializer
 
+from .utils import patch_transaction_test_case
+
 
 class DefaultConfig(AppConfig):
     """
-    Default AppConfig for dbdiff.
+    Register patched serializers and patch TransactionTestCase for sqlite.
 
     .. py:attribute:: debug
 
@@ -18,12 +20,25 @@ class DefaultConfig(AppConfig):
 
     name = 'dbdiff'
     debug = False
+    default_indent = 4
 
     def ready(self):
         """
         Register dbdiff.serializers.json and set debug.
 
         Enables debug if a DBDIFF_DEBUG environment variable is found.
+
+        It is important to use serializers which dump data in a predictible way
+        because this app relies on diff between an expected - user-generated
+        and versioned - fixture and dumped database data. This method also
+        overrides the default json serializer with dbdiff's.
+
+        When dbdiff is installed, ``dumpdata`` will use its serializers which
+        have predictible output and cross-database support, so fixtures dumped
+        without dbdiff installed will have to be regenerated after dbdiff is
+        installed to be usable with dbdiff.
+
         """
         self.debug = os.environ.get('DBDIFF_DEBUG', False)
         register_serializer('json', 'dbdiff.serializers.json')
+        patch_transaction_test_case()

dbdiff/dbdiff.py

@@ -5,17 +5,23 @@ class DbDiffException(Exception):
     """Base exception for this app."""
 
 
-class EmptyFixtures(DbDiffException):
-    """Raised when a fixtures file is empty."""
-
-    def __init__(self, path):
-        """Exception for when path does not contain any fixture data."""
-        super(EmptyFixtures, self).__init__('%s is empty' % path)
-
-
 class DiffFound(DbDiffException):
     """Raised when a diff is found by the context manager."""
 
-    def __init__(self, out):
+    def __init__(self, cmd, out):
         """Exception for when a diff command had output."""
-        super(DiffFound, self).__init__(out)
+        super(DiffFound, self).__init__('%s\n%s' % (cmd, out.decode('utf8')))
+
+
+class FixtureCreated(DbDiffException):
+    """
+    Raised when a fixture was created.
+
+    This purposely fails a test, to avoid misleading the user into thinking
+    that the test was properly executed against a versioned fixture. Imagine
+    one pushes a test without the fixture, it will break because of this
+    exception in CI.
+
+    However, this should only happen once per fixture - unless the user in
+    question forgets to commit the generated fixture !
+    """