update package for godoc

sqlmock.go

@@ -1,3 +1,56 @@
+/*
+Package sqlmock provides sql driver mock connecection, which allows to test database,
+create expectations and ensure the correct execution flow of any database operations.
+It hooks into Go standard library's database/sql package.
+
+The package provides convenient methods to mock database queries, transactions and
+expect the right execution flow, compare query arguments or even return error instead
+to simulate failures. See the example bellow, which illustrates how convenient it is
+to work with:
+
+
+    package main
+
+    import (
+        "database/sql"
+        "github.com/DATA-DOG/go-sqlmock"
+        "testing"
+        "fmt"
+    )
+
+    // will test that order with a different status, cannot be cancelled
+    func TestShouldNotCancelOrderWithNonPendingStatus(t *testing.T) {
+        // open database stub
+        db, err := sql.Open("mock", "")
+        if err != nil {
+            t.Errorf("An error '%s' was not expected when opening a stub database connection", err)
+        }
+
+        // columns to be used for result
+        columns := []string{"id", "status"}
+        // expect transaction begin
+        sqlmock.ExpectBegin()
+        // expect query to fetch order, match it with regexp
+        sqlmock.ExpectQuery("SELECT (.+) FROM orders (.+) FOR UPDATE").
+            WithArgs(1).
+            WillReturnRows(sqlmock.RowsFromCSVString(columns, "1,1"))
+        // expect transaction rollback, since order status is "cancelled"
+        sqlmock.ExpectRollback()
+
+        // run the cancel order function
+        someOrderId := 1
+        // call a function which executes expected database operations
+        err = cancelOrder(someOrderId, db)
+        if err != nil {
+            t.Errorf("Expected no error, but got %s instead", err)
+        }
+        // db.Close() ensures that all expectations have been met
+        if err = db.Close(); err != nil {
+            t.Errorf("Error '%s' was not expected while closing the database", err)
+        }
+    }
+
+*/
 package sqlmock
 
 import (
@@ -11,7 +64,7 @@ var mock *mockDriver
 
 // Mock interface defines a mock which is returned
 // by any expectation and can be detailed further
-// with the following methods
+// with the methods this interface provides
 type Mock interface {
 	WithArgs(...driver.Value) Mock
 	WillReturnError(error) Mock
@@ -23,7 +76,6 @@ type mockDriver struct {
 	conn *conn
 }
 
-// opens a mock driver database connection
 func (d *mockDriver) Open(dsn string) (driver.Conn, error) {
 	return mock.conn, nil
 }
@@ -33,7 +85,7 @@ func init() {
 	sql.Register("mock", mock)
 }
 
-// expect transaction to be started
+// Expect transaction to be started
 func ExpectBegin() Mock {
 	e := &expectedBegin{}
 	mock.conn.expectations = append(mock.conn.expectations, e)
@@ -41,7 +93,7 @@ func ExpectBegin() Mock {
 	return mock.conn
 }
 
-// expect transaction to be commited
+// Expect transaction to be commited
 func ExpectCommit() Mock {
 	e := &expectedCommit{}
 	mock.conn.expectations = append(mock.conn.expectations, e)
@@ -49,7 +101,7 @@ func ExpectCommit() Mock {
 	return mock.conn
 }
 
-// expect transaction to be rolled back
+// Expect transaction to be rolled back
 func ExpectRollback() Mock {
 	e := &expectedRollback{}
 	mock.conn.expectations = append(mock.conn.expectations, e)
@@ -57,11 +109,14 @@ func ExpectRollback() Mock {
 	return mock.conn
 }
 
+// The expectation will return an error
 func (c *conn) WillReturnError(err error) Mock {
 	c.active.setError(err)
 	return c
 }
 
+// Expect database Exec to be triggered, which will match
+// the given query string as a regular expression
 func ExpectExec(sqlRegexStr string) Mock {
 	e := &expectedExec{}
 	e.sqlRegex = regexp.MustCompile(sqlRegexStr)
@@ -70,6 +125,8 @@ func ExpectExec(sqlRegexStr string) Mock {
 	return mock.conn
 }
 
+// Expect database Query to be triggered, which will match
+// the given query string as a regular expression
 func ExpectQuery(sqlRegexStr string) Mock {
 	e := &expectedQuery{}
 	e.sqlRegex = regexp.MustCompile(sqlRegexStr)
@@ -79,6 +136,8 @@ func ExpectQuery(sqlRegexStr string) Mock {
 	return mock.conn
 }
 
+// The expectation should be called with given arguments.
+// Works with Exec and Query expectations
 func (c *conn) WithArgs(args ...driver.Value) Mock {
 	eq, ok := c.active.(*expectedQuery)
 	if !ok {
@@ -93,6 +152,8 @@ func (c *conn) WithArgs(args ...driver.Value) Mock {
 	return c
 }
 
+// The expectation will return a Result.
+// Works only with Exec expectations
 func (c *conn) WillReturnResult(result driver.Result) Mock {
 	eq, ok := c.active.(*expectedExec)
 	if !ok {
@@ -102,6 +163,8 @@ func (c *conn) WillReturnResult(result driver.Result) Mock {
 	return c
 }
 
+// The expectation will return Rows.
+// Works only with Query expectations
 func (c *conn) WillReturnRows(rows driver.Rows) Mock {
 	eq, ok := c.active.(*expectedQuery)
 	if !ok {