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.room.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(
    @NonNull Instrumentation instrumentation,
    @NonNull Class<@NonNull RoomDatabase> databaseClass
)

Creates a new migration helper.
MigrationTestHelper(
    @NonNull Instrumentation instrumentation,
    @NonNull String assetsFolder,
    @NonNull SupportSQLiteOpenHelper.Factory openFactory
)

This method is deprecated. Cannot be used to run migration tests involving auto migrations.
MigrationTestHelper(
    @NonNull Instrumentation instrumentation,
    @NonNull Class<@NonNull RoomDatabase> databaseClass,
    @NonNull List<@NonNull AutoMigrationSpec> specs,
    @NonNull SupportSQLiteOpenHelper.Factory openFactory
)

Creates a new migration helper.
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.
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
)

Public methods
@NonNull Statement
@NonNull Statement
void

Registers a database connection to be automatically closed when the test finishes.
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.
@NonNull SupportSQLiteDatabase
createDatabase(@NonNull String name, int version)

Creates the database in the given version.
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.
@NonNull SupportSQLiteDatabase
runMigrationsAndValidate(
    @NonNull String name,
    int version,
    boolean validateDroppedTables,
    @NonNull Migration migrations
)

Runs the given set of migrations on the provided database.

Protected methods
void
void
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
void
void
starting(Description description)
void
void
void

Public constructors

MigrationTestHelper

Added in 2.4.0
public MigrationTestHelper(
    @NonNull Instrumentation instrumentation,
    @NonNull Class<@NonNull RoomDatabase> databaseClass
)

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 SupportSQLiteDatabase can be used.

Parameters
@NonNull Instrumentation instrumentation

The instrumentation instance.
@NonNull Class<@NonNull RoomDatabase> databaseClass

The Database class to be tested.

MigrationTestHelper

Added in 2.0.0
Deprecated in 2.4.0
public MigrationTestHelper(
    @NonNull Instrumentation instrumentation,
    @NonNull String assetsFolder,
    @NonNull SupportSQLiteOpenHelper.Factory openFactory
)

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 SupportSQLiteDatabase can be used.

Parameters
@NonNull Instrumentation instrumentation

The instrumentation instance.
@NonNull String assetsFolder

The asset folder in the assets directory.
@NonNull SupportSQLiteOpenHelper.Factory openFactory

factory for creating an SupportSQLiteOpenHelper

MigrationTestHelper

Added in 2.4.0
public MigrationTestHelper(
    @NonNull Instrumentation instrumentation,
    @NonNull Class<@NonNull RoomDatabase> databaseClass,
    @NonNull List<@NonNull AutoMigrationSpec> specs,
    @NonNull SupportSQLiteOpenHelper.Factory openFactory
)

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.

Instances of classes annotated with androidx.room.ProvidedAutoMigrationSpec have provided using this constructor. MigrationTestHelper will map auto migration spec classes to their provided instances before running and validating the migrations.

When the MigrationTestHelper is created with this constructor configuration then only createDatabase and runMigrationsAndValidate that return SupportSQLiteDatabase can be used.

Parameters
@NonNull Instrumentation instrumentation

The instrumentation instance.
@NonNull Class<@NonNull RoomDatabase> databaseClass

The Database class to be tested.
@NonNull List<@NonNull AutoMigrationSpec> specs

The list of available auto migration specs that will be provided to the RoomDatabase at runtime.
@NonNull SupportSQLiteOpenHelper.Factory openFactory

factory for creating an SupportSQLiteOpenHelper

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 androidx.room.Database annotated class.
@NonNull Function0<@NonNull RoomDatabase> databaseFactory

An optional factory function to create an instance of the databaseClass. Should be the same factory used when building the database via androidx.room.Room.databaseBuilder.
@NonNull List<@NonNull AutoMigrationSpec> autoMigrationSpecs

The list of androidx.room.ProvidedAutoMigrationSpec instances for androidx.room.AutoMigrations that require them.

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 androidx.room.Database annotated class.
@NonNull Function0<@NonNull RoomDatabase> databaseFactory

An optional factory function to create an instance of the databaseClass. Should be the same factory used when building the database via androidx.room.Room.databaseBuilder.
@NonNull List<@NonNull AutoMigrationSpec> autoMigrationSpecs

The list of androidx.room.ProvidedAutoMigrationSpec instances for androidx.room.AutoMigrations that require them.

Public methods

apply

public @NonNull Statement apply(@NonNull Statement p0, @NonNull Description p1)

apply

public @NonNull Statement apply(@NonNull Statement p0, @NonNull Description p1)

closeWhenFinished

Added in 2.0.0
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.

closeWhenFinished

Added in 2.0.0
public void closeWhenFinished(@NonNull SupportSQLiteDatabase 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 SupportSQLiteDatabase db

The database connection that should be closed after the test finishes.

createDatabase

Added in 2.7.0-alpha11
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
kotlin.IllegalStateException

If a new database was not created.

createDatabase

Added in 2.0.0
public @NonNull SupportSQLiteDatabase createDatabase(@NonNull String name, int version)

Creates the database in the given version.

If the database file already exists, it tries to delete it first. If delete fails, throws an exception.

Parameters
@NonNull String name

The name of the database.
int version

The version in which the database should be created.
Returns
@NonNull SupportSQLiteDatabase

A database connection which has the schema in the requested version.

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.room.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
kotlin.IllegalStateException

If the schema validation fails.

runMigrationsAndValidate

Added in 2.0.0
public @NonNull SupportSQLiteDatabase runMigrationsAndValidate(
    @NonNull String name,
    int version,
    boolean validateDroppedTables,
    @NonNull Migration migrations
)

Runs the given set of migrations on the provided database.

It uses the same algorithm that Room uses to choose migrations so the migrations instances that are provided to this method must be sufficient to bring the database from current version to the desired version.

After the migration, the method validates the database schema to ensure that migration result matches the expected schema. Handling of dropped tables depends on the validateDroppedTables argument. If set to true, the verification will fail if it finds a table that is not registered in the Database. If set to false, extra tables in the database will be ignored (this is the runtime library behavior).

Parameters
@NonNull String name

The database name. You must first create this database via createDatabase.
int version

The final version after applying the migrations.
boolean validateDroppedTables

If set to true, validation will fail if the database has unknown tables.
@NonNull Migration migrations

The list of available migrations.
Throws
kotlin.IllegalStateException

If the schema validation fails.

Protected methods

failed

protected void failed(@NonNull Throwable p0, @NonNull Description p1)

failed

protected void failed(@NonNull Throwable p0, @NonNull Description p1)

finished

protected void finished(Description description)

finished

protected void finished(Description description)

skipped

protected void skipped(@NonNull AssumptionViolatedException p0, @NonNull Description p1)

skipped

protected void skipped(@NonNull AssumptionViolatedException p0, @NonNull Description p1)

skipped

protected void skipped(@NonNull AssumptionViolatedException p0, @NonNull Description p1)

skipped

protected void skipped(@NonNull AssumptionViolatedException p0, @NonNull Description p1)

starting

protected void starting(Description description)

starting

protected void starting(@NonNull Description p0)

succeeded

protected void succeeded(@NonNull Description p0)

succeeded

protected void succeeded(@NonNull Description p0)