1[](https://travis-ci.org/DATA-DOG/go-sqlmock)
2[](https://godoc.org/github.com/DATA-DOG/go-sqlmock)
3[](https://goreportcard.com/report/github.com/DATA-DOG/go-sqlmock)
4[](https://codecov.io/github/DATA-DOG/go-sqlmock)
5
6# Sql driver mock for Golang
7
8**sqlmock** is a mock library implementing [sql/driver](https://godoc.org/database/sql/driver). Which has one and only
9purpose - to simulate any **sql** driver behavior in tests, without needing a real database connection. It helps to
10maintain correct **TDD** workflow.
11
12- this library is now complete and stable. (you may not find new changes for this reason)
13- supports concurrency and multiple connections.
14- supports **go1.8** Context related feature mocking and Named sql parameters.
15- does not require any modifications to your source code.
16- the driver allows to mock any sql driver method behavior.
17- has strict by default expectation order matching.
18- has no third party dependencies.
19
20**NOTE:** in **v1.2.0** **sqlmock.Rows** has changed to struct from interface, if you were using any type references to that
21interface, you will need to switch it to a pointer struct type. Also, **sqlmock.Rows** were used to implement **driver.Rows**
22interface, which was not required or useful for mocking and was removed. Hope it will not cause issues.
23
24## Looking for maintainers
25
26I do not have much spare time for this library and willing to transfer the repository ownership
27to person or an organization motivated to maintain it. Open up a conversation if you are interested. See #230.
28
29## Install
30
31 go get github.com/DATA-DOG/go-sqlmock
32
33## Documentation and Examples
34
35Visit [godoc](http://godoc.org/github.com/DATA-DOG/go-sqlmock) for general examples and public api reference.
36See **.travis.yml** for supported **go** versions.
37Different use case, is to functionally test with a real database - [go-txdb](https://github.com/DATA-DOG/go-txdb)
38all database related actions are isolated within a single transaction so the database can remain in the same state.
39
40See implementation examples:
41
42- [blog API server](https://github.com/DATA-DOG/go-sqlmock/tree/master/examples/blog)
43- [the same orders example](https://github.com/DATA-DOG/go-sqlmock/tree/master/examples/orders)
44
45### Something you may want to test, assuming you use the [go-mysql-driver](https://github.com/go-sql-driver/mysql)
46
47``` go
48package main
49
50import (
51 "database/sql"
52
53 _ "github.com/go-sql-driver/mysql"
54)
55
56func recordStats(db *sql.DB, userID, productID int64) (err error) {
57 tx, err := db.Begin()
58 if err != nil {
59 return
60 }
61
62 defer func() {
63 switch err {
64 case nil:
65 err = tx.Commit()
66 default:
67 tx.Rollback()
68 }
69 }()
70
71 if _, err = tx.Exec("UPDATE products SET views = views + 1"); err != nil {
72 return
73 }
74 if _, err = tx.Exec("INSERT INTO product_viewers (user_id, product_id) VALUES (?, ?)", userID, productID); err != nil {
75 return
76 }
77 return
78}
79
80func main() {
81 // @NOTE: the real connection is not required for tests
82 db, err := sql.Open("mysql", "root@/blog")
83 if err != nil {
84 panic(err)
85 }
86 defer db.Close()
87
88 if err = recordStats(db, 1 /*some user id*/, 5 /*some product id*/); err != nil {
89 panic(err)
90 }
91}
92```
93
94### Tests with sqlmock
95
96``` go
97package main
98
99import (
100 "fmt"
101 "testing"
102
103 "github.com/DATA-DOG/go-sqlmock"
104)
105
106// a successful case
107func TestShouldUpdateStats(t *testing.T) {
108 db, mock, err := sqlmock.New()
109 if err != nil {
110 t.Fatalf("an error '%s' was not expected when opening a stub database connection", err)
111 }
112 defer db.Close()
113
114 mock.ExpectBegin()
115 mock.ExpectExec("UPDATE products").WillReturnResult(sqlmock.NewResult(1, 1))
116 mock.ExpectExec("INSERT INTO product_viewers").WithArgs(2, 3).WillReturnResult(sqlmock.NewResult(1, 1))
117 mock.ExpectCommit()
118
119 // now we execute our method
120 if err = recordStats(db, 2, 3); err != nil {
121 t.Errorf("error was not expected while updating stats: %s", err)
122 }
123
124 // we make sure that all expectations were met
125 if err := mock.ExpectationsWereMet(); err != nil {
126 t.Errorf("there were unfulfilled expectations: %s", err)
127 }
128}
129
130// a failing test case
131func TestShouldRollbackStatUpdatesOnFailure(t *testing.T) {
132 db, mock, err := sqlmock.New()
133 if err != nil {
134 t.Fatalf("an error '%s' was not expected when opening a stub database connection", err)
135 }
136 defer db.Close()
137
138 mock.ExpectBegin()
139 mock.ExpectExec("UPDATE products").WillReturnResult(sqlmock.NewResult(1, 1))
140 mock.ExpectExec("INSERT INTO product_viewers").
141 WithArgs(2, 3).
142 WillReturnError(fmt.Errorf("some error"))
143 mock.ExpectRollback()
144
145 // now we execute our method
146 if err = recordStats(db, 2, 3); err == nil {
147 t.Errorf("was expecting an error, but there was none")
148 }
149
150 // we make sure that all expectations were met
151 if err := mock.ExpectationsWereMet(); err != nil {
152 t.Errorf("there were unfulfilled expectations: %s", err)
153 }
154}
155```
156
157## Customize SQL query matching
158
159There were plenty of requests from users regarding SQL query string validation or different matching option.
160We have now implemented the `QueryMatcher` interface, which can be passed through an option when calling
161`sqlmock.New` or `sqlmock.NewWithDSN`.
162
163This now allows to include some library, which would allow for example to parse and validate `mysql` SQL AST.
164And create a custom QueryMatcher in order to validate SQL in sophisticated ways.
165
166By default, **sqlmock** is preserving backward compatibility and default query matcher is `sqlmock.QueryMatcherRegexp`
167which uses expected SQL string as a regular expression to match incoming query string. There is an equality matcher:
168`QueryMatcherEqual` which will do a full case sensitive match.
169
170In order to customize the QueryMatcher, use the following:
171
172``` go
173 db, mock, err := sqlmock.New(sqlmock.QueryMatcherOption(sqlmock.QueryMatcherEqual))
174```
175
176The query matcher can be fully customized based on user needs. **sqlmock** will not
177provide a standard sql parsing matchers, since various drivers may not follow the same SQL standard.
178
179## Matching arguments like time.Time
180
181There may be arguments which are of `struct` type and cannot be compared easily by value like `time.Time`. In this case
182**sqlmock** provides an [Argument](https://godoc.org/github.com/DATA-DOG/go-sqlmock#Argument) interface which
183can be used in more sophisticated matching. Here is a simple example of time argument matching:
184
185``` go
186type AnyTime struct{}
187
188// Match satisfies sqlmock.Argument interface
189func (a AnyTime) Match(v driver.Value) bool {
190 _, ok := v.(time.Time)
191 return ok
192}
193
194func TestAnyTimeArgument(t *testing.T) {
195 t.Parallel()
196 db, mock, err := sqlmock.New()
197 if err != nil {
198 t.Errorf("an error '%s' was not expected when opening a stub database connection", err)
199 }
200 defer db.Close()
201
202 mock.ExpectExec("INSERT INTO users").
203 WithArgs("john", AnyTime{}).
204 WillReturnResult(sqlmock.NewResult(1, 1))
205
206 _, err = db.Exec("INSERT INTO users(name, created_at) VALUES (?, ?)", "john", time.Now())
207 if err != nil {
208 t.Errorf("error '%s' was not expected, while inserting a row", err)
209 }
210
211 if err := mock.ExpectationsWereMet(); err != nil {
212 t.Errorf("there were unfulfilled expectations: %s", err)
213 }
214}
215```
216
217It only asserts that argument is of `time.Time` type.
218
219## Run tests
220
221 go test -race
222
223## Change Log
224
225- **2019-04-06** - added functionality to mock a sql MetaData request
226- **2019-02-13** - added `go.mod` removed the references and suggestions using `gopkg.in`.
227- **2018-12-11** - added expectation of Rows to be closed, while mocking expected query.
228- **2018-12-11** - introduced an option to provide **QueryMatcher** in order to customize SQL query matching.
229- **2017-09-01** - it is now possible to expect that prepared statement will be closed,
230 using **ExpectedPrepare.WillBeClosed**.
231- **2017-02-09** - implemented support for **go1.8** features. **Rows** interface was changed to struct
232 but contains all methods as before and should maintain backwards compatibility. **ExpectedQuery.WillReturnRows** may now
233 accept multiple row sets.
234- **2016-11-02** - `db.Prepare()` was not validating expected prepare SQL
235 query. It should still be validated even if Exec or Query is not
236 executed on that prepared statement.
237- **2016-02-23** - added **sqlmock.AnyArg()** function to provide any kind
238 of argument matcher.
239- **2016-02-23** - convert expected arguments to driver.Value as natural
240 driver does, the change may affect time.Time comparison and will be
241 stricter. See [issue](https://github.com/DATA-DOG/go-sqlmock/issues/31).
242- **2015-08-27** - **v1** api change, concurrency support, all known issues fixed.
243- **2014-08-16** instead of **panic** during reflect type mismatch when comparing query arguments - now return error
244- **2014-08-14** added **sqlmock.NewErrorResult** which gives an option to return driver.Result with errors for
245interface methods, see [issue](https://github.com/DATA-DOG/go-sqlmock/issues/5)
246- **2014-05-29** allow to match arguments in more sophisticated ways, by providing an **sqlmock.Argument** interface
247- **2014-04-21** introduce **sqlmock.New()** to open a mock database connection for tests. This method
248calls sql.DB.Ping to ensure that connection is open, see [issue](https://github.com/DATA-DOG/go-sqlmock/issues/4).
249This way on Close it will surely assert if all expectations are met, even if database was not triggered at all.
250The old way is still available, but it is advisable to call db.Ping manually before asserting with db.Close.
251- **2014-02-14** RowsFromCSVString is now a part of Rows interface named as FromCSVString.
252It has changed to allow more ways to construct rows and to easily extend this API in future.
253See [issue 1](https://github.com/DATA-DOG/go-sqlmock/issues/1)
254**RowsFromCSVString** is deprecated and will be removed in future
255
256## Contributions
257
258Feel free to open a pull request. Note, if you wish to contribute an extension to public (exported methods or types) -
259please open an issue before, to discuss whether these changes can be accepted. All backward incompatible changes are
260and will be treated cautiously
261
262## License
263
264The [three clause BSD license](http://en.wikipedia.org/wiki/BSD_licenses)
265
View as plain text