New assertions and more flexible assertion calling. Also documentation and some tests.

README.md

@@ -1,45 +1,269 @@
-# Assert (c) Blake Mizerany and Keith Rarick -- MIT LICENCE
+## Simple assertions for Go tests
 
-## Assertions for Go tests
+This is a small collection of assertions to make Go tests more concise and readable.
 
-## Install
+## Repository contains two packages:
 
-    $ go get github.com/bmizerany/assert
+* **assert** - collection of assertion functions.
+* **assertmysql** - collection of assertion functions to test programs that are using *github.com/ziutek/mymysql/mysql* mysql client but not only.
 
-## Use
+If you don't use *github.com/ziutek/mymysql/mysql* in your program you can still use just **assert** package.
 
-**point.go**
+## Assertions
 
-    package point
+**assert.Equal**
 
-    type Point struct {
-        x, y int
-    }
+Asserts parameters are equal.
 
-**point_test.go**
+```go
+func Test_add(t *testing.T) {
+	exp := 3
+	got := add(1, 3)
 
+	assert.Equal(t, exp, got)
 
-    package point
+	// Test with optional comment
+	assert.Equal(t, exp, got, "Add function is broken.")
+}
+```
 
-    import (
-        "testing"
-        "github.com/bmizerany/assert"
-    )
+Parameters **exp** and **got** could be of any type.
 
-    func TestAsserts(t *testing.T) {
-        p1 := Point{1, 1}
-        p2 := Point{2, 1}
+**assert.NotEqual**
 
-        assert.Equal(t, p1, p2)
-    }
+Works the same way as *assert.Equal()* but asserts parameters are not equal.
 
-**output**
-    $ go test
-     --- FAIL: TestAsserts (0.00 seconds)
-	 assert.go:15: /Users/flavio.barbosa/dev/stewie/src/point_test.go:12
-         assert.go:24: ! X: 1 != 2
-	 FAIL
+**assert.Error**
 
-## Docs
+Asserts parameter is an instance of *error*.
 
-    http://github.com/bmizerany/assert
+```go
+func Test_Error(t *testing.T) {
+	file, err := getFile("/file/path")
+
+	assert.Error(err)
+
+	// Test with optional comment
+	assert.Error(t, err, "Expected file error.")
+}
+```
+
+**assert.NotError**
+
+Works the same way as *assert.Error()* but asserts parameter is not an *error*.
+
+**assert.Nil**
+
+Asserts parameter is nil.
+
+```go
+func Test_nil(t *testing.T) {
+	nilValue := doWork()
+
+	assert.Nil(nilValue)
+
+	// Test with optional comment
+	assert.Nil(t, nilValue, "Some comment")
+}
+```
+
+**assert.ErrorMsgContains**
+
+```go
+func Test_WTF(t *testing.T) {
+	err := errors.New("WTF?")
+	assert.ErrorMsgContains(t, err, "WTF")
+}
+```
+
+**assert.NotNil**
+
+Works the same way as *assert.Nil()* but asserts parameter is not a *nil* value.
+
+**assert.T**
+
+Asserts parameter is *true*.
+
+**assert.F**
+
+Asserts parameter is *false*.
+
+**assert.FileExists**
+
+Asserts file exists and is accessible.
+
+```go
+func Test_WTF(t *testing.T) {
+	testLog := "/some/path/testlog.log"
+	createLogFile(testLog)
+	assert.FileExists(t, testLog)
+}
+```
+
+**assert.EqualFuncPtr**
+
+Asserts two function pointers are pointing to the same function.
+
+```go
+func A() string {
+	return "A"
+}
+
+type T struct{
+	fn1: func() string
+	fn2: func() string
+}
+
+func Test_Ptr(t *testing.T) {
+	t := &T{A, A}
+	assert.EqualFuncPtr(t, t.fn1, t.fn2)
+
+	assert.FuncPtr(t, t.fn1)
+	assert.FuncPtr(t, t.fn2)
+}
+```
+
+**assert.FuncPtr**
+
+Asserts pointer is a function pointer. See previous example.
+
+**assert.Panic**
+
+Asserts function panics.
+
+```go
+func A() string {
+	panic("Not implemented")
+}
+
+
+func Test_Panic(t *testing.T) {
+
+	fn := func() {
+		A()
+	}
+
+	assert.Panic(t, fn, "Not implemented")
+}
+```
+
+## Assertion comments
+
+You may pass as many comments to assertions as you want. You can even use formating:
+
+```go
+assert.Equal(t, exp, got, "Add function is broken for input (%d,%d).", 1, 2)
+```
+
+## Failing fast / slow
+
+By default all the tests are failing slow. Meaning all the assertions in the test case are run. But sometimes you need to fail the test case on first error. This is how you are doing it:
+
+```go
+gotValue, err := doWork()
+assert.Equal(t, someTestStruct, gotValue, assert.FAIL_FAST, "Did not expect this.")
+assert.Equal(t, "expected", gotValue.field1)
+```
+
+In this case if first assertion fails the the whole test case fails and second assertion will never be run.
+
+## Example output
+
+	--- FAIL: Test_add (0.00 seconds)
+		assert.go:199: /golang/src/a/a_test.go:9
+		assert.go:212: ! 5 != 4
+	--- FAIL: Test_notEqual (0.00 seconds)
+		assert.go:199: /golang/src/a/a_test.go:14
+		assert.go:66: !  Values not supposed to be equal.
+		assert.go:67: !  1
+	--- FAIL: Test_nil (0.00 seconds)
+		assert.go:199: /golang/src/a/a_test.go:35
+		assert.go:166: Expected nil got "asdads"
+		assert.go:168: !  - Test comment
+		assert.go:199: /golang/src/a/a_test.go:36
+		assert.go:179: Did not expect nil
+		assert.go:181: !  - Some other test comment
+
+## Writing your own tests helpers or assertions
+
+See the code for **assertmysql** package which uses the **assert** package to implement its assertions.
+
+## Documentation
+
+* http://godoc.org/github.com/rzajac/assert/assert
+* http://godoc.org/github.com/rzajac/assert/assertmysql
+
+## Installation
+
+To install assertions run:
+
+    $ go get github.com/rzajac/assert
+
+## Import
+
+```go
+package my_package
+
+import (
+	"github.com/rzajac/assert/assert"
+	"github.com/rzajac/assert/assertmysql"
+)
+```
+
+This imports both packages but you can use only one of them.
+
+## MySQL assertions
+
+* **assertmysql.Error** - asserts MySQL error.
+* **assertmysql.NotError** - asserts error is not MySQL error.
+* **assertmysql.ErrorCode** - asserts error is MySQL error and has specific code.
+* **assertmysql.RowExists** - asserts row exists in a table.
+* **assertmysql.RowDoesNotExist** - asserts row does not exists in a table.
+* **assertmysql.TableExists** - asserts table exists in database.
+* **assertmysql.TableDoesNotExists** - asserts table does not exist in database.
+* **assertmysql.TableCount**  - asserts database has x tables.
+* **assertmysql.TableRowCount**  - asserts database table has x rows.
+* **assertmysql.TableNotEmpty** - asserts table is not empty (has at least one row).
+
+## MySQL helper functions
+
+* **assertmysql.GetMySqlError** - returns an error and returns *mysql.Error.
+* **assertmysql.GetTableNames** - returns an array of database table names.
+* **assertmysql.GetTableRowCount** - returns a number of rows in a table.
+* **assertmysql.DropTable** - drops table from database.
+* **assertmysql.TruncateTable** - truncates table.
+* **assertmysql.DropAllTables** - drops all tables from database.
+
+## Setup MySQL assertions package
+
+**mydb_test.go**
+
+```go
+package my_package
+
+import (
+	"github.com/rzajac/assert/assert"
+	"github.com/rzajac/assert/assertmysql"
+	"testing"
+)
+
+func init() {
+	assertmysql.InitMySqlAssertions("tcp", "", "localhost:3306", "test_user", "test_user_password", "test_database")
+}
+
+func Test_createMasterTable(t *testing.T) {
+	dropAllSqlTables(t)
+	err := createMasterTable()
+
+	assert.NotError(t, err)
+	assertmysql.TableExists(t, "master_table_name")
+	assertmysql.TableCount(t, 0)
+}
+```
+
+**You need only one *init* function per package.**
+
+## License
+
+Released under the MIT License.
+Assert (c) Blake Mizerany, Keith Rarick and Rafal Zajac <rzajac@gmail.com>