add tests for update-checks-doc tool

Author: rhysd

scripts/update-checks-doc/main.go

@@ -15,7 +15,7 @@ import (
 	"github.com/rhysd/actionlint"
 )
 
-func generatePermalink(src []byte) (string, error) {
+func GeneratePermalink(src []byte) (string, error) {
 	var out bytes.Buffer
 
 	b64 := base64.NewEncoder(base64.StdEncoding, &out)
@@ -45,7 +45,7 @@ func generatePermalink(src []byte) (string, error) {
 	return fmt.Sprintf("[Playground](https://rhysd.github.io/actionlint/#%s)", out.Bytes()), nil
 }
 
-func runActionlint(src []byte) ([]byte, error) {
+func Actionlint(src []byte) ([]byte, error) {
 	var out bytes.Buffer
 
 	opts := &actionlint.LinterOptions{
@@ -75,7 +75,7 @@ func runActionlint(src []byte) ([]byte, error) {
 	return b, nil
 }
 
-func update(in []byte) ([]byte, error) {
+func Update(in []byte) ([]byte, error) {
 	var buf bytes.Buffer
 
 	var input bytes.Buffer
@@ -84,6 +84,7 @@ func update(in []byte) ([]byte, error) {
 	var inputHeader bool
 	var outputHeader bool
 	var inInput bool
+	var skipOutput bool
 	var count int
 	lnum := 0
 	scan := bufio.NewScanner(bytes.NewReader(in))
@@ -103,6 +104,7 @@ func update(in []byte) ([]byte, error) {
 			inputHeader = false
 			outputHeader = false
 			inInput = false
+			skipOutput = false
 			count = 0
 		}
 		if strings.HasPrefix(l, `<a name="`) && strings.HasSuffix(l, `"></a>`) {
@@ -138,7 +140,7 @@ func update(in []byte) ([]byte, error) {
 					return nil, fmt.Errorf("output cannot be generated because example input for %q does not exist", section)
 				}
 				log.Printf("Generating output for the input example for %q at line %d", section, lnum)
-				out, err := runActionlint(input.Bytes())
+				out, err := Actionlint(input.Bytes())
 				if err != nil {
 					return nil, err
 				}
@@ -152,15 +154,16 @@ func update(in []byte) ([]byte, error) {
 		if l == "<!-- Skip update output -->" {
 			log.Printf("Skip updating output for %q due to the comment at line %d", section, lnum)
 			outputHeader = false
+			skipOutput = true
 		}
 		if strings.HasPrefix(l, "[Playground](https://rhysd.github.io/actionlint/#") && strings.HasSuffix(l, ")") {
 			if input.Len() == 0 {
 				return nil, fmt.Errorf("playground link cannot be generated because example input for %q does not exist", section)
 			}
-			if !outputHeader {
+			if !outputHeader && !skipOutput {
 				return nil, fmt.Errorf("output code block is missing for %q", section)
 			}
-			link, err := generatePermalink(input.Bytes())
+			link, err := GeneratePermalink(input.Bytes())
 			if err != nil {
 				return nil, err
 			}
@@ -175,12 +178,21 @@ func update(in []byte) ([]byte, error) {
 		if l == "<!-- Skip playground link -->" {
 			log.Printf("Skip generating playground link for %q due to the comment at line %d", section, lnum)
 			outputHeader = false
+			if input.Len() == 0 {
+				return nil, fmt.Errorf("example input for %q is empty", section)
+			}
 			input.Reset()
 			count++
 		}
 		buf.WriteString(l)
 		buf.WriteByte('\n')
 	}
+	if err := scan.Err(); err != nil {
+		return nil, err
+	}
+	if inInput {
+		return nil, fmt.Errorf("code block for example input for %q is not closed", section)
+	}
 	return buf.Bytes(), scan.Err()
 }
 
@@ -202,11 +214,11 @@ func Main(args []string) error {
 
 	in, err := os.ReadFile(path)
 	if err != nil {
-		return err
+		return fmt.Errorf("could not read the document file: %w", err)
 	}
 	log.Printf("Read %d bytes from %q", len(in), path)
 
-	out, err := update(in)
+	out, err := Update(in)
 	if err != nil {
 		return err
 	}
@@ -221,11 +233,7 @@ func Main(args []string) error {
 	}
 
 	log.Printf("Generate the updated content (%d bytes) for %q", len(out), path)
-	if err := os.WriteFile(path, out, 0666); err != nil {
-		return err
-	}
-
-	return nil
+	return os.WriteFile(path, out, 0666)
 }
 
 func main() {

scripts/update-checks-doc/main_test.go

@@ -0,0 +1,164 @@
+package main
+
+import (
+	"bytes"
+	"io"
+	"log"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+)
+
+// Disable trace logs while running tests. Commenting out this function is useful when debugging test cases.
+func init() {
+	log.SetOutput(io.Discard)
+}
+
+func must[T any](v T, err error) T {
+	if err != nil {
+		panic(err)
+	}
+	return v
+}
+
+func testErr(t *testing.T, err error, want ...string) {
+	t.Helper()
+	if err == nil {
+		t.Fatal("error did not occur")
+	}
+	msg := err.Error()
+	for _, w := range want {
+		if !strings.Contains(msg, w) {
+			t.Errorf("error message %q does not cotnain expected text %q", msg, w)
+		}
+	}
+}
+
+func TestMainGenerateOK(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("update-checks-doc doesn't support Windows")
+	}
+	root := t.TempDir()
+
+	in := must(os.Open(filepath.FromSlash("testdata/ok/minimal.in")))
+	path := filepath.FromSlash(root + "/minimal.in")
+	tmp := must(os.Create(path))
+	must(io.Copy(tmp, in))
+	in.Close()
+	tmp.Close()
+
+	if err := Main([]string{"exe", path}); err != nil {
+		t.Fatal(err)
+	}
+
+	want := must(os.ReadFile(filepath.FromSlash("testdata/ok/minimal.out")))
+	have := must(os.ReadFile(path))
+	if !bytes.Equal(want, have) {
+		t.Fatal(cmp.Diff(want, have))
+	}
+}
+
+func TestMainCheckOK(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("update-checks-doc doesn't support Windows")
+	}
+	path := filepath.FromSlash("testdata/ok/minimal.out")
+	if err := Main([]string{"exe", "-check", path}); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestMainCheckError(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("update-checks-doc doesn't support Windows")
+	}
+	path := filepath.FromSlash("testdata/ok/minimal.in")
+	testErr(t, Main([]string{"exe", "-check", path}), "checks document has some update")
+}
+
+func TestMainFileNotFound(t *testing.T) {
+	testErr(t, Main([]string{"exe", "-check", "this-file-does-not-exist.md"}), "could not read the document file")
+}
+
+func TestMainTooManyArgs(t *testing.T) {
+	testErr(t, Main([]string{"exe", "a", "b", "c"}), "usage: update-checks-doc [-check] FILE")
+}
+
+func TestMainInvalidCheckFlag(t *testing.T) {
+	testErr(t, Main([]string{"exe", "-c", "foo.md"}), "usage: update-checks-doc [-check] FILE")
+}
+
+func TestMainNoUpdate(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("update-checks-doc doesn't support Windows")
+	}
+	path := filepath.FromSlash("testdata/ok/minimal.out")
+	if err := Main([]string{"exe", path}); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestMainUpdateError(t *testing.T) {
+	path := filepath.FromSlash("testdata/err/no_playground_link.md")
+	if err := Main([]string{"exe", path}); err == nil {
+		t.Fatal("no error occurred")
+	}
+}
+
+func TestUpdateOK(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("update-checks-doc doesn't support Windows")
+	}
+
+	dir := filepath.FromSlash("testdata/ok")
+
+	tests := []string{}
+	for _, e := range must(os.ReadDir(dir)) {
+		n := e.Name()
+		if !strings.HasSuffix(n, ".in") {
+			continue
+		}
+		tests = append(tests, strings.TrimSuffix(n, filepath.Ext(n)))
+	}
+
+	for _, tc := range tests {
+		in := filepath.Join(dir, tc+".in")
+		out := filepath.Join(dir, tc+".out")
+		t.Run(tc, func(t *testing.T) {
+			have, err := Update(must(os.ReadFile(in)))
+			if err != nil {
+				t.Fatal(err)
+			}
+			want := must(os.ReadFile(out))
+			if !bytes.Equal(want, have) {
+				t.Fatal(cmp.Diff(want, have))
+			}
+		})
+	}
+}
+
+func TestUpdateError(t *testing.T) {
+	dir := filepath.FromSlash("testdata/err")
+
+	tests := []string{}
+	for _, e := range must(os.ReadDir(dir)) {
+		n := e.Name()
+		if !strings.HasSuffix(n, ".md") {
+			continue
+		}
+		tests = append(tests, strings.TrimSuffix(n, filepath.Ext(n)))
+	}
+
+	for _, tc := range tests {
+		path := filepath.Join(dir, tc+".md")
+		t.Run(tc, func(t *testing.T) {
+			if _, err := Update(must(os.ReadFile(path))); err == nil {
+				t.Fatal("no error occurred")
+			}
+		})
+	}
+}

scripts/update-checks-doc/testdata/err/empty_input.md

@@ -0,0 +1,13 @@
+<a name="hello"></a>
+## Hello
+
+Example input:
+
+```yaml
+```
+
+Output:
+
+```
+This section will be generated
+```

scripts/update-checks-doc/testdata/err/empty_input_with_skip_output.md

@@ -0,0 +1,16 @@
+<a name="hello"></a>
+## Hello
+
+Example input:
+
+```yaml
+```
+
+Output:
+<!-- Skip update output -->
+
+```
+This section will NOT be updated
+```
+
+[Playground](https://rhysd.github.io/actionlint/#THIS_URL_WILL_BE_UPDATED)

scripts/update-checks-doc/testdata/err/empty_input_with_skip_output_and_playground.md

@@ -0,0 +1,16 @@
+<a name="hello"></a>
+## Hello
+
+Example input:
+
+```yaml
+```
+
+Output:
+<!-- Skip update output -->
+
+```
+This section will NOT be updated
+```
+
+<!-- Skip playground link -->

scripts/update-checks-doc/testdata/err/empty_input_with_skip_playground.md

@@ -0,0 +1,15 @@
+<a name="hello"></a>
+## Hello
+
+Example input:
+
+```yaml
+```
+
+Output:
+
+```
+This section will be updated
+```
+
+<!-- Skip playground link -->

scripts/update-checks-doc/testdata/err/no_input.md

@@ -0,0 +1,10 @@
+<a name="hello"></a>
+## Hello
+
+Output:
+
+```
+This section will be generated
+```
+
+[Playground](https://rhysd.github.io/actionlint/#THIS_URL_WILL_BE_UPDATED)

scripts/update-checks-doc/testdata/err/no_input_with_skip_output.md

@@ -0,0 +1,11 @@
+<a name="hello"></a>
+## Hello
+
+Output:
+<!-- Skip update output -->
+
+```
+This section will NOT be updated
+```
+
+[Playground](https://rhysd.github.io/actionlint/#THIS_URL_WILL_BE_UPDATED)

scripts/update-checks-doc/testdata/err/no_input_with_skip_output_and_playground.md

@@ -0,0 +1,11 @@
+<a name="hello"></a>
+## Hello
+
+Output:
+<!-- Skip update output -->
+
+```
+This section will NOT be updated
+```
+
+<!-- Skip playground link -->

scripts/update-checks-doc/testdata/err/no_input_with_skip_playground.md

@@ -0,0 +1,10 @@
+<a name="hello"></a>
+## Hello
+
+Output:
+
+```
+This section will be updated
+```
+
+<!-- Skip playground link -->