# MigrationTestHelper

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

*** ** * ** ***

Common/AllAndroid/JVMNative/C/iOS
- Cmn

  ```
  class MigrationTestHelper
  ```
- android

  ```
  open class MigrationTestHelper
  ```

*** ** * ** ***

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:

```kotlin
@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/kotlin/androidx/room/Database#exportSchema()` should be enabled. Schema location should be configured via Room's Gradle Plugin (id 'androidx.room'):

```kotlin
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/kotlin/androidx/room/testing/MigrationTestHelper#MigrationTestHelper(android.app.Instrumentation,java.lang.Class)( instrumentation: https://developer.android.com/reference/android/app/Instrumentation.html, databaseClass: https://developer.android.com/reference/java/lang/Class.html<https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase> )` Creates a new migration helper. | android |
| `[MigrationTestHelper](https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#MigrationTestHelper(android.app.Instrumentation,kotlin.String,androidx.sqlite.db.SupportSQLiteOpenHelper.Factory))( instrumentation: https://developer.android.com/reference/android/app/Instrumentation.html, assetsFolder: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, openFactory: https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteOpenHelper.Factory )` **This function is deprecated.** Cannot be used to run migration tests involving auto migrations. | android |
| `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#MigrationTestHelper(android.app.Instrumentation,java.lang.Class,kotlin.collections.List,androidx.sqlite.db.SupportSQLiteOpenHelper.Factory)( instrumentation: https://developer.android.com/reference/android/app/Instrumentation.html, databaseClass: https://developer.android.com/reference/java/lang/Class.html<https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase>, specs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/room/migration/AutoMigrationSpec>, openFactory: https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteOpenHelper.Factory )` Creates a new migration helper. | android |
| `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#MigrationTestHelper(android.app.Instrumentation,java.io.File,androidx.sqlite.SQLiteDriver,kotlin.reflect.KClass,kotlin.Function0,kotlin.collections.List)( instrumentation: https://developer.android.com/reference/android/app/Instrumentation.html, file: https://developer.android.com/reference/java/io/File.html, driver: https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteDriver, databaseClass: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase>, databaseFactory: () -> https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase, autoMigrationSpecs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/room/migration/AutoMigrationSpec> )` Creates a new migration helper. | android |
| `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#MigrationTestHelper(java.nio.file.Path,java.nio.file.Path,androidx.sqlite.SQLiteDriver,kotlin.reflect.KClass,kotlin.Function0,kotlin.collections.List)( schemaDirectoryPath: https://developer.android.com/reference/java/nio/file/Path.html, databasePath: https://developer.android.com/reference/java/nio/file/Path.html, driver: https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteDriver, databaseClass: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase>, databaseFactory: () -> https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase, autoMigrationSpecs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/room/migration/AutoMigrationSpec> )` | android |
| `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#MigrationTestHelper(kotlin.String,kotlin.String,androidx.sqlite.SQLiteDriver,kotlin.reflect.KClass,kotlin.Function0,kotlin.collections.List)( schemaDirectoryPath: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, fileName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, driver: https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteDriver, databaseClass: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase>, databaseFactory: () -> https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase, autoMigrationSpecs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/room/migration/AutoMigrationSpec> )` | N |

| ### Public functions |
|---|---|---|
| `https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#apply(org.junit.runners.model.Statement,org.junit.runner.Description)(base: https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html, description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html)` | android |
| `https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#apply(org.junit.runners.model.Statement,org.junit.runner.Description)(base: https://junit.org/junit4/javadoc/latest/org/junit/runners/model/Statement.html, description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html)` | android |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#closeWhenFinished(androidx.room.RoomDatabase)(db: https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase)` Registers a database connection to be automatically closed when the test finishes. | android |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#closeWhenFinished(androidx.sqlite.db.SupportSQLiteDatabase)(db: https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase)` Registers a database connection to be automatically closed when the test finishes. | android |
| `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteConnection` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#createDatabase(kotlin.Int)(version: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Creates the database at the given version. | Cmn android N |
| `open https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#createDatabase(kotlin.String,kotlin.Int)(name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, version: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Creates the database in the given version. | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#finished()()` | N |
| `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteConnection` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#runMigrationsAndValidate(kotlin.Int,kotlin.collections.List)(version: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, migrations: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/room/migration/Migration>)` Runs the given set of migrations on the existing database once created via `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#createDatabase(kotlin.Int)`. | Cmn android N |
| `open https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#runMigrationsAndValidate(kotlin.String,kotlin.Int,kotlin.Boolean,kotlin.Array)( name: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, version: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, validateDroppedTables: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html, vararg migrations: https://developer.android.com/reference/kotlin/androidx/room/migration/Migration )` Runs the given set of migrations on the provided database. | android |

| ### Protected functions |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#failed(java.lang.Throwable,org.junit.runner.Description)(e: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-throwable/index.html, description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html)` | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#failed(java.lang.Throwable,org.junit.runner.Description)(e: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-throwable/index.html, description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html)` | android |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#finished(org.junit.runner.Description)(description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html?)` | android |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#finished(org.junit.runner.Description)(description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html?)` | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#skipped(org.junit.internal.AssumptionViolatedException,org.junit.runner.Description)( e: org.junit.internal.AssumptionViolatedException, description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html )` | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#skipped(org.junit.internal.AssumptionViolatedException,org.junit.runner.Description)( e: org.junit.internal.AssumptionViolatedException, description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html )` | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#skipped(org.junit.AssumptionViolatedException,org.junit.runner.Description)(e: https://junit.org/junit4/javadoc/latest/org/junit/AssumptionViolatedException.html, description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html)` | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#skipped(org.junit.AssumptionViolatedException,org.junit.runner.Description)(e: https://junit.org/junit4/javadoc/latest/org/junit/AssumptionViolatedException.html, description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html)` | android |
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#starting(org.junit.runner.Description)(description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html?)` | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#starting(org.junit.runner.Description)(description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html)` | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#succeeded(org.junit.runner.Description)(description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html)` | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#succeeded(org.junit.runner.Description)(description: https://junit.org/junit4/javadoc/latest/org/junit/runner/Description.html)` | android |

## Public constructors

### MigrationTestHelper

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

```
MigrationTestHelper(
    instrumentation: Instrumentation,
    databaseClass: Class<RoomDatabase>
)
```

Creates a new migration helper. It uses the `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#(android.app.Instrumentation,java.lang.Class)` 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/kotlin/androidx/room/testing/MigrationTestHelper` is created with this constructor configuration then only `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#createDatabase(kotlin.String,kotlin.Int)` and `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#runMigrationsAndValidate(kotlin.String,kotlin.Int,kotlin.Boolean,kotlin.Array)` that return `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase` can be used.

| Parameters |
|---|---|
| `instrumentation: https://developer.android.com/reference/android/app/Instrumentation.html` | The instrumentation instance. |
| `databaseClass: https://developer.android.com/reference/java/lang/Class.html<https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase>` | The Database class to be tested. |

### MigrationTestHelper

android Added in [2.0.0](https://developer.android.com/jetpack/androidx/releases/room#2.0.0) Deprecated in [2.4.0](https://developer.android.com/jetpack/androidx/releases/room#2.4.0)

```
[MigrationTestHelper](https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#MigrationTestHelper(android.app.Instrumentation,kotlin.String,androidx.sqlite.db.SupportSQLiteOpenHelper.Factory))(
    instrumentation: Instrumentation,
    assetsFolder: String,
    openFactory: SupportSQLiteOpenHelper.Factory = FrameworkSQLiteOpenHelperFactory()
)
```

> [!CAUTION]
> **This function is deprecated.**   
> Cannot be used to run migration tests involving auto migrations. To test an auto migrations, you must use the constructors that receives the database class as parameter.

Creates a new migration helper. It uses the `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#(android.app.Instrumentation,kotlin.String,androidx.sqlite.db.SupportSQLiteOpenHelper.Factory)` 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/kotlin/androidx/room/testing/MigrationTestHelper` is created with this constructor configuration then only `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#createDatabase(kotlin.String,kotlin.Int)` and `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#runMigrationsAndValidate(kotlin.String,kotlin.Int,kotlin.Boolean,kotlin.Array)` that return `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase` can be used.

| Parameters |
|---|---|
| `instrumentation: https://developer.android.com/reference/android/app/Instrumentation.html` | The instrumentation instance. |
| `assetsFolder: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The asset folder in the assets directory. |
| `openFactory: https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteOpenHelper.Factory = FrameworkSQLiteOpenHelperFactory()` | factory for creating an `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteOpenHelper` |

### MigrationTestHelper

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

```
MigrationTestHelper(
    instrumentation: Instrumentation,
    databaseClass: Class<RoomDatabase>,
    specs: List<AutoMigrationSpec>,
    openFactory: SupportSQLiteOpenHelper.Factory = FrameworkSQLiteOpenHelperFactory()
)
```

Creates a new migration helper. It uses the `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#(android.app.Instrumentation,java.lang.Class,kotlin.collections.List,androidx.sqlite.db.SupportSQLiteOpenHelper.Factory)` context to load the schema (falls back to the app resources) and the target context to create the database.

Instances of classes annotated with `https://developer.android.com/reference/kotlin/androidx/room/ProvidedAutoMigrationSpec` have provided using this constructor. `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper` will map auto migration spec classes to their provided instances before running and validating the migrations.

When the `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper` is created with this constructor configuration then only `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#createDatabase(kotlin.String,kotlin.Int)` and `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#runMigrationsAndValidate(kotlin.String,kotlin.Int,kotlin.Boolean,kotlin.Array)` that return `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase` can be used.

| Parameters |
|---|---|
| `instrumentation: https://developer.android.com/reference/android/app/Instrumentation.html` | The instrumentation instance. |
| `databaseClass: https://developer.android.com/reference/java/lang/Class.html<https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase>` | The Database class to be tested. |
| `specs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/room/migration/AutoMigrationSpec>` | The list of available auto migration specs that will be provided to the RoomDatabase at runtime. |
| `openFactory: https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteOpenHelper.Factory = FrameworkSQLiteOpenHelperFactory()` | factory for creating an `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteOpenHelper` |

### MigrationTestHelper

android

```
MigrationTestHelper(
    instrumentation: Instrumentation,
    file: File,
    driver: SQLiteDriver,
    databaseClass: KClass<RoomDatabase>,
    databaseFactory: () -> RoomDatabase = {
            findAndInstantiateDatabaseImpl(databaseClass.java)
        },
    autoMigrationSpecs: List<AutoMigrationSpec> = emptyList()
)
```

Creates a new migration helper. It uses the `https://developer.android.com/reference/kotlin/androidx/room/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/kotlin/androidx/room/testing/MigrationTestHelper` is created with this constructor configuration then only `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#createDatabase(kotlin.String,kotlin.Int)` and `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#runMigrationsAndValidate(kotlin.String,kotlin.Int,kotlin.Boolean,kotlin.Array)` that return `https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteConnection` can be used.

| Parameters |
|---|---|
| `instrumentation: https://developer.android.com/reference/android/app/Instrumentation.html` | The instrumentation instance. |
| `file: https://developer.android.com/reference/java/io/File.html` | The database file. |
| `driver: https://developer.android.com/reference/kotlin/androidx/sqlite/SQLiteDriver` | A driver that opens connection to a file database. A driver that opens connections to an in-memory database would be meaningless. |
| `databaseClass: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.reflect/-k-class/index.html<https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase>` | The `https://developer.android.com/reference/kotlin/androidx/room/Database` annotated class. |
| `databaseFactory: () -> https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase = { findAndInstantiateDatabaseImpl(databaseClass.java) }` | An optional factory function to create an instance of the `https://developer.android.com/reference/kotlin/androidx/room/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/kotlin/androidx/room/Room#databaseBuilder(android.content.Context,java.lang.Class,kotlin.String)`. |
| `autoMigrationSpecs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/room/migration/AutoMigrationSpec> = emptyList()` | The list of `https://developer.android.com/reference/kotlin/androidx/room/ProvidedAutoMigrationSpec` instances for `https://developer.android.com/reference/kotlin/androidx/room/AutoMigration`s that require them. |

### MigrationTestHelper

android

```
MigrationTestHelper(
    schemaDirectoryPath: Path,
    databasePath: Path,
    driver: SQLiteDriver,
    databaseClass: KClass<RoomDatabase>,
    databaseFactory: () -> RoomDatabase = { findAndInstantiateDatabaseImpl(databaseClass.java) },
    autoMigrationSpecs: List<AutoMigrationSpec> = emptyList()
)
```

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

### MigrationTestHelper

N

```
MigrationTestHelper(
    schemaDirectoryPath: String,
    fileName: String,
    driver: SQLiteDriver,
    databaseClass: KClass<RoomDatabase>,
    databaseFactory: () -> RoomDatabase = {
        findDatabaseConstructorAndInitDatabaseImpl(databaseClass)
    },
    autoMigrationSpecs: List<AutoMigrationSpec> = emptyList()
)
```

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

## Public functions

### apply

android

```
fun apply(base: Statement, description: Description): Statement
```

### apply

android

```
fun apply(base: Statement, description: Description): Statement
```

### closeWhenFinished

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

```
open fun closeWhenFinished(db: RoomDatabase): Unit
```

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

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

| Parameters |
|---|---|
| `db: https://developer.android.com/reference/kotlin/androidx/room/RoomDatabase` | The RoomDatabase instance which holds the database. |

### closeWhenFinished

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

```
open fun closeWhenFinished(db: SupportSQLiteDatabase): Unit
```

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

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

| Parameters |
|---|---|
| `db: https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase` | The database connection that should be closed after the test finishes. |

### createDatabase

Cmn android N Added in [2.7.0](https://developer.android.com/jetpack/androidx/releases/room#2.7.0)

```
fun createDatabase(version: Int): SQLiteConnection
```

Creates the database at the given version.

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

| Parameters |
|---|---|
| `version: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The version of the schema at which the database should be created. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/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. |

### createDatabase

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

```
open fun createDatabase(name: String, version: Int): SupportSQLiteDatabase
```

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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The name of the database. |
| `version: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The version in which the database should be created. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/sqlite/db/SupportSQLiteDatabase` | A database connection which has the schema in the requested version. |

### finished

N

```
fun finished(): Unit
```

### runMigrationsAndValidate

Cmn android N

```
fun runMigrationsAndValidate(
    version: Int,
    migrations: List<Migration> = emptyList()
): SQLiteConnection
```

Runs the given set of migrations on the existing database once created via `https://developer.android.com/reference/kotlin/androidx/room/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/kotlin/androidx/room/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/kotlin/androidx/room/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 |
|---|---|
| `version: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The final version the database should migrate to. |
| `migrations: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/room/migration/Migration> = emptyList()` | The list of migrations used to attempt the database migration. |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/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. |

### runMigrationsAndValidate

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

```
open fun runMigrationsAndValidate(
    name: String,
    version: Int,
    validateDroppedTables: Boolean,
    vararg migrations: Migration
): SupportSQLiteDatabase
```

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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The database name. You must first create this database via `https://developer.android.com/reference/kotlin/androidx/room/testing/MigrationTestHelper#createDatabase(kotlin.String,kotlin.Int)`. |
| `version: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | The final version after applying the migrations. |
| `validateDroppedTables: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | If set to true, validation will fail if the database has unknown tables. |
| `vararg migrations: https://developer.android.com/reference/kotlin/androidx/room/migration/Migration` | The list of available migrations. |

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

## Protected functions

### failed

android

```
protected fun failed(e: Throwable, description: Description): Unit
```

### failed

android

```
protected fun failed(e: Throwable, description: Description): Unit
```

### finished

android

```
protected open fun finished(description: Description?): Unit
```

### finished

android

```
protected open fun finished(description: Description?): Unit
```

### skipped

android

```
protected fun skipped(
    e: org.junit.internal.AssumptionViolatedException,
    description: Description
): Unit
```

### skipped

android

```
protected fun skipped(
    e: org.junit.internal.AssumptionViolatedException,
    description: Description
): Unit
```

### skipped

android

```
protected fun skipped(e: AssumptionViolatedException, description: Description): Unit
```

### skipped

android

```
protected fun skipped(e: AssumptionViolatedException, description: Description): Unit
```

### starting

android

```
protected open fun starting(description: Description?): Unit
```

### starting

android

```
protected fun starting(description: Description): Unit
```

### succeeded

android

```
protected fun succeeded(description: Description): Unit
```

### succeeded

android

```
protected fun succeeded(description: Description): Unit
```