# MigrationTestHelper

added in[version 1.1.0](https://developer.android.com/topic/libraries/support-library/revisions)  
belongs to Maven artifact android.arch.persistence.room:testing:1.1.0-beta2  
Summary:[Ctors](https://developer.android.com/reference/android/arch/persistence/room/testing/MigrationTestHelper#pubctors)\|[Methods](https://developer.android.com/reference/android/arch/persistence/room/testing/MigrationTestHelper#pubmethods)\|[Protected Methods](https://developer.android.com/reference/android/arch/persistence/room/testing/MigrationTestHelper#promethods)\|[Inherited Methods](https://developer.android.com/reference/android/arch/persistence/room/testing/MigrationTestHelper#inhmethods)  

# MigrationTestHelper

| The`android.arch`Architecture Components packages are no longer maintained. They have been superseded by the corresponding[androidx.\*](https://developer.android.com/jetpack/androidx/migrate)packages. See[androidx.room.testing.MigrationTestHelper](https://developer.android.com/reference/androidx/room/testing/MigrationTestHelper)instead.

`
public


class
MigrationTestHelper
`  
`


``

extends TestWatcher


``


`

|---|---|-----------------------------------------------------------|
| java.lang.Object                                                |||
| ↳ | org.junit.rules.TestWatcher                                  ||
|   | ↳ | android.arch.persistence.room.testing.MigrationTestHelper |

<br />

*** ** * ** ***

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())
   }
 }
 
```

<br />

## Summary

|                                                                                                                                                                                                                                                                                   ### Public constructors                                                                                                                                                                                                                                                                                   ||
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|
| ` `[MigrationTestHelper](https://developer.android.com/reference/android/arch/persistence/room/testing/MigrationTestHelper#MigrationTestHelper(android.app.Instrumentation, java.lang.String))`(`[Instrumentation](https://developer.android.com/reference/android/app/Instrumentation.html)` instrumentation, String assetsFolder) ` Creates a new migration helper.                                                                                                                                                                                                                    |
| ` `[MigrationTestHelper](https://developer.android.com/reference/android/arch/persistence/room/testing/MigrationTestHelper#MigrationTestHelper(android.app.Instrumentation, java.lang.String, android.arch.persistence.db.SupportSQLiteOpenHelper.Factory))`(`[Instrumentation](https://developer.android.com/reference/android/app/Instrumentation.html)` instrumentation, String assetsFolder, `[SupportSQLiteOpenHelper.Factory](https://developer.android.com/reference/android/arch/persistence/db/SupportSQLiteOpenHelper.Factory)` openFactory) ` Creates a new migration helper. |

|                                                                                                                                                                                                                                                                                                  ### Public methods                                                                                                                                                                                                                                                                                                   ||
|-----------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ` void`                                                                                                               | ` `[closeWhenFinished](https://developer.android.com/reference/android/arch/persistence/room/testing/MigrationTestHelper#closeWhenFinished(android.arch.persistence.db.SupportSQLiteDatabase))`(`[SupportSQLiteDatabase](https://developer.android.com/reference/android/arch/persistence/db/SupportSQLiteDatabase)` db) ` Registers a database connection to be automatically closed when the test finishes.                                                                                  |
| ` void`                                                                                                               | ` `[closeWhenFinished](https://developer.android.com/reference/android/arch/persistence/room/testing/MigrationTestHelper#closeWhenFinished(android.arch.persistence.room.RoomDatabase))`(`[RoomDatabase](https://developer.android.com/reference/android/arch/persistence/room/RoomDatabase)` db) ` Registers a database connection to be automatically closed when the test finishes.                                                                                                         |
| ` `[SupportSQLiteDatabase](https://developer.android.com/reference/android/arch/persistence/db/SupportSQLiteDatabase) | ` `[createDatabase](https://developer.android.com/reference/android/arch/persistence/room/testing/MigrationTestHelper#createDatabase(java.lang.String, int))`(String name, int version) ` Creates the database in the given version.                                                                                                                                                                                                                                                           |
| ` `[SupportSQLiteDatabase](https://developer.android.com/reference/android/arch/persistence/db/SupportSQLiteDatabase) | ` `[runMigrationsAndValidate](https://developer.android.com/reference/android/arch/persistence/room/testing/MigrationTestHelper#runMigrationsAndValidate(java.lang.String, int, boolean, android.arch.persistence.room.migration.Migration...))`(String name, int version, boolean validateDroppedTables, `[Migration...](https://developer.android.com/reference/android/arch/persistence/room/migration/Migration)` migrations) ` Runs the given set of migrations on the provided database. |

|                                                                                    ### Protected methods                                                                                     ||
|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ` void` | ` `[finished](https://developer.android.com/reference/android/arch/persistence/room/testing/MigrationTestHelper#finished(org.junit.runner.Description))`(Description description) ` |
| ` void` | ` `[starting](https://developer.android.com/reference/android/arch/persistence/room/testing/MigrationTestHelper#starting(org.junit.runner.Description))`(Description description) ` |

| ### Inherited methods |
|-----------------------|---|
| From class` org.junit.rules.TestWatcher ` |--------------|-----------------------------------------------------------------| | ` Statement` | ` apply(Statement arg0, Description arg1) `                     | | ` void`      | ` failed(Throwable arg0, Description arg1) `                    | | ` void`      | ` finished(Description arg0) `                                  | | ` void`      | ` skipped(AssumptionViolatedException arg0, Description arg1) ` | | ` void`      | ` skipped(AssumptionViolatedException arg0, Description arg1) ` | | ` void`      | ` starting(Description arg0) `                                  | | ` void`      | ` succeeded(Description arg0) `                                 | ||
| From class` java.lang.Object ` |-------------------|-------------------------------| | ` Object`         | ` clone() `                   | | ` boolean`        | ` equals(Object arg0) `       | | ` void`           | ` finalize() `                | | ` final Class<?>` | ` getClass() `                | | ` int`            | ` hashCode() `                | | ` final void`     | ` notify() `                  | | ` final void`     | ` notifyAll() `               | | ` String`         | ` toString() `                | | ` final void`     | ` wait(long arg0, int arg1) ` | | ` final void`     | ` wait(long arg0) `           | | ` final void`     | ` wait() `                    | ||
| From interface` org.junit.rules.TestRule ` |-----------------------|---------------------------------------------| | ` abstract Statement` | ` apply(Statement arg0, Description arg1) ` | ||

## Public constructors

### MigrationTestHelper

added in[version 1.1.0](https://developer.android.com/topic/libraries/support-library/revisions)  

```
MigrationTestHelper (Instrumentation instrumentation, 
                String assetsFolder)
```

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.

<br />

|                                  Parameters                                   ||
|-------------------|------------------------------------------------------------|
| `instrumentation` | `Instrumentation`: The instrumentation instance. <br />    |
| `assetsFolder`    | `String`: The asset folder in the assets directory. <br /> |

### MigrationTestHelper

added in[version 1.1.0](https://developer.android.com/topic/libraries/support-library/revisions)  

```
MigrationTestHelper (Instrumentation instrumentation, 
                String assetsFolder, 
                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.

<br />

|                                                                                                        Parameters                                                                                                        ||
|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `instrumentation` | `Instrumentation`: The instrumentation instance. <br />                                                                                                                                               |
| `assetsFolder`    | `String`: The asset folder in the assets directory. <br />                                                                                                                                            |
| `openFactory`     | `SupportSQLiteOpenHelper.Factory`: Factory class that allows creation of[SupportSQLiteOpenHelper](https://developer.android.com/reference/android/arch/persistence/db/SupportSQLiteOpenHelper) <br /> |

## Public methods

### closeWhenFinished

added in[version 1.1.0](https://developer.android.com/topic/libraries/support-library/revisions)  

```
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](https://developer.android.com/reference/org/junit/Rule)annotation.

<br />

|                                                  Parameters                                                  ||
|------|--------------------------------------------------------------------------------------------------------|
| `db` | `SupportSQLiteDatabase`: The database connection that should be closed after the test finishes. <br /> |

### closeWhenFinished

added in[version 1.1.0](https://developer.android.com/topic/libraries/support-library/revisions)  

```
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](https://developer.android.com/reference/org/junit/Rule)annotation.

<br />

|                                    Parameters                                    ||
|------|----------------------------------------------------------------------------|
| `db` | `RoomDatabase`: The RoomDatabase instance which holds the database. <br /> |

### createDatabase

added in[version 1.1.0](https://developer.android.com/topic/libraries/support-library/revisions)  

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

<br />

|                                  Parameters                                   ||
|-----------|--------------------------------------------------------------------|
| `name`    | `String`: The name of the database. <br />                         |
| `version` | `int`: The version in which the database should be created. <br /> |

|                                                                                             Returns                                                                                             ||
|--------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| [SupportSQLiteDatabase](https://developer.android.com/reference/android/arch/persistence/db/SupportSQLiteDatabase) | A database connection which has the schema in the requested version. <br /> |

|                                    Throws                                     ||
|---------------|----------------------------------------------------------------|
| `IOException` | If it cannot find the schema description in the assets folder. |

### runMigrationsAndValidate

added in[version 1.1.0](https://developer.android.com/topic/libraries/support-library/revisions)  

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

<br />

|                                                                                                                                 Parameters                                                                                                                                  ||
|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `name`                  | `String`: The database name. You must first create this database via[createDatabase(String, int)](https://developer.android.com/reference/android/arch/persistence/room/testing/MigrationTestHelper#createDatabase(java.lang.String, int)). <br /> |
| `version`               | `int`: The final version after applying the migrations. <br />                                                                                                                                                                                     |
| `validateDroppedTables` | `boolean`: If set to true, validation will fail if the database has unknown tables. <br />                                                                                                                                                         |
| `migrations`            | `Migration`: The list of available migrations. <br />                                                                                                                                                                                              |

|                                                          Returns                                                           ||
|--------------------------------------------------------------------------------------------------------------------|--------|
| [SupportSQLiteDatabase](https://developer.android.com/reference/android/arch/persistence/db/SupportSQLiteDatabase) | <br /> |

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

## Protected methods

### finished

```
void finished (Description description)
```

<br />

<br />

|             Parameters              ||
|---------------|----------------------|
| `description` | `Description` <br /> |

### starting

```
void starting (Description description)
```

<br />

<br />

|             Parameters              ||
|---------------|----------------------|
| `description` | `Description` <br /> |

-

  ## Classes

  - [MigrationTestHelper](https://developer.android.com/reference/android/arch/persistence/room/testing/MigrationTestHelper)