MigrationTestHelper

open class MigrationTestHelper : TestWatcher


A class that can be used in your Instrumentation tests that can create the database in an older schema.

You must copy the schema json files (created by passing room.schemaLocation argument into the annotation processor) into your test assets and pass in the path for that folder into the constructor. This class will read the folder and extract the schemas from there.

android {
defaultConfig {
javaCompileOptions {
annotationProcessorOptions {
arguments = ["room.schemaLocation": "$projectDir/schemas".toString()]
}
}
}
sourceSets {
androidTest.assets.srcDirs += files("$projectDir/schemas".toString())
}
}

Summary

Public constructors

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

Creates a new migration helper.

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

This function is deprecated. Cannot be used to run migration tests involving [AutoMigration].

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

Creates a new migration helper.

Public functions

open Unit

Registers a database connection to be automatically closed when the test finishes.

open Unit

Registers a database connection to be automatically closed when the test finishes.

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

Creates the database in the given version.

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

Runs the given set of migrations on the provided database.

Protected functions

open Unit
finished(description: Description?)
open Unit
starting(description: Description?)

Inherited functions

From org.junit.rules.TestWatcher
open Statement
open Unit
open Unit

This function is deprecated. Deprecated in Java

open Unit
open Unit

Public constructors

MigrationTestHelper

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

An instance of a class annotated with androidx.room.ProvidedAutoMigrationSpec has to be provided to Room using this constructor. MigrationTestHelper will map auto migration spec classes to their provided instances before running and validating the Migrations.

Parameters
instrumentation: Instrumentation

The instrumentation instance.

databaseClass: Class<RoomDatabase>

The Database class to be tested.

MigrationTestHelper

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

Parameters
instrumentation: Instrumentation

The instrumentation instance.

assetsFolder: String

The asset folder in the assets directory.

openFactory: SupportSQLiteOpenHelper.Factory = FrameworkSQLiteOpenHelperFactory()

factory for creating an SupportSQLiteOpenHelper

MigrationTestHelper

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

An instance of a class annotated with androidx.room.ProvidedAutoMigrationSpec has to be provided to Room using this constructor. MigrationTestHelper will map auto migration spec classes to their provided instances before running and validating the Migrations.

Parameters
instrumentation: Instrumentation

The instrumentation instance.

databaseClass: Class<RoomDatabase>

The Database class to be tested.

specs: List<AutoMigrationSpec>

The list of available auto migration specs that will be provided to Room at runtime.

openFactory: SupportSQLiteOpenHelper.Factory = FrameworkSQLiteOpenHelperFactory()

factory for creating an SupportSQLiteOpenHelper

Public functions

closeWhenFinished

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

Parameters
db: RoomDatabase

The RoomDatabase instance which holds the database.

closeWhenFinished

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

Parameters
db: SupportSQLiteDatabase

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

createDatabase

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

Parameters
name: String

The name of the database.

version: Int

The version in which the database should be created.

Returns
SupportSQLiteDatabase

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

runMigrationsAndValidate

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

Parameters
name: String

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

version: Int

The final version after applying the migrations.

validateDroppedTables: Boolean

If set to true, validation will fail if the database has unknown tables.

vararg migrations: Migration

The list of available migrations.

Throws
kotlin.IllegalArgumentException

If the schema validation fails.

Protected functions

finished

Added in 2.6.1
protected open fun finished(description: Description?): Unit

starting

Added in 2.6.1
protected open fun starting(description: Description?): Unit