From 6e3eec1e7274ec1ef9992299c07b038d61a76415 Mon Sep 17 00:00:00 2001
From: Miek Gieben <miek@miek.nl>
Date: Sun, 10 Sep 2017 19:52:15 +0100
Subject: [PATCH] documention: test README snippets (#1043)

If a README has a corefile snippet that is annotated with `corefile`,
this test will parse the instance and checks the snippet is legal.
This means a) we will get better docs b) we know for sure everything
still parses.

The test parses everything in middleware/*/README.md, it does not check
for README presence, just Corefile snippets. The port used is 10053 and
overrides whatever port is set in the docs.

The secondary middleware was used as an example and adds two examples
that should parse.

failures show up as:

~~~
--- FAIL: TestReadme (0.04s)
	readme_test.go:50: Testing ../middleware/secondary/README.md, with 100 byte snippet
	readme_test.go:50: Testing ../middleware/secondary/README.md, with 93 byte snippet
	readme_test.go:53: Failed to start server for input "middleware/secondary: Corefile:3 - Error during parsing: unknown property 'transfeT'":
		. {
		    secondary example.net {
		        transfeT from 10.1.2.1
		        transfer to *
		    }
		}
FAIL
~~~
---
 middleware/secondary/README.md | 23 ++++++--
 test/readme_test.go            | 99 ++++++++++++++++++++++++++++++++++
 2 files changed, 118 insertions(+), 4 deletions(-)
 create mode 100644 test/readme_test.go

diff --git a/middleware/secondary/README.md b/middleware/secondary/README.md
index 7d5338c95..d6cbe465a 100644
--- a/middleware/secondary/README.md
+++ b/middleware/secondary/README.md
@@ -31,9 +31,24 @@ secondary [zones...] {
 
 ## Examples
 
-~~~
-secondary example.org {
-    transfer from 10.0.1.1
-    transfer from 10.1.2.1
+Transfer `example.org` from 10.0.1.1, and if that fails try 10.1.2.1.
+
+~~~ corefile
+example.org {
+    secondary {
+        transfer from 10.0.1.1
+        transfer from 10.1.2.1
+    }
+}
+~~~
+
+Or re-export the retrieved zone to other secondaries.
+
+~~~ corefile
+. {
+    secondary example.net {
+        transfer from 10.1.2.1
+        transfer to *
+    }
 }
 ~~~
diff --git a/test/readme_test.go b/test/readme_test.go
new file mode 100644
index 000000000..f231ebc5a
--- /dev/null
+++ b/test/readme_test.go
@@ -0,0 +1,99 @@
+package test
+
+import (
+	"bufio"
+	"io/ioutil"
+	"log"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/coredns/coredns/core/dnsserver"
+
+	"github.com/mholt/caddy"
+)
+
+// Pasrse all README.md's of the middleware and check if every example Corefile
+// actually works. Each corefile is only used if:
+//
+// ~~~ corefile
+// . {
+//	# check-this-please
+// }
+// ~~~
+
+func TestReadme(t *testing.T) {
+	caddy.Quiet = true
+	dnsserver.Quiet = true
+	dnsserver.Port = "10053"
+	log.SetOutput(ioutil.Discard)
+
+	middle := filepath.Join("..", "middleware")
+	dirs, err := ioutil.ReadDir(middle)
+	if err != nil {
+		t.Fatalf("Could not read %s: %q", middle, err)
+	}
+	for _, d := range dirs {
+		if !d.IsDir() {
+			continue
+		}
+		readme := filepath.Join(middle, d.Name())
+		readme = filepath.Join(readme, "README.md")
+
+		inputs, err := corefileFromReadme(readme)
+		if err != nil {
+			continue
+		}
+
+		// Test each snippet.
+		for _, in := range inputs {
+			t.Logf("Testing %s, with %d byte snippet", readme, len(in.Body()))
+			server, err := caddy.Start(in)
+			if err != nil {
+				t.Errorf("Failed to start server for input %q:\n%s", err, in.Body())
+			}
+			server.Stop()
+		}
+	}
+}
+
+// corefileFromReadme parses a readme and returns all fragments that
+// have ~~~ corefile (or ``` corefile).
+func corefileFromReadme(readme string) ([]*Input, error) {
+	f, err := os.Open(readme)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+
+	s := bufio.NewScanner(f)
+	input := []*Input{}
+	corefile := false
+	temp := ""
+
+	for s.Scan() {
+		line := s.Text()
+		if line == "~~~ corefile" || line == "``` corefile" {
+			corefile = true
+			continue
+		}
+
+		if corefile && (line == "~~~" || line == "```") {
+			// last line
+			input = append(input, NewInput(temp))
+
+			temp = ""
+			corefile = false
+			continue
+		}
+
+		if corefile {
+			temp += line + "\n" // readd newline stripped by s.Text()
+		}
+	}
+
+	if err := s.Err(); err != nil {
+		return nil, err
+	}
+	return input, nil
+}