cleanup (#6)

* Cleanup public API

* Move alias

* Test coverage

* Rename

formatting/formatters.go

@@ -10,26 +10,6 @@ import (
 	"gopkg.in/yaml.v3"
 )
 
-// Formats is an alias for function signature that reads from reader, formats it and writes to writer.
-type Formats func(reader io.Reader, writer io.Writer) error
-
-type encoder interface {
-	Encode(v interface{}) error
-}
-
-type decoder interface {
-	Decode(v interface{}) error
-}
-
-func format(encoder encoder, decoder decoder) error {
-	var decoded interface{}
-	err := decoder.Decode(&decoded)
-	if err != nil {
-		return err
-	}
-	return encoder.Encode(decoded)
-}
-
 // JSON formats the contents of reader and writes the results to writer.
 func JSON(reader io.Reader, writer io.Writer) error {
 	decoder := json.NewDecoder(reader)

formatting/io.go

@@ -0,0 +1,18 @@
+package formatting
+
+type encoder interface {
+	Encode(v interface{}) error
+}
+
+type decoder interface {
+	Decode(v interface{}) error
+}
+
+func format(encoder encoder, decoder decoder) error {
+	var decoded interface{}
+	err := decoder.Decode(&decoded)
+	if err != nil {
+		return err
+	}
+	return encoder.Encode(decoded)
+}

gold/assertions.go

@@ -0,0 +1,46 @@
+package gold
+
+import (
+	"github.com/eberkund/rose/formatting"
+)
+
+// AssertEqualsJSON compares a JSON string to the golden file. Data is
+// noramlized before comparing so data which is formatted differently but
+// semantically equivalent will not fail.
+func (g *Gold) AssertEqualsJSON(goldenPath, actual string) {
+	g.t.Helper()
+	g.verify(g.assert(goldenPath, actual, formatting.JSON))
+}
+
+// AssertEqualsHTML compares an HTML string to the golden file. Data is
+// noramlized before comparing so data which is formatted differently but
+// semantically equivalent will not fail.
+func (g *Gold) AssertEqualsHTML(goldenPath, actual string) {
+	g.t.Helper()
+	g.verify(g.assert(goldenPath, actual, formatting.HTML))
+}
+
+// AssertEqualsTOML compares a TOML string to the golden file. Data is
+// noramlized before comparing so data which is formatted differently but
+// semantically equivalent will not fail.
+func (g *Gold) AssertEqualsTOML(goldenPath, actual string) {
+	g.t.Helper()
+	g.verify(g.assert(goldenPath, actual, formatting.TOML))
+}
+
+// AssertEqualsYAML compares a YAML string to the golden file. Data is
+// noramlized before comparing so data which is formatted differently but
+// semantically equivalent will not fail.
+func (g *Gold) AssertEqualsYAML(goldenPath, actual string) {
+	g.t.Helper()
+	g.verify(g.assert(goldenPath, actual, formatting.YAML))
+}
+
+// AssertEquals compares a string to the contents of the golden file. If Gold
+// was configured with an update flag which is true then the golden file will
+// be created if it does not exist or overwritten with the supplied data if it
+// does.
+func (g *Gold) AssertEquals(goldenPath, actual string) {
+	g.t.Helper()
+	g.verify(g.assert(goldenPath, actual, formatting.NoOp))
+}

gold/gold.go

@@ -2,16 +2,19 @@ package gold
 
 import (
 	"bytes"
+	"io"
 	"os"
 	"path/filepath"
 	"strings"
 
-	"github.com/eberkund/rose/formatting"
 	"github.com/pkg/errors"
 	"github.com/pmezard/go-difflib/difflib"
 	"github.com/spf13/afero"
 )
 
+// Formats is an alias for function signature that reads from reader, formats it and writes to writer.
+type Formats func(reader io.Reader, writer io.Writer) error
+
 // Testing is a subset of testing.TB that can be reimplemented.
 type Testing interface {
 	Cleanup(func())
@@ -43,7 +46,7 @@ type Gold struct {
 	fs     afero.Fs
 }
 
-// New initializes a Gold.
+// New initializes an instance of Gold.
 func New(t Testing, options ...Option) *Gold {
 	g := &Gold{
 		t:      t,
@@ -62,7 +65,7 @@ func (g *Gold) prependPrefix(path string) string {
 	return filepath.Join(g.prefix, path)
 }
 
-func (g *Gold) update(filename, actual string, formatter formatting.Formats) error {
+func (g *Gold) update(filename, actual string, formatter Formats) error {
 	if !g.flag {
 		return nil
 	}
@@ -84,12 +87,12 @@ func (g *Gold) update(filename, actual string, formatter formatting.Formats) err
 	}
 	err = formatter(strings.NewReader(actual), file)
 	if err != nil {
-		return errors.Wrap(err, "could not format or write inputData data to golden file")
+		return errors.Wrap(err, "could not format or write data to golden file")
 	}
 	return nil
 }
 
-func (g *Gold) assert(goldenPath, given string, formatter formatting.Formats) (string, error) {
+func (g *Gold) assert(goldenPath, given string, formatter Formats) (string, error) {
 	prefixed := g.prependPrefix(goldenPath)
 	if err := g.update(prefixed, given, formatter); err != nil {
 		return "", err

gold/gold_test.go

@@ -22,27 +22,27 @@ func TestExistingFiles(t *testing.T) {
 	}{
 		"json": {
 			inputData:  `{"foo":123,"bar":"hello world","a":true}`,
-			goldenFile: "json_eq.golden.json",
+			goldenFile: "assert_json.golden.json",
 			testFn: func(g *gold.Gold) func(string, string) {
-				return g.JSONEq
+				return g.AssertEqualsJSON
 			},
 		},
 		"text": {
-			goldenFile: "text_eq.golden.txt",
+			goldenFile: "assert_text.golden.txt",
 			inputData:  "Hello\nWorld\n!",
 			testFn: func(g *gold.Gold) func(string, string) {
-				return g.Eq
+				return g.AssertEquals
 			},
 		},
 		"html": {
-			goldenFile: "xml_eq.golden.toml",
+			goldenFile: "assert_xml.golden.toml",
 			inputData:  `<fruits><apple/><banana/></fruits>`,
 			testFn: func(g *gold.Gold) func(string, string) {
-				return g.HTMLEq
+				return g.AssertEqualsHTML
 			},
 		},
 		"toml": {
-			goldenFile: "toml_eq.golden.toml",
+			goldenFile: "assert_toml.golden.toml",
 			inputData: `
 Age = 25
 Cats = [ "Cauchy", "Plato" ]
@@ -52,11 +52,11 @@ Perfection = [ 6, 28, 496, 8128 ]
 DOB = 1987-07-05T05:45:00Z
 `,
 			testFn: func(g *gold.Gold) func(string, string) {
-				return g.TOMLEq
+				return g.AssertEqualsTOML
 			},
 		},
 		"yaml": {
-			goldenFile: "yaml_eq.golden.yaml",
+			goldenFile: "assert_yaml.golden.yaml",
 			inputData: `
 jobs:
  test:
@@ -68,14 +68,14 @@ jobs:
          go-version: "1.18"
 `,
 			testFn: func(g *gold.Gold) func(string, string) {
-				return g.YAMLEq
+				return g.AssertEqualsYAML
 			},
 		},
 	}
 	for name, tc := range testCases {
-		t.Run(name, func(subTest *testing.T) {
+		t.Run(name, func(st *testing.T) {
 			g := gold.New(
-				subTest,
+				st,
 				gold.WithPrefix("testdata", t.Name()),
 				gold.WithFlag(*update),
 				gold.WithFailAfter(),
@@ -101,20 +101,29 @@ func TestUpdatingGoldenFile(t *testing.T) {
 	require.NoError(t, err)
 
 	g := gold.New(t, gold.WithFS(memFs), gold.WithFlag(true))
-	g.Eq("test_data.txt", newData)
+	g.AssertEquals("test_data.txt", newData)
 
 	data, err := afero.ReadFile(memFs, "testdata/test_data.txt")
 	require.NoError(t, err)
 	require.Equal(t, newData, string(data))
 }
 
+func TestInvalidData(t *testing.T) {
+	tm := mocks.NewTesting(t)
+	tm.On("Helper")
+	tm.On("Log", mock.Anything).Once()
+	tm.On("FailNow").Once()
+	g := gold.New(tm, gold.WithPrefix("testdata", t.Name()))
+	g.AssertEqualsJSON("empty_json.golden.json", "this is not valid JSON")
+}
+
 func TestDiffGoldenFile(t *testing.T) {
 	tm := mocks.NewTesting(t)
 	tm.On("Helper")
 	tm.On("Logf", mock.Anything, mock.Anything).Once()
 	tm.On("FailNow").Once()
-	g := gold.New(tm, gold.WithPrefix("testdata", "TestExistingFiles"))
-	g.JSONEq("json_eq.golden.json", "{}")
+	g := gold.New(tm, gold.WithPrefix("testdata", t.Name()))
+	g.AssertEqualsJSON("empty_json.golden.json", "{}")
 }
 
 func TestFileSystemError(t *testing.T) {
@@ -124,5 +133,5 @@ func TestFileSystemError(t *testing.T) {
 	tm.On("FailNow").Once()
 	readOnlyFS := afero.NewReadOnlyFs(afero.NewMemMapFs())
 	g := gold.New(tm, gold.WithFS(readOnlyFS), gold.WithFlag(true))
-	g.Eq("testdata/hello_world.txt", "Hello, World!")
+	g.AssertEquals("any/path/hello_world.golden.txt", "Hello, World!")
 }

gold/testdata/TestDiffGoldenFile/empty_json.golden.json

@@ -0,0 +1,3 @@
+{
+    "foo": "bar"
+}

gold/testdata/TestInvalidData/valid_json.golden.json

@@ -0,0 +1 @@
+{}