{"id":29014836,"url":"https://github.com/arteam/jdit","last_synced_at":"2025-06-25T20:30:32.243Z","repository":{"id":26244833,"uuid":"29691830","full_name":"arteam/jdit","owner":"arteam","description":"JDBI Integration Testing","archived":false,"fork":false,"pushed_at":"2025-06-16T12:55:28.000Z","size":699,"stargazers_count":26,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-16T13:56:51.644Z","etag":null,"topics":["db","java","jdbi","unit-testing"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arteam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-01-22T17:53:55.000Z","updated_at":"2025-06-16T12:55:25.000Z","dependencies_parsed_at":"2023-02-13T02:16:09.726Z","dependency_job_id":"30f8d2ea-5efd-418f-9799-fd9b063049a6","html_url":"https://github.com/arteam/jdit","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/arteam/jdit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arteam%2Fjdit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arteam%2Fjdit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arteam%2Fjdit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arteam%2Fjdit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arteam","download_url":"https://codeload.github.com/arteam/jdit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arteam%2Fjdit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261948694,"owners_count":23234879,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["db","java","jdbi","unit-testing"],"created_at":"2025-06-25T20:30:28.861Z","updated_at":"2025-06-25T20:30:32.220Z","avatar_url":"https://github.com/arteam.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JDIT\n[![Build Status](https://travis-ci.org/arteam/jdit.svg?branch=master)](https://travis-ci.org/arteam/jdit)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.arteam/jdit/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.github.arteam/jdit/)\n\n## Overview\n\n*JDIT* is a library for simplifying of integration\ntesting of [*JDBI3*](https://jdbi.github.io/) data access objects\n\n## What it does\n\nThe library does the following things:\n\n* Supports *[HSQLDB](http://hsqldb.org/)*, *[PostgreSQL](https://www.postgresql.org/)*,\n*[MySQL](https://www.mysql.com/)*, *[H2](http://h2database.com)* databases;\n* Optionally migrates a user-defined sql schema;\n* The database and the DBI instance are shared between the tests, so they are\nperformed quickly;\n* Provides a *JUnit* runner for running DBI-related tests;\n* Supports injecting a DBI DAO or a SQL object to the current test\nby annotating a tested instance;\n* Supports injecting a `DBI` instance or an `Handle` instance to the\ncurrent test for performing SQL requests against the database;\n* Sweeps data from the database and reset sequences after every test.\nAll data changes performed in tests are discarded (but the schema\nremains), so the database is in the clean state before every test.\nIt affords to tests to be independent and don't impact to each other.\n* Supports executing of an arbitrary SQL script before every test\n(or set of tests) by specifying an annotation on a test method or\ntest class.\n\n## Getting started\n\n\n### Define a simple SQL Object to test\n\n\n````java\npublic interface PlayerDao {\n\n    @GetGeneratedKeys\n    @SqlUpdate(\"insert into players(first_name, last_name, birth_date, weight, height)\"\n            + \" values (:first_name, :last_name, :birth_date, :weight, :height)\")\n    Long createPlayer(@Bind(\"first_name\") String firstName,\n                      @Bind(\"last_name\") String lastName,\n                      @Bind(\"birth_date\") Date birthDate,\n                      @Bind(\"height\") int height, @Bind(\"weight\") int weight);\n\n    @SqlQuery(\"select last_name from players order by last_name\")\n    List\u003cString\u003e getPlayerLastNames();\n\n    @SqlQuery(\"select count(*) from players where year(birth_date) = :year\")\n    int getAmountPlayersBornInYear(@Bind(\"year\") int year);\n\n    @SqlQuery(\"select * from players where first_name=:first_name and \" +\n              \"last_name=:last_name\")\t      \n    Optional\u003cPlayer\u003e findPlayer(@Bind(\"first_name\") String firstName,\n                                @Bind(\"last_name\") String lastName);\n}\n````\n\n### Add Maven dependency\n\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.arteam\u003c/groupId\u003e\n    \u003cartifactId\u003ejdit\u003c/artifactId\u003e\n    \u003cversion\u003e0.8\u003c/version\u003e\n    \u003cscope\u003etest\u003c/scope\u003e\n\u003c/dependency\u003e\n```\n\n### Setup a database driver\n\nIf your test database is different from the production one, add a test database driver via Maven:\n\n```xml\n\u003cdependency\u003e\n\t\u003cgroupId\u003eorg.hsqldb\u003c/groupId\u003e\n\t\u003cartifactId\u003ehsqldb\u003c/artifactId\u003e\n\t\u003cversion\u003e2.3.3\u003c/version\u003e\n\t\u003cscope\u003etest\u003c/scope\u003e\n\u003c/dependency\u003e\n```\n\n### Create a test resources directory\n\nYou need to create a test resource directory to host resources.\nBy default it's '*src/test/resources*'.\n\nIf you want to use another directory, don't forget to set it in Maven as\na test resources directory in the *build* section:\n\n````xml\n\u003cbuild\u003e\n    \u003ctestResources\u003e\n        \u003ctestResource\u003e\n           \u003cdirectory\u003esrc/custom_test_resources\u003c/directory\u003e\n        \u003c/testResource\u003e\n    \u003c/testResources\u003e\n\u003c/build\u003e\n````\n\n### Define a database schema\n\nAdd a file with a database schema to your test resources directory.\nBy default it should have name *schema.sql*.\n\n````sql\ncreate table players(\n    id  identity,\n    first_name varchar(128) not null,\n    last_name varchar(128) not null,\n    birth_date date not null,\n    weight int not null,\n    height int not null\n);\n````\n\n### Write a test\n\n````java\n@ExtendWith(DBIExtension.class)\npublic class PlayerDaoTest {\n\n    @TestedSqlObject\n    PlayerDao playerDao;\n\n    @DBIHandle\n    Handle handle;\n\n    @Test\n    public void testCreatePlayer() {\n        Long playerId = playerDao.createPlayer(\"Vladimir\", \"Tarasenko\", date(\"1991-12-13\"), 184, 90);\n        List\u003cMap\u003cString,Object\u003e\u003e rows = handle.select(\"select * from players where id=?\", playerId);\n        assertFalse(rows.isEmpty());\n\n        Map\u003cString, Object\u003e row = rows.get(0);\n        assertEquals(0, row.get(\"id\"));\n        assertEquals(\"Vladimir\", row.get(\"first_name\"));\n        assertEquals(\"Tarasenko\", row.get(\"last_name\"));\n        assertEquals(date(\"1991-12-13\"), row.get(\"birth_date\"));\n        assertEquals(184, row.get(\"height\"));\n        assertEquals(90, row.get(\"weight\"));\n    }\n\n    private static Date date(String textDate) {\n        return ISODateTimeFormat.date().parseDateTime(textDate).toDate();\n    }\n}\n````\n\nYou should see  something like this in output:\n\n````\n23:57:30.091 [main] INFO  DBI - Handle [org.skife.jdbi.v2.BasicHandle@18cc8e9] obtained in 783 millis\n23:57:30.157 [main] INFO  DBI - batch:[[create table players(     id  identity,     first_name varchar(128) not null,     last_name varchar(128) not null,     birth_date date not null,     weight int not null,     height int not null )]] took 3 millis\n23:57:30.158 [main] INFO  DBI - Handle [org.skife.jdbi.v2.BasicHandle@18cc8e9] released\n23:57:30.159 [main] INFO  DBI - Handle [org.skife.jdbi.v2.BasicHandle@3dacfa] obtained in 0 millis\n23:57:30.639 [main] INFO  DBI - statement:[/* PlayerDao.createPlayer */ insert into players(first_name, last_name, birth_date, weight, height) values (?, ?, ?, ?, ?)] took 0 millis\n23:57:30.664 [main] INFO  DBI - statement:[select * from players where id=?] took 0 millis\n23:57:30.676 [main] INFO  DBI - statement:[TRUNCATE SCHEMA public RESTART IDENTITY AND COMMIT] took 0 millis\n23:57:30.679 [main] INFO  DBI - Handle [org.skife.jdbi.v2.BasicHandle@3dacfa] released\n````\n\nThings to notice:\n* Annotation `@RunWith` is crucial.  It makes the test aware of\na DBI context. Without it nothing will work.\n* Annotation `@TestedSqlObject` is used for marking a tested SQL object.\n* Annotation `@DBIHandle` is used for obtaining a reference to a handle\nto the active database for performing queries.\n* During a first invocation the schema has been migrated to the database.\nIt happens only once for all tests.\n* As you see from the logs, data was swept from the database after\nthe completion of the test. But the schema wasn't removed.\n\n### Load data before a test\n\nWrite a SQL DML script that populates the DB with needed data for testing.\n\nGive it a name, say, *playerDao/players.sql* and place it into the test resources\ndirectory.\n\n````sql\ninsert into players(first_name, last_name, birth_date, weight, height)\nvalues ('Vladimir','Tarasenko', '1991-12-13', 99, 184);\ninsert into players(first_name, last_name, birth_date, weight, height)\nvalues ('Tyler','Seguin', '1992-01-30', 88, 185);\ninsert into players(first_name, last_name, birth_date, weight, height)\nvalues ('Ryan','Ellis', '1991-01-03', 79, 176);\ninsert into players(first_name, last_name, birth_date, weight, height)\nvalues ('John','Tavares', '1990-09-20', 93, 185);\n````\n\nLoad this script before the test execution.\n\n````java\n@DataSet(\"playerDao/players.sql\")\n@Test\npublic void testGetPlayerListNames(){\n    List\u003cString\u003e playerLastNames = playerDao.getPlayerLastNames();\n    assertEquals(playerLastNames, ImmutableList.of(\"Ellis\", \"Seguin\", \"Tarasenko\", \"Tavares\"));\n}\n````\n\nAnnotation `@DataSet` is used for marking a script that should be loaded\nbefore a test.\n\nIf you find that you reuse the same data set for different tests, consider\nto place this annotation on a class level.\n\n````java\n@ExtendWith(DBIRunner.class)\n@DataSet(\"playerDao/players.sql\")\npublic class PlayerDaoTest {\n````\n\nIn this mode a script will be loaded for every method in the test.\nNevertheless, this script can be overridden by a method level annotation.\n\n## Configuration\n\n*JDIT* reads a configuration file of the following format:\n\n````properties\ndb.url=jdbc:hsqldb:mem:jdbi-testing\ndb.username=sa\ndb.password=\n\nschema.migration.enabled=true\nschema.migration.location=schema.sql\n\ndbi.factory=com.github.arteam.jdit.StandardDBIFactory\n````\n\n* _db.url_ - Database URL;\n* _db.username_ - Database username;\n* _db.password_ - Database password;\n* _schema.migration.enabled_ - Whether schema migration is enabled;\n* _schema.migration.location_ - Location of the database schema in\nresources;  If it's a directory, then all .sql files in the directory\nare processed as the schema;\n* _dbi.factory_ - Implementation of a factory for creating DBI instances.\n\nIf you need to override this configuration, you should place the\n*jdit.properties* file in your test resources directory with needed\nchanges.\n\nFor example, for overriding the schema location you should create a file\nwith following content:\n\n````properties\nschema.migration.location=db/migration\n````\n\nIf you need to specify properties for a specific test you can do it\nwith the `@JditProperties` annotation on the the test class level.\n\n## Examples\n\nMore examples available in a separate [repository](https://github.com/arteam/jdit-examples).\n\n## Dependencies\n\n* [JDBI3](https://jdbi.github.io/) 3.0.0-beta2\n* [JUnit](http://junit.org/) 5.9.1","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farteam%2Fjdit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farteam%2Fjdit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farteam%2Fjdit/lists"}