Fuzzers (#69)

Adds fuzz tests to the generated output

Adds fuzz tests to the generated Elm output and now also generates a slightly more elaborate directory structure, see README, allowing the user to much easier test that the generated decoders and encoders behave as expected before merging them into their existing project.

Reduces the noise when referencing qualified Elm types and functions across modules in the generated files by using `import Data.Foo as Foo` statements.

Refactors code according to dialyzer and credo warnings.

Author: dragonwasrobot

.gitignore

@@ -1,5 +1,6 @@
 # The packaged executable
 js2e
+/js2e_output
 
 # The directory Mix will write compiled artifacts to.
 /_build

README.md

@@ -1,7 +1,7 @@
 # JSON schema to Elm
 
-Generates Elm types, JSON decoders and JSON encoders from JSON schema
-specifications.
+Generates Elm types, JSON decoders, JSON encoders, and Fuzz tests from JSON
+schema specifications.
 
 ## Installation
 
@@ -26,14 +26,14 @@ Run `./js2e` for usage instructions.
 > have to pass it the enclosing directory of the relevant JSON schema files,
 > in order for it to be able to resolve the references correctly.
 
-A proper description of which properties are mandatory are how the generator
+A proper description of which properties are mandatory and how the generator
 works is still in progress, but feel free to take a look at the `examples`
 folder which contains an example of a pair of JSON schemas and their
 corresponding Elm output. Likewise, representations of each of the different
 JSON schema types are described in the `lib/types` folder.
 
-The tool aims to produce `elm-make`-like errors if something is missing,
-mispelled or cannot be resolved in the supplied JSON schema file(s), e.g.
+The tool aims to produce `elm-make`-like errors in case something is missing,
+misspelled or cannot be resolved in the supplied JSON schema file(s), e.g.
 
 ```
 --- UNKNOWN NODE TYPE -------------------------------------- all_of_example.json
@@ -137,21 +137,25 @@ type alias Point =
 
 colorDecoder : String -> Decoder Color
 colorDecoder color =
-    case color of
-        "red" ->
-            succeed Red
+    Decode.string
+        |> andThen
+            (\color ->
+                case color of
+                    "red" ->
+                        succeed Red
 
-        "yellow" ->
-            succeed Yellow
+                    "yellow" ->
+                        succeed Yellow
 
-        "green" ->
-            succeed Green
+                    "green" ->
+                        succeed Green
 
-        "blue" ->
-            succeed Blue
+                    "blue" ->
+                        succeed Blue
 
-        _ ->
-            fail <| "Unknown color type: " ++ color
+                    _ ->
+                        fail <| "Unknown color type: " ++ color
+            )
 
 
 pointDecoder : Decoder Point
@@ -253,34 +257,34 @@ import Json.Encode as Encode
         , object
         , list
         )
-import Data.Definitions
+import Data.Definitions as Definitions
 
 
 type alias Circle =
-    { center : Data.Definitions.Point
-    , color : Maybe Data.Definitions.Color
+    { center : Definitions.Point
+    , color : Maybe Definitions.Color
     , radius : Float
     }
 
 
 circleDecoder : Decoder Circle
 circleDecoder =
     decode Circle
-        |> required "center" Data.Definitions.pointDecoder
-        |> optional "color" (Decode.string |> andThen Data.Definitions.colorDecoder |> maybe) Nothing
+        |> required "center" Definitions.pointDecoder
+        |> optional "color" (nullable Definitions.colorDecoder) Nothing
         |> required "radius" Decode.float
 
 
 encodeCircle : Circle -> Value
 encodeCircle circle =
     let
         center =
-            [ ( "center", Data.Definitions.encodePoint circle.center ) ]
+            [ ( "center", Definitions.encodePoint circle.center ) ]
 
         color =
             case circle.color of
                 Just color ->
-                    [ ( "color", Data.Definitions.encodeColor color ) ]
+                    [ ( "color", Definitions.encodeColor color ) ]
 
                 Nothing ->
                     []
@@ -294,6 +298,170 @@ encodeCircle circle =
                 ++ radius
 ```
 
+Furthermore, `js2e` also generates test files for the generated decoders and
+encoders, which fuzzes instances of a given Elm type and tests that encoding it
+as JSON and decoding it back into Elm returns the original instance of that
+generated Elm type. In the above case, the following test files,
+`tests/Data/CircleTests.elm` and `tests/Data/DefinitionsTests.elm`, are
+generated:
+
+``` elm
+module Data.CircleTests exposing (..)
+
+-- Tests: Schema for a circle shape
+
+import Expect exposing (Expectation)
+import Fuzz exposing (Fuzzer)
+import Test exposing (..)
+import Json.Decode as Decode
+import Data.Circle exposing (..)
+import Data.DefinitionsTests as Definitions
+
+
+circleFuzzer : Fuzzer Circle
+circleFuzzer =
+    Fuzz.map3
+        Circle
+        Definitions.pointFuzzer
+        (Fuzz.maybe Definitions.colorFuzzer)
+        Fuzz.float
+
+
+encodeDecodeCircleTest : Test
+encodeDecodeCircleTest =
+    fuzz circleFuzzer "can encode and decode Circle object" <|
+        \circle ->
+            circle
+                |> encodeCircle
+                |> Decode.decodeValue circleDecoder
+                |> Expect.equal (Ok circle)
+```
+and
+
+``` elm
+module Data.DefinitionsTests exposing (..)
+
+-- Tests: Schema for common types
+
+import Expect exposing (Expectation)
+import Fuzz exposing (Fuzzer)
+import Test exposing (..)
+import Json.Decode as Decode
+import Data.Definitions exposing (..)
+
+
+colorFuzzer : Fuzzer Color
+colorFuzzer =
+    Fuzz.oneOf
+        [ Fuzz.constant Red
+        , Fuzz.constant Yellow
+        , Fuzz.constant Green
+        , Fuzz.constant Blue
+        ]
+
+
+encodeDecodeColorTest : Test
+encodeDecodeColorTest =
+    fuzz colorFuzzer "can encode and decode Color object" <|
+        \color ->
+            color
+                |> encodeColor
+                |> Decode.decodeValue colorDecoder
+                |> Expect.equal (Ok color)
+
+
+pointFuzzer : Fuzzer Point
+pointFuzzer =
+    Fuzz.map2
+        Point
+        Fuzz.float
+        Fuzz.float
+
+
+encodeDecodePointTest : Test
+encodeDecodePointTest =
+    fuzz pointFuzzer "can encode and decode Point object" <|
+        \point ->
+            point
+                |> encodePoint
+                |> Decode.decodeValue pointDecoder
+                |> Expect.equal (Ok point)
+
+```
+
+Finally, `js2e` also generates package config files, `package.json` and
+`elm-package.json` making it easy to test that the generated Elm code is
+behaving as expected. Thus, if we supply the following directory structure to
+`js2e` in the above case:
+
+```
+.
+└── js2e_input/
+    ├── definitions.json
+    └── circle.json
+```
+
+the following new directory structure is generated:
+
+```
+.
+└── js2e_output/
+    ├── package.json
+    ├── elm-package.json
+    ├── Data/
+    │   ├── Circle.elm
+    │   └── Definitions.elm
+    └── tests/
+        ├── elm-package.json
+        └── Data/
+            ├── CircleTests.elm
+            └── DefinitionsTests.elm
+```
+
+containing the files described above along with the needed package config files
+to compile and run the tests.
+
+## Error reporting
+
+Any errors encountered by the `js2e` tool while parsing the JSON schema files or
+printing the Elm code output, is reported in an Elm-like style, e.g.
+
+```
+--- UNKNOWN NODE TYPE -------------------------------------- all_of_example.json
+
+The value of "type" at '#/allOf/0/properties/description' did not match a known node type
+
+    "type": "strink"
+            ^^^^^^^^
+
+Was expecting one of the following types
+
+    ["null", "boolean", "object", "array", "number", "integer", "string"]
+
+Hint: See the specification section 6.25. "Validation keywords - type"
+<http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.25>
+```
+
+or
+
+```
+--- UNRESOLVED REFERENCE ----------------------------------- all_of_example.json
+
+
+The following reference at `#/allOf/0/color` could not be resolved
+
+    "$ref": #/definitions/kolor
+            ^^^^^^^^^^^^^^^^^^^
+
+
+Hint: See the specification section 9. "Base URI and dereferencing"
+<http://json-schema.org/latest/json-schema-core.html#rfc.section.9>
+```
+
+If you encounter an error while using `js2e` that does not mimic the above
+Elm-like style, but instead looks like an Elixir stacktrace, please report this
+as a bug by opening an issue and includin a JSON schema example that recreates
+the error.
 
 ## Contributing
 

config/config.exs

@@ -3,5 +3,6 @@ use Mix.Config
 config :elixir, ansi_enabled: true
 
 config :js2e, templates_location: "./priv/templates/"
+config :js2e, output_location: "js2e_output"
 
 import_config "#{Mix.env()}.exs"