This project implements a Groovy DSL that can be used to populate a database using JPA entities. Its indented use is testing but it could be used in other scenarios as well.
The DSL is implemented in Groovy but can be used from pure Java. Entities are modularly defined in separate .groovy files using the DSL syntax. Those entity definition files can then be loaded as needed using the de.triology.blog.testdata.loader.TestDataLoader
, which also provides access to loaded entities. Thus, the client code does not need to deal with any database or JPA specific concerns other than providing an initialized EntityManager.
This project was started while working on an article published in Java aktuell 03/2017:
A Groovy DSL for the Creation of Test Data using JPA.
The original article (🇩🇪) can be found here: Eine Groovy-DSL zum Erzeugen von Testdaten über JPA.
Please note that from version 1.x the implementation as described in the article referenced above has changed. For more information about the changes, please refer to the release notes of each release.
Add the latest stable version of test-data-loader to the dependency management tool of your choice.
E.g. for maven
<dependency>
<groupId>de.triology.test-data-loader</groupId>
<artifactId>test-data-loader</artifactId>
<version>1.0.0</version>
</dependency>
You can get snapshot versions from maven central (for the most recent commit on develop branch) or via JitPack (note that JitPack uses different maven coordinates).
An example entity definition Groovy script file can be found here: https://github.com/triologygmbh/test-data-loader/blob/master/src/test/resources/tests/itTestData.groovy
The de.triology.blog.testdata.loader.TestDataLoaderIT
integration test shows how to load that file.
Use the following syntax in a separate .groovy file to define a User
entity. The entity will be created, persisted and registered under the name "Peter" when the definition file is loaded. Note: Entity definition files are expected to be UTF-8 encoded.
import de.triology.blog.testdata.loader.testentities.User
create User, 'Peter', {
id = 123
firstName = 'Peter'
lastName = 'Pan'
login = 'pete'
email = 'peter.pan@example.com'
}
Create nested entities by simply nesting their definitions:
import de.triology.blog.testdata.loader.testentities.User
import de.triology.blog.testdata.loader.testentities.Department
create User, 'Peter', {
// ...
department = create Department, 'lostBoys', {
id = 999
name = 'The Lost Boys'
}
}
And reference previously created entities by their name like so:
import de.triology.blog.testdata.loader.testentities.User
import de.triology.blog.testdata.loader.testentities.Department
create User, 'Peter', {
// ...
department = create Department, 'lostBoys', {
// ...
head = Peter
}
}
create User, 'Tinker', {
id = 555
firstName = 'Tinker'
lastName = 'Bell'
department = lostBoys
}
Since entity definition files are just plain Groovy scripts, you are free to use any control structures, like loops and conditions, e.g.:
import de.triology.blog.testdata.loader.testentities.User
5.times { count ->
create User, "user_$count", {
id = 1000 + count
if(count % 2 == 0) {
firstName = "even_$count"
} else {
firstName = "odd_$count"
}
}
}
Private fields from superclasses
For now, we must work around this, by setting the field to protected
or creating a protected
setter method.
See this issue.
Use the de.triology.blog.testdata.loader.TestDataLoader
to load entity definition files (from classpath or file system) and persist the defined entities.
The TestDataLoader
requires a fully initialized, ready-to-use EntityManager
and can then be used to load entity definition files and access the persisted entities.
EntityManager entityManager = // ... init EntityManager
TestDataLoader testDataLoader = new TestDataLoader(entityManager);
testDataLoader.loadTestData(Collections.singletonList("demo/testData.groovy"));
User peter = entityManager.find(User.class, 123L);
assert "Pan".equals(peter.getLastName());
User tinker = testDataLoader.getEntityByName("Tinker", User.class);
assert "Bell".equals(tinker.getLastName());
To reset the database as well as the TestDataLoader to a clean state after a test case simply call testDataLoader.clear()
. That will delete all created entities from the database and from TestDataLoader's entity cache.
We have approved TestDataLoader in multiple projects and use cases including
- "unit" tests with H2 and JUnit
- Integration test with arquillian, WildFly (Swarm) and Postgresql
- Integration tests with arquillian, IBM WebSphere Liberty Profile and IBM DB2
The test-data-loader has been derived and generalized from real world development projects but has yet to prove itself as stand-alone library. Any feedback or contributions are highly welcome!