MigrationTestHelper
public final class MigrationTestHelper
A class that can help test and verify database creation and migration at different versions with different schemas.
Common usage of this helper is to create a database at an older version first and then attempt a migration and validation:
@Test
fun migrationTest() {
val migrationTestHelper = getMigrationTestHelper()
// Create the database at version 1
val newConnection = migrationTestHelper.createDatabase(1)
// Insert some data that should be preserved
newConnection.execSQL("INSERT INTO Pet (id, name) VALUES (1, 'Tom')")
newConnection.close()
// Migrate the database to version 2
val migratedConnection =
migrationTestHelper.runMigrationsAndValidate(2, listOf(MIGRATION_1_2)))
migratedConnection.prepare("SELECT * FROM Pet).use { stmt ->
// Validates data is preserved between migrations.
assertThat(stmt.step()).isTrue()
assertThat(stmt.getText(1)).isEqualTo("Tom")
}
migratedConnection.close()
}
The helper relies on exported schemas so androidx.room3.Database.exportSchema should be enabled. Schema location should be configured via Room's Gradle Plugin (id 'androidx.room'):
room {
schemaDirectory("$projectDir/schemas")
}The helper is then instantiated to use the same schema location where they are exported to. See platform-specific documentation for further configuration.
Summary
Public constructors |
|---|
MigrationTestHelper(Creates a new migration helper. |
MigrationTestHelper( |
Public methods |
|
|---|---|
@NonNull Statement |
apply(@NonNull Statement base, @NonNull Description description) |
@NonNull Statement |
apply(@NonNull Statement base, @NonNull Description description) |
void |
Registers a database connection to be automatically closed when the test finishes. |
final @NonNull SQLiteConnection |
createDatabase(int version)Creates the database at the given version. |
final @NonNull SQLiteConnection |
runMigrationsAndValidate(Runs the given set of migrations on the existing database once created via |
Protected methods |
|
|---|---|
void |
failed(@NonNull Throwable e, @NonNull Description description) |
void |
failed(@NonNull Throwable e, @NonNull Description description) |
void |
finished(Description description) |
void |
finished(Description description) |
void |
This method is deprecated. Deprecated in Java |
void |
This method is deprecated. Deprecated in Java |
void |
skipped( |
void |
skipped( |
void |
starting(Description description) |
void |
starting(@NonNull Description description) |
void |
succeeded(@NonNull Description description) |
void |
succeeded(@NonNull Description description) |
Public constructors
MigrationTestHelper
public MigrationTestHelper(
@NonNull Instrumentation instrumentation,
@NonNull File file,
@NonNull SQLiteDriver driver,
@NonNull KClass<@NonNull RoomDatabase> databaseClass,
@NonNull Function0<@NonNull RoomDatabase> databaseFactory,
@NonNull List<@NonNull AutoMigrationSpec> autoMigrationSpecs
)
Creates a new migration helper. It uses the instrumentation context to load the schema (falls back to the app resources) and the target context to create the database.
When the MigrationTestHelper is created with this constructor configuration then only createDatabase and runMigrationsAndValidate that return SQLiteConnection can be used.
| Parameters | |
|---|---|
@NonNull Instrumentation instrumentation |
The instrumentation instance. |
@NonNull File file |
The database file. |
@NonNull SQLiteDriver driver |
A driver that opens connection to a file database. A driver that opens connections to an in-memory database would be meaningless. |
@NonNull KClass<@NonNull RoomDatabase> databaseClass |
The |
@NonNull Function0<@NonNull RoomDatabase> databaseFactory |
An optional factory function to create an instance of the |
@NonNull List<@NonNull AutoMigrationSpec> autoMigrationSpecs |
The list of |
MigrationTestHelper
public MigrationTestHelper(
@NonNull Path schemaDirectoryPath,
@NonNull Path databasePath,
@NonNull SQLiteDriver driver,
@NonNull KClass<@NonNull RoomDatabase> databaseClass,
@NonNull Function0<@NonNull RoomDatabase> databaseFactory,
@NonNull List<@NonNull AutoMigrationSpec> autoMigrationSpecs
)
| Parameters | |
|---|---|
@NonNull Path schemaDirectoryPath |
The schema directory where schema files are exported. |
@NonNull Path databasePath |
Name of the database. |
@NonNull SQLiteDriver driver |
A driver that opens connection to a file database. A driver that opens connections to an in-memory database would be meaningless. |
@NonNull KClass<@NonNull RoomDatabase> databaseClass |
The |
@NonNull Function0<@NonNull RoomDatabase> databaseFactory |
An optional factory function to create an instance of the |
@NonNull List<@NonNull AutoMigrationSpec> autoMigrationSpecs |
The list of |
Public methods
closeWhenFinished
public void closeWhenFinished(@NonNull RoomDatabase db)
Registers a database connection to be automatically closed when the test finishes.
This only works if MigrationTestHelper is registered as a Junit test rule via the org.junit.Rule annotation.
| Parameters | |
|---|---|
@NonNull RoomDatabase db |
The RoomDatabase instance which holds the database. |
createDatabase
public final @NonNull SQLiteConnection createDatabase(int version)
Creates the database at the given version.
Once a database is created it can further validate with runMigrationsAndValidate.
| Parameters | |
|---|---|
int version |
The version of the schema at which the database should be created. |
| Returns | |
|---|---|
@NonNull SQLiteConnection |
A database connection of the newly created database. |
| Throws | |
|---|---|
IllegalStateException |
If a new database was not created. |
runMigrationsAndValidate
public final @NonNull SQLiteConnection runMigrationsAndValidate(
int version,
@NonNull List<@NonNull Migration> migrations
)
Runs the given set of migrations on the existing database once created via createDatabase.
This function uses the same algorithm that Room performs to choose migrations such that the migrations instances provided must be sufficient to bring the database from current version to the desired version. If the database contains androidx.room3.AutoMigrations, then those are already included in the list of migrations to execute if necessary. Note that provided manual migrations take precedence over auto migrations if they overlap in migration paths.
Once migrations are done, this functions validates the database schema to ensure the migration performed resulted in the expected schema.
| Parameters | |
|---|---|
int version |
The final version the database should migrate to. |
@NonNull List<@NonNull Migration> migrations |
The list of migrations used to attempt the database migration. |
| Returns | |
|---|---|
@NonNull SQLiteConnection |
A database connection of the migrated database. |
| Throws | |
|---|---|
IllegalStateException |
If the schema validation fails. |
Protected methods
skipped
protected voidskipped(
@NonNull AssumptionViolatedException e,
@NonNull Description description
)
skipped
protected voidskipped(
@NonNull AssumptionViolatedException e,
@NonNull Description description
)
skipped
protected void skipped(
@NonNull AssumptionViolatedException e,
@NonNull Description description
)
skipped
protected void skipped(
@NonNull AssumptionViolatedException e,
@NonNull Description description
)