From 6f1be66c439224d48fdee51e411bd0815f7a9e57 Mon Sep 17 00:00:00 2001 From: gedi Date: Fri, 7 Feb 2014 10:44:41 +0200 Subject: [PATCH] update package for godoc --- README.md | 7 ++++-- result.go | 10 ++++---- rows.go | 4 +-- sqlmock.go | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 4 files changed, 80 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index f5a6778..672ecc7 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ This is a **mock** driver as **database/sql/driver** which is very flexible and pragmatic to manage and mock expected queries. All the expectations should be met and all queries and actions -triggered should be mocked in order to pass a test. +triggered should be mocked in order to pass a test. See exported [api on godoc](http://godoc.org/github.com/DATA-DOG/go-sqlmock) ## Install @@ -285,9 +285,12 @@ to compare them correctly, this may be improved. go test +## Documentation + +See it on [godoc](http://godoc.org/github.com/DATA-DOG/go-sqlmock) + ## TODO -- export to godoc - handle argument comparison more efficiently ## Contributions diff --git a/result.go b/result.go index 5f2c447..190c29b 100644 --- a/result.go +++ b/result.go @@ -1,14 +1,14 @@ package sqlmock -// a structure which implements database/sql/driver.Result +// Result satisfies sql driver Result, which // holds last insert id and rows affected -// should be returned by Exec queries +// by Exec queries type Result struct { lastInsertId int64 rowsAffected int64 } -// creates a new result for Exec based query mocks +// Creates a new Result for Exec based query mocks func NewResult(lastInsertId int64, rowsAffected int64) *Result { return &Result{ lastInsertId, @@ -16,12 +16,12 @@ func NewResult(lastInsertId int64, rowsAffected int64) *Result { } } -// get last insert id +// Retrieve last inserted id func (res *Result) LastInsertId() (int64, error) { return res.lastInsertId, nil } -// get rows affected +// Retrieve number rows affected func (res *Result) RowsAffected() (int64, error) { return res.rowsAffected, nil } diff --git a/rows.go b/rows.go index fd08c80..a0bd3b3 100644 --- a/rows.go +++ b/rows.go @@ -40,8 +40,8 @@ func (r *rows) Next(dest []driver.Value) error { return nil } -// create rows from a csv string -// to be used for mocked queries +// Create Rows from CSV string +// to be used for mocked queries. Satisfies sql driver Rows interface func RowsFromCSVString(columns []string, s string) driver.Rows { rs := &rows{} rs.cols = columns diff --git a/sqlmock.go b/sqlmock.go index 9fde320..b76c3b8 100644 --- a/sqlmock.go +++ b/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 {