Overview

VerifyTableDefinition (org.dbunit, since 2.4.8) defines one database table to verify: which columns to include or exclude from the comparison, which ValueComparer (if any) to use per column, and (since 3.5.0) whether row sorting for the comparison considers only those included/excluded columns. It is consumed by PrepAndExpectedTestCase — one instance per table you want verified after a test runs.

Fields

Constructors

VerifyTableDefinition has 7 constructor overloads. All of them delegate to the 6-argument canonical form; pick whichever overload matches what you need to configure:

VerifyTableDefinitionVerifier

Every constructor’s last step is verifyTableDefinitionVerifier.verify(this), using a DefaultVerifyTableDefinitionVerifier by default. It catches one specific configuration conflict: a column listed in both columnExclusionFilters and columnValueComparers — excluded from comparison, yet also given a specific comparer — and throws IllegalStateException with a message naming the table and column. This is a fail-fast check at construction time, not at comparison time, so a misconfigured VerifyTableDefinition breaks loudly wherever it’s built (commonly a static field or factory method) rather than surfacing later as a confusing assertion failure.

getVerifyTableDefinitionVerifier()/setVerifyTableDefinitionVerifier() expose the verifier instance for reuse (e.g. calling .verify(…​) again manually) or replacement with a custom VerifyTableDefinitionVerifier. Note the setter has no automatic effect on verification already performed — construction always verifies using the default verifier, since the setter can only be called on an instance that already exists.

Sort Mode

PrepAndExpectedTestCase sorts both the actual and expected tables before comparing them row-by-row. By default (sortOnFilteredColumnsOnly is false) it sorts the actual table by all of its native database columns and the expected table by only the columns its dataset file declares — typically every column except a generated/identity one, since its value is unknown ahead of time.

That default breaks down for a table whose generated column is excluded from comparison when production code does not insert rows in a predictable order — for example, Hibernate reordering a batch insert. The database still assigns the excluded column’s value in insertion order, so the actual table ends up sorted primarily by that unpredictable value while the expected table sorts by data content, misaligning same-data rows and failing the comparison even though both sides hold identical data. See issue #672.

Set sortOnFilteredColumnsOnly to true to sort both actual and expected tables by only the columns that survive columnExclusionFilters/columnInclusionFilters instead — the same columns that end up compared — so an excluded generated column never participates in the sort:

VerifyTableDefinition table = new VerifyTableDefinition(
        "IDENTITY_TABLE", new String[] {"IDENTITY_TABLE_ID"});
table.setSortOnFilteredColumnsOnly(true);

Or set it directly at construction time instead of calling the setter afterward. The common case — no include filter needed — uses the five-argument constructor:

VerifyTableDefinition table = new VerifyTableDefinition("IDENTITY_TABLE",
        new String[] {"IDENTITY_TABLE_ID"}, null, null, true);

If you also need an include filter, use the six-argument canonical constructor instead:

VerifyTableDefinition table = new VerifyTableDefinition("IDENTITY_TABLE",
        new String[] {"IDENTITY_TABLE_ID"}, null, null, null, true);

Default is false, preserving the historical sort-by-all-columns behavior. It remains safe whenever every column needed to tell otherwise-identical rows apart is present on both the actual and expected tables. Opt in per table whenever such a distinguishing column is absent from the expected table - typically because it is excluded from comparison - regardless of whether that column happens to be generated/identity or not.

When a comparison fails in that situation - the default mode, and an expected table that omits a column of the actual one, so the two sort by different columns - the verification compares again with both tables sorted by only the compared columns. If that passes, the failure carries (since 3.6.0) a suppressed exception that says so and names setSortOnFilteredColumnsOnly(true) as the remedy, and the same text is logged as a warning, for a build that trims stack traces, such as Surefire with trimStackTrace set to true. Nothing is added when the comparison passes, which it can when the omitted columns sort the same way, or when it also fails sorted that way, as it does for a different row count, a different set of columns or a genuine difference in the data.

Since 3.6.0, sortOnFilteredColumnsOnly set to true also narrows what is read from the database: the actual table is loaded selecting only the columns that survive the filters, so an excluded column, often a large one such as a BLOB or CLOB, is not fetched. A column that only the include filter drops is not fetched either, so the additional row info of a failure message, which in the default mode lists such a column to help identify the mismatching row, then lists only the compared columns. The columns come from the connection’s database metadata, the way a DatabaseDataSet gets them. When they cannot be determined, or every column is filtered out, every column is selected as before. A subclass of DefaultPrepAndExpectedTestCase that overrides loadTableDataFromDatabase(String, IDatabaseConnection), for example to add a WHERE clause, keeps deciding what is loaded. The default false still selects every column, because each one is a sort key there.

Usage Examples

This page covers the class’s shape. For full usage — static shared instances, test-specific factory methods, and wiring ValueComparer instances per table — see PrepAndExpectedTestCase.

For selecting a shared VerifyTableDefinition catalog class by table name from an annotation-driven test, see the catalog section of DbUnit Annotations.