Hibernate JUnit Infastructure

sebersole edited this page Nov 28, 2012 · 1 revision

The Hibernate team have developed some extensions to JUnit 4 that are used in the Hibernate ORM testsuite. Those extensions are covered here. It is also important to understand the notion of matrix (multi-db) testing as discussed here. Everything discussed here is part of the hibernate-testing module.

BaseUnitTestCase versus BaseCoreFunctionalTestCase

org.hibernate.testing.junit4.BaseCoreFunctionalTestCase is meant for typical functional testing scenarios where the test needs to build a single SessionFactory and perform some tests using that SessionFactory. BaseCoreFunctionalTestCase provides convenience methods for building the SessionFactory from various settings, mappings and annotated classes.

org.hibernate.testing.junit4.BaseUnitTestCase is meant for typical unit testing scenarios, although support for any kind of testing can be built on top of it (BaseCoreFunctionalTestCase extends from BaseUnitTestCase as an example). Mainly BaseUnitTestCase is used to apply org.hibernate.testing.junit4.CustomRunner which is how we tie in most of the Hibernate extensions to JUnit. CustomRunner is a org.junit.runner.Runner implementation; org.junit.runner.Runner is meant to be extended and is the wrapper around how tests are instantiated and run. All of the extensions are controlled via annotations on the tests.

Extension annotations


@org.hibernate.testing.FailureExpected is intended to mark a test (when applied to a method) or all tests in a class (when applied to a class) as being expected to fail. This is useful when starting identification of a bug or development of a missing feature. Basically we are saying that we expected that this test is going to fail for some amount of time. That is actually considered a passing condition then if the test does in fact fail (and a failing condition if the test does not fail). Also good to know about the 'hibernate.test.validatefailureexpected' setting. If your test needs to react specially to an expected failure, @OnExpectedFailure is used to name a method to be called on such conditions.


@org.hibernate.testing.TestForIssue is an annotation intended to document the JIRA issue that led to the creation of the annotated test method/class. Useful for researching.


@org.hibernate.testing.OnFailure is used to annotate a callback method that should be called when a test fails.

@BeforeClassOnce and @AfterClassOnce

Corollary to org.junit.BeforeClass and org.junit.AfterClass except that they only get called once for each test class. This gets into JUnit specifics, but essentially for each test method on a given class, JUnit instantiates a new instance of the test class. It does so for isolation purposes, but it also makes it difficult to share expensive resources (like SessionFactories!) between tests. Anyway, to allow that behavior we added @org.hibernate.testing.BeforeClassOnce and @org.hibernate.testing.AfterClassOnce


@org.hibernate.testing.Skip is a general purpose test skip conditioner. It defines a org.hibernate.testing.Skip.Matcher as a condition for the skip.

@RequiresDialect, @RequiresDialectFeature and @SkipForDialect

Are all annotations which intend to limit the databases (see matrix testing) on which the test runs. @org.hibernate.testing.RequiresDialect names a dialect which should be in effect for that test to be run. @org.hibernate.testing.RequiresDialectFeature names a feature (through one or more org.hibernate.testing.DialectCheck) that the dialect under test should have for the test to be run. @org.hibernate.testing.SkipForDialect names a dialect which if the one under test indicates the test should be skipped.