MigrationTestHelper

MigrationTestHelper(
    instrumentation: Instrumentation,
    databaseClass: Class<RoomDatabase>
)

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.

MigrationTestHelper(
    instrumentation: Instrumentation,
    assetsFolder: String,
    openFactory: SupportSQLiteOpenHelper.Factory = FrameworkSQLiteOpenHelperFactory()
)

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.

MigrationTestHelper(
    instrumentation: Instrumentation,
    databaseClass: Class<RoomDatabase>,
    specs: List<AutoMigrationSpec>,
    openFactory: SupportSQLiteOpenHelper.Factory = FrameworkSQLiteOpenHelperFactory()
)

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.

MigrationTestHelper(
    instrumentation: Instrumentation,
    file: File,
    driver: SQLiteDriver,
    databaseClass: KClass<RoomDatabase>,
    databaseFactory: () -> RoomDatabase = {
            findAndInstantiateDatabaseImpl(databaseClass.java)
        },
    autoMigrationSpecs: List<AutoMigrationSpec> = emptyList()
)

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.

open fun closeWhenFinished(db: RoomDatabase): Unit

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.

open fun closeWhenFinished(db: SupportSQLiteDatabase): Unit

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.

fun createDatabase(version: Int): SQLiteConnection

Creates the database at the given version.

Once a database is created it can further validate with runMigrationsAndValidate.

open fun createDatabase(name: String, version: Int): SupportSQLiteDatabase

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.

fun runMigrationsAndValidate(
    version: Int,
    migrations: List<Migration> = emptyList()
): SQLiteConnection

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.

open fun runMigrationsAndValidate(
    name: String,
    version: Int,
    validateDroppedTables: Boolean,
    vararg migrations: Migration
): SupportSQLiteDatabase

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).