Add repo-root README.adoc, rendered natively by GitHub via Asciidoctor, so the repository landing page shows a pitch, build/reproducible-build badges, a pointer to the "dbUnit in 5 Minutes" tutorial, and links to the documentation site, Maven coordinates, GitHub Discussions, and CONTRIBUTING.md instead of nothing.
diff --git a/src/main/java/org/dbunit/DefaultPrepAndExpectedTestCase.java b/src/main/java/org/dbunit/DefaultPrepAndExpectedTestCase.java
index d3b0400c9..0ed3a4edc 100644
--- a/src/main/java/org/dbunit/DefaultPrepAndExpectedTestCase.java
+++ b/src/main/java/org/dbunit/DefaultPrepAndExpectedTestCase.java
@@ -34,6 +34,8 @@
import org.dbunit.assertion.comparer.value.ValueComparer;
import org.dbunit.database.DatabaseConfig;
import org.dbunit.database.IDatabaseConnection;
+import org.dbunit.database.rowcount.RowCountCheck;
+import org.dbunit.database.rowcount.RowCountChecker;
import org.dbunit.dataset.Column;
import org.dbunit.dataset.CompositeDataSet;
import org.dbunit.dataset.DataSetException;
@@ -132,6 +134,15 @@ public class DefaultPrepAndExpectedTestCase extends DBTestCase
*/
private Boolean cachedIsCaseSensitiveTableNames;
+ /**
+ * Manages the row count check baseline used by preTest() and cleanupData() to detect a
+ * table the test left dirty - either one it should have cleaned up and did not, or a
+ * reference table it wrongly cleaned.
+ *
+ * @since 3.6.0
+ */
+ private final RowCountChecker rowCountChecker = new RowCountChecker();
+
private ExpectedDataSetAndVerifyTableDefinitionVerifier expectedDataSetAndVerifyTableDefinitionVerifier =
new DefaultExpectedDataSetAndVerifyTableDefinitionVerifier();
@@ -425,13 +436,40 @@ public void operationTearDownFinished(
/**
* {@inheritDoc}
+ *
+ * Captures the row count check baseline, if enabled, before setting up the prep data - see
+ * {@link RowCountCheck#capture(IDatabaseConnection)}.
*/
@Override
public void preTest() throws Exception
{
+ captureRowCountBaseline();
setupData();
}
+ /**
+ * Capture the row count check baseline, using the connection shared with the rest of this
+ * test's lifecycle. A no-op that leaves no baseline captured when the check is disabled.
+ *
+ * @throws Exception On dbUnit errors.
+ * @since 3.6.0
+ */
+ private void captureRowCountBaseline() throws Exception
+ {
+ final boolean acquiredConnectionHere = connection == null;
+ try
+ {
+ rowCountChecker.capture(getReusableConnection());
+ } catch (final Exception e)
+ {
+ if (acquiredConnectionHere)
+ {
+ closeReusableConnectionSuppressing(e);
+ }
+ throw e;
+ }
+ }
+
/**
* {@inheritDoc}
*/
@@ -507,6 +545,11 @@ public void postTest() throws Exception
/**
* {@inheritDoc}
+ *
+ * When {@code verifyData} is false - the test steps already failed - discards any
+ * captured row count check baseline, so cleanupData() skips that check too: the database
+ * is in an unknown state, so a count difference would be noise around the real failure,
+ * not a finding worth its own report.
*/
@Override
public void postTest(final boolean verifyData) throws Exception
@@ -517,6 +560,9 @@ public void postTest(final boolean verifyData) throws Exception
if (verifyData)
{
verifyData();
+ } else
+ {
+ rowCountChecker.discardBaseline();
}
} catch (final Throwable t)
{
@@ -585,6 +631,7 @@ public void cleanupData() throws Exception
makeReusableConnectionDatabaseTester(dataset);
reusableTester.onTearDown();
log.debug("cleanupData: Clean up done");
+ verifyRowCountUnchanged();
closeReusableConnection();
} catch (final Exception e)
{
@@ -594,6 +641,21 @@ public void cleanupData() throws Exception
}
}
+ /**
+ * Verify the row count check baseline, if one was captured, using the connection shared
+ * with the rest of this test's lifecycle. A no-op when no baseline was captured - the
+ * check is disabled, capture never ran, or {@link #postTest(boolean)} discarded it
+ * because the test steps already failed.
+ *
+ * @throws Exception On dbUnit errors, including {@link org.dbunit.database.rowcount.UnexpectedRowCountException}
+ * when a table's row count no longer matches the baseline.
+ * @since 3.6.0
+ */
+ private void verifyRowCountUnchanged() throws Exception
+ {
+ rowCountChecker.verify(getReusableConnection());
+ }
+
/**
* Legacy JUnit-3-era tear-down hook. Not invoked automatically under JUnit 5;
* kept for subclasses that drive the lifecycle manually. Calling it after a
@@ -1488,6 +1550,34 @@ public void setFailureHandler(final FailureHandler failureHandler)
this.failureHandler = failureHandler;
}
+ /**
+ * Get the RowCountCheck in use.
+ *
+ * @see #rowCountChecker
+ *
+ * @return The RowCountCheck, or null if none has been resolved or set yet.
+ * @since 3.6.0
+ */
+ public RowCountCheck getRowCountCheck()
+ {
+ return rowCountChecker.getRowCountCheck();
+ }
+
+ /**
+ * Set the RowCountCheck, overriding the one otherwise lazily built from the shared
+ * connection's DatabaseConfig.
+ *
+ * @see #rowCountChecker
+ *
+ * @param rowCountCheck
+ * The RowCountCheck to use.
+ * @since 3.6.0
+ */
+ public void setRowCountCheck(final RowCountCheck rowCountCheck)
+ {
+ rowCountChecker.setRowCountCheck(rowCountCheck);
+ }
+
/**
* {@link IDatabaseTester} that runs setUp/tearDown operations against a
* connection supplied by the given {@link Callable} instead of calling
diff --git a/src/main/java/org/dbunit/database/DatabaseConfig.java b/src/main/java/org/dbunit/database/DatabaseConfig.java
index 6443a06a6..79a501aff 100644
--- a/src/main/java/org/dbunit/database/DatabaseConfig.java
+++ b/src/main/java/org/dbunit/database/DatabaseConfig.java
@@ -28,6 +28,8 @@
import java.util.Properties;
import org.dbunit.DatabaseUnitException;
+import org.dbunit.database.rowcount.QueryPerTableRowCounter;
+import org.dbunit.database.rowcount.RowCounter;
import org.dbunit.database.statement.IStatementFactory;
import org.dbunit.database.statement.PreparedStatementFactory;
import org.dbunit.dataset.datatype.DefaultDataTypeFactory;
@@ -89,6 +91,12 @@ public class DatabaseConfig
/** Name of the property configuring the {@link IColumnFilter} used to determine MS SQL identity columns. */
public static final String PROPERTY_IDENTITY_COLUMN_FILTER =
"http://www.dbunit.org/properties/mssql/identityColumnFilter";
+ /** Name of the property configuring the table name patterns excluded from the row count check. */
+ public static final String PROPERTY_ROW_COUNT_CHECK_EXCLUDE_TABLES =
+ "http://www.dbunit.org/properties/rowCountCheckExcludeTables";
+ /** Name of the property configuring the {@link RowCounter} implementation to use. */
+ public static final String PROPERTY_ROW_COUNTER =
+ "http://www.dbunit.org/properties/rowCounter";
/** Name of the feature controlling whether table names are treated as case sensitive. */
public static final String FEATURE_CASE_SENSITIVE_TABLE_NAMES =
@@ -120,9 +128,15 @@ public class DatabaseConfig
*/
public static final String FEATURE_SKIP_CYCLE_CHECK =
"http://www.dbunit.org/features/skipCycleCheck";
+ /**
+ * Name of the feature controlling whether table row counts are compared before and after
+ * each test.
+ */
+ public static final String FEATURE_ROW_COUNT_CHECK =
+ "http://www.dbunit.org/features/rowCountCheck";
/**
- * A list of all properties as {@link ConfigProperty} objects.
+ * A list of all properties as {@link ConfigProperty} objects.
* The objects contain the allowed java type and whether or not a property is nullable.
*/
public static final ConfigProperty[] ALL_PROPERTIES = new ConfigProperty[] {
@@ -145,6 +159,9 @@ public class DatabaseConfig
new ConfigProperty(PROPERTY_ALLOW_VERIFYTABLEDEFINITION_EXPECTEDTABLE_COUNT_MISMATCH, Boolean.class, false),
new ConfigProperty(FEATURE_SORT_ALL_COLUMNS_WHEN_NO_PRIMARY_KEY, Boolean.class, false),
new ConfigProperty(FEATURE_SKIP_CYCLE_CHECK, Boolean.class, false),
+ new ConfigProperty(PROPERTY_ROW_COUNT_CHECK_EXCLUDE_TABLES, String[].class, false),
+ new ConfigProperty(PROPERTY_ROW_COUNTER, RowCounter.class, false),
+ new ConfigProperty(FEATURE_ROW_COUNT_CHECK, Boolean.class, false),
};
/**
@@ -159,7 +176,8 @@ public class DatabaseConfig
FEATURE_SKIP_ORACLE_RECYCLEBIN_TABLES,
FEATURE_ALLOW_EMPTY_FIELDS,
FEATURE_SORT_ALL_COLUMNS_WHEN_NO_PRIMARY_KEY,
- FEATURE_SKIP_CYCLE_CHECK
+ FEATURE_SKIP_CYCLE_CHECK,
+ FEATURE_ROW_COUNT_CHECK
};
private static final DefaultDataTypeFactory DEFAULT_DATA_TYPE_FACTORY =
@@ -172,6 +190,9 @@ public class DatabaseConfig
private static final String[] DEFAULT_TABLE_TYPE = {"TABLE"};
private static final Integer DEFAULT_BATCH_SIZE = 100;
private static final Integer DEFAULT_FETCH_SIZE = 100;
+ private static final String[] DEFAULT_ROW_COUNT_CHECK_EXCLUDE_TABLES = new String[0];
+ private static final QueryPerTableRowCounter DEFAULT_ROW_COUNTER =
+ new QueryPerTableRowCounter();
@@ -192,6 +213,7 @@ public DatabaseConfig()
setFeature(FEATURE_ALLOW_EMPTY_FIELDS, false);
setFeature(FEATURE_SORT_ALL_COLUMNS_WHEN_NO_PRIMARY_KEY, false);
setFeature(FEATURE_SKIP_CYCLE_CHECK, false);
+ setFeature(FEATURE_ROW_COUNT_CHECK, false);
setProperty(PROPERTY_STATEMENT_FACTORY, PREPARED_STATEMENT_FACTORY);
setProperty(PROPERTY_RESULTSET_TABLE_FACTORY, RESULT_SET_TABLE_FACTORY);
@@ -204,6 +226,9 @@ public DatabaseConfig()
setProperty(
PROPERTY_ALLOW_VERIFYTABLEDEFINITION_EXPECTEDTABLE_COUNT_MISMATCH,
Boolean.FALSE);
+ setProperty(PROPERTY_ROW_COUNT_CHECK_EXCLUDE_TABLES,
+ DEFAULT_ROW_COUNT_CHECK_EXCLUDE_TABLES);
+ setProperty(PROPERTY_ROW_COUNTER, DEFAULT_ROW_COUNTER);
this.configurator = new Configurator(this);
}
diff --git a/src/main/java/org/dbunit/database/rowcount/QueryPerTableRowCounter.java b/src/main/java/org/dbunit/database/rowcount/QueryPerTableRowCounter.java
new file mode 100644
index 000000000..6b01fb2e5
--- /dev/null
+++ b/src/main/java/org/dbunit/database/rowcount/QueryPerTableRowCounter.java
@@ -0,0 +1,60 @@
+/*
+ *
+ * The DbUnit Database Testing Framework
+ * Copyright (C)2002-2026, 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.database.rowcount;
+
+import java.sql.SQLException;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.dbunit.database.DatabaseConfig;
+import org.dbunit.database.IDatabaseConnection;
+
+/**
+ * {@link RowCounter} that issues one SELECT COUNT(*) per table, by
+ * looping {@link IDatabaseConnection#getRowCount(String)}. Already handles schema
+ * qualification and {@link DatabaseConfig#PROPERTY_ESCAPE_PATTERN} through
+ * {@link org.dbunit.util.QualifiedTableName}, and is exercised across every
+ * supported database by that method's own tests.
+ *
+ * This is the {@link RowCountCheck} v1 implementation, and the value
+ * {@link DatabaseConfig#PROPERTY_ROW_COUNTER} initialises to.
+ *
+ * @author dbunit
+ * @since 3.6.0
+ */
+public class QueryPerTableRowCounter implements RowCounter
+{
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public Map countRows(final IDatabaseConnection connection,
+ final List tableNames) throws SQLException
+ {
+ final Map rowCounts = new LinkedHashMap<>();
+ for (final String tableName : tableNames)
+ {
+ rowCounts.put(tableName, connection.getRowCount(tableName));
+ }
+ return rowCounts;
+ }
+}
diff --git a/src/main/java/org/dbunit/database/rowcount/RowCountCheck.java b/src/main/java/org/dbunit/database/rowcount/RowCountCheck.java
new file mode 100644
index 000000000..2ebda27e4
--- /dev/null
+++ b/src/main/java/org/dbunit/database/rowcount/RowCountCheck.java
@@ -0,0 +1,127 @@
+/*
+ *
+ * The DbUnit Database Testing Framework
+ * Copyright (C)2002-2026, 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.database.rowcount;
+
+import java.sql.SQLException;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+import org.dbunit.DatabaseUnitException;
+import org.dbunit.database.IDatabaseConnection;
+import org.dbunit.dataset.filter.ExcludeTableFilter;
+
+/**
+ * Compares a database's table row counts before and after a test, to catch a table the test
+ * left dirty - either one it should have cleaned up and did not, or a reference table it wrongly
+ * cleaned. Read-only: never modifies data.
+ *
+ * Every method is a no-op, and never queries the connection, when
+ * {@link RowCountCheckConfiguration#isEnabled()} is {@code false} - the check costs nothing
+ * when a caller has not opted in.
+ *
+ * @author dbunit
+ * @since 3.6.0
+ */
+public class RowCountCheck
+{
+ private final RowCountCheckConfiguration configuration;
+
+ /**
+ * Creates a check using the given configuration.
+ *
+ * @param configuration resolves whether the check is enabled, the excluded table patterns,
+ * and the {@link RowCounter} to use.
+ */
+ public RowCountCheck(final RowCountCheckConfiguration configuration)
+ {
+ this.configuration = configuration;
+ }
+
+ /**
+ * Captures the baseline row counts to later {@link #verify(RowCountSnapshot, IDatabaseConnection)}
+ * against, of every table {@code connection} exposes that survives the configured exclude
+ * patterns.
+ *
+ * @param connection the connection to capture the baseline from.
+ * @return the baseline snapshot, or {@code null} when the check is disabled.
+ * @throws DatabaseUnitException if enumerating or filtering the tables fails.
+ * @throws SQLException if counting a table's rows fails.
+ */
+ public RowCountSnapshot capture(final IDatabaseConnection connection)
+ throws DatabaseUnitException, SQLException
+ {
+ if (!configuration.isEnabled())
+ {
+ return null;
+ }
+ return snapshot(connection);
+ }
+
+ /**
+ * Verifies that {@code connection}'s current row counts still match {@code baseline}.
+ * A no-op that never queries the connection when the check is disabled or when
+ * {@code baseline} is {@code null} - the latter meaning no baseline was captured, e.g.
+ * because the caller intentionally skipped {@link #capture(IDatabaseConnection)}.
+ *
+ * @param baseline the baseline to compare against; {@code null} to skip the check silently.
+ * @param connection the connection to read the current row counts from.
+ * @throws DatabaseUnitException if enumerating or filtering the tables fails, or if any
+ * table's row count no longer matches the baseline
+ * ({@link UnexpectedRowCountException}).
+ * @throws SQLException if counting a table's rows fails.
+ */
+ public void verify(final RowCountSnapshot baseline, final IDatabaseConnection connection)
+ throws DatabaseUnitException, SQLException
+ {
+ if (!configuration.isEnabled() || baseline == null)
+ {
+ return;
+ }
+
+ final RowCountSnapshot current = snapshot(connection);
+ final List differences = baseline.difference(current);
+ if (!differences.isEmpty())
+ {
+ throw new UnexpectedRowCountException(differences);
+ }
+ }
+
+ private RowCountSnapshot snapshot(final IDatabaseConnection connection)
+ throws DatabaseUnitException, SQLException
+ {
+ final String[] allTableNames = connection.createDataSet().getTableNames();
+ final ExcludeTableFilter excludeTableFilter = configuration.getExcludeTableFilter();
+
+ final List tableNames = new ArrayList<>();
+ for (final String tableName : allTableNames)
+ {
+ if (excludeTableFilter.isValidName(tableName))
+ {
+ tableNames.add(tableName);
+ }
+ }
+
+ final Map rowCounts =
+ configuration.getRowCounter().countRows(connection, tableNames);
+ return new RowCountSnapshot(rowCounts);
+ }
+}
diff --git a/src/main/java/org/dbunit/database/rowcount/RowCountCheckConfiguration.java b/src/main/java/org/dbunit/database/rowcount/RowCountCheckConfiguration.java
new file mode 100644
index 000000000..23982317c
--- /dev/null
+++ b/src/main/java/org/dbunit/database/rowcount/RowCountCheckConfiguration.java
@@ -0,0 +1,139 @@
+/*
+ *
+ * The DbUnit Database Testing Framework
+ * Copyright (C)2002-2026, 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.database.rowcount;
+
+import org.dbunit.database.DatabaseConfig;
+import org.dbunit.dataset.filter.ExcludeTableFilter;
+
+/**
+ * Resolves whether the row count check is enabled, its excluded table patterns, and the
+ * {@link RowCounter} to use, from a {@link DatabaseConfig} and the {@code dbunit.*} system
+ * property overrides.
+ *
+ * Precedence, for both the enabled flag and the exclude patterns: the system property, when
+ * present, wins in either direction, so it can force-enable in CI and force-disable locally.
+ * Absent, resolution falls through to the {@link DatabaseConfig} value; absent there too, the
+ * enabled flag defaults to {@code false}. The exclude system property, when present, replaces
+ * rather than appends to the configured patterns.
+ *
+ * The {@link RowCounter} has no system property override: swapping the counting implementation
+ * is a code-level decision made once for a suite, not something flipped per run.
+ *
+ * @author dbunit
+ * @since 3.6.0
+ */
+public final class RowCountCheckConfiguration
+{
+ /**
+ * System property overriding {@link DatabaseConfig#FEATURE_ROW_COUNT_CHECK}, in either
+ * direction, when present.
+ */
+ public static final String DBUNIT_ROW_COUNT_CHECK = "dbunit.rowCountCheck";
+
+ /**
+ * System property overriding {@link DatabaseConfig#PROPERTY_ROW_COUNT_CHECK_EXCLUDE_TABLES}
+ * when present, replacing rather than appending to the configured patterns.
+ */
+ public static final String DBUNIT_ROW_COUNT_CHECK_EXCLUDE_TABLES =
+ "dbunit.rowCountCheckExcludeTables";
+
+ private final boolean enabled;
+ private final ExcludeTableFilter excludeTableFilter;
+ private final RowCounter rowCounter;
+
+ /**
+ * Resolves the configuration from the given database config and the current system
+ * properties.
+ *
+ * @param databaseConfig the database config to resolve {@link DatabaseConfig#FEATURE_ROW_COUNT_CHECK},
+ * {@link DatabaseConfig#PROPERTY_ROW_COUNT_CHECK_EXCLUDE_TABLES}, and
+ * {@link DatabaseConfig#PROPERTY_ROW_COUNTER} from when no system property
+ * overrides them.
+ */
+ public RowCountCheckConfiguration(final DatabaseConfig databaseConfig)
+ {
+ enabled = resolveEnabled(databaseConfig);
+ excludeTableFilter = new ExcludeTableFilter(resolveExcludeTablePatterns(databaseConfig));
+ rowCounter = (RowCounter) databaseConfig.getProperty(DatabaseConfig.PROPERTY_ROW_COUNTER);
+ }
+
+ private static boolean resolveEnabled(final DatabaseConfig databaseConfig)
+ {
+ final String systemProperty = System.getProperty(DBUNIT_ROW_COUNT_CHECK);
+ if (systemProperty != null)
+ {
+ return Boolean.parseBoolean(systemProperty);
+ }
+ return databaseConfig.getFeature(DatabaseConfig.FEATURE_ROW_COUNT_CHECK);
+ }
+
+ private static String[] resolveExcludeTablePatterns(final DatabaseConfig databaseConfig)
+ {
+ final String systemProperty =
+ System.getProperty(DBUNIT_ROW_COUNT_CHECK_EXCLUDE_TABLES);
+ if (systemProperty != null)
+ {
+ return splitAndTrim(systemProperty);
+ }
+ return (String[]) databaseConfig
+ .getProperty(DatabaseConfig.PROPERTY_ROW_COUNT_CHECK_EXCLUDE_TABLES);
+ }
+
+ private static String[] splitAndTrim(final String commaSeparatedPatterns)
+ {
+ final String[] patterns = commaSeparatedPatterns.split(",");
+ for (int i = 0; i < patterns.length; i++)
+ {
+ patterns[i] = patterns[i].trim();
+ }
+ return patterns;
+ }
+
+ /**
+ * Returns whether the row count check is enabled.
+ *
+ * @return {@code true} when enabled.
+ */
+ public boolean isEnabled()
+ {
+ return enabled;
+ }
+
+ /**
+ * Returns the filter built from the resolved exclude table patterns.
+ *
+ * @return the exclude table filter.
+ */
+ public ExcludeTableFilter getExcludeTableFilter()
+ {
+ return excludeTableFilter;
+ }
+
+ /**
+ * Returns the {@link RowCounter} to use.
+ *
+ * @return the configured row counter.
+ */
+ public RowCounter getRowCounter()
+ {
+ return rowCounter;
+ }
+}
diff --git a/src/main/java/org/dbunit/database/rowcount/RowCountChecker.java b/src/main/java/org/dbunit/database/rowcount/RowCountChecker.java
new file mode 100644
index 000000000..6d5a3ada0
--- /dev/null
+++ b/src/main/java/org/dbunit/database/rowcount/RowCountChecker.java
@@ -0,0 +1,137 @@
+/*
+ *
+ * The DbUnit Database Testing Framework
+ * Copyright (C)2002-2026, 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.database.rowcount;
+
+import java.sql.SQLException;
+
+import org.dbunit.DatabaseUnitException;
+import org.dbunit.database.IDatabaseConnection;
+
+/**
+ * Manages a {@link RowCountCheck} baseline across one caller's test lifecycle: lazily
+ * resolves a {@link RowCountCheck} from a connection's
+ * {@link org.dbunit.database.DatabaseConfig} on first use (unless one is supplied),
+ * captures a baseline, verifies it later, and lets the baseline be discarded when a
+ * verify would be noise - e.g. the caller's own test steps already failed, so the
+ * database is in an unknown state and a count difference is not a finding worth its own
+ * report.
+ *
+ * Holds no connection of its own; every method takes the connection to use, leaving
+ * acquisition and closing entirely to the caller.
+ *
+ * @author dbunit
+ * @since 3.6.0
+ */
+public class RowCountChecker
+{
+ private RowCountCheck rowCountCheck;
+ private RowCountSnapshot baseline;
+
+ /**
+ * Captures the baseline using the given connection, resolving a {@link RowCountCheck}
+ * from its {@link org.dbunit.database.DatabaseConfig} first if none has been resolved
+ * or set yet.
+ *
+ * @param connection the connection to capture the baseline from.
+ * @throws DatabaseUnitException if enumerating or filtering the tables fails.
+ * @throws SQLException if counting a table's rows fails.
+ */
+ public void capture(final IDatabaseConnection connection)
+ throws DatabaseUnitException, SQLException
+ {
+ baseline = resolve(connection).capture(connection);
+ }
+
+ /**
+ * Verifies the captured baseline against the given connection's current row counts.
+ * A no-op that never queries the connection when no baseline was captured - the check
+ * is disabled, {@link #capture(IDatabaseConnection)} was never called, or
+ * {@link #discardBaseline()} was.
+ *
+ * @param connection the connection to read the current row counts from.
+ * @throws DatabaseUnitException if enumerating or filtering the tables fails, or if any
+ * table's row count no longer matches the baseline
+ * ({@link UnexpectedRowCountException}).
+ * @throws SQLException if counting a table's rows fails.
+ */
+ public void verify(final IDatabaseConnection connection)
+ throws DatabaseUnitException, SQLException
+ {
+ if (baseline == null)
+ {
+ return;
+ }
+ resolve(connection).verify(baseline, connection);
+ }
+
+ /**
+ * Discards the captured baseline, so a later {@link #verify(IDatabaseConnection)} call
+ * skips silently instead of comparing against it.
+ */
+ public void discardBaseline()
+ {
+ baseline = null;
+ }
+
+ /**
+ * Returns whether a baseline is currently held, so a caller can tell there is nothing to
+ * verify - e.g. to skip acquiring a connection for {@link #verify(IDatabaseConnection)}
+ * entirely - without needing one just to ask.
+ *
+ * @return {@code true} when a baseline was captured and neither consumed by
+ * {@link #discardBaseline()} nor left uncaptured because the check was disabled.
+ */
+ public boolean hasBaseline()
+ {
+ return baseline != null;
+ }
+
+ private RowCountCheck resolve(final IDatabaseConnection connection)
+ {
+ if (rowCountCheck == null)
+ {
+ rowCountCheck =
+ new RowCountCheck(new RowCountCheckConfiguration(connection.getConfig()));
+ }
+ return rowCountCheck;
+ }
+
+ /**
+ * Returns the {@link RowCountCheck} in use.
+ *
+ * @return the row count check, or {@code null} if none has been resolved or set yet.
+ */
+ public RowCountCheck getRowCountCheck()
+ {
+ return rowCountCheck;
+ }
+
+ /**
+ * Sets the {@link RowCountCheck} to use, overriding the one otherwise lazily built from
+ * a connection's DatabaseConfig on first use.
+ *
+ * @param rowCountCheck the row count check to use.
+ */
+ public void setRowCountCheck(final RowCountCheck rowCountCheck)
+ {
+ this.rowCountCheck = rowCountCheck;
+ }
+}
diff --git a/src/main/java/org/dbunit/database/rowcount/RowCountDifference.java b/src/main/java/org/dbunit/database/rowcount/RowCountDifference.java
new file mode 100644
index 000000000..b9916534a
--- /dev/null
+++ b/src/main/java/org/dbunit/database/rowcount/RowCountDifference.java
@@ -0,0 +1,146 @@
+/*
+ *
+ * The DbUnit Database Testing Framework
+ * Copyright (C)2002-2026, 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.database.rowcount;
+
+import java.util.Objects;
+
+/**
+ * Immutable record of one table's row count having changed between a
+ * {@link RowCountCheck} baseline and a later comparison.
+ *
+ * @author dbunit
+ * @since 3.6.0
+ */
+public final class RowCountDifference
+{
+ private static final String ADVICE_ROWS_LEFT_BEHIND =
+ "rows left behind; add the table to the expected dataset, or exclude it";
+ private static final String ADVICE_ROWS_REMOVED =
+ "rows removed that should remain; drop the table from the prep/expected dataset, or exclude it";
+
+ private final String tableName;
+ private final int baselineCount;
+ private final int currentCount;
+
+ /**
+ * Creates a difference for the given table.
+ *
+ * @param tableName The name of the table whose count changed, in the form
+ * {@link org.dbunit.dataset.IDataSet#getTableNames()} returned it.
+ * @param baselineCount The row count captured before the test.
+ * @param currentCount The row count found at comparison time.
+ */
+ public RowCountDifference(final String tableName, final int baselineCount,
+ final int currentCount)
+ {
+ this.tableName = tableName;
+ this.baselineCount = baselineCount;
+ this.currentCount = currentCount;
+ }
+
+ /**
+ * Returns the name of the table whose count changed.
+ *
+ * @return The table name, in the form {@link org.dbunit.dataset.IDataSet#getTableNames()}
+ * returned it.
+ */
+ public String getTableName()
+ {
+ return tableName;
+ }
+
+ /**
+ * Returns the row count captured before the test.
+ *
+ * @return The baseline row count.
+ */
+ public int getBaselineCount()
+ {
+ return baselineCount;
+ }
+
+ /**
+ * Returns the row count found at comparison time.
+ *
+ * @return The current row count.
+ */
+ public int getCurrentCount()
+ {
+ return currentCount;
+ }
+
+ /**
+ * Returns how much the row count changed.
+ *
+ * @return {@link #getCurrentCount()} minus {@link #getBaselineCount()}; positive when rows
+ * were left behind, negative when rows that should remain were removed.
+ */
+ public int getDelta()
+ {
+ return currentCount - baselineCount;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public boolean equals(final Object o)
+ {
+ if (this == o)
+ {
+ return true;
+ }
+ if (!(o instanceof RowCountDifference))
+ {
+ return false;
+ }
+ final RowCountDifference other = (RowCountDifference) o;
+ return baselineCount == other.baselineCount && currentCount == other.currentCount
+ && Objects.equals(tableName, other.tableName);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public int hashCode()
+ {
+ return Objects.hash(tableName, baselineCount, currentCount);
+ }
+
+ /**
+ * Returns a one-line, human-readable description of this difference, naming the table, both
+ * counts, the signed delta, and direction-specific advice; the table name prints in the form
+ * {@link org.dbunit.dataset.IDataSet#getTableNames()} returned it, so it can be pasted
+ * straight into a dataset or an exclude list.
+ *
+ * @return The one-line description.
+ */
+ @Override
+ public String toString()
+ {
+ final int delta = getDelta();
+ final String signedDelta = delta > 0 ? "+" + delta : String.valueOf(delta);
+ final String advice = delta > 0 ? ADVICE_ROWS_LEFT_BEHIND : ADVICE_ROWS_REMOVED;
+ return tableName + " " + baselineCount + " -> " + currentCount + " (" + signedDelta
+ + ") " + advice;
+ }
+}
diff --git a/src/main/java/org/dbunit/database/rowcount/RowCountSnapshot.java b/src/main/java/org/dbunit/database/rowcount/RowCountSnapshot.java
new file mode 100644
index 000000000..a4404bc8f
--- /dev/null
+++ b/src/main/java/org/dbunit/database/rowcount/RowCountSnapshot.java
@@ -0,0 +1,132 @@
+/*
+ *
+ * The DbUnit Database Testing Framework
+ * Copyright (C)2002-2026, 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.database.rowcount;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Set;
+
+/**
+ * Immutable snapshot of table row counts, keyed by table name, taken at one point in
+ * a {@link RowCountCheck}. Holds no connection and issues no SQL of its own; it is built
+ * from the map a {@link RowCounter} already returned.
+ *
+ * @author dbunit
+ * @since 3.6.0
+ */
+public final class RowCountSnapshot
+{
+ private final Map rowCounts;
+
+ /**
+ * Creates a snapshot from a {@link RowCounter}'s result.
+ *
+ * @param rowCounts The row count of each table, keyed by table name; copied, not retained.
+ */
+ public RowCountSnapshot(final Map rowCounts)
+ {
+ this.rowCounts = Collections.unmodifiableMap(new LinkedHashMap<>(rowCounts));
+ }
+
+ /**
+ * Returns the row count of each table in this snapshot.
+ *
+ * @return An unmodifiable map of row count keyed by table name.
+ */
+ public Map getRowCounts()
+ {
+ return rowCounts;
+ }
+
+ /**
+ * Compares this snapshot, used as the baseline, against a snapshot captured later.
+ * Does not assume the two snapshots share the identical key set: a table absent from
+ * one side - e.g. dropped or created between the two captures, or the two connections
+ * behind them not enumerating identically - counts as {@code 0} on that side rather
+ * than throwing, so the difference is reported like any other rather than failing with
+ * a {@code NullPointerException}.
+ *
+ * @param current The snapshot to compare this baseline against.
+ * @return One {@link RowCountDifference} per table whose count changed, in this
+ * snapshot's table order followed by any table {@code current} has that this
+ * snapshot does not, in {@code current}'s order; empty when every count is
+ * unchanged.
+ */
+ public List difference(final RowCountSnapshot current)
+ {
+ final Set tableNames = new LinkedHashSet<>(rowCounts.keySet());
+ tableNames.addAll(current.rowCounts.keySet());
+
+ final List differences = new ArrayList<>();
+ for (final String tableName : tableNames)
+ {
+ final int baselineCount = rowCounts.getOrDefault(tableName, 0);
+ final int currentCount = current.rowCounts.getOrDefault(tableName, 0);
+ if (currentCount != baselineCount)
+ {
+ differences.add(
+ new RowCountDifference(tableName, baselineCount, currentCount));
+ }
+ }
+ return differences;
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public boolean equals(final Object o)
+ {
+ if (this == o)
+ {
+ return true;
+ }
+ if (!(o instanceof RowCountSnapshot))
+ {
+ return false;
+ }
+ final RowCountSnapshot other = (RowCountSnapshot) o;
+ return Objects.equals(rowCounts, other.rowCounts);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public int hashCode()
+ {
+ return Objects.hash(rowCounts);
+ }
+
+ /**
+ * {@inheritDoc}
+ */
+ @Override
+ public String toString()
+ {
+ return getClass().getSimpleName() + rowCounts;
+ }
+}
diff --git a/src/main/java/org/dbunit/database/rowcount/RowCounter.java b/src/main/java/org/dbunit/database/rowcount/RowCounter.java
new file mode 100644
index 000000000..f70a39d6b
--- /dev/null
+++ b/src/main/java/org/dbunit/database/rowcount/RowCounter.java
@@ -0,0 +1,66 @@
+/*
+ *
+ * The DbUnit Database Testing Framework
+ * Copyright (C)2002-2026, 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.database.rowcount;
+
+import java.sql.SQLException;
+import java.util.List;
+import java.util.Map;
+
+import org.dbunit.database.DatabaseConfig;
+import org.dbunit.database.IDatabaseConnection;
+
+/**
+ * Counts the rows of a set of database tables. The strategy behind
+ * {@link RowCountCheck}, configured via
+ * {@link DatabaseConfig#PROPERTY_ROW_COUNTER}; counting is the expensive part
+ * of the row count check and the part most likely to be improved, so it is
+ * the one seam the check opens.
+ *
+ * An implementation's contract:
+ *
+ * - Return an entry for every requested table name, keyed exactly as
+ * supplied.
+ *
- Return entries for no other tables.
+ *
- Counts must be exact. Estimates, such as vendor statistics views
+ * that lag asynchronously, are not acceptable however cheap they are, since
+ * they would produce false failures.
+ *
+ * Table enumeration and exclusion filtering are handled by {@link RowCountCheck}
+ * before this interface is ever consulted, so an implementation's whole job is
+ * counting the list it is handed.
+ *
+ * @author dbunit
+ * @since 3.6.0
+ */
+public interface RowCounter
+{
+ /**
+ * Counts the rows of every given table.
+ *
+ * @param connection the connection to count rows through.
+ * @param tableNames the names of the tables to count; every name must appear
+ * as a key in the returned map, and no other keys may appear.
+ * @return the row count of each requested table, keyed exactly as supplied.
+ * @throws SQLException if counting a table's rows fails.
+ */
+ Map countRows(IDatabaseConnection connection, List tableNames)
+ throws SQLException;
+}
diff --git a/src/main/java/org/dbunit/database/rowcount/UnexpectedRowCountException.java b/src/main/java/org/dbunit/database/rowcount/UnexpectedRowCountException.java
new file mode 100644
index 000000000..44b222501
--- /dev/null
+++ b/src/main/java/org/dbunit/database/rowcount/UnexpectedRowCountException.java
@@ -0,0 +1,81 @@
+/*
+ *
+ * The DbUnit Database Testing Framework
+ * Copyright (C)2002-2026, 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.database.rowcount;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+import org.dbunit.DatabaseUnitException;
+import org.dbunit.database.IDatabaseConnection;
+
+/**
+ * Thrown by {@link RowCountCheck#verify(RowCountSnapshot, IDatabaseConnection)} when one or
+ * more tables' row counts no longer match the baseline. The message names every affected
+ * table, both counts, the signed delta, and direction-specific advice, in the form a reader can
+ * paste straight into a dataset or an exclude list.
+ *
+ * @author dbunit
+ * @since 3.6.0
+ */
+public class UnexpectedRowCountException extends DatabaseUnitException
+{
+ private static final long serialVersionUID = 1L;
+
+ private final List differences;
+
+ /**
+ * Creates an exception reporting the given differences.
+ *
+ * @param differences The tables whose row counts no longer match the baseline; must not be
+ * empty.
+ */
+ public UnexpectedRowCountException(final List differences)
+ {
+ super(buildMessage(differences));
+ this.differences = Collections.unmodifiableList(new ArrayList<>(differences));
+ }
+
+ /**
+ * Returns the tables whose row counts no longer match the baseline.
+ *
+ * @return The differences, one per affected table.
+ */
+ public List getDifferences()
+ {
+ return differences;
+ }
+
+ private static String buildMessage(final List differences)
+ {
+ final int count = differences.size();
+ final String tableWord = count == 1 ? " table differs" : " tables differ";
+
+ final StringBuilder message = new StringBuilder();
+ message.append("Row count check failed: ").append(count).append(tableWord)
+ .append(" from the pre-test baseline.");
+ for (final RowCountDifference difference : differences)
+ {
+ message.append(System.lineSeparator()).append(" ").append(difference);
+ }
+ return message.toString();
+ }
+}
diff --git a/src/main/java/org/dbunit/junit/jupiter/DbUnitExtension.java b/src/main/java/org/dbunit/junit/jupiter/DbUnitExtension.java
index fc28b0c08..e8adc666d 100644
--- a/src/main/java/org/dbunit/junit/jupiter/DbUnitExtension.java
+++ b/src/main/java/org/dbunit/junit/jupiter/DbUnitExtension.java
@@ -24,6 +24,10 @@
import java.lang.reflect.Modifier;
import org.dbunit.IDatabaseTester;
+import org.dbunit.database.IDatabaseConnection;
+import org.dbunit.database.rowcount.RowCountCheck;
+import org.dbunit.database.rowcount.RowCountCheckConfiguration;
+import org.dbunit.database.rowcount.RowCountChecker;
import org.junit.jupiter.api.extension.AfterTestExecutionCallback;
import org.junit.jupiter.api.extension.BeforeTestExecutionCallback;
import org.junit.jupiter.api.extension.ExtensionContext;
@@ -66,6 +70,20 @@
* enclosing class instances—since a Java nested class does not extend its
* enclosing class.
*
+ * Also runs the {@link RowCountCheck row count check} around the test, via the same
+ * {@link RowCountChecker} that manages it for {@code DefaultPrepAndExpectedTestCase}: a
+ * baseline is captured before {@code onSetup()}, and verified after {@code onTearDown()}
+ * unless the test method itself threw, in which case the database is in an unknown state and
+ * a count difference would be noise around the real failure. The check is opt-in and off by
+ * default - see {@link RowCountCheckConfiguration}. A tester whose
+ * {@link IDatabaseTester#getConnection()} returns {@code null} (e.g. a test double) is
+ * tolerated; the check simply never activates for it. The connection {@link
+ * IDatabaseTester#getConnection()} returns is never closed here - only its owner (the
+ * tester's {@link org.dbunit.IOperationListener}, or the caller that constructed the
+ * tester) knows whether it is safe to close, e.g. a {@code DefaultDatabaseTester} built
+ * from one fixed connection returns that same connection from every call, and closing it
+ * early would break the {@code onSetup()} that runs right after capturing the baseline.
+ *
* @author dbunit
* @since 3.5.0
*/
@@ -75,34 +93,95 @@ public class DbUnitExtension implements BeforeTestExecutionCallback, AfterTestEx
private static final ExtensionContext.Namespace NAMESPACE =
ExtensionContext.Namespace.create(DbUnitExtension.class);
- private static final String TESTER_KEY = "databaseTester";
+ /** Package-visible so tests can reference it instead of duplicating the literal. */
+ static final String TESTER_KEY = "databaseTester";
+ /** Package-visible so tests can reference it instead of duplicating the literal. */
+ static final String ROW_COUNT_CHECKER_KEY = "rowCountChecker";
/**
* Runs database setup before the test method executes.
*
* @param context The extension context for the test method.
- * @throws Exception If resolving the {@link IDatabaseTester} field or its onSetup() call fails.
+ * @throws Exception If resolving the {@link IDatabaseTester} field, capturing the row
+ * count check baseline, or its onSetup() call fails.
*/
@Override
public void beforeTestExecution(final ExtensionContext context) throws Exception {
final IDatabaseTester tester = resolveTester(context);
- context.getStore(NAMESPACE).put(TESTER_KEY, tester);
+ final ExtensionContext.Store store = context.getStore(NAMESPACE);
+ store.put(TESTER_KEY, tester);
+ store.put(ROW_COUNT_CHECKER_KEY, captureRowCountBaseline(tester));
+
tester.onSetup();
}
/**
- * Runs database teardown after the test method executes.
+ * Runs database teardown after the test method executes, then verifies the row count
+ * check baseline unless the test method itself threw.
*
* @param context The extension context for the test method.
- * @throws Exception If the stored {@link IDatabaseTester}'s onTearDown() call fails.
+ * @throws Exception If the stored {@link IDatabaseTester}'s onTearDown() call fails, or if
+ * a table's row count no longer matches the baseline
+ * ({@link org.dbunit.database.rowcount.UnexpectedRowCountException}).
*/
@Override
public void afterTestExecution(final ExtensionContext context) throws Exception {
- final IDatabaseTester tester =
- context.getStore(NAMESPACE).get(TESTER_KEY, IDatabaseTester.class);
+ final ExtensionContext.Store store = context.getStore(NAMESPACE);
+ final IDatabaseTester tester = store.get(TESTER_KEY, IDatabaseTester.class);
if (tester != null) {
tester.onTearDown();
+
+ final RowCountChecker rowCountChecker =
+ store.get(ROW_COUNT_CHECKER_KEY, RowCountChecker.class);
+ if (rowCountChecker != null && rowCountChecker.hasBaseline()
+ && !context.getExecutionException().isPresent()) {
+ verifyRowCountUnchanged(tester, rowCountChecker);
+ }
+ }
+ }
+
+ /**
+ * Captures the row count check baseline for {@code tester} into a fresh
+ * {@link RowCountChecker}, using whatever connection {@code tester.getConnection()}
+ * returns - the same one {@code onSetup()} itself will use if the tester always returns
+ * one fixed connection - without closing it: that connection's lifecycle belongs to the
+ * tester, not to this check.
+ *
+ * @param tester the tester to capture a baseline for.
+ * @return the checker holding the captured baseline, or {@code null} when {@code tester}
+ * has no connection to inspect. The returned checker holds no baseline - see
+ * {@link RowCountChecker#hasBaseline()} - when the check is disabled.
+ * @throws Exception if resolving the connection or capturing the baseline fails.
+ */
+ private RowCountChecker captureRowCountBaseline(final IDatabaseTester tester)
+ throws Exception {
+ final IDatabaseConnection connection = tester.getConnection();
+ if (connection == null) {
+ return null;
+ }
+ final RowCountChecker rowCountChecker = new RowCountChecker();
+ rowCountChecker.capture(connection);
+ return rowCountChecker;
+ }
+
+ /**
+ * Verifies {@code rowCountChecker}'s baseline against whatever connection
+ * {@code tester.getConnection()} returns, without closing it - see
+ * {@link #captureRowCountBaseline(IDatabaseTester)}.
+ *
+ * @param tester the tester to verify against.
+ * @param rowCountChecker the checker holding the baseline captured by
+ * {@link #captureRowCountBaseline(IDatabaseTester)}.
+ * @throws Exception if resolving the connection fails, or if a table's row count no longer
+ * matches the baseline.
+ */
+ private void verifyRowCountUnchanged(final IDatabaseTester tester,
+ final RowCountChecker rowCountChecker) throws Exception {
+ final IDatabaseConnection connection = tester.getConnection();
+ if (connection == null) {
+ return;
}
+ rowCountChecker.verify(connection);
}
private IDatabaseTester resolveTester(final ExtensionContext context) throws Exception {
diff --git a/src/site/asciidoc/bestpractices.adoc b/src/site/asciidoc/bestpractices.adoc
index 7890c929c..9eaa8c33c 100644
--- a/src/site/asciidoc/bestpractices.adoc
+++ b/src/site/asciidoc/bestpractices.adoc
@@ -5,6 +5,7 @@
. <>
. <>
. <>
+. <>
[#onedbperdev]
== Use one database instance per developer
@@ -115,3 +116,18 @@ public class MyJNDIDatabaseTest extends JndiBasedDBTestCase {
----
You may also use JndiDatabaseTester if you can't subclass JndiBasedDBTestCase.
+
+[#rowcountcheck]
+== Periodically run with the row count check enabled
+
+link:components/rowcountcheck.html[RowCountCheck] catches a table your teardown forgot
+(its leftover rows corrupt whatever unrelated test runs next) and a reference table your
+teardown wrongly cleaned (every later test depending on it fails in ways that look
+nothing like the cause). It is read-only and opt-in for a reason: capturing two row-count
+snapshots per test roughly doubles that test's table-counting cost, so it is not something
+you want paying for on every routine run.
+
+Instead, run your suite with it enabled periodically — e.g. a scheduled/nightly CI job via
+`-Ddbunit.rowCountCheck=true` — rather than leaving it on permanently. That is enough to
+catch a teardown regression soon after it's introduced, without slowing down the CI feedback
+loop of every pull request.
diff --git a/src/site/asciidoc/components.adoc b/src/site/asciidoc/components.adoc
index b73d825b6..c4e192dc4 100644
--- a/src/site/asciidoc/components.adoc
+++ b/src/site/asciidoc/components.adoc
@@ -111,4 +111,5 @@ A few — `ITable`, `VerifyTableDefinition`, `IOperationListener`, and
|`PrepAndExpectedTestCase`, `PrepAndExpectedTestCaseSteps` |link:testcases/PrepAndExpectedTestCase.html[PrepAndExpectedTestCase] — turn-key prep/verify/cleanup test case.
|anchor:verifytabledefinition[]`link:components/verifytabledefinition.html[VerifyTableDefinition]` |*New:* link:components/verifytabledefinition.html[VerifyTableDefinition] — defines one table to verify: column filters and `ValueComparer`s.
|`link:components/ioperationlistener.html[IOperationListener]` |*New:* link:components/ioperationlistener.html[IOperationListener] — hooks into connection setup/teardown lifecycle events.
+|`link:components/rowcountcheck.html[RowCountCheck]`, `RowCounter`, `RowCountChecker`, `RowCountSnapshot`, `RowCountDifference` |*New:* link:components/rowcountcheck.html[RowCountCheck] — opt-in diagnostic that fails a test when a table's row count moved between setup and teardown, catching prep/expected datasets that are missing a table or wrongly list one.
|===
diff --git a/src/site/asciidoc/components/rowcountcheck.adoc b/src/site/asciidoc/components/rowcountcheck.adoc
new file mode 100644
index 000000000..8b45bed1f
--- /dev/null
+++ b/src/site/asciidoc/components/rowcountcheck.adoc
@@ -0,0 +1,209 @@
+= RowCountCheck
+
+[#overview]
+== Overview
+
+link:/dbunit/apidocs/org/dbunit/database/rowcount/RowCountCheck.html[RowCountCheck]
+(`org.dbunit.database.rowcount`, since 3.6.0) is an opt-in diagnostic that compares every table's
+row count before and after a test, and fails the test when a count moved. It catches two
+mistakes that are otherwise silent at the point they happen and only surface later, in an
+unrelated test:
+
+[cols="1,3", options="header"]
+|===
+|Mistake |Consequence
+
+|*Under-listing* — a table the code under test writes to is missing from the
+prep/expected dataset
+|Its rows survive teardown. A *later, unrelated* test fails on the extra data, naming the
+wrong test and starting the debugging in the wrong place.
+
+|*Over-listing* — a reference table is listed that should never be cleaned
+|The teardown operation strips rows the DDL seeded. Every later test that depends on that
+reference data fails in ways that look nothing like the cause.
+|===
+
+Both are the same underlying defect: the database did not return to the state the test
+inherited, and nothing checked that — until now.
+
+[#what-it-detects]
+== What It Detects, and What It Does Not
+
+The check compares `COUNT(*)` per table, captured fresh before the test and compared again
+after teardown. That catches every row added or removed, regardless of *how* — application
+code, triggers, `ON DELETE CASCADE`, stored procedures, or a `DataSource` the test never
+sees. It is immune to the mechanism because it reads the end state, not the statements that
+produced it.
+
+It does *not* catch:
+
+* An `UPDATE` that changes values without changing the row count.
+* An insert-N/delete-N sequence that nets to zero.
+
+Neither leaves extra or missing rows, which is the problem this check solves.
+
+[#enabling]
+== Enabling It
+
+The check is *off by default* and read-only — it never modifies data. Turn it on to verify
+a suite's teardown correctness; leave it off for routine runs, since capturing two snapshots
+per test roughly doubles that test's table-counting cost.
+
+Enable it via the link:../properties.html#rowcountcheck[`FEATURE_ROW_COUNT_CHECK`] feature:
+
+[source,java]
+----
+DatabaseConfig config = connection.getConfig();
+config.setFeature(DatabaseConfig.FEATURE_ROW_COUNT_CHECK, true);
+----
+
+or, without touching code, via a system property — which wins over the feature in *either*
+direction, so it can force-enable in CI or force-disable locally regardless of what the code
+configures:
+
+[source]
+----
+-Ddbunit.rowCountCheck=true
+----
+
+It is wired into both link:../testcases/PrepAndExpectedTestCase.html[PrepAndExpectedTestCase]
+and link:../testcases/DbUnitExtension.html[DbUnitExtension]; enabling the feature (or the
+system property) is everything a test needs to do. Both integration points share the same
+`org.dbunit.database.rowcount.RowCountChecker`, the class that captures a baseline, verifies
+it later, and lets it be discarded when a verify would be noise (e.g. the test's own steps
+already failed) — plumbing a test integration reuses, not something a test author calls
+directly.
+
+[#exclusions]
+== Excluding Tables
+
+Some tables legitimately change and can never be cleaned back to a fixed baseline:
+
+* Append-only audit and log tables that nothing cleans.
+* Sequence-emulation tables (a `NEXT_ID`/`HIBERNATE_SEQUENCES` table) that change on every
+insert by design.
+* Tables owned by a different lifecycle than the test's.
+* A very large, static reference table where `COUNT(*)` itself is what makes the run slow —
+a performance exclusion, not a correctness one.
+
+Configure patterns — supporting the same `*`/`?` wildcards as
+link:../filters.html[`ExcludeTableFilter`] — via
+link:../properties.html#rowcountcheckexcludetables[`PROPERTY_ROW_COUNT_CHECK_EXCLUDE_TABLES`]:
+
+[source,java]
+----
+config.setProperty(DatabaseConfig.PROPERTY_ROW_COUNT_CHECK_EXCLUDE_TABLES,
+ new String[] {"AUDIT_*", "HIBERNATE_SEQUENCES"});
+----
+
+or the matching system property, which *replaces* rather than appends to any configured
+patterns:
+
+[source]
+----
+-Ddbunit.rowCountCheckExcludeTables=AUDIT_*,HIBERNATE_SEQUENCES
+----
+
+[#failure-message]
+== Reading a Failure
+
+[source]
+----
+Row count check failed: 2 tables differ from the pre-test baseline.
+ ACCOUNT_AUDIT 0 -> 3 (+3) rows left behind; add the table to the expected dataset, or exclude it
+ COUNTRY_CODE 12 -> 0 (-12) rows removed that should remain; drop the table from the prep/expected dataset, or exclude it
+----
+
+Each line names the table in the exact form `getTableNames()` returned it, so it can be
+pasted straight into a dataset or an exclude list, and the delta's sign tells you which fix
+applies:
+
+* *Positive* — rows were left behind. Add the table to the expected dataset (so teardown
+cleans it) — with `DefaultPrepAndExpectedTestCase`, that also means adding a matching
+`VerifyTableDefinition`, since an expected table with none fails verification on its own
+by default — or exclude it if it legitimately can't be cleaned.
+* *Negative* — rows that should remain were removed. Drop the table from the prep/expected
+dataset (so teardown never touches it), or exclude it.
+
+[#row-counter]
+== Supplying Your Own RowCounter
+
+Counting is the expensive part of the check, so it is the one seam left open:
+link:/dbunit/apidocs/org/dbunit/database/rowcount/RowCounter.html[`RowCounter`], registered like
+every other dbUnit extension point via
+link:../properties.html#rowcounter[`DatabaseConfig.PROPERTY_ROW_COUNTER`]. The shipped
+implementation, `QueryPerTableRowCounter`, issues one `SELECT COUNT(*)` per table.
+
+A `RowCounter` implementation's contract:
+
+* Return an entry for *every* requested table name, keyed exactly as supplied.
+* Return entries for *no other* tables.
+* Counts must be *exact* — a vendor statistics view (e.g. PostgreSQL's
+`pg_stat_user_tables`) lags asynchronously and would produce false failures, however cheap
+it is to query.
+
+Table enumeration and exclusion filtering happen in `RowCountCheck` itself, outside the
+strategy, so an implementation's whole job is counting the list it is handed:
+
+[source,java]
+----
+public interface RowCounter
+{
+ Map countRows(IDatabaseConnection connection, List tableNames)
+ throws SQLException;
+}
+----
+
+An illustrative sketch, *not* production-ready — batching every table into one query per
+round trip instead of one round trip per table. It embeds table names directly into both a
+`FROM` identifier and a string literal; a real implementation has to correctly quote and
+escape both for every supported vendor before this is safe to use as-is:
+
+[source,java]
+----
+public class UnionAllRowCounter implements RowCounter
+{
+ @Override
+ public Map countRows(IDatabaseConnection connection,
+ List tableNames) throws SQLException
+ {
+ Map rowCounts = new LinkedHashMap<>();
+ if (tableNames.isEmpty())
+ {
+ return rowCounts;
+ }
+
+ String sql = tableNames.stream()
+ .map(name -> "SELECT '" + name + "' AS t, COUNT(*) AS c FROM " + name)
+ .collect(Collectors.joining(" UNION ALL "));
+
+ try (Statement statement = connection.getConnection().createStatement();
+ ResultSet resultSet = statement.executeQuery(sql))
+ {
+ while (resultSet.next())
+ {
+ rowCounts.put(resultSet.getString("t"), resultSet.getInt("c"));
+ }
+ }
+ return rowCounts;
+ }
+}
+----
+
+Register it the same way as any other `DatabaseConfig` property:
+
+[source,java]
+----
+config.setProperty(DatabaseConfig.PROPERTY_ROW_COUNTER, new UnionAllRowCounter());
+----
+
+[#caveats]
+== Caveats
+
+* *Sequences and identity columns are not reset.* Deleting leftover rows never resets
+them, so generated IDs still drift across tests even when counts balance.
+* *A row-removing teardown operation is presumed.* With `DatabaseOperation.NONE`, every
+prep row reads as a difference.
+* *Modified rows are invisible* — see <>.
+* *Parallel tests against one database break the check*, as they already break
+`DELETE_ALL` teardown. Not specific to this check.
diff --git a/src/site/asciidoc/index.adoc b/src/site/asciidoc/index.adoc
index 6adf6db04..0d7a90f0b 100644
--- a/src/site/asciidoc/index.adoc
+++ b/src/site/asciidoc/index.adoc
@@ -46,14 +46,14 @@ We will gladly help you as needed with your ideas and contributions and look to
|===
|Date |News
-// |TBD
-// |Please try the 3.5.0-SNAPSHOT snapshot build and let us know how it works!
-// It adds `DbUnitExtension` for *native JUnit 5/6 lifecycle management*, a new *JSON dataset format* and JSON `ValueComparer`, *MariaDB and H2 2.x* database support, expanded PostgreSQL `json`/`jsonb` and array type support, and an opt-in escape hatch for *circular foreign keys*, plus a ground-up *documentation site overhaul* and numerous other bug fixes.
-// See link:https://dbunit.github.io/dbunit-extension/repos.html#snapshots[SNAPSHOTS] for how to use them.
-// Refer to the link:changes.html#a3.5.0-SNAPSHOT[changes report],
-// the link:https://github.com/dbunit/dbunit-extension/issues?q=is%3Aissue+milestone%3A3.5.0%20type%3AFeature[feature list], and
-// the link:https://github.com/dbunit/dbunit-extension/issues?q=is%3Aissue+milestone%3A3.5.0%20type%3ABug[bug list]
-// for the snapshot contents (and subsequent updates).
+|TBD
+|Please try the 3.6.0-SNAPSHOT snapshot build and let us know how it works!
+It adds an opt-in *row count check* (`RowCountCheck`) that catches tables teardown missed or wrongly cleaned.
+See link:https://dbunit.github.io/dbunit-extension/repos.html#snapshots[SNAPSHOTS] for how to use them.
+Refer to the link:changes.html#a3.6.0-SNAPSHOT[changes report],
+the link:https://github.com/dbunit/dbunit-extension/issues?q=is%3Aissue+milestone%3A3.6.0%20type%3AFeature[feature list], and
+the link:https://github.com/dbunit/dbunit-extension/issues?q=is%3Aissue+milestone%3A3.6.0%20type%3ABug[bug list]
+for the snapshot contents (and subsequent updates).
|2026-08-11
|Release 3.5.0 available.
diff --git a/src/site/asciidoc/properties.adoc b/src/site/asciidoc/properties.adoc
index cc048bfe2..eed87e149 100644
--- a/src/site/asciidoc/properties.adoc
+++ b/src/site/asciidoc/properties.adoc
@@ -80,6 +80,11 @@ _Note:_ this feature was not compatible with the <
|http://www.dbunit.org/features/skipCycleCheck
|false
|Let link:filters.html#databasesequencefilter[DatabaseSequenceFilter] skip its foreign-key dependency cycle check instead of throwing `CyclicTablesDependencyException`. Each cycle is instead treated as one unit for ordering purposes: tables outside it are still correctly sorted relative to it, but the relative order of the tables making up the cycle falls back to their original input order — only useful when the cycle is handled another way (e.g. nullable FK columns populated by a later operation, or database-side deferred constraint checking).
+
+|anchor:rowcountcheck[]`FEATURE_ROW_COUNT_CHECK`
+|http://www.dbunit.org/features/rowCountCheck
+|false
+|Compare every table's row count before and after each test, failing the test when a count moved — see link:components/rowcountcheck.html[RowCountCheck] for what it catches and how to read a failure. Read-only; never modifies data. The `dbunit.rowCountCheck` system property overrides this feature in *either* direction when present (e.g. `-Ddbunit.rowCountCheck=true`), so it can force-enable in CI or force-disable locally regardless of what the code configures.
|===
== Properties
@@ -164,4 +169,14 @@ For all others the default handler should do the job: link:apidocs/org/dbunit/da
|false
|By default, link:apidocs/org/dbunit/DefaultPrepAndExpectedTestCase.html[DefaultPrepAndExpectedTestCase] fails the test when the expected dataset has more tables than the supplied link:apidocs/org/dbunit/VerifyTableDefinition.html[VerifyTableDefinition]s (see link:components/verifytabledefinition.html[VerifyTableDefinition] for the class reference) — a safety net for an expected table that was defined but never wired to a VerifyTableDefinition, which would otherwise be silently skipped during verification. Set this property to true to relax that check and allow the counts to disagree.
|
+
+|anchor:rowcountcheckexcludetables[]http://www.dbunit.org/properties/rowCountCheckExcludeTables
+|String[]{}
+|Table name patterns (`*`/`?` wildcards supported, same as link:filters.html[ExcludeTableFilter]) excluded from the <>. See link:components/rowcountcheck.html[RowCountCheck] for worked examples.
+|The `dbunit.rowCountCheckExcludeTables` system property, when present, *replaces* rather than appends to these patterns (e.g. `-Ddbunit.rowCountCheckExcludeTables=AUDIT_*,HIBERNATE_SEQUENCES`, comma-separated, each pattern trimmed).
+
+|anchor:rowcounter[]http://www.dbunit.org/properties/rowCounter
+|org.dbunit.database.rowcount.QueryPerTableRowCounter
+|Used to configure the row-counting strategy the <> uses. The Object must implement link:apidocs/org/dbunit/database/rowcount/RowCounter.html[org.dbunit.database.rowcount.RowCounter]. See link:components/rowcountcheck.html#row-counter[Supplying Your Own RowCounter] for the contract and a worked implementation.
+|No system property override — swapping the counting implementation is a code-level decision made once for a suite, not something flipped per run.
|===
diff --git a/src/site/asciidoc/testcases/DbUnitExtension.adoc b/src/site/asciidoc/testcases/DbUnitExtension.adoc
index 28ce4ebc2..aab5e04ee 100644
--- a/src/site/asciidoc/testcases/DbUnitExtension.adoc
+++ b/src/site/asciidoc/testcases/DbUnitExtension.adoc
@@ -57,6 +57,18 @@ NOTE: `@Nested` test classes are not supported — field discovery only walks
the innermost test instance and its superclasses, not enclosing class
instances, since a Java nested class does not extend its enclosing class.
+== Row Count Check
+
+The same link:../components/rowcountcheck.html[RowCountCheck] diagnostic available to
+link:PrepAndExpectedTestCase.html[PrepAndExpectedTestCase] applies here too: a baseline is
+captured from the resolved `IDatabaseTester`'s connection before `onSetup()` and verified
+after `onTearDown()`, failing the test by name when a table's row count moved. Verification
+is skipped whenever `onTearDown()` itself throws, and also when the test method threw
+before reaching it, since either way the database is left in an unknown state and a count
+difference would only be noise around the real failure. It is off by default; enable it
+with `DatabaseConfig.FEATURE_ROW_COUNT_CHECK` (or `-Ddbunit.rowCountCheck=true`) on the
+connection's config.
+
== When to Use This Instead of Manual Lifecycle Calls
Reach for `DbUnitExtension` when a `@BeforeEach`/`@AfterEach` pair that only
diff --git a/src/site/asciidoc/testcases/PrepAndExpectedTestCase.adoc b/src/site/asciidoc/testcases/PrepAndExpectedTestCase.adoc
index 5f9797eca..b92957e69 100644
--- a/src/site/asciidoc/testcases/PrepAndExpectedTestCase.adoc
+++ b/src/site/asciidoc/testcases/PrepAndExpectedTestCase.adoc
@@ -86,6 +86,23 @@ link:../operations.html[DatabaseOperation]s (default `CLEAN_INSERT` / `NONE`) ru
automatically around your test steps — no manual `onSetup()`/`onTearDown()` calls
needed when using `runTest()`.
+== Verifying Your Teardown Table List Is Complete
+
+The teardown operation only cleans the tables named in your prep and expected datasets.
+Two mistakes here are silent at the point they happen and only surface later, in an
+*unrelated* test: forgetting to list a table the code under test writes to (its rows
+survive teardown), and wrongly listing a reference table that should never be cleaned
+(teardown strips rows the DDL seeded).
+
+link:../components/rowcountcheck.html[RowCountCheck] is an opt-in diagnostic for exactly
+this: it compares every table's row count before `preTest()` and after `cleanupData()`,
+failing the test by name when a count moved instead of letting the corruption surface in
+whichever test happens to run next. It is off by default; turn it on with
+`DatabaseConfig.FEATURE_ROW_COUNT_CHECK` (or `-Ddbunit.rowCountCheck=true`) when
+verifying a suite's teardown correctness, and see
+link:../components/rowcountcheck.html[the RowCountCheck page] for what it catches, how
+to exclude legitimately-changing tables, and how to read a failure.
+
== Usage
=== Configure
diff --git a/src/site/site.xml b/src/site/site.xml
index f7ce2f072..c19442387 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -113,6 +113,7 @@