PrepAndExpectedTestCase.java
/*
*
* The DbUnit Database Testing Framework
* Copyright (C)2002-2008, DbUnit.org
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
*/
package org.dbunit;
import java.util.Properties;
import org.dbunit.assertion.FailureHandler;
import org.dbunit.database.IDatabaseConnection;
import org.dbunit.dataset.IDataSet;
import org.dbunit.util.fileloader.DataFileLoader;
/**
* Test case supporting prep data and expected data.
*
* @author Jeff Jensen jeffjensen AT users.sourceforge.net
* @author Last changed by: $Author$
* @version $Revision$ $Date$
* @since 2.4.8
*/
public interface PrepAndExpectedTestCase
{
/**
* Configure the test. Call this method before performing the test steps.
*
* @param verifyTableDefinitions
* Table definitions to verify after test execution; null means
* none.
* @param prepDataFiles
* The prep data files (as classpath resources) to load and
* insert contents into the database as seed data; null means
* none.
* @param expectedDataFiles
* The expected data files (as classpath resources) to load as
* expected data and verify actual data matches at test end; null
* means none.
* @throws Exception if the test cannot be configured.
*/
void configureTest(VerifyTableDefinition[] verifyTableDefinitions,
String[] prepDataFiles, String[] expectedDataFiles)
throws Exception;
/**
* Configure the test from a {@link PrepAndExpectedTestData} bundle instead of
* the three separate array arguments. Equivalent to calling
* {@link #configureTest(VerifyTableDefinition[], String[], String[])} with
* the bundle's three values.
*
* @param testData
* The verification definitions and prep and expected data files
* for this test.
* @throws Exception If the test cannot be configured.
* @since 3.6.0
*/
default void configureTest(final PrepAndExpectedTestData testData)
throws Exception
{
configureTest(testData.getVerifyTableDefinitions(),
testData.getPrepDataFiles(), testData.getExpectedDataFiles());
}
/**
* Execute pre-test steps. Call this method before performing the test
* steps.
*
* @throws Exception if the pre-test steps fail.
*/
void preTest() throws Exception;
/**
* Convenience method to call configureTest() and preTest().
*
* @param verifyTables
* Table definitions to verify after test execution.
* @param prepDataFiles
* The prep data files (as classpath resources) to load and
* insert contents into the database as seed data.
* @param expectedDataFiles
* The expected data files (as classpath resources) to load as
* expected data and verify actual data matches at test end.
* @throws Exception if the pre-test steps fail.
*/
void preTest(VerifyTableDefinition[] verifyTables, String[] prepDataFiles,
String[] expectedDataFiles) throws Exception;
/**
* Convenience method to call configureTest() and preTest(), taking a
* {@link PrepAndExpectedTestData} bundle instead of the three separate array
* arguments. Equivalent to calling
* {@link #preTest(VerifyTableDefinition[], String[], String[])} with the
* bundle's three values.
*
* @param testData
* The verification definitions and prep and expected data files
* for this test.
* @throws Exception If the pre-test steps fail.
* @since 3.6.0
*/
default void preTest(final PrepAndExpectedTestData testData) throws Exception
{
preTest(testData.getVerifyTableDefinitions(),
testData.getPrepDataFiles(), testData.getExpectedDataFiles());
}
/**
* Run the DbUnit test.
*
* @param verifyTables
* Table definitions to verify after test execution.
* @param prepDataFiles
* The prep data files (as classpath resources) to load and
* insert contents into the database as seed data.
* @param expectedDataFiles
* The expected data files (as classpath resources) to load as
* expected data and verify actual data matches at test end.
* @param testSteps
* The test steps to run.
* @return User defined object from running the test steps.
* @throws Exception if the test steps fail.
* @since 2.5.2
*/
Object runTest(VerifyTableDefinition[] verifyTables, String[] prepDataFiles,
String[] expectedDataFiles, PrepAndExpectedTestCaseSteps testSteps)
throws Exception;
/**
* Run the DbUnit test from a {@link PrepAndExpectedTestData} bundle instead
* of the three separate array arguments. Equivalent to calling
* {@link #runTest(VerifyTableDefinition[], String[], String[], PrepAndExpectedTestCaseSteps)}
* with the bundle's three values and the given test steps.
*
* @param testData
* The verification definitions and prep and expected data files
* for this test.
* @param testSteps
* The test steps to run.
* @return The user-defined object from running the test steps.
* @throws Exception If the test steps fail.
* @since 3.6.0
*/
default Object runTest(final PrepAndExpectedTestData testData,
final PrepAndExpectedTestCaseSteps testSteps) throws Exception
{
return runTest(testData.getVerifyTableDefinitions(),
testData.getPrepDataFiles(), testData.getExpectedDataFiles(),
testSteps);
}
/**
* Execute all post-test steps. Call this method after performing the test
* steps.
*
* @throws Exception if the post-test steps fail.
*/
void postTest() throws Exception;
/**
* Execute post-test steps. Call this method after performing the test
* steps.
*
* @param verifyData
* Specify true to perform verify data steps, false to not.
* Useful to specify false when test has failure in progress
* (e.g. an exception) and verifying data would fail, masking
* original test failure.
* @throws Exception if the post-test steps fail.
*/
void postTest(boolean verifyData) throws Exception;
/**
* For the provided VerifyTableDefinitions, verify each table's actual
* results are as expected.
*
* @throws Exception if verifying the data fails.
*/
void verifyData() throws Exception;
/**
* Cleanup tables specified in prep and expected datasets, using the
* provided databaseTester. See
* {@link org.dbunit.IDatabaseTester#onTearDown()}.
*
* @throws Exception if cleaning up the data fails.
*/
void cleanupData() throws Exception;
/**
* Get the prep dataset, created from the prepDataFiles.
*
* @return The prep dataset.
*/
IDataSet getPrepDataset();
/**
* Get the expected dataset, created from the expectedDataFiles.
*
* @return The expected dataset.
*/
IDataSet getExpectedDataset();
/**
* Get the databaseTester this test case uses.
* <p>
* Default method for binary compatibility with implementations predating this method; they
* report having no databaseTester of their own rather than failing to compile. An
* implementation backed by {@link #setDatabaseTester(IDatabaseTester)} should override this
* to return the value that method was last called with, the way
* {@link DefaultPrepAndExpectedTestCase} does - doing so lets a caller resolving a tester on
* this test case's behalf (e.g. {@code org.dbunit.junit.jupiter.DbUnitExtension}) keep the
* two in sync instead of silently driving two different testers.
*
* @return The databaseTester, or {@code null} if none is set or this implementation does
* not support reporting one.
* @since 3.6.0
*/
default IDatabaseTester getDatabaseTester()
{
return null;
}
/**
* Set the databaseTester this test case uses.
* <p>
* Default method for binary compatibility with implementations predating this method; it is
* a no-op for one that does not support being given a databaseTester after construction, so
* a caller can invoke it unconditionally regardless of implementation. Override it, alongside
* {@link #getDatabaseTester()}, to accept a tester resolved after construction - e.g. from a
* {@code @DbUnitTester} field or a {@code DatabaseTesterFactory} - the way
* {@link DefaultPrepAndExpectedTestCase} does.
*
* @param databaseTester The databaseTester to use.
* @since 3.6.0
*/
default void setDatabaseTester(final IDatabaseTester databaseTester)
{
}
/**
* Returns the connection this test case's own steps use for the current test, resolving one
* from {@link #getDatabaseTester()} first if it has not already.
* <p>
* Default method for binary compatibility with implementations predating this method; its
* default body simply asks {@link #getDatabaseTester()} for a connection independently on
* every call - the same connection-identity limitation this method exists to let a caller
* avoid. Override it, memoizing the result the way {@link DefaultPrepAndExpectedTestCase}
* does, so repeated calls - and a caller resolving a connection on this test case's behalf -
* reuse the same connection object instead of each opening a new one.
* <p>
* {@code org.dbunit.annotation}'s {@code AnnotatedTestExecutor} calls this - instead of
* asking {@link #getDatabaseTester()} for a connection of its own - to resolve a
* {@code Connection}/{@code IDatabaseConnection} parameter injection on the prep/expected
* path, so the injected connection is the same one this test case's own setup/verify/cleanup
* steps use rather than a second, independently-opened one. For a tester whose
* {@code getConnection()} is not itself idempotent (e.g. a plain {@code JdbcDatabaseTester}),
* a non-overriding implementation still returns a usable connection, just not necessarily
* the same physical one this test case uses internally.
*
* @return The connection to reuse, or {@code null} if {@link #getDatabaseTester()} returns
* none.
* @throws Exception On dbUnit errors.
* @since 3.6.0
*/
default IDatabaseConnection getReusableConnection() throws Exception
{
final IDatabaseTester databaseTester = getDatabaseTester();
return databaseTester == null ? null : databaseTester.getConnection();
}
/**
* Set the {@link DataFileLoader} this test case uses to load prepDataFiles/expectedDataFiles.
* <p>
* Default method for binary compatibility with implementations predating this method; it is
* a no-op for one that does not support being given a loader after construction. Override it
* to receive a loader resolved after construction the way {@link DefaultPrepAndExpectedTestCase}
* does.
* <p>
* {@code org.dbunit.annotation}'s {@code AnnotatedTestExecutor} calls this on a
* {@code @DbUnitTestCase}-injected instance whenever {@code @DbUnitConfig.dataFileLoader()}
* names a non-default loader, and throws {@code IllegalStateException} if this method is
* not overridden - a silent no-op there would otherwise leave the instance loading with
* whatever loader it was already constructed with. It also calls it, with the configured
* default loader, on an instance whose {@link #getDataFileLoader()} reports none, since that
* instance cannot load datasets without one. Either way the instance's own loader is put
* back with this method once the test is over.
*
* @param dataFileLoader The dataFileLoader to use.
* @since 3.6.0
*/
default void setDataFileLoader(final DataFileLoader dataFileLoader)
{
}
/**
* Set the {@link FailureHandler} this test case hands verifyData()'s assertion failures to.
* <p>
* Default method for binary compatibility with implementations predating this method; it is
* a no-op for one that does not support being given a failure handler after construction.
* Override it to receive a handler resolved after construction the way
* {@link DefaultPrepAndExpectedTestCase} does.
* <p>
* {@code org.dbunit.annotation}'s {@code AnnotatedTestExecutor} calls this on a
* {@code @DbUnitTestCase}-injected instance whenever {@code @DbUnitConfig.failureHandler()}
* is set, and throws {@code IllegalStateException} if this method is not overridden - a
* silent no-op there would otherwise leave the configured handler applied nowhere. When
* {@code @DbUnitConfig.failureHandler()} is not set the instance's own handler is left
* alone, and after a test that set one the instance's own is put back with this method.
*
* @param failureHandler The failureHandler to use.
* @since 3.6.0
*/
default void setFailureHandler(final FailureHandler failureHandler)
{
}
/**
* Set whether this test case closes its connection after each test.
* <p>
* Default method for binary compatibility with implementations predating this method; it is
* a no-op for one that does not support this being set after construction. Override it to
* receive a value resolved after construction the way {@link DefaultPrepAndExpectedTestCase}
* does.
* <p>
* {@code org.dbunit.annotation}'s {@code AnnotatedTestExecutor} calls this on a
* {@code @DbUnitTestCase}-injected instance whenever
* {@code @DbUnitConfig.closeConnectionAfterTest()} is {@code false}, and logs a warning if
* this method is not overridden - unlike the other {@code @DbUnitConfig}-driven setters
* this is not a complete no-op even then, since that executor's own connection (for the
* row count check or parameter injection) still honors the value regardless; only this
* test case's own connection handling might not. Only {@code false} is applied: the default
* {@code true} is not a request to change a value the instance was built with. After a test
* that applied {@code false} the instance's own value is put back with this method.
*
* @param closeConnectionAfterTest True to close the connection after each test, false to
* leave it open.
* @since 3.6.0
*/
default void setCloseConnectionAfterTest(final boolean closeConnectionAfterTest)
{
}
/**
* Set DatabaseConfig property name/value pairs for this test case to apply to its connection.
* <p>
* Default method for binary compatibility with implementations predating this method; it is
* a no-op for one that does not support this being set after construction. Override it to
* apply properties resolved after construction the way {@link DefaultPrepAndExpectedTestCase}
* does.
* <p>
* {@code org.dbunit.annotation}'s {@code AnnotatedTestExecutor} calls this on a
* {@code @DbUnitTestCase}-injected instance whenever
* {@code @DbUnitConfig.properties()}/{@code propertiesProvider()} is non-empty, and throws
* {@code IllegalStateException} if this method is not overridden - on the prep/expected
* path this is the only route to the connection at all, so a silent no-op here would
* otherwise apply the configured properties nowhere. The configured properties are added to
* the instance's own {@link #getDatabaseConfigProperties()}, not substituted for them, and
* after the test the instance's own are put back with this method. An implementation
* keeping its connection past the test should put back, at the end of the test and when
* this method changes the properties, the {@code DatabaseConfig} values the previous
* properties replaced, as {@link DefaultPrepAndExpectedTestCase} does.
*
* @param databaseConfigProperties The properties to apply; null or empty applies none.
* @since 3.6.0
*/
default void setDatabaseConfigProperties(final Properties databaseConfigProperties)
{
}
/**
* Set the enabled flag and excluded table patterns this test case resolves its row count
* check from, instead of its connection's DatabaseConfig.
* <p>
* Default method for binary compatibility with implementations predating this method; it is
* a no-op for one that does not support a row count check override. Override it, alongside
* {@link #clearRowCountCheckOverride()}, to apply an override resolved after construction the
* way {@link DefaultPrepAndExpectedTestCase} does.
* <p>
* {@code org.dbunit.annotation}'s {@code AnnotatedTestExecutor} calls this on a
* {@code @DbUnitTestCase}-injected instance whenever {@code @DbUnitRowCountCheck} is
* declared, and throws {@code IllegalStateException} if this method is not overridden - a
* silent no-op here would otherwise leave the check silently never running for this test
* at all.
*
* @param enabled Whether the check is enabled.
* @param exclude The excluded table patterns; null is treated as empty (excludes none).
* @since 3.6.0
*/
default void setRowCountCheckOverride(final boolean enabled, final String[] exclude)
{
}
/**
* Clear a previously set row count check override, returning to resolving it from this test
* case's connection's DatabaseConfig.
* <p>
* Default method for binary compatibility with implementations predating this method; it is
* a no-op for one that does not support a row count check override. Override it, alongside
* {@link #setRowCountCheckOverride(boolean, String[])}, the way
* {@link DefaultPrepAndExpectedTestCase} does.
* <p>
* {@code AnnotatedTestExecutor} calls this once a test that set an override with
* {@link #setRowCountCheckOverride(boolean, String[])} is over, so a test case reused across
* several tests (e.g. a {@code @DbUnitTestCase} static field) does not carry one test's
* override onto the next. It never calls it for a test that declared no
* {@code @DbUnitRowCountCheck}, so an override its owner set directly stands.
*
* @since 3.6.0
*/
default void clearRowCountCheckOverride()
{
}
/**
* Get the {@link DataFileLoader} this test case uses to load prepDataFiles/expectedDataFiles,
* so a caller about to replace it with {@link #setDataFileLoader(DataFileLoader)} can put it
* back afterward.
* <p>
* Default method for binary compatibility with implementations predating this method; it
* reports no loader for one that does not expose it. Override it, alongside
* {@link #setDataFileLoader(DataFileLoader)}, the way {@link DefaultPrepAndExpectedTestCase}
* does.
*
* @return The loader in use, or {@code null} if none is set or this test case does not
* expose it.
* @since 3.6.0
*/
default DataFileLoader getDataFileLoader()
{
return null;
}
/**
* Get the {@link FailureHandler} this test case hands verifyData()'s assertion failures to,
* so a caller about to replace it with {@link #setFailureHandler(FailureHandler)} can put it
* back afterward.
* <p>
* Default method for binary compatibility with implementations predating this method; it
* reports no handler for one that does not expose it. Override it, alongside
* {@link #setFailureHandler(FailureHandler)}, the way {@link DefaultPrepAndExpectedTestCase}
* does.
*
* @return The handler in use, or {@code null} if none is set or this test case does not
* expose it.
* @since 3.6.0
*/
default FailureHandler getFailureHandler()
{
return null;
}
/**
* Get whether this test case closes the connection it shares across its lifecycle after each
* test, so a caller about to change it with {@link #setCloseConnectionAfterTest(boolean)} can
* put it back afterward.
* <p>
* Default method for binary compatibility with implementations predating this method; it
* reports the usual default of closing for one that does not expose it. Override it,
* alongside {@link #setCloseConnectionAfterTest(boolean)}, the way
* {@link DefaultPrepAndExpectedTestCase} does.
*
* @return {@code true} if the connection is closed after each test.
* @since 3.6.0
*/
default boolean isCloseConnectionAfterTest()
{
return true;
}
/**
* Get the DatabaseConfig property name/value pairs this test case applies to its connection,
* so a caller about to change them with {@link #setDatabaseConfigProperties(Properties)} can
* put them back afterward.
* <p>
* Default method for binary compatibility with implementations predating this method; it
* reports none for one that does not expose them. Override it, alongside
* {@link #setDatabaseConfigProperties(Properties)}, the way
* {@link DefaultPrepAndExpectedTestCase} does.
*
* @return A copy of the properties applied, or {@code null} if none are set or this test case
* does not expose them.
* @since 3.6.0
*/
default Properties getDatabaseConfigProperties()
{
return null;
}
}