testndoc

WIP.

Package testndoc generates API documentation by listening to your tests.

Check a demo for Markdown here

Credits goes to test2doc for initial insipiration.

TODOS

add documentation generators
add tests
refactor code copied from test2doc
implement noop url params extractor
add doc to explain routers integration based on the existing one.

Install

Glide

mkdir -p $GOPATH/src/github.com/mh-cbon/testndoc
cd $GOPATH/src/github.com/mh-cbon/testndoc
git clone https://github.com/mh-cbon/testndoc.git .
glide install
go install

Supported routers

gorilla mux

Supported export format

md: a one-file github Markdown export with a TOC. demo
json: a one-file JSON export. demo

Test suite integration

To integrate the documentation generator to your tests,

Add a TestMain function, see the doc, to export the documentation once the tests finished.

func TestMain(m *testing.M) {
  exitCode := m.Run() // run the tests
	// if err := testndoc.Recorder.Save("../temp.json"); err != nil {
	// 	panic(err)
	// }
	apidoc, err2 := testndoc.Recorder.LoadMetadata()       // Load more metadata**
	if err2 != nil {
		panic(err2)
	}
	// export the documentation
	if err := md.Export(apidoc, "../api.md"); err != nil {
		panic(err)
	}
	// os.Remove("../temp.json")
	os.Exit(exitCode)
  //** Loading metadata require to parse your program,
  // which can be slow to run on every test execution.
  // Thus you might simply save the recorder to a temporary file,
  // Later, load it back, load metadata, export the doc.
  // That way of working is well suited for release based software delivery.
}

In your API test handlers, make use of a RouterProxy,

import (
  "github.com/gorilla/mux"
  "github.com/mh-cbon/testndoc/recorder"
)

// declare a router instance proxy, give it the proxied router, and an api recorder.
var router = recorder.NewMuxRouter(mux.NewRouter(), testndoc.Recorder)

// setup a regular test function
func TestMyEpApi(t *testing.T) {

  // Somewhere, setup a regular router.
  router.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("response"))
  })

  // Create a regular request.
  req, err := http.NewRequest("GET", "/", nil)
  if err != nil {
    panic(err)
  }

  // Create a regular ResponseRecorder.
  rr := httptest.NewRecorder()

  // Execute a regular request on the router.
  router.ServeHTTP(rr, req)

  // execute the test assertions
  // ....
}

Usage

All in one example

> main_test.go

package testndoc_test

import (
	"net/http"
	"net/http/httptest"

	"github.com/gorilla/mux"
	"github.com/mh-cbon/testndoc"
	"github.com/mh-cbon/testndoc/md"
	"github.com/mh-cbon/testndoc/recorder"
)

// Create a proxy router to listen the requests / responses.
var router = recorder.NewMuxRouter(mux.NewRouter(), testndoc.Recorder)

// Example ...
func Example() {

	// Setup regular route handlers.
	router.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("response"))
	})

	// Create a regular request.
	req, err := http.NewRequest("GET", "/", nil)
	if err != nil {
		panic(err)
	}

	// Create a regular ResponseRecorder.
	rr := httptest.NewRecorder()

	// Execute a regular request on the router.
	router.ServeHTTP(rr, req)

	// Later, generate the doc
	md.Export(testndoc.Recorder, "path/")
}

Recipes

Release the project

gump patch -d # check
gump patch # bump

mh-cbon / testndoc