MigrationTestHelper

public class MigrationTestHelper extends 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(
    @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 [AutoMigration].

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

Creates a new migration helper.

Public methods

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.

@NonNull SupportSQLiteDatabase
createDatabase(@NonNull String name, int version)

Creates the database in the given version.

@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
finished(Description description)
void
starting(Description description)

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.

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

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.

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
@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 Room at runtime.

@NonNull SupportSQLiteOpenHelper.Factory openFactory

factory for creating an SupportSQLiteOpenHelper

Public methods

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 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 Rule annotation.

Parameters
@NonNull SupportSQLiteDatabase db

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

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

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

If the schema validation fails.

Protected methods

finished

Added in 2.6.1
protected void finished(Description description)

starting

Added in 2.6.1
protected void starting(Description description)