Skip to content

Commit 79631d5

Browse files
eddumelendezeddumelendez
committed
Merge pull request #149 from kazuki43zoo/create-doc-test-autoconfigure
* pr/149: Add doc for mybatis-spring-boot-test-autoconfigure
2 parents 6890cd0 + 5d7a8c9 commit 79631d5

File tree

2 files changed

+370
-0
lines changed

2 files changed

+370
-0
lines changed

‎mybatis-spring-boot-test-autoconfigure/src/site/site.xml

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
4+
Copyright 2015-2017 the original author or authors.
5+
6+
Licensed under the Apache License, Version 2.0 (the "License");
7+
you may not use this file except in compliance with the License.
8+
You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing, software
13+
distributed under the License is distributed on an "AS IS" BASIS,
14+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
See the License for the specific language governing permissions and
16+
limitations under the License.
17+
18+
-->
19+
<project name="${project.name}" xmlns="http://maven.apache.org/DECORATION/1.7.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
20+
xsi:schemaLocation="http://maven.apache.org/DECORATION/1.7.0 http://maven.apache.org/xsd/decoration-1.7.0.xsd">
21+
22+
<body>
23+
<menu name="Reference Documentation">
24+
<item name="Introduction" href="index.html"/>
25+
</menu>
26+
27+
<menu ref="reports"/>
28+
</body>
29+
</project>

‎mybatis-spring-boot-test-autoconfigure/src/site/xdoc/index.xml.vm

Lines changed: 341 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,341 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<!--
3+
4+
Copyright 2015-2017 the original author or authors.
5+
6+
Licensed under the Apache License, Version 2.0 (the "License");
7+
you may not use this file except in compliance with the License.
8+
You may obtain a copy of the License at
9+
10+
http://www.apache.org/licenses/LICENSE-2.0
11+
12+
Unless required by applicable law or agreed to in writing, software
13+
distributed under the License is distributed on an "AS IS" BASIS,
14+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
See the License for the specific language governing permissions and
16+
limitations under the License.
17+
18+
-->
19+
<document xmlns="http://maven.apache.org/XDOC/2.0"
20+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
21+
xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
22+
23+
<properties>
24+
<title>MyBatis Sring-Boot-Starter-Test | Reference Documentation</title>
25+
<author email="kazuki43zoo@gmail.com">Kazuki Shimizu</author>
26+
</properties>
27+
28+
<body>
29+
<section name="Introduction">
30+
<subsection name="What is MyBatis-Spring-Boot-Starter-Test?">
31+
32+
<p>The MyBatis-Spring-Boot-Starter-Test help creating a test cases for MyBatis component using the <a
33+
href="http://www.mybatis.org/spring-boot-starter/mybatis-spring-boot-autoconfigure/">
34+
MyBatis-Spring-Boot-Starter</a>.
35+
</p>
36+
37+
<p>By using this module you will can be:</p>
38+
39+
<ul>
40+
<li>Can use the <code>@MybatisTest</code> that setup test components for testing pure MyBatis
41+
component
42+
</li>
43+
<li>Can import dependency artifacts for performing tests for pure MyBatis component</li>
44+
</ul>
45+
46+
</subsection>
47+
48+
<subsection name="Requirements">
49+
<p>
50+
The MyBatis-Spring-Boot-Starter-Test requirements refer to <a
51+
href="http://www.mybatis.org/spring-boot-starter/mybatis-spring-boot-autoconfigure/#Requirements">
52+
here</a>.
53+
</p>
54+
</subsection>
55+
56+
<subsection name="Installation">
57+
<p>
58+
If you are using Maven just add the following dependency to your <code>pom.xml</code>:
59+
</p>
60+
<source><![CDATA[
61+
<dependency>
62+
<groupId>org.mybatis.spring.boot</groupId>
63+
<artifactId>mybatis-spring-boot-starter-test</artifactId>
64+
<version>${project.version}</version>
65+
</dependency>]]></source>
66+
67+
<p>
68+
If using gradle add this to your <code>build.gradle</code>:
69+
</p>
70+
<source><![CDATA[
71+
dependencies {
72+
compile("org.mybatis.spring.boot:mybatis-spring-boot-starter-test:${project.version}")
73+
}]]></source>
74+
75+
</subsection>
76+
77+
<subsection name="Using @MybatisTest">
78+
<p>
79+
The <code>@MybatisTest</code> can be used if you want to test MyBatis components(Mapper interface
80+
and <code>SqlSession</code>).
81+
By default it will configure MyBatis(MyBatis-Spring) components(<code>SqlSessionFactory
82+
</code> and <code>SqlSessionTemplate</code>), configure MyBatis mapper interfaces and configure an
83+
in-memory embedded database.
84+
MyBatis tests are transactional and rollback at the end of each test by default, for more details
85+
refer to the <a
86+
href="http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#testcontext-tx-enabling-transactions">
87+
relevant section in the Spring Reference Documentation</a>.
88+
Also regular <code>@Component</code> beans will not be loaded into the <code>
89+
ApplicationContext</code>.
90+
</p>
91+
92+
<h4>Test for Mapper interface:</h4>
93+
94+
<p>
95+
if you create a test case for following mapper interface, you add just <code>@MybatisTest</code> on
96+
your test case class.
97+
</p>
98+
99+
<p>
100+
Mapper interface :
101+
</p>
102+
103+
<source><![CDATA[
104+
package sample.mybatis.mapper;
105+
106+
import org.apache.ibatis.annotations.Mapper;
107+
import org.apache.ibatis.annotations.Param;
108+
import org.apache.ibatis.annotations.Select;
109+
import sample.mybatis.domain.City;
110+
111+
@Mapper
112+
public interface CityMapper {
113+
114+
@Select("SELECT * FROM CITY WHERE state = #{state}")
115+
City findByState(@Param("state") String state);
116+
117+
}]]></source>
118+
119+
<p>
120+
TestCase class :
121+
</p>
122+
123+
<source><![CDATA[
124+
package sample.mybatis.mapper;
125+
126+
import org.junit.Test;
127+
import org.junit.runner.RunWith;
128+
import org.mybatis.spring.boot.test.autoconfigure.MybatisTest;
129+
import sample.mybatis.domain.City;
130+
import org.springframework.beans.factory.annotation.Autowired;
131+
import org.springframework.test.context.junit4.SpringRunner;
132+
133+
import static org.assertj.core.api.Assertions.assertThat;
134+
135+
@RunWith(SpringRunner.class)
136+
@MybatisTest
137+
public class CityMapperTest {
138+
139+
@Autowired
140+
private CityMapper cityMapper;
141+
142+
@Test
143+
public void findByStateTest() {
144+
City city = cityMapper.findByState("CA");
145+
assertThat(city.getName()).isEqualTo("San Francisco");
146+
assertThat(city.getState()).isEqualTo("CA");
147+
assertThat(city.getCountry()).isEqualTo("US");
148+
}
149+
150+
}]]></source>
151+
152+
<h4>Test for DAO pattern:</h4>
153+
154+
<p>
155+
if you create a test case for following DAO class, you add just <code>@MybatisTest</code> and <code>@Import</code> on your test case class.
156+
</p>
157+
158+
<p>
159+
DAO class :
160+
</p>
161+
162+
<source><![CDATA[
163+
package sample.mybatis.dao;
164+
165+
import org.apache.ibatis.session.SqlSession;
166+
import sample.mybatis.domain.City;
167+
168+
import org.springframework.stereotype.Component;
169+
170+
@Component
171+
public class CityDao {
172+
173+
private final SqlSession sqlSession;
174+
175+
public CityDao(SqlSession sqlSession) {
176+
this.sqlSession = sqlSession;
177+
}
178+
179+
public City selectCityById(long id) {
180+
return this.sqlSession.selectOne("selectCityById", id);
181+
}
182+
183+
}]]></source>
184+
185+
<p>
186+
TestCase class :
187+
</p>
188+
189+
<source><![CDATA[
190+
package sample.mybatis.dao;
191+
192+
import org.junit.Test;
193+
import org.junit.runner.RunWith;
194+
import org.mybatis.spring.boot.test.autoconfigure.MybatisTest;
195+
import org.springframework.beans.factory.annotation.Autowired;
196+
import org.springframework.context.annotation.Import;
197+
import org.springframework.test.context.junit4.SpringRunner;
198+
import sample.mybatis.domain.City;
199+
200+
import static org.assertj.core.api.Assertions.assertThat;
201+
202+
@RunWith(SpringRunner.class)
203+
@MybatisTest
204+
@Import(CityDao.class)
205+
public class CityDaoTest {
206+
207+
@Autowired
208+
private CityDao cityDao;
209+
210+
@Test
211+
public void selectCityByIdTest() {
212+
City city = cityDao.selectCityById(1);
213+
assertThat(city.getName()).isEqualTo("San Francisco");
214+
assertThat(city.getState()).isEqualTo("CA");
215+
assertThat(city.getCountry()).isEqualTo("US");
216+
}
217+
218+
}]]></source>
219+
220+
</subsection>
221+
222+
<subsection name="Using a real database">
223+
<p>
224+
The In-memory embedded databases generally work well for tests since they are fast and don’t require
225+
any developer installation.
226+
However if you prefer to run tests against a real database, you can use the <code>@AutoConfigureTestDatabase</code> as follow:
227+
</p>
228+
229+
<source><![CDATA[
230+
package sample.mybatis.mapper;
231+
// ...
232+
import org.springframework.boot.test.autoconfigure.orm.jpa.AutoConfigureTestDatabase;
233+
234+
@RunWith(SpringRunner.class)
235+
@MybatisTest
236+
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
237+
public class CityMapperTest {
238+
// ...
239+
}]]></source>
240+
241+
</subsection>
242+
243+
<subsection name="Prevent detecting a real @SpringBootApplication">
244+
<p>
245+
The <code>@MybatisTest</code> will detect a class that annotated <code>@SpringBootApplication</code> by
246+
default.
247+
Therefore by depend on bean definition methods, there is case that an unexpected error is occurred
248+
or unnecessary components are loaded into <code>ApplicationContext</code>.
249+
This behavior can prevent by creating a <code>@SpringBootApplication</code> class into same package
250+
as test class as follow:
251+
</p>
252+
253+
<source><![CDATA[
254+
package sample.mybatis.mapper;
255+
256+
import org.springframework.boot.autoconfigure.SpringBootApplication;
257+
258+
@SpringBootApplication
259+
class MapperTestApplication {
260+
261+
}]]></source>
262+
</subsection>
263+
264+
<subsection name="Appendix A. Imported auto-configuration">
265+
266+
<p>
267+
The <code>@MybatisTest</code> will import following auto-configuration classes.
268+
</p>
269+
270+
<ul>
271+
<li>
272+
<code>org.springframework.boot.autoconfigure.cache.CacheAutoConfiguration</code>
273+
</li>
274+
<li>
275+
<code>org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration</code>
276+
</li>
277+
<li>
278+
<code>
279+
org.springframework.boot.autoconfigure.jdbc.DataSourceTransactionManagerAutoConfiguration
280+
</code>
281+
</li>
282+
<li>
283+
<code>org.springframework.boot.autoconfigure.jdbc.JdbcTemplateAutoConfiguration</code>
284+
</li>
285+
<li>
286+
<code>org.springframework.boot.autoconfigure.transaction.TransactionAutoConfiguration</code>
287+
</li>
288+
<li>
289+
<code>org.mybatis.spring.boot.autoconfigure.MybatisAutoConfiguration</code>
290+
</li>
291+
</ul>
292+
293+
</subsection>
294+
295+
<subsection name="Appendix B. Running Samples">
296+
<p>
297+
The project provides two samples so you play and experiment with them.
298+
</p>
299+
300+
<table>
301+
<thead>
302+
<tr>
303+
<th>
304+
Sample
305+
</th>
306+
<th>
307+
Description
308+
</th>
309+
</tr>
310+
</thead>
311+
<tbody>
312+
<tr>
313+
<td>
314+
<a href="https://github.com/mybatis/spring-boot-starter/tree/master/mybatis-spring-boot-samples/mybatis-spring-boot-sample-annotation">
315+
1st Sample
316+
</a>
317+
</td>
318+
<td>
319+
Show the simplest scenario with just a mapper and a bean where the mapper is injected
320+
into. This is the sample we saw in the Quick Setup section.
321+
</td>
322+
</tr>
323+
<tr>
324+
<td>
325+
<a href="https://github.com/mybatis/spring-boot-starter/tree/master/mybatis-spring-boot-samples/mybatis-spring-boot-sample-xml">
326+
2nd Sample
327+
</a>
328+
</td>
329+
<td>
330+
Shows how to use a Mapper that has its statements in an xml file and DAO that uses
331+
an <code>SqlSesionTemplate</code>.
332+
</td>
333+
</tr>
334+
</tbody>
335+
</table>
336+
337+
</subsection>
338+
</section>
339+
</body>
340+
341+
</document>

0 commit comments

Comments
 (0)