<commit_before>gophertron
==========

This package is just the code for a short talk on Go's coverage testing & the [httptest](http://golang.org/pkg/net/http/httptest/) package. I'll probably keep adding features for future discussions.

Gophertron is a JSON API for spawning, mutating, zapping & kapowing gophers.

Pre-requisite: install Go. Now install & run gophertron:

	go get github.com/laher/gophertron
	gophertron

To test, cd into the gophertron/gophers directory, and run `go test .`. 

Coverage isn't the be-all and end-all: there's a bug which has been intentionally left uncaptured by the tests, and won't be captured by coverage testing. See `Gopher.Kapow()`. 


httptest
--------

httptest is a small package providing 2 utilities for testing HTTP functionality. 
 
 * ResponseRecorder helps you test your http handlers. Sample code is in gophers/gopher_api_test.go. [httptest.ResponseRecorder](http://golang.org/pkg/net/http/httptest/#ResponseRecorder) implements the [http.ResponseWriter](http://golang.org/pkg/net/http/#ResponseWriter) interface, so that you can pass it to any http handler.
 * The second utility is an actual server. The system chooses a port itself, and supplies information for connecting. I haven't included examples here.

Note that my use of ResponseRecorder is for Martini handlers rather than actual [http.HandlerFunc](http://golang.org/pkg/net/http/#HandlerFunc)s, but the idea is the same.

Code Coverage
-------------

For coverage testing, you'll need to install go's coverage tooling, part of the 'go.tools' repo:

	go get code.google.com/p/go.tools/cmd/cover

(If you don't have it, the `go` tool will tell you where to get it as above).

At its most basic level, you can just run `go test -cover .`. This gives you percentages.

Now you can either run ./cover.sh, or the following (for Windows you'll need to change the location of the cover.out file):

	go test -coverprofile=/tmp/cover.out .
	go tool cover -func=/tmp/cover.out
	go tool cover -html=/tmp/cover.out

You can also [visit gocover.io to see the coverage report](http://gocover.io/github.com/laher/gophertron/gophers) ![coverage status](http://gocover.io/_badge/github.com/laher/gophertron/gophers?)


Reading on Go coverage testing:

 * [Go 1.2 Announcement](http://golang.org/doc/go1.2#cover)
 * [The cover story](http://blog.golang.org/cover)


### Go's own code coverage

Here's the output of coverage testing from go's source tree (v1.3):


	../go-1.3/src/pkg$ go test -cover ./...
	ok  	archive/tar	0.020s	coverage: 84.8% of statements
	ok  	archive/zip	13.773s	coverage: 85.6% of statements
	ok  	bufio	0.103s	coverage: 89.2% of statements
	?   	builtin	[no test files]
	ok  	bytes	1.530s	coverage: 94.8% of statements
	ok  	compress/bzip2	0.073s	coverage: 88.1% of statements
	ok  	compress/flate	18.315s	coverage: 91.1% of statements
	ok  	compress/gzip	0.035s	coverage: 84.5% of statements<commit_msg>updating readme<commit_after>gophertron
==========

This package is just the code for a short talk on Go's coverage testing & the [httptest](http://golang.org/pkg/net/http/httptest/) package. I'll probably keep adding features for future discussions.

Gophertron is a JSON API for spawning, mutating, zapping & kapowing gophers. The app depends on [martini](http://martini.codegangsta.io/) and [mgo](http://labix.org/mgo), and assumes a local Mongodb installation for running the server (but not for testing).

### Installation

Pre-requisite: install Go. Make sure your GOPATH is set.

Now install gophertron:

	go get github.com/laher/gophertron

### Running Gophertron

Pre-requisite: install mongodb. 

Now run gophertron:

	gophertron

### Running tests

To test, cd into the gophertron/gophers directory, and run:

	go test .



httptest
--------

httptest is a small package providing 2 utilities for testing HTTP functionality. 
 
 * ResponseRecorder helps you test your http handlers. Sample code is in gophers/gopher_api_test.go. [httptest.ResponseRecorder](http://golang.org/pkg/net/http/httptest/#ResponseRecorder) implements the [http.ResponseWriter](http://golang.org/pkg/net/http/#ResponseWriter) interface, so that you can pass it to any http handler.
 * The second utility is an actual server. The system chooses a port itself, and supplies information for connecting. I haven't included examples here.

Note that my use of ResponseRecorder is for Martini handlers rather than actual [http.HandlerFunc](http://golang.org/pkg/net/http/#HandlerFunc)s, but the idea is the same.

Code Coverage
-------------

For coverage testing, you'll need to install go's coverage tooling, part of the 'go.tools' repo:

	go get code.google.com/p/go.tools/cmd/cover

(If you don't have it, the `go` tool will tell you where to get it as above).

At its most basic level, you can just run `go test -cover .`. This gives you percentages.

Now you can either run ./cover.sh, or the following (for Windows you'll need to change the location of the cover.out file):

	go test -coverprofile=/tmp/cover.out .
	go tool cover -func=/tmp/cover.out
	go tool cover -html=/tmp/cover.out

You can also [visit gocover.io to see the coverage report](http://gocover.io/github.com/laher/gophertron/gophers) ![coverage status](http://gocover.io/_badge/github.com/laher/gophertron/gophers?)

Finally, coverage isn't the be-all and end-all: there's a bug which has been intentionally left uncaptured by the tests, and won't be captured by coverage testing. See `Gopher.Kapow()` is a non-pointer method trying to modify the object. Pointers, yes. Sorry to alarm you, but it's good to get familiar with pointers in Go - not nearly as scary as it sounds. 

Reading on Go coverage testing:

 * [Go 1.2 Announcement](http://golang.org/doc/go1.2#cover)
 * [The cover story](http://blog.golang.org/cover)


### Go's own code coverage

Here's the output of coverage testing from go's source tree (v1.3):


	../go-1.3/src/pkg$ go test -cover ./...
	ok  	archive/tar	0.020s	coverage: 84.8% of statements
	ok  	archive/zip	13.773s	coverage: 85.6% of statements
	ok  	bufio	0.103s	coverage: 89.2% of statements
	?   	builtin	[no test files]
	ok  	bytes	1.530s	coverage: 94.8% of statements
	ok  	compress/bzip2	0.073s	coverage: 88.1% of statements
	ok  	compress/flate	18.315s	coverage: 91.1% of statements
	ok  	compress/gzip	0.035s	coverage: 84.5% of statements
{'fraction_non_alphanumeric': 0.10544538873150772, 'fraction_numerical': 0.019200503619767075, 'mean_word_length': 3.8585626911314983, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1578319', 'n_tokens_mistral': 2172, 'n_tokens_neox': 1965, 'n_words': 768}