MigrationTestHelper

public class MigrationTestHelper
extends TestWatcher

java.lang.Object
   ↳ org.junit.rules.TestWatcher
     ↳ androidx.room.testing.MigrationTestHelper

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, String assetsFolder)

This constructor is deprecated. Cannot be used to run migration tests involving AutoMigration.

To test AutoMigration, you must use MigrationTestHelper(Instrumentation, Class, List, SupportSQLiteOpenHelper.Factory) for tests containing a ProvidedAutoMigrationSpec, or use MigrationTestHelper(Instrumentation, Class, List) otherwise.

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

This constructor is deprecated. Cannot be used to run migration tests involving AutoMigration.

To test AutoMigration, you must use MigrationTestHelper(Instrumentation, Class, List, SupportSQLiteOpenHelper.Factory) for tests containing a ProvidedAutoMigrationSpec, or use MigrationTestHelper(Instrumentation, Class, List) otherwise.

MigrationTestHelper(Instrumentation instrumentation, Class<? extends RoomDatabase> databaseClass)

Creates a new migration helper.

MigrationTestHelper(Instrumentation instrumentation, Class<? extends RoomDatabase> databaseClass, List<AutoMigrationSpec> specs)

Creates a new migration helper.

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

Creates a new migration helper.

Public methods

void closeWhenFinished(RoomDatabase db)

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

void closeWhenFinished(SupportSQLiteDatabase db)

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

SupportSQLiteDatabase createDatabase(String name, int version)

Creates the database in the given version.

SupportSQLiteDatabase runMigrationsAndValidate(String name, int version, boolean validateDroppedTables, Migration... migrations)

Runs the given set of migrations on the provided database.

Protected methods

void finished(Description description)
void starting(Description description)

Inherited methods

Public constructors

MigrationTestHelper

public MigrationTestHelper (Instrumentation instrumentation, 
                String assetsFolder)

This constructor is deprecated.
Cannot be used to run migration tests involving AutoMigration.

To test AutoMigration, you must use MigrationTestHelper(Instrumentation, Class, List, SupportSQLiteOpenHelper.Factory) for tests containing a ProvidedAutoMigrationSpec, or use MigrationTestHelper(Instrumentation, Class, List) otherwise.

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.

MigrationTestHelper

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

This constructor is deprecated.
Cannot be used to run migration tests involving AutoMigration.

To test AutoMigration, you must use MigrationTestHelper(Instrumentation, Class, List, SupportSQLiteOpenHelper.Factory) for tests containing a ProvidedAutoMigrationSpec, or use MigrationTestHelper(Instrumentation, Class, List) otherwise.

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: Factory class that allows creation of SupportSQLiteOpenHelper

MigrationTestHelper

public MigrationTestHelper (Instrumentation instrumentation, 
                Class<? extends 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.

Parameters
instrumentation Instrumentation: The instrumentation instance.
databaseClass Class: The Database class to be tested.

MigrationTestHelper

public MigrationTestHelper (Instrumentation instrumentation, 
                Class<? extends RoomDatabase> databaseClass, 
                List<AutoMigrationSpec> specs)

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 ProvidedAutoMigrationSpec has to be provided to Room using this constructor. MigrationTestHelper will map auto migration spec classes to their provided instances before running and validatingt the Migrations.

Parameters
instrumentation Instrumentation: The instrumentation instance.
databaseClass Class: The Database class to be tested.
specs List: The list of available auto migration specs that will be provided to Room at runtime.

MigrationTestHelper

public MigrationTestHelper (Instrumentation instrumentation, 
                Class<? extends RoomDatabase> databaseClass, 
                List<AutoMigrationSpec> specs, 
                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 ProvidedAutoMigrationSpec has to be provided to Room using this constructor. MigrationTestHelper will map auto migration spec classes to their provided instances before running and validatingt the Migrations.

Parameters
instrumentation Instrumentation: The instrumentation instance.
databaseClass Class: The Database class to be tested.
specs List: The list of available auto migration specs that will be provided to Room at runtime.
openFactory SupportSQLiteOpenHelper.Factory: Factory class that allows creation of SupportSQLiteOpenHelper

Public methods

closeWhenFinished

public void closeWhenFinished (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
db RoomDatabase: The RoomDatabase instance which holds the database.

closeWhenFinished

public void closeWhenFinished (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
db SupportSQLiteDatabase: The database connection that should be closed after the test finishes.

createDatabase

public SupportSQLiteDatabase createDatabase (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
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.
Throws
IOException If it cannot find the schema description in the assets folder.

runMigrationsAndValidate

public SupportSQLiteDatabase runMigrationsAndValidate (String name, 
                int version, 
                boolean validateDroppedTables, 
                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
name String: The database name. You must first create this database via createDatabase(String, int).
version int: The final version after applying the migrations.
validateDroppedTables boolean: If set to true, validation will fail if the database has unknown tables.
migrations Migration: The list of available migrations.
Returns
SupportSQLiteDatabase

Throws
IOException If it cannot find the schema for toVersion.
IllegalStateException If the schema validation fails.

Protected methods

finished

protected void finished (Description description)

Parameters
description Description

starting

protected void starting (Description description)

Parameters
description Description