# MigrationTestHelper

Artifact: [androidx.room3:room3-testing](https://developer.android.com/jetpack/androidx/releases/room3) [View Source](https://cs.android.com/search?q=file:androidx/room3/testing/MigrationTestHelper.+class:androidx.room3.testing.MigrationTestHelper) Added in [3.0.0](https://developer.android.com/jetpack/androidx/releases/room3#3.0.0)

*** ** * ** ***


```
public final class MigrationTestHelper
```

<br />

*** ** * ** ***

A class that can help test and verify database creation and migration at different versions with different schemas.

Common usage of this helper is to create a database at an older version first and then attempt a migration and validation:

```
@Test
fun migrationTest() {
  val migrationTestHelper = getMigrationTestHelper()
  // Create the database at version 1
  val newConnection = migrationTestHelper.createDatabase(1)
  // Insert some data that should be preserved
  newConnection.execSQL("INSERT INTO Pet (id, name) VALUES (1, 'Tom')")
  newConnection.close()

  // Migrate the database to version 2
  val migratedConnection =
      migrationTestHelper.runMigrationsAndValidate(2, listOf(MIGRATION_1_2)))
  migratedConnection.prepare("SELECT * FROM Pet).use { stmt ->
    // Validates data is preserved between migrations.
    assertThat(stmt.step()).isTrue()
    assertThat(stmt.getText(1)).isEqualTo("Tom")
  }
  migratedConnection.close()
}
```

The helper relies on exported schemas so `https://developer.android.com/reference/androidx/room3/Database#exportSchema()` should be enabled. Schema location should be configured via Room's Gradle Plugin (id 'androidx.room'):

```
room {
  schemaDirectory("$projectDir/schemas")
}
```

The helper is then instantiated to use the same schema location where they are exported to. See platform-specific documentation for further configuration.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#MigrationTestHelper(android.app.Instrumentation,java.io.File,androidx.sqlite.SQLiteDriver,kotlin.reflect.KClass,kotlin.Function0,kotlin.collections.List)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/app/Instrumentation.html instrumentation, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/io/File.html file, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/sqlite/SQLiteDriver driver, @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/RoomDatabase> databaseClass, @https://developer.android.com/reference/androidx/annotation/NonNull Function0<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/RoomDatabase> databaseFactory, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/migration/AutoMigrationSpec> autoMigrationSpecs )` Creates a new migration helper. |
| `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#MigrationTestHelper(java.nio.file.Path,java.nio.file.Path,androidx.sqlite.SQLiteDriver,kotlin.reflect.KClass,kotlin.Function0,kotlin.collections.List)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/nio/file/Path.html schemaDirectoryPath, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/nio/file/Path.html databasePath, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/sqlite/SQLiteDriver driver, @https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/RoomDatabase> databaseClass, @https://developer.android.com/reference/androidx/annotation/NonNull Function0<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/RoomDatabase> databaseFactory, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/migration/AutoMigrationSpec> autoMigrationSpecs )` |

| ### Public methods |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#apply(org.junit.runners.model.Statement,org.junit.runner.Description)(@https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html base, @https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html description)` |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#apply(org.junit.runners.model.Statement,org.junit.runner.Description)(@https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html base, @https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html description)` |
| `void` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#closeWhenFinished(androidx.room3.RoomDatabase)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/RoomDatabase db)` Registers a database connection to be automatically closed when the test finishes. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/sqlite/SQLiteConnection` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#createDatabase(kotlin.Int)(int version)` Creates the database at the given version. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/sqlite/SQLiteConnection` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#runMigrationsAndValidate(kotlin.Int,kotlin.collections.List)( int version, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/migration/Migration> migrations )` Runs the given set of migrations on the existing database once created via `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#createDatabase(kotlin.Int)`. |

| ### Protected methods |
|---|---|
| `void` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#failed(java.lang.Throwable,org.junit.runner.Description)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Throwable.html e, @https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html description)` |
| `void` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#failed(java.lang.Throwable,org.junit.runner.Description)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Throwable.html e, @https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html description)` |
| `void` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#finished(org.junit.runner.Description)(https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html description)` |
| `void` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#finished(org.junit.runner.Description)(https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html description)` |
| `void` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#skipped(org.junit.internal.AssumptionViolatedException,org.junit.runner.Description)( @https://developer.android.com/reference/androidx/annotation/NonNull org.junit.internal.AssumptionViolatedException e, @https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html description )` |
| `void` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#skipped(org.junit.internal.AssumptionViolatedException,org.junit.runner.Description)( @https://developer.android.com/reference/androidx/annotation/NonNull org.junit.internal.AssumptionViolatedException e, @https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html description )` |
| `void` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#skipped(org.junit.AssumptionViolatedException,org.junit.runner.Description)( @https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/AssumptionViolatedException.html e, @https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html description )` |
| `void` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#skipped(org.junit.AssumptionViolatedException,org.junit.runner.Description)( @https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/AssumptionViolatedException.html e, @https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html description )` |
| `void` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#starting(org.junit.runner.Description)(https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html description)` |
| `void` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#starting(org.junit.runner.Description)(@https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html description)` |
| `void` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#succeeded(org.junit.runner.Description)(@https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html description)` |
| `void` | `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#succeeded(org.junit.runner.Description)(@https://developer.android.com/reference/androidx/annotation/NonNull https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html description)` |

## Public constructors

### MigrationTestHelper

```
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 `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#(android.app.Instrumentation,java.io.File,androidx.sqlite.SQLiteDriver,kotlin.reflect.KClass,kotlin.Function0,kotlin.collections.List)` context to load the schema (falls back to the app resources) and the target context to create the database.

When the `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper` is created with this constructor configuration then only `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#createDatabase(kotlin.Int)` and `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#runMigrationsAndValidate(kotlin.Int,kotlin.collections.List)` that return `https://developer.android.com/reference/androidx/sqlite/SQLiteConnection` can be used.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/app/Instrumentation.html instrumentation` | The instrumentation instance. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/io/File.html file` | The database file. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/sqlite/SQLiteDriver driver` | A driver that opens connection to a file database. A driver that opens connections to an in-memory database would be meaningless. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/RoomDatabase> databaseClass` | The `https://developer.android.com/reference/androidx/room3/Database` annotated class. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function0<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/RoomDatabase> databaseFactory` | An optional factory function to create an instance of the `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#(android.app.Instrumentation,java.io.File,androidx.sqlite.SQLiteDriver,kotlin.reflect.KClass,kotlin.Function0,kotlin.collections.List)`. Should be the same factory used when building the database via `https://developer.android.com/reference/androidx/room3/Room#databaseBuilder(android.content.Context,java.lang.Class,kotlin.String)`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/migration/AutoMigrationSpec> autoMigrationSpecs` | The list of `https://developer.android.com/reference/androidx/room3/ProvidedAutoMigrationSpec` instances for `https://developer.android.com/reference/androidx/room3/AutoMigration`s that require them. |

### MigrationTestHelper

```
public MigrationTestHelper(
    @NonNull Path schemaDirectoryPath,
    @NonNull Path databasePath,
    @NonNull SQLiteDriver driver,
    @NonNull KClass<@NonNull RoomDatabase> databaseClass,
    @NonNull Function0<@NonNull RoomDatabase> databaseFactory,
    @NonNull List<@NonNull AutoMigrationSpec> autoMigrationSpecs
)
```

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/nio/file/Path.html schemaDirectoryPath` | The schema directory where schema files are exported. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/nio/file/Path.html databasePath` | Name of the database. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/sqlite/SQLiteDriver driver` | A driver that opens connection to a file database. A driver that opens connections to an in-memory database would be meaningless. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/RoomDatabase> databaseClass` | The `https://developer.android.com/reference/androidx/room3/Database` annotated class. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function0<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/RoomDatabase> databaseFactory` | An optional factory function to create an instance of the `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#databaseClass()`. Should be the same factory used when building the database via `https://developer.android.com/reference/androidx/room3/Room#databaseBuilder(kotlin.String,kotlin.Function0)`. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/migration/AutoMigrationSpec> autoMigrationSpecs` | The list of `https://developer.android.com/reference/androidx/room3/ProvidedAutoMigrationSpec` instances for `https://developer.android.com/reference/androidx/room3/AutoMigration`s that require them. |

## Public methods

### apply

```
public @NonNull Statement apply(@NonNull Statement base, @NonNull Description description)
```

### apply

```
public @NonNull Statement apply(@NonNull Statement base, @NonNull Description description)
```

### closeWhenFinished

Added in [3.0.0](https://developer.android.com/jetpack/androidx/releases/room3#3.0.0)

```
public void closeWhenFinished(@NonNull RoomDatabase db)
```

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

This only works if `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper` is registered as a Junit test rule via the `https://junit.org/junit4/javadoc/latest/org/junit/Rule.html` annotation.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/RoomDatabase db` | The RoomDatabase instance which holds the database. |

### createDatabase

```
public final @NonNull SQLiteConnection createDatabase(int version)
```

Creates the database at the given version.

Once a database is created it can further validate with `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#runMigrationsAndValidate(kotlin.Int,kotlin.collections.List)`.

| Parameters |
|---|---|
| `int version` | The version of the schema at which the database should be created. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/sqlite/SQLiteConnection` | A database connection of the newly created database. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | If a new database was not created. |

### runMigrationsAndValidate

```
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 `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#createDatabase(kotlin.Int)`.

This function uses the same algorithm that Room performs to choose migrations such that the `https://developer.android.com/reference/androidx/room3/testing/MigrationTestHelper#runMigrationsAndValidate(kotlin.Int,kotlin.collections.List)` instances provided must be sufficient to bring the database from current version to the desired version. If the database contains `https://developer.android.com/reference/androidx/room3/AutoMigration`s, 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.

| Parameters |
|---|---|
| `int version` | The final version the database should migrate to. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/room3/migration/Migration> migrations` | The list of migrations used to attempt the database migration. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/sqlite/SQLiteConnection` | A database connection of the migrated database. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | If the schema validation fails. |

## Protected methods

### failed

```
protected void failed(@NonNull Throwable e, @NonNull Description description)
```

### failed

```
protected void failed(@NonNull Throwable e, @NonNull Description description)
```

### finished

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

### finished

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

### skipped

```
protected void skipped(
    @NonNull org.junit.internal.AssumptionViolatedException e,
    @NonNull Description description
)
```

### skipped

```
protected void skipped(
    @NonNull org.junit.internal.AssumptionViolatedException e,
    @NonNull Description description
)
```

### skipped

```
protected void skipped(
    @NonNull AssumptionViolatedException e,
    @NonNull Description description
)
```

### skipped

```
protected void skipped(
    @NonNull AssumptionViolatedException e,
    @NonNull Description description
)
```

### starting

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

### starting

```
protected void starting(@NonNull Description description)
```

### succeeded

```
protected void succeeded(@NonNull Description description)
```

### succeeded

```
protected void succeeded(@NonNull Description description)
```