Add documentation to UnmarshalJSON implementations (#179)

Author: helenjw

config.go

@@ -32,6 +32,10 @@ func (c *Config) Validate() error {
 	return nil
 }
 
+// UnmarshalJSON implements json.Unmarshaler for Config.
+//
+// As per established convention this method should only ever
+// be invoked *indirectly* via [encoding/json] library.
 func (c *Config) UnmarshalJSON(b []byte) error {
 	type rawConfig Config
 	var config rawConfig

expression.go

@@ -47,6 +47,9 @@ type ExpressionData struct {
 }
 
 // UnmarshalJSON implements json.Unmarshaler for Expression.
+//
+// As per established convention this method should only ever
+// be invoked *indirectly* via [encoding/json] library.
 func (e *Expression) UnmarshalJSON(b []byte) error {
 	result := new(ExpressionData)
 

metadata.go

@@ -57,6 +57,10 @@ func (f *MetadataFunctions) Validate() error {
 	return nil
 }
 
+// UnmarshalJSON implements json.Unmarshaler for MetadataFunctions.
+//
+// As per established convention this method should only ever
+// be invoked *indirectly* via [encoding/json] library.
 func (f *MetadataFunctions) UnmarshalJSON(b []byte) error {
 	type rawFunctions MetadataFunctions
 	var functions rawFunctions

parse_test.go

@@ -18,6 +18,7 @@ const testFixtureDir = "testdata"
 const testGoldenPlanFileName = "plan.json"
 const testGoldenStateFileName = "state.json"
 const testGoldenSchemasFileName = "schemas.json"
+const testInvalidDir = "invalid"
 
 func testParse(t *testing.T, filename string, typ reflect.Type) {
 	entries, err := os.ReadDir(testFixtureDir)
@@ -31,6 +32,10 @@ func testParse(t *testing.T, filename string, typ reflect.Type) {
 		}
 
 		t.Run(e.Name(), func(t *testing.T) {
+			if e.Name() == testInvalidDir {
+				t.Skip("Skipping known invalid test fixture")
+			}
+
 			expected, err := os.ReadFile(filepath.Join(testFixtureDir, e.Name(), filename))
 			if err != nil {
 				if os.IsNotExist(err) {

plan.go

@@ -142,6 +142,10 @@ func (p *Plan) Validate() error {
 	return nil
 }
 
+// UnmarshalJSON implements json.Unmarshaler for Plan.
+//
+// As per established convention this method should only ever
+// be invoked *indirectly* via [encoding/json] library.
 func (p *Plan) UnmarshalJSON(b []byte) error {
 	type rawPlan Plan
 	var plan rawPlan

plan_test.go

@@ -5,6 +5,7 @@ package tfjson
 
 import (
 	"encoding/json"
+	"io"
 	"os"
 	"reflect"
 	"testing"
@@ -187,7 +188,7 @@ func TestPlan_UnmarshalJSON(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	testCases := map[string]struct {
+	numericsTestCases := map[string]struct {
 		useJSONNumber bool
 		expected      any
 	}{
@@ -200,17 +201,15 @@ func TestPlan_UnmarshalJSON(t *testing.T) {
 		},
 	}
 
-	for name, testCase := range testCases {
-		name, testCase := name, testCase
-
+	for name, testCase := range numericsTestCases {
 		t.Run(name, func(t *testing.T) {
 			t.Parallel()
 
 			plan := &Plan{}
 
 			plan.UseJSONNumber(testCase.useJSONNumber)
 
-			err = plan.UnmarshalJSON(b)
+			err = json.Unmarshal(b, &plan)
 			if err != nil {
 				t.Fatal(err)
 			}
@@ -232,4 +231,43 @@ func TestPlan_UnmarshalJSON(t *testing.T) {
 			}
 		})
 	}
+
+	jsonValidationTestCases := map[string]struct {
+		filePath    string
+		expectError bool
+	}{
+		"invalid plan JSON": {
+			filePath:    "testdata/invalid/plan.json",
+			expectError: true,
+		},
+		"valid plan JSON": {
+			filePath: "testdata/basic/plan.json",
+		},
+	}
+
+	for tn, tc := range jsonValidationTestCases {
+		t.Run(tn, func(t *testing.T) {
+			f, err := os.Open(tc.filePath)
+			if err != nil {
+				t.Fatal(err)
+			}
+			defer f.Close()
+
+			b, err := io.ReadAll(f)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			var plan Plan
+			err = json.Unmarshal(b, &plan)
+
+			if tc.expectError && err == nil {
+				t.Fatalf("expected error; got none")
+			}
+
+			if !tc.expectError && err != nil {
+				t.Errorf("expected no error, got %q", err.Error())
+			}
+		})
+	}
 }

schemas.go

@@ -60,6 +60,10 @@ func (p *ProviderSchemas) Validate() error {
 	return nil
 }
 
+// UnmarshalJSON implements json.Unmarshaler for ProviderSchemas.
+//
+// As per established convention this method should only ever
+// be invoked *indirectly* via [encoding/json] library.
 func (p *ProviderSchemas) UnmarshalJSON(b []byte) error {
 	type rawSchemas ProviderSchemas
 	var schemas rawSchemas

state.go

@@ -78,6 +78,10 @@ func (s *State) Validate() error {
 	return nil
 }
 
+// UnmarshalJSON implements json.Unmarshaler for State.
+//
+// As per established convention this method should only ever
+// be invoked *indirectly* via [encoding/json] library.
 func (s *State) UnmarshalJSON(b []byte) error {
 	type rawState State
 	var state rawState

state_test.go

@@ -42,22 +42,44 @@ func TestStateValidate_raw(t *testing.T) {
 	}
 }
 
-func TestStateUnmarshal_valid(t *testing.T) {
-	f, err := os.Open("testdata/no_changes/state.json")
-	if err != nil {
-		t.Fatal(err)
+func TestStateUnmarshal(t *testing.T) {
+	testCases := map[string]struct {
+		filePath    string
+		expectError bool
+	}{
+		"valid state JSON": {
+			filePath: "testdata/no_changes/state.json",
+		},
+		"invalid state JSON": {
+			filePath:    "testdata/invalid/state.json",
+			expectError: true,
+		},
 	}
-	defer f.Close()
 
-	b, err := io.ReadAll(f)
-	if err != nil {
-		t.Fatal(err)
-	}
+	for tn, tc := range testCases {
+		t.Run(tn, func(t *testing.T) {
+			f, err := os.Open(tc.filePath)
+			if err != nil {
+				t.Fatal(err)
+			}
+			defer f.Close()
 
-	var state State
-	err = json.Unmarshal(b, &state)
-	if err != nil {
-		t.Fatal(err)
+			b, err := io.ReadAll(f)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			var state State
+			err = json.Unmarshal(b, &state)
+
+			if tc.expectError && err == nil {
+				t.Fatalf("expected error; got none")
+			}
+
+			if !tc.expectError && err != nil {
+				t.Errorf("expected no error, got %q", err.Error())
+			}
+		})
 	}
 }