MigrationTestHelper

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.

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.

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.

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.

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.

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.

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.

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.

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.

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