Update documentation and add example snapshot tests. Rearrange files …

…to have a snapshot_test directory that exports a DashSnapshotTestCase

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+end_of_line = lf
+charset = utf-8
+
+[*.py]
+max_line_length = 100

.gitignore

@@ -13,3 +13,6 @@ pyvenv.cfg
 .venv
 pip-selfcheck.json
 
+.idea/
+*.egg-info/
+*.whl

README.md

@@ -1,11 +1,88 @@
 # dash-snapshot-testing
-Use snapshot testing to test Dash components
+Use snapshot testing, inspired by Jest snapshot testing, to test [Dash][] components.
 
+## Inspiration
+Testing a long HTML component output for a Dash application is difficult.
+It typically requires hardcoding data or setting up a dummy database.
+Using snapshot tests that JSON serialize the Dash component output provide another
+easy testing layer to ensure that code refactors/changes do not change the
+output unexpectedly.
 
-## Example
+To learn more about snapshot testing in general, see a much more elaborate explanation from the [Facebook Jest site](https://facebook.github.io/jest/docs/en/snapshot-testing.html)
+
+## Usage
+```python
+import dash_html_components as html
+
+from snapshot_test import DashSnapshotTestCase
+
+
+class MyUnitTestCase(DashSnapshotTestCase):
+    def test_component(self):
+        my_component = html.Div([html.P('wow'), html.Span('this works')], id='test-id')
+
+        self.assertSnapshotEqual(my_component, 'my-test-unique-id')
+```
+
+This outputs/checks this JSON at `__snapshots__/MyUnitTestCase-my-test-unique-id.json`:
+```json
+{
+  "type": "Div",
+  "props": {
+    "id": "test-id",
+    "children": [
+      {
+        "type": "P",
+        "props": {"children": "wow"},
+        "namespace": "dash_html_components"
+      },
+      {
+        "type": "Span",
+        "props": {"children": "this works"},
+        "namespace": "dash_html_components"
+      }
+    ]
+  },
+  "namespace": "dash_html_components"
+}
+```
+
+### Setting a custom `snapshots_dir` for the class
 ```python
- class MyComponentNameTest(DashSnapshotUnitTest):
-     def test_func(self) -> None:
+class MyOtherUnitTestCase(DashSnapshotTestCase):
+    snapshots_dir = '__snapshots_2__'
+
+    def test_component(self):
+        my_component = html.Div([html.P('wow'), html.Span('another one')], id='test-id')
+
+        self.assertSnapshotEqual(my_component, 'my-test-unique-id')
+```
+
+This outputs/checks this JSON at `__snapshots_2__/MyOtherUnitTestCase-my-test-unique-id.json`:
+```json
+{
+  "type": "Div",
+  "props": {
+    "id": "test-id",
+    "children": [
+      {
+        "type": "P",
+        "props": {"children": "wow"},
+        "namespace": "dash_html_components"
+      },
+      {
+        "type": "Span",
+        "props": {"children": "another one"},
+        "namespace": "dash_html_components"
+      }
+    ]
+  },
+  "namespace": "dash_html_components"
+}
+```
+
+At its core, this `unittest.TestCase` compares a JSON-serialized Dash component
+against a previously stored JSON-serialized Dash component, and checks if the `dict`
+objects from `json.loads` are equivalent using `assertEqual`.
 
-         self.assertSnapshotEqual()
-```
+[Dash]: https://github.com/plotly/dash

__snapshots_2__/MyOtherUnitTestCase-my-test-unique-id.json

@@ -0,0 +1 @@
+{"type": "Div", "props": {"id": "test-id", "children": [{"type": "P", "props": {"children": "wow"}, "namespace": "dash_html_components"}, {"type": "Span", "props": {"children": "another one"}, "namespace": "dash_html_components"}]}, "namespace": "dash_html_components"}

__snapshots__/MyUnitTestCase-my-test-unique-id.json

@@ -0,0 +1 @@
+{"type": "Div", "props": {"id": "test-id", "children": [{"type": "P", "props": {"children": "wow"}, "namespace": "dash_html_components"}, {"type": "Span", "props": {"children": "this works"}, "namespace": "dash_html_components"}]}, "namespace": "dash_html_components"}

requirements-dev.txt

@@ -0,0 +1,4 @@
+-r ./requirements.txt
+
+dash-html-components
+dash-renderer

requirements.txt

@@ -0,0 +1,2 @@
+dash>=0.19
+plotly>=2.2.3

setup.py

@@ -1,10 +1,10 @@
 """
 StratoDem Analytics : setup
 Principal Author(s) : Eric Linden
-Secondary Author(s) : 
+Secondary Author(s) :
 Description :
 
-Notes : 
+Notes :
 
 March 27, 2018
 """
@@ -16,9 +16,7 @@
     version='1.0.0',
     author='Michael Clawar, Eric Linden',
     author_email='tech@stratodem.com',
-    packages=[
-        'SnapshotTest.DashSnapshotUnitTest',
-    ],
+    packages=['snapshot_test'],
     license='(c) 2018 StratoDem Analytics. All rights reserved.',
     description='Dash snapshot testing package',
     url='https://github.com/StratoDem/dash-snapshot-testing',

snapshot_test/__init__.py

@@ -0,0 +1,12 @@
+"""
+StratoDem Analytics : __init__.py
+Principal Author(s) : Michael Clawar
+Secondary Author(s) :
+Description :
+
+Notes :
+
+March 27, 2018
+"""
+
+from .snapshot_test_case import *

snapshot_test/__tests__/__init__.py

@@ -0,0 +1,10 @@
+"""
+StratoDem Analytics : __init__.py
+Principal Author(s) : Michael Clawar
+Secondary Author(s) : 
+Description :
+
+Notes : 
+
+March 27, 2018
+"""

snapshot_test/__tests__/test_snapshot_test_case.py

@@ -0,0 +1,31 @@
+"""
+StratoDem Analytics : __test_snapshot_test_case
+Principal Author(s) : Michael Clawar
+Secondary Author(s) :
+Description :
+
+Notes :
+
+March 27, 2018
+"""
+
+
+import dash_html_components as html
+
+from snapshot_test import DashSnapshotTestCase
+
+
+class MyUnitTestCase(DashSnapshotTestCase):
+    def test_component(self):
+        my_component = html.Div([html.P('wow'), html.Span('this works')], id='test-id')
+
+        self.assertSnapshotEqual(my_component, 'my-test-unique-id')
+
+
+class MyOtherUnitTestCase(DashSnapshotTestCase):
+    snapshots_dir = '__snapshots_2__'
+
+    def test_component(self):
+        my_component = html.Div([html.P('wow'), html.Span('another one')], id='test-id')
+
+        self.assertSnapshotEqual(my_component, 'my-test-unique-id')

SnapshotTest.py → snapshot_test/snapshot_test_case.py

@@ -1,10 +1,10 @@
 """
 StratoDem Analytics : SnapshotTest
 Principal Author(s) : Eric Linden
-Secondary Author(s) : 
+Secondary Author(s) :
 Description :
 
-Notes : 
+Notes :
 
 March 26, 2018
 """
@@ -17,7 +17,12 @@
 from dash.development.base_component import Component
 
 
-class DashSnapshotUnitTest(unittest.TestCase):
+__all__ = ['DashSnapshotTestCase']
+
+
+class DashSnapshotTestCase(unittest.TestCase):
+    snapshots_dir = None
+
     def assertSnapshotEqual(self, component: Component, file_id: str) -> None:
         """
         Tests the supplied component against the specified JSON file snapshot, if it exists.
@@ -37,19 +42,21 @@ def assertSnapshotEqual(self, component: Component, file_id: str) -> None:
         -------
         None
         """
-        assert isinstance(component, Component)
-        assert isinstance(file_id, str)
+        assert isinstance(component, Component), 'Component passed in must be Dash Component'
+        assert isinstance(file_id, str), 'must pass in a file id to use as unique file ID'
 
         filename = self.__get_filename(file_id=file_id)
 
         component_json = component.to_plotly_json()
 
         if os.path.exists(filename):
+            # Load a dumped JSON for the passed-in component, to ensure matches standard format
             expected_dict = json.loads(
                 json.dumps(component_json, cls=plotly.utils.PlotlyJSONEncoder))
             self.assertEqual(self.__load_snapshot(filename=filename), expected_dict)
         else:
-            with open(filename, 'w+') as file:
+            # Component did not already exist, so we'll write to the file
+            with open(filename, 'w') as file:
                 json.dump(component_json, file, cls=plotly.utils.PlotlyJSONEncoder)
 
     def __get_filename(self, file_id: str) -> str:
@@ -68,7 +75,9 @@ def __get_filename(self, file_id: str) -> str:
         """
         assert isinstance(file_id, str)
 
-        return os.path.join(self.__get_snapshots_dir(), '{}-{}.json'.format(self.__name__, file_id))
+        return os.path.join(
+            self.__get_snapshots_dir(),
+            '{}-{}.json'.format(self.__class__.__name__, file_id))
 
     @staticmethod
     def __load_snapshot(filename: str) -> dict:
@@ -89,8 +98,8 @@ def __load_snapshot(filename: str) -> dict:
         with open(filename, 'r') as f:
             return json.load(f)
 
-    @staticmethod
-    def __get_snapshots_dir() -> str:
+    @classmethod
+    def __get_snapshots_dir(cls) -> str:
         """
         Checks for the existence of the snapshots directory, and creates it if it is not found.
         It then returns the directory path.
@@ -99,9 +108,15 @@ def __get_snapshots_dir() -> str:
         -------
         A string containing the path of the snapshots directory.
         """
-        directory = os.path.join(os.curdir, 'snapshots')
+        if cls.snapshots_dir is None:
+            directory = os.path.join(os.curdir, '__snapshots__')
+
+            if not os.path.exists(directory):
+                os.mkdir(directory)
 
-        if not os.path.exists(directory):
-            os.mkdir(directory)
+            return directory
+        else:
+            if not os.path.exists(cls.snapshots_dir):
+                os.mkdir(cls.snapshots_dir)
 
-        return directory
+            return cls.snapshots_dir