test(godocfx): add golden test (#2881)

I did some minor refactoring of the write logic to take it out of `func main` and make it testable.

internal/godocfx/.gitignore

@@ -1,3 +1,4 @@
 obj/
 site/
 docfxgen
+testdata/out/

internal/godocfx/README.md

@@ -17,3 +17,13 @@ godocfx -print cloud.google.com/go/storage/...
 godocfx -out custom/output/dir cloud.google.com/go/...
 godocfx -rm custom/output/dir cloud.google.com/go/...
 ```
+
+## Testing
+
+You can run the tests with `go test`.
+
+If you need to update the golden files, add the `-update-goldens` flag:
+
+```
+go test -v -update-goldens
+```

internal/godocfx/godocfx_test.go

@@ -17,11 +17,23 @@
 package main
 
 import (
+	"flag"
+	"io/ioutil"
+	"os"
+	"path/filepath"
 	"testing"
 
 	_ "cloud.google.com/go/storage" // Implicitly required by test.
 )
 
+var updateGoldens bool
+
+func TestMain(m *testing.M) {
+	flag.BoolVar(&updateGoldens, "update-goldens", false, "Update the golden files")
+	flag.Parse()
+	os.Exit(m.Run())
+}
+
 func TestParse(t *testing.T) {
 	testPath := "cloud.google.com/go/storage"
 	pages, toc, module, err := parse(testPath)
@@ -67,3 +79,71 @@ func TestParse(t *testing.T) {
 		}
 	}
 }
+
+func TestGoldens(t *testing.T) {
+	gotDir := "testdata/out"
+	goldenDir := "testdata/golden"
+
+	testPath := "cloud.google.com/go/storage"
+	pages, toc, module, err := parse(testPath)
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+
+	ignoreFiles := map[string]bool{"docs.metadata": true}
+
+	if updateGoldens {
+		os.RemoveAll(goldenDir)
+
+		if err := write(goldenDir, pages, toc, module); err != nil {
+			t.Fatalf("write: %v", err)
+		}
+
+		for ignore := range ignoreFiles {
+			if err := os.Remove(filepath.Join(goldenDir, ignore)); err != nil {
+				t.Fatalf("Remove: %v", err)
+			}
+		}
+
+		t.Logf("Successfully updated goldens in %s", goldenDir)
+
+		return
+	}
+
+	if err := write(gotDir, pages, toc, module); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+
+	gotFiles, err := ioutil.ReadDir(gotDir)
+	if err != nil {
+		t.Fatalf("ReadDir: %v", err)
+	}
+
+	goldens, err := ioutil.ReadDir(goldenDir)
+	if err != nil {
+		t.Fatalf("ReadDir: %v", err)
+	}
+
+	if got, want := len(gotFiles)-len(ignoreFiles), len(goldens); got != want {
+		t.Fatalf("parse & write got %d files in %s, want %d ignoring %v", got, gotDir, want, ignoreFiles)
+	}
+
+	for _, golden := range goldens {
+		gotPath := filepath.Join(gotDir, golden.Name())
+		goldenPath := filepath.Join(goldenDir, golden.Name())
+
+		gotContent, err := ioutil.ReadFile(gotPath)
+		if err != nil {
+			t.Fatalf("ReadFile: %v", err)
+		}
+
+		goldenContent, err := ioutil.ReadFile(goldenPath)
+		if err != nil {
+			t.Fatalf("ReadFile: %v", err)
+		}
+
+		if string(gotContent) != string(goldenContent) {
+			t.Errorf("got %s is different from expected %s", gotPath, goldenPath)
+		}
+	}
+}

internal/godocfx/main.go

@@ -45,6 +45,7 @@ import (
 	"strings"
 	"time"
 
+	"golang.org/x/tools/go/packages"
 	"gopkg.in/yaml.v2"
 )
 
@@ -76,8 +77,15 @@ func main() {
 	if *rm {
 		os.RemoveAll(*outDir)
 	}
-	if err := os.MkdirAll(*outDir, os.ModePerm); err != nil {
-		log.Fatalf("os.MkdirAll: %v", err)
+
+	if err := write(*outDir, pages, toc, module); err != nil {
+		log.Fatalf("write: %v", err)
+	}
+}
+
+func write(outDir string, pages map[string]*page, toc tableOfContents, module *packages.Module) error {
+	if err := os.MkdirAll(outDir, os.ModePerm); err != nil {
+		return fmt.Errorf("os.MkdirAll: %v", err)
 	}
 	for path, p := range pages {
 		// Make the module root page the index.
@@ -86,29 +94,29 @@ func main() {
 		}
 		// Trim the module path from all other paths.
 		path = strings.TrimPrefix(path, module.Path+"/")
-		path = filepath.Join(*outDir, path+".yml")
+		path = filepath.Join(outDir, path+".yml")
 		if err := os.MkdirAll(filepath.Dir(path), os.ModePerm); err != nil {
-			log.Fatalf("os.MkdirAll: %v", err)
+			return fmt.Errorf("os.MkdirAll: %v", err)
 		}
 		f, err := os.Create(path)
 		if err != nil {
-			log.Fatal(err)
+			return err
 		}
 		defer f.Close()
 		fmt.Fprintln(f, "### YamlMime:UniversalReference")
 		if err := yaml.NewEncoder(f).Encode(p); err != nil {
-			log.Fatal(err)
+			return err
 		}
 
-		path = filepath.Join(*outDir, "toc.yml")
+		path = filepath.Join(outDir, "toc.yml")
 		f, err = os.Create(path)
 		if err != nil {
-			log.Fatal(err)
+			return err
 		}
 		defer f.Close()
 		fmt.Fprintln(f, "### YamlMime:TableOfContent")
 		if err := yaml.NewEncoder(f).Encode(toc); err != nil {
-			log.Fatal(err)
+			return err
 		}
 	}
 
@@ -124,10 +132,10 @@ func main() {
 		version: "v0.65.0"
 		language: "go"
 	*/
-	path := filepath.Join(*outDir, "docs.metadata")
+	path := filepath.Join(outDir, "docs.metadata")
 	f, err := os.Create(path)
 	if err != nil {
-		log.Fatal(err)
+		return err
 	}
 	defer f.Close()
 	now := time.Now().UTC()
@@ -138,4 +146,5 @@ func main() {
 name: %q
 version: %q
 language: "go"`, now.Unix(), now.Nanosecond(), module.Path, module.Version)
+	return nil
 }