diff --git a/jOOQ-website/src/main/resources/manual-3.0.xml b/jOOQ-website/src/main/resources/manual-3.0.xml index 3cb46cf7f6..403b370744 100644 --- a/jOOQ-website/src/main/resources/manual-3.0.xml +++ b/jOOQ-website/src/main/resources/manual-3.0.xml @@ -9187,6 +9187,122 @@ create.selectFrom(AUTHOR) +
+ JDBC mocking for unit testing + +

+ When writing unit tests for your data access layer, you have probably used some generic mocking tool offered by popular providers like Mockito, jmock, mockrunner, or even DBUnit. With jOOQ, you can take advantage of the built-in JDBC mock API that allows you to simulate a database on the JDBC level for precisely those SQL/JDBC use cases supported by jOOQ. +

+ +

Mocking the JDBC API

+

+ JDBC is a very complex API. It takes a lot of time to write a useful and correct mock implementation, implementing at least these interfaces: +

+
    +
    • +
    • +
    • +
    • +
    • +
    • +
+ +

+ Optionally, you may even want to implement interfaces, such as , , , and many others. In addition to the above, you might need to find a way to simultaneously support incompatible JDBC minor versions, such as 4.0, 4.1 +

+ +

Using jOOQ's own mock API

+

+ This work is greatly simplified, when using jOOQ's own mock API. The org.jooq.tools.jdbc package contains all the essential implementations for both JDBC 4.0 and 4.1, which are needed to mock JDBC for jOOQ. In order to write mock tests, provide the jOOQ with a , and implement the : +

+ + result = create.selectFrom(BOOK).where(BOOK.ID.equal(5)).fetch();]]> + +

+ As you can see, the configuration setup is simple. Now, the MockDataProvider acts as your single point of contact with JDBC / jOOQ. It unifies any of these execution modes, transparently: +

+ +
    +
  • Statements without results
    • +
  • Statements without results but with generated keys
    • +
  • Statements with results
    • +
  • Statements with several results
    • +
  • Batch statements with single queries and multiple bind value sets
    • +
  • Batch statements with multiple queries and no bind values
    • +
+ +

+ The above are the execution modes supported by jOOQ. Whether you're using any of jOOQ's various fetching modes (e.g. , , , ) is irrelevant, as those modes are all built on top of the standard JDBC API. +

+ +

Implementing MockDataProvider

+

+ Now, here's how to implement MockDataProvider: +

+ + result = create.newResult(AUTHOR); + result.add(create.newRecord(AUTHOR)); + result.get(0).setValue(AUTHOR.ID, 1); + result.get(0).setValue(AUTHOR.LAST_NAME, "Orwell"); + mock[0] = new MockResult(1, create.newResult(AUTHOR))); + } + + // You can detect batch statements easily + else if (ctx.isBatch()) { + // [...] + } + + return mock; + } +}]]> + +

+ Essentially, the contains all the necessary information for you to decide, what kind of data you should return. The wraps up two pieces of information: +

+
    +
  • : The number of affected rows
    • +
  • : The result set
    • +
+ +

+ You should return as many MockResult objects as there were query executions (in ) or results (in ). Instead of an awkward JDBC ResultSet, however, you can construct a "friendlier" with your own record types. The jOOQ mock API will use meta data provided with this Result in order to create the necessary JDBC +

+ +

+ See the for a list of rules that you should follow. +

+ +
+
jOOQ Console @@ -9838,8 +9954,8 @@ Condition condition3 = BOOK.TITLE.isNotDistinctFrom(possiblyNull);]]>
-
+ -->
Credits